Skip to content

Commit f09627f

Browse files
author
Mattia Moretti
authored
api use doc (#282)
* api use doc * docs for api * cleaning
1 parent 374d608 commit f09627f

File tree

1 file changed

+177
-5
lines changed

1 file changed

+177
-5
lines changed

‎docs/datasource_configuration.md‎

Lines changed: 177 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -86,8 +86,6 @@ datasources:
8686
editable: false
8787
```
8888

89-
90-
9189
## Configure Grafana using datasource.yaml for User Principals in Single tenancy mode
9290

9391
Following parameters must be set:
@@ -125,7 +123,7 @@ Here is the representation of the required JSON data in a tabular format:
125123
| secureJsonData | fingerprint0 | Fingerprint value for the first tenancy. |
126124
| secureJsonData | privkey0 | Private key for the first tenancy. |
127125

128-
### Configuration example for User Principal in SIngle Tenancy mode
126+
### Configuration example for User Principal in Single Tenancy mode
129127

130128
```
131129
# Configuration file version
@@ -210,7 +208,7 @@ Following parameters must be set:
210208
* *jsonData*
211209
+ **environment*: The environment in which the application will run, which can be either 'local' (for local development) or an OCI Instance.
212210
+ **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'
211+
+ *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'
214212
+ *profile1* and *region1*: These are the profile name and region code for the second tenancy.
215213
+ *profile2*, *region2*, *profile3*, *region3*, *profile4*, and *region4*: These are the profile names and region codes for the third to fifth tenancies.
216214

@@ -254,7 +252,7 @@ Here is the representation of the required JSON data in a tabular format:
254252
| secureJsonData | fingerprint5 | Fingerprint value for the sixth tenancy. |
255253
| secureJsonData | privkey5 | Private key for the sixth tenancy. |
256254

257-
### Configuration example for User Principal in SIngle Tenancy mode
255+
### Configuration example for User Principal in Multi Tenancy mode
258256

259257
```
260258
# Configuration file version
@@ -349,4 +347,178 @@ datasources:
349347
# Grafana UI.
350348
editable: false
351349
350+
```
351+
352+
# Configuring OCI Metrics Plugin Datasource using Grafana API
353+
354+
## Introduction
355+
356+
Configuring datasources in Grafana can be automated using the Grafana HTTP API. This approach allows for programmatic setup and management of datasources, which is particularly useful for large-scale deployments or when integrating Grafana into other systems.
357+
358+
To configure the OCI Metrics plugin datasource, you'll need to send a POST request to the Grafana API endpoint `/api/datasources`. The configuration details are sent in the request body as JSON. The specific parameters will vary depending on the authentication mode you're using: Single Tenancy, Multi-tenancy, or Instance Principal.
359+
360+
Before proceeding, ensure you have:
361+
362+
1. Grafana installed and running
363+
2. Admin API key for authentication
364+
3. OCI Metrics plugin installed in Grafana
365+
366+
Let's explore how to configure the OCI Metrics plugin datasource for each authentication mode.
367+
368+
## Configure Grafana using Grafana API for User Principals in Single tenancy mode
369+
370+
Following parameters must be set:
371+
372+
**jsonData**
373+
374+
* **profile0**: The profile name, it must be set to 'DEFAULT'.
375+
* **environment**: The environment in which the application will run, use 'local' for User Principals in single tenancy mode.
376+
* **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'.
377+
* **region0**: The region code.
378+
379+
**secureJsonData**
380+
381+
This section contains sensitive data that should be encrypted before being stored in the JSON file. It includes:
382+
383+
* **user0**: user OCID.
384+
* **tenancy0**: tenancy OCID.
385+
* **fingerprint0**: Fingerprint value, hash of the API PEM key.
386+
* **privkey0**: API PEM key. The key is formatted as a multi-line string.
387+
388+
### Payload example for User Principals in Single tenancy mode
389+
390+
```
391+
{
392+
"name": "api injected",
393+
"type": "oci-metrics-datasource",
394+
"editable": true,
395+
"access": "proxy",
396+
"jsonData": {
397+
"profile0": "DEFAULT",
398+
"environment": "local",
399+
"tenancymode": "single",
400+
"region0": "eu-zurich-1"
401+
},
402+
"secureJsonData": {
403+
"user0": "ocid1.user.oc1..XXXXXXX",
404+
"tenancy0": "ocid1.tenancy.oc1..XXXXXXXX",
405+
"fingerprint0": "62:d3:XXXXXXXXXXXX",
406+
"privkey0": "-----BEGIN PRIVATE KEY-----\nMIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIXXXXXX=\n-----END PRIVATE KEY-----"
407+
}
408+
}
409+
```
410+
411+
412+
## Configure Grafana using Grafana API for User Principals in Multi tenancy mode
413+
414+
Following parameters must be set:
415+
416+
* *jsonData*
417+
+ **environment*: The environment in which the application will run, which can be either 'local' (for local development) or an OCI Instance.
418+
+ **tenancymode*: The tenancy mode, which is set to 'multitenancy', indicating that the application supports multiple tenants.
419+
+ *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'
420+
+ *profile1* and *region1*: These are the profile name and region code for the second tenancy.
421+
+ *profile2*, *region2*, *profile3*, *region3*, *profile4*, and *region4*: These are the profile names and region codes for the third to fifth tenancies.
422+
423+
* *secureJsonData*
424+
This section contains sensitive data that should be encrypted before being stored in the JSON file. It includes:
425+
426+
+ *user0*, *tenancy0*, *fingerprint0*, and *privkey0*: These are the user ID, tenancy ID, fingerprint value, and private key for the first tenancy.
427+
+ *user1*, *tenancy1*, *fingerprint1*, and *privkey1*: These are the user ID, tenancy ID, fingerprint value, and private key for the second tenancy.
428+
+ *user2*, *tenancy2*, *fingerprint2*, and *privkey2*: These are the user ID, tenancy ID, fingerprint value, and private key for the third tenancy.
429+
+ *user3*, *tenancy3*, *fingerprint3*, and *privkey3*: These are the user ID, tenancy ID, fingerprint value, and private key for the fourth tenancy.
430+
+ *user4*, *tenancy4*, *fingerprint4*, and *privkey4*: These are the user ID, tenancy ID, fingerprint value, and private key for the fifth tenancy.
431+
+ *user5*, *tenancy5*, *fingerprint5*, and *privkey5*: These are the user ID, tenancy ID, fingerprint value, and private key for the sixth tenancy.
432+
433+
### Payload example for User Principals in Multi tenancy mode
434+
435+
```
436+
{
437+
"name": "api injected MULTI",
438+
"type": "oci-metrics-datasource",
439+
"editable": true,
440+
"access": "proxy",
441+
"jsonData": {
442+
"profile0": "DEFAULT",
443+
"environment": "local",
444+
"tenancymode": "multitenancy",
445+
"region0": "eu-zurich-1",
446+
"profile1": "SWEDEN",
447+
"region1": "eu-stockholm-1"
448+
},
449+
"secureJsonData": {
450+
"user0": "ocid1.user.oc1..XXXXXX",
451+
"tenancy0": "ocid1.tenancy.oc1..XXXXXXXX",
452+
"fingerprint0": "62:d3:XXXXXXXXXXXX",
453+
"privkey0": "-----BEGIN PRIVATE KEY-----\nMIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIXXXXXX=\n-----END PRIVATE KEY-----",
454+
"user1": "ocid1.user.oc1..aaaaaaaahsmfbxrirfsimdrdyouyuya26jvv5226hikv3gu3qbng63kwbmha",
455+
"tenancy1": "ocid1.tenancy.oc1..XXXXXXX",
456+
"fingerprint1": "62:d3:XXXXXXXXXXXX",
457+
"privkey1": "-----BEGIN PRIVATE KEY-----\nMIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIXXXXXX=\n-----END PRIVATE KEY-----"
458+
}
459+
}
460+
```
461+
462+
| **Section** | **Element** | **Description** |
463+
| --- | --- | --- |
464+
| jsonData | environment | The environment in which the application will run, either 'local' or an OCI Instance. use "local" for multitenancy configuration|
465+
| jsonData | tenancymode | The tenancy mode, set to 'multitenancy', indicating that the application supports multiple tenants. |
466+
| jsonData | profile0 | Profile name for the first tenancy, always set to 'DEFAULT'. |
467+
| jsonData | region0 | Region code for the first tenancy |
468+
| jsonData | profile1 | Profile name for the second tenancy. |
469+
| jsonData | region1 | Region code for the second tenancy. |
470+
| ... | ... | ... |
471+
| jsonData | profile5 | Profile name for the sixth tenancy. |
472+
| jsonData | region5 | Region code for the sixth tenancy. |
473+
474+
| **Section** | **Element** | **Description** |
475+
| --- | --- | --- |
476+
| secureJsonData | user0 | User ID for the first tenancy. |
477+
| secureJsonData | tenancy0 | Tenancy ID for the first tenancy. |
478+
| secureJsonData | fingerprint0 | Fingerprint value for the first tenancy. |
479+
| secureJsonData | privkey0 | Private key for the first tenancy. |
480+
| secureJsonData | user1 | User ID for the second tenancy. |
481+
| secureJsonData | tenancy1 | Tenancy ID for the second tenancy. |
482+
| secureJsonData | fingerprint1 | Fingerprint value for the second tenancy. |
483+
| secureJsonData | privkey1 | Private key for the second tenancy. |
484+
| ... | ... | ... |
485+
| secureJsonData | user5 | User ID for the sixth tenancy. |
486+
| secureJsonData | tenancy5 | Tenancy ID for the sixth tenancy. |
487+
| secureJsonData | fingerprint5 | Fingerprint value for the sixth tenancy. |
488+
| secureJsonData | privkey5 | Private key for the sixth tenancy. |
489+
490+
Here is the representation of the required JSON data in a tabular format:
491+
492+
## Configure Grafana using Grafana API for Instance Principals
493+
494+
Following parameters must be set:
495+
496+
* *jsonData*
497+
+ **profile0**: A string that specifies the profile name. This field has a default value of 'DEFAULT', which is also the only allowed value.
498+
+ **environment**: A string that specifies the environment type, either 'local' or 'OCI Instance'. Use 'OCI Instance' for instance principals.
499+
500+
Note: The DEFAULT value for profile0 is mandatory, as it is the only allowed value.
501+
502+
Here is the representation of the required JSON data in a tabular format:
503+
504+
**jsonData**
505+
506+
| **Section** | **Element** | **Description** |
507+
| --- | --- | --- |
508+
| jsonData | profile0 | Profile name, **must** be set to 'DEFAULT' for single instance and user principal. |
509+
| jsonData | environment | Environment in which the application will run, set to 'OCI Instance'. |
510+
511+
### Payload example for Instance Principal
512+
513+
```
514+
{
515+
"name": "api injected INSTANCE",
516+
"type": "oci-metrics-datasource",
517+
"editable": true,
518+
"access": "proxy",
519+
"jsonData": {
520+
"profile0": "DEFAULT",
521+
"environment": "OCI Instance"
522+
}
523+
}
352524
```

0 commit comments

Comments
 (0)