Skip to content

Commit ccc2e0f

Browse files
author
Mattia Moretti
authored
Include documentation for datasource.yaml based configuration (#275)
* early stage * tabolar * beta
1 parent ea12110 commit ccc2e0f

File tree

4 files changed

+368
-1
lines changed

4 files changed

+368
-1
lines changed

‎docs/datasource_configuration.md‎

Lines changed: 352 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,352 @@
1+
2+
# Configure Grafana using datasource.yaml
3+
4+
You can manage data sources in Grafana by adding YAML configuration files in the provisioning/datasources directory. Each config file can contain a list of datasources to add or update during startup. If the data source already exists, Grafana reconfigures it to match the provisioned configuration file.
5+
6+
The configuration file can also list data sources to automatically delete, called deleteDatasources. Grafana deletes the data sources listed in deleteDatasources before adding or updating those in the datasources list.
7+
8+
For more details how datasource configuration works, you may refer to the official Grafana documentation [here](https://grafana.com/docs/grafana/latest/administration/provisioning/).
9+
10+
## Configure Grafana using datasource.yaml for Instance Principals
11+
12+
Following parameters must be set:
13+
14+
* *jsonData*
15+
+ **profile0**: A string that specifies the profile name. This field has a default value of 'DEFAULT', which is also the only allowed value.
16+
+ **environment**: A string that specifies the environment type, either 'local' or 'OCI Instance'. Use 'OCI Instance' for instance principals.
17+
18+
Note: The DEFAULT value for profile0 is mandatory, as it is the only allowed value.
19+
20+
Here is the representation of the required JSON data in a tabular format:
21+
22+
**jsonData**
23+
24+
| **Section** | **Element** | **Description** |
25+
| --- | --- | --- |
26+
| jsonData | profile0 | Profile name, **must** be set to 'DEFAULT' for single instance and user principal. |
27+
| jsonData | environment | Environment in which the application will run, set to 'OCI Instance'. |
28+
29+
### Configuration example for Instance Principal
30+
31+
```
32+
# Configuration file version
33+
apiVersion: 1
34+
35+
# List of data sources to delete from the database.
36+
deleteDatasources:
37+
- name: InstancePrincipal
38+
orgId: 1
39+
40+
# List of data sources to insert/update depending on what's
41+
# available in the database.
42+
datasources:
43+
# <string, required> Sets the name you use to refer to
44+
# the data source in panels and queries.
45+
- name: InstancePrincipal
46+
# <string, required> Sets the data source type.
47+
type: oci-metrics-datasource
48+
# <string, required> Sets the access mode, either
49+
# proxy or direct (Server or Browser in the UI).
50+
# Some data sources are incompatible with any setting
51+
# but proxy (Server).
52+
access: proxy
53+
# <int> Sets the organization id. Defaults to orgId 1.
54+
orgId: 1
55+
# <string> Sets a custom UID to reference this
56+
# data source in other parts of the configuration.
57+
# If not specified, Grafana generates one.
58+
# uid: my_unique_uid
59+
# <string> Sets the database user, if necessary.
60+
user:
61+
# <string> Sets the database name, if necessary.
62+
database:
63+
# <bool> Enables basic authorization.multitenancy
64+
basicAuth:
65+
# <string> Sets the basic authorization username.
66+
basicAuthUser:
67+
# <bool> Enables credential headers.
68+
withCredentials:
69+
# <bool> Toggles whether the data source is pre-selected
70+
# for new panels. You can set only one default
71+
# data source per organization.
72+
isDefault:
73+
# <map> Fields to convert to JSON and store in jsonData.
74+
jsonData:
75+
# profile name (use DEFAULT for single instance and user principal)
76+
profile0: 'DEFAULT'
77+
# environment: use local or OCI Instance
78+
environment: 'OCI Instance'
79+
# <map> Fields to encrypt before storing in jsonData.
80+
secureJsonData:
81+
# <int> Sets the version. Used to compare versions when
82+
# updating. Ignored when creating a new data source.
83+
version: 1
84+
# <bool> Allows users to edit data sources from the
85+
# Grafana UI.
86+
editable: false
87+
```
88+
89+
90+
91+
## Configure Grafana using datasource.yaml for User Principals in Single tenancy mode
92+
93+
Following parameters must be set:
94+
95+
**jsonData**
96+
97+
* **profile0**: The profile name, it must be set to 'DEFAULT'.
98+
* **environment**: The environment in which the application will run, use 'local' for User Principals in single tenancy mode.
99+
* **tenancymode**: The tenancy mode, which can be either 'single' (for single-tenant) or 'multi' (for multi-tenant). For User Principals in single tenancy mode use 'single'.
100+
* **region0**: The region code.
101+
102+
**secureJsonData**
103+
104+
This section contains sensitive data that should be encrypted before being stored in the JSON file. It includes:
105+
106+
* **user0**: user OCID.
107+
* **tenancy0**: tenancy OCID.
108+
* **fingerprint0**: Fingerprint value, hash of the API PEM key.
109+
* **privkey0**: API PEM key. The key is formatted as a multi-line string.
110+
111+
Here is the representation of the required JSON data in a tabular format:
112+
113+
| **Section** | **Element** | **Description** |
114+
| --- | --- | --- |
115+
| jsonData | environment | The environment in which the application will run, either 'local' or an OCI Instance. |
116+
| jsonData | tenancymode | The tenancy mode, set to 'singl', indicating that the datasource is configured in signel tenancy mode. |
117+
| jsonData | profile0 | Profile name for the first tenancy, **must** be always set to 'DEFAULT'. |
118+
| jsonData | region0 | Region code for the first tenancy. |
119+
120+
121+
| **Section** | **Element** | **Description** |
122+
| --- | --- | --- |
123+
| secureJsonData | user0 | User ID for the first tenancy. |
124+
| secureJsonData | tenancy0 | Tenancy ID for the first tenancy. |
125+
| secureJsonData | fingerprint0 | Fingerprint value for the first tenancy. |
126+
| secureJsonData | privkey0 | Private key for the first tenancy. |
127+
128+
### Configuration example for User Principal in SIngle Tenancy mode
129+
130+
```
131+
# Configuration file version
132+
apiVersion: 1
133+
134+
# List of data sources to delete from the database.
135+
deleteDatasources:
136+
- name: Single
137+
orgId: 1
138+
139+
# List of data sources to insert/update depending on what's
140+
# available in the database.
141+
datasources:
142+
# <string, required> Sets the name you use to refer to
143+
# the data source in panels and queries.
144+
- name: Single
145+
# <string, required> Sets the data source type.
146+
type: oci-metrics-datasource
147+
# <string, required> Sets the access mode, either
148+
# proxy or direct (Server or Browser in the UI).
149+
# Some data sources are incompatible with any setting
150+
# but proxy (Server).
151+
access: proxy
152+
# <int> Sets the organization id. Defaults to orgId 1.
153+
orgId: 1
154+
# <string> Sets a custom UID to reference this
155+
# data source in other parts of the configuration.
156+
# If not specified, Grafana generates one.
157+
# uid: my_unique_uid
158+
# <string> Sets the database user, if necessary.
159+
user:
160+
# <string> Sets the database name, if necessary.
161+
database:
162+
# <bool> Enables basic authorization.multitenancy
163+
basicAuth:
164+
# <string> Sets the basic authorization username.
165+
basicAuthUser:
166+
# <bool> Enables credential headers.
167+
withCredentials:
168+
# <bool> Toggles whether the data source is pre-selected
169+
# for new panels. You can set only one default
170+
# data source per organization.
171+
isDefault:
172+
# <map> Fields to convert to JSON and store in jsonData.
173+
jsonData:
174+
# profile name (use DEFAULT for single instance and user principal, always DEFAULT for first tenancy in multi tenancy mode)
175+
profile0: 'DEFAULT'
176+
# environment: use local or OCI Instance
177+
environment: 'local'
178+
# use single or multitenancy
179+
tenancymode: 'single'
180+
# region code
181+
region0: 'eu-zurich-1'
182+
# <map> Fields to encrypt before storing in jsonData.
183+
secureJsonData:
184+
user0: 'ocid1.user.oc1..xxx'
185+
tenancy0: 'ocid1.tenancy.oc1..xxx'
186+
fingerprint0: 'XXX:XXX'
187+
privkey0: |
188+
-----BEGIN PRIVATE KEY-----
189+
MIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQDiwW4Pkz20vFPr
190+
...
191+
-----END PRIVATE KEY-----
192+
# <string> Sets the database password, if necessary.
193+
password:
194+
# <string> Sets the basic authorization password.
195+
basicAuthPassword:
196+
# <int> Sets the version. Used to compare versions when
197+
# updating. Ignored when creating a new data source.
198+
version: 1
199+
# <bool> Allows users to edit data sources from the
200+
# Grafana UI.
201+
editable: false
202+
203+
```
204+
205+
206+
## Configure Grafana using datasource.yaml for User Principals in Multi tenancy mode
207+
208+
Following parameters must be set:
209+
210+
* *jsonData*
211+
+ **environment*: The environment in which the application will run, which can be either 'local' (for local development) or an OCI Instance.
212+
+ **tenancymode*: The tenancy mode, which is set to 'multitenancy', indicating that the application supports multiple tenants.
213+
+ *profile0* and *region0*: These are the profile name and region code for the first tenancy. PRofile name for first tenancy **must** be set to 'DEFAULT'
214+
+ *profile1* and *region1*: These are the profile name and region code for the second tenancy.
215+
+ *profile2*, *region2*, *profile3*, *region3*, *profile4*, and *region4*: These are the profile names and region codes for the third to fifth tenancies.
216+
217+
* *secureJsonData*
218+
This section contains sensitive data that should be encrypted before being stored in the JSON file. It includes:
219+
220+
+ *user0*, *tenancy0*, *fingerprint0*, and *privkey0*: These are the user ID, tenancy ID, fingerprint value, and private key for the first tenancy.
221+
+ *user1*, *tenancy1*, *fingerprint1*, and *privkey1*: These are the user ID, tenancy ID, fingerprint value, and private key for the second tenancy.
222+
+ *user2*, *tenancy2*, *fingerprint2*, and *privkey2*: These are the user ID, tenancy ID, fingerprint value, and private key for the third tenancy.
223+
+ *user3*, *tenancy3*, *fingerprint3*, and *privkey3*: These are the user ID, tenancy ID, fingerprint value, and private key for the fourth tenancy.
224+
+ *user4*, *tenancy4*, *fingerprint4*, and *privkey4*: These are the user ID, tenancy ID, fingerprint value, and private key for the fifth tenancy.
225+
+ *user5*, *tenancy5*, *fingerprint5*, and *privkey5*: These are the user ID, tenancy ID, fingerprint value, and private key for the sixth tenancy.
226+
227+
Here is the representation of the required JSON data in a tabular format:
228+
229+
| **Section** | **Element** | **Description** |
230+
| --- | --- | --- |
231+
| jsonData | environment | The environment in which the application will run, either 'local' or an OCI Instance. use "local" for multitenancy configuration|
232+
| jsonData | tenancymode | The tenancy mode, set to 'multitenancy', indicating that the application supports multiple tenants. |
233+
| jsonData | profile0 | Profile name for the first tenancy, always set to 'DEFAULT'. |
234+
| jsonData | region0 | Region code for the first tenancy |
235+
| jsonData | profile1 | Profile name for the second tenancy. |
236+
| jsonData | region1 | Region code for the second tenancy. |
237+
| ... | ... | ... |
238+
| jsonData | profile5 | Profile name for the sixth tenancy. |
239+
| jsonData | region5 | Region code for the sixth tenancy. |
240+
241+
| **Section** | **Element** | **Description** |
242+
| --- | --- | --- |
243+
| secureJsonData | user0 | User ID for the first tenancy. |
244+
| secureJsonData | tenancy0 | Tenancy ID for the first tenancy. |
245+
| secureJsonData | fingerprint0 | Fingerprint value for the first tenancy. |
246+
| secureJsonData | privkey0 | Private key for the first tenancy. |
247+
| secureJsonData | user1 | User ID for the second tenancy. |
248+
| secureJsonData | tenancy1 | Tenancy ID for the second tenancy. |
249+
| secureJsonData | fingerprint1 | Fingerprint value for the second tenancy. |
250+
| secureJsonData | privkey1 | Private key for the second tenancy. |
251+
| ... | ... | ... |
252+
| secureJsonData | user5 | User ID for the sixth tenancy. |
253+
| secureJsonData | tenancy5 | Tenancy ID for the sixth tenancy. |
254+
| secureJsonData | fingerprint5 | Fingerprint value for the sixth tenancy. |
255+
| secureJsonData | privkey5 | Private key for the sixth tenancy. |
256+
257+
### Configuration example for User Principal in SIngle Tenancy mode
258+
259+
```
260+
# Configuration file version
261+
apiVersion: 1
262+
263+
# List of data sources to delete from the database.
264+
deleteDatasources:
265+
- name: Multi
266+
orgId: 1
267+
268+
# List of data sources to insert/update depending on what's
269+
# available in the database.
270+
datasources:
271+
# <string, required> Sets the name you use to refer to
272+
# the data source in panels and queries.
273+
- name: Multi
274+
# <string, required> Sets the data source type.
275+
type: oci-metrics-datasource
276+
# <string, required> Sets the access mode, either
277+
# proxy or direct (Server or Browser in the UI).
278+
# Some data sources are incompatible with any setting
279+
# but proxy (Server).
280+
access: proxy
281+
# <int> Sets the organization id. Defaults to orgId 1.
282+
orgId: 1
283+
# <string> Sets a custom UID to reference this
284+
# data source in other parts of the configuration.
285+
# If not specified, Grafana generates one.
286+
# uid: my_unique_uid
287+
# <string> Sets the database user, if necessary.
288+
user:
289+
# <string> Sets the database name, if necessary.
290+
database:
291+
# <bool> Enables basic authorization.multitenancy
292+
basicAuth:
293+
# <string> Sets the basic authorization username.
294+
basicAuthUser:
295+
# <bool> Enables credential headers.
296+
withCredentials:
297+
# <bool> Toggles whether the data source is pre-selected
298+
# for new panels. You can set only one default
299+
# data source per organization.
300+
isDefault:
301+
# <map> Fields to convert to JSON and store in jsonData.
302+
jsonData:
303+
# environment: use local or OCI Instance
304+
environment: 'local'
305+
# use single or multitenancy
306+
tenancymode: 'multitenancy'
307+
# profile name for first tenancy, set always to DEFAULT
308+
profile0: 'DEFAULT'
309+
# region code for first tenancy
310+
region0: 'eu-zurich-1'
311+
# profile name for second tenancy
312+
profile1: 'SWEDEN'
313+
# region code for second tenancy
314+
region1: 'eu-stockholm-1'
315+
# <map> Fields to encrypt before storing in jsonData.
316+
secureJsonData:
317+
# user OCID
318+
user0: 'ocid1.user.oc1..xxx'
319+
# tenancy OCID
320+
tenancy0: 'ocid1.tenancy.oc1..xxx'
321+
# fingerprint of the api key
322+
fingerprint0: 'xxxx:xxxxxxxa'
323+
# api pem key
324+
privkey0: |
325+
-----BEGIN PRIVATE KEY-----
326+
MIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQDiwW4Pkz20vFPr
327+
...
328+
-----END PRIVATE KEY-----
329+
# user OCID for second tenancy
330+
user1: 'ocid1.user.oc1..xxx'
331+
# tenancy ocid for second tenancy
332+
tenancy1: 'ocid1.tenancy.oc1..xxx'
333+
# fingerprint of the api key for second tenancy
334+
fingerprint1: 'xxx:xxxxxxx'
335+
# api pem key for second tenancy
336+
privkey1: |
337+
-----BEGIN PRIVATE KEY-----
338+
MIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQDiwW4Pkz20vFPr
339+
...
340+
-----END PRIVATE KEY-----
341+
# <string> Sets the database password, if necessary.
342+
password:
343+
# <string> Sets the basic authorization password.
344+
basicAuthPassword:
345+
# <int> Sets the version. Used to compare versions when
346+
# updating. Ignored when creating a new data source.
347+
version: 1
348+
# <bool> Allows users to edit data sources from the
349+
# Grafana UI.
350+
editable: false
351+
352+
```

‎docs/linux.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,11 @@ Navigate to the Grafana homepage at http://localhost:3000.
116116

117117
## Configure Grafana
118118

119+
You can use a manual configuration or a programatic configuration.
120+
In case you want to use the datasource.yaml based plugin configuration you can refers to this document: [Data source configuration using yaml file](https://github.com/oracle/oci-grafana-plugin/blob/master/docs/datasource_configuration.md)
121+
122+
For Manual installation use the following steps:
123+
119124
![Screen Shot 2018-12-17 at 3.23.46 PM](images/Screen%20Shot%202018-12-17%20at%203.23.46%20PM.png)
120125

121126
Log in with the default username `admin` and the password `admin`. You will be prompted to change your password. Click **Skip** or **Save** to continue.

‎docs/linuxoci.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,12 @@ Navigate to the Grafana homepage at http://localhost:3000.
5252

5353
## Configure Grafana
5454

55-
The next step is to configure the plugin. To find the IP address of the newly-created instance, navigate to Compute > Instances > [Your Instance]. The Public IP address is listed under the Primary VNIC Information section. Connect to Grafana via port forward by running `ssh opc@[Instance Public IP] -L 3000:localhost:3000`.
55+
The next step is to configure the plugin.
56+
57+
You can use a manual configuration or a programatic configuration.
58+
In case you want to use the datasource.yaml based plugin configuration you can refers to this document: [Data source configuration using yaml file](https://github.com/oracle/oci-grafana-plugin/blob/master/docs/datasource_configuration.md)
59+
60+
To find the IP address of the newly-created instance, navigate to Compute > Instances > [Your Instance]. The Public IP address is listed under the Primary VNIC Information section. Connect to Grafana via port forward by running `ssh opc@[Instance Public IP] -L 3000:localhost:3000`.
5661

5762
Navigate to the Grafana homepage at http://localhost:3000.
5863

‎docs/macos.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -117,6 +117,11 @@ Navigate to the Grafana homepage at http://localhost:3000.
117117

118118
## Configure Grafana
119119

120+
You can use a manual configuration or a programatic configuration.
121+
In case you want to use the datasource.yaml based plugin configuration you can refers to this document: [Data source configuration using yaml file](https://github.com/oracle/oci-grafana-plugin/blob/master/docs/datasource_configuration.md)
122+
123+
For Manual installation use the following steps:
124+
120125
![Screen Shot 2018-12-17 at 3.23.46 PM](images/Screen%20Shot%202018-12-17%20at%203.23.46%20PM.png)
121126

122127
Log in with the default username `admin` and the password `admin`. You will be prompted to change your password. Click **Skip** or **Save** to continue.

0 commit comments

Comments
 (0)