vnfs/DAaaS/deploy/visualization/charts/grafana/README.md

   1 # Grafana Helm Chart
   2
   3 * Installs the web dashboarding system [Grafana](http://grafana.org/)
   4
   5 ## TL;DR;
   6
   7 ```console
   8 $ helm install stable/grafana
   9 ```
  10
  11 ## Installing the Chart
  12
  13 To install the chart with the release name `my-release`:
  14
  15 ```console
  16 $ helm install --name my-release stable/grafana
  17 ```
  18
  19 ## Uninstalling the Chart
  20
  21 To uninstall/delete the my-release deployment:
  22
  23 ```console
  24 $ helm delete my-release
  25 ```
  26
  27 The command removes all the Kubernetes components associated with the chart and deletes the release.
  28
  29
  30 ## Configuration
  31
  32 | Parameter                                 | Description                                   | Default                                                 |
  33 |-------------------------------------------|-----------------------------------------------|---------------------------------------------------------|
  34 | `replicas`                                | Number of nodes                               | `1`                                                     |
  35 | `deploymentStrategy`                      | Deployment strategy                           | `RollingUpdate`                                         |
  36 | `livenessProbe`                           | Liveness Probe settings                       | `{ "httpGet": { "path": "/api/health", "port": 3000 } "initialDelaySeconds": 60, "timeoutSeconds": 30, "failureThreshold": 10 }` |
  37 | `readinessProbe`                          | Rediness Probe settings                       | `{ "httpGet": { "path": "/api/health", "port": 3000 } }`|
  38 | `securityContext`                         | Deployment securityContext                    | `{"runAsUser": 472, "fsGroup": 472}`                    |
  39 | `priorityClassName`                       | Name of Priority Class to assign pods         | `nil`                                                   |
  40 | `image.repository`                        | Image repository                              | `grafana/grafana`                                       |
  41 | `image.tag`                               | Image tag. (`Must be >= 5.0.0`)               | `6.0.2`                                                 |
  42 | `image.pullPolicy`                        | Image pull policy                             | `IfNotPresent`                                          |
  43 | `service.type`                            | Kubernetes service type                       | `ClusterIP`                                             |
  44 | `service.port`                            | Kubernetes port where service is exposed      | `80`                                                    |
  45 | `service.targetPort`                      | internal service is port                      | `3000`                                                  |
  46 | `service.annotations`                     | Service annotations                           | `{}`                                                    |
  47 | `service.labels`                          | Custom labels                                 | `{}`                                                    |
  48 | `ingress.enabled`                         | Enables Ingress                               | `false`                                                 |
  49 | `ingress.annotations`                     | Ingress annotations                           | `{}`                                                    |
  50 | `ingress.labels`                          | Custom labels                                 | `{}`                                                    |
  51 | `ingress.hosts`                           | Ingress accepted hostnames                    | `[]`                                                    |
  52 | `ingress.tls`                             | Ingress TLS configuration                     | `[]`                                                    |
  53 | `resources`                               | CPU/Memory resource requests/limits           | `{}`                                                    |
  54 | `nodeSelector`                            | Node labels for pod assignment                | `{}`                                                    |
  55 | `tolerations`                             | Toleration labels for pod assignment          | `[]`                                                    |
  56 | `affinity`                                | Affinity settings for pod assignment          | `{}`                                                    |
  57 | `extraInitContainers`                     | Init containers to add to the grafana pod     | `{}` |
  58 | `extraContainers`                         | Sidecar containers to add to the grafana pod  | `{}` |
  59 | `persistence.enabled`                     | Use persistent volume to store data           | `false`                                                 |
  60 | `persistence.initChownData`               | Change ownership of persistent volume on initialization | `true`                                                  |
  61 | `persistence.size`                        | Size of persistent volume claim               | `10Gi`                                                  |
  62 | `persistence.existingClaim`               | Use an existing PVC to persist data           | `nil`                                                   |
  63 | `persistence.storageClassName`            | Type of persistent volume claim               | `nil`                                                   |
  64 | `persistence.accessModes`                 | Persistence access modes                      | `[ReadWriteOnce]`                                       |
  65 | `persistence.subPath`                     | Mount a sub dir of the persistent volume      | `nil`                                                   |
  66 | `schedulerName`                           | Alternate scheduler name                      | `nil`                                                   |
  67 | `env`                                     | Extra environment variables passed to pods    | `{}`                                                    |
  68 | `envFromSecret`                           | Name of a Kubenretes secret (must be manually created in the same namespace) containing values to be added to the environment | `""` |
  69 | `extraSecretMounts`                       | Additional grafana server secret mounts       | `[]`                                                    |
  70 | `extraVolumeMounts`                       | Additional grafana server volume mounts       | `[]`                                                    |
  71 | `extraConfigmapMounts`                    | Additional grafana server configMap volume mounts  | `[]`                                               |
  72 | `extraEmptyDirMounts`                     | Additional grafana server emptyDir volume mounts   | `[]`                                               |
  73 | `plugins`                                 | Plugins to be loaded along with Grafana       | `[]`                                                    |
  74 | `datasources`                             | Configure grafana datasources (passed through tpl) | `{}`                                                    |
  75 | `notifiers`                               | Configure grafana notifiers | `{}`                                                                      |
  76 | `dashboardProviders`                      | Configure grafana dashboard providers         | `{}`                                                    |
  77 | `dashboards`                              | Dashboards to import                          | `{}`                                                    |
  78 | `dashboardsConfigMaps`                    | ConfigMaps reference that contains dashboards | `{}`                                                    |
  79 | `grafana.ini`                             | Grafana's primary configuration               | `{}`                                                    |
  80 | `ldap.existingSecret`                     | The name of an existing secret containing the `ldap.toml` file, this must have the key `ldap-toml`. | `""` |
  81 | `ldap.config  `                           | Grafana's LDAP configuration                  | `""`                                                    |
  82 | `annotations`                             | Deployment annotations                        | `{}`                                                    |
  83 | `podAnnotations`                          | Pod annotations                               | `{}`                                                    |
  84 | `sidecar.image`              | Sidecar image | `kiwigrid/k8s-sidecar:0.0.13`       |
  85 | `sidecar.imagePullPolicy`              | Sidecar image pull policy | `IfNotPresent`       |
  86 | `sidecar.resources`              | Sidecar resources | `{}`       |
  87 | `sidecar.dashboards.enabled`              | Enabled the cluster wide search for dashboards and adds/updates/deletes them in grafana | `false`       |
  88 | `sidecar.dashboards.label`                | Label that config maps with dashboards should have to be added | `grafana_dashboard`                                |
  89 | `sidecar.dashboards.searchNamespace`      | If specified, the sidecar will search for dashboard config-maps inside this namespace. Otherwise the namespace in which the sidecar is running will be used. It's also possible to specify ALL to search in all namespaces | `nil`                                |
  90 | `sidecar.datasources.enabled`             | Enabled the cluster wide search for datasources and adds/updates/deletes them in grafana |`false`       |
  91 | `sidecar.datasources.label`               | Label that config maps with datasources should have to be added | `grafana_datasource`                               |
  92 | `sidecar.datasources.searchNamespace`     | If specified, the sidecar will search for datasources config-maps inside this namespace. Otherwise the namespace in which the sidecar is running will be used. It's also possible to specify ALL to search in all namespaces | `nil`                               |
  93 | `smtp.existingSecret`                     | The name of an existing secret containing the SMTP credentials. | `""`                                  |
  94 | `smtp.userKey`                            | The key in the existing SMTP secret containing the username. | `"user"`                                 |
  95 | `smtp.passwordKey`                        | The key in the existing SMTP secret containing the password. | `"password"`                             |
  96 | `admin.existingSecret`                    | The name of an existing secret containing the admin credentials. | `""`                                 |
  97 | `admin.userKey`                           | The key in the existing admin secret containing the username. | `"admin-user"`                          |
  98 | `admin.passwordKey`                       | The key in the existing admin secret containing the password. | `"admin-password"`                      |
  99 | `rbac.create`                             | Create and use RBAC resources | `true` |
 100 | `rbac.namespaced`                         | Creates Role and Rolebinding instead of the default ClusterRole and ClusteRoleBindings for the grafana instance  | `false` |
 101 | `rbac.pspEnabled`                         | Create PodSecurityPolicy (with `rbac.create`, grant roles permissions as well) | `true` |
 102 | `rbac.pspUseAppArmor`                     | Enforce AppArmor in created PodSecurityPolicy (requires `rbac.pspEnabled`)  | `true` |
 103 | `command`                     | Define command to be executed by grafana container at startup  | `nil` |
 104
 105 ### Example of extraVolumeMounts
 106
 107 ```yaml
 108 - extraVolumeMounts:
 109   - name: plugins
 110     mountPath: /var/lib/grafana/plugins
 111     subPath: configs/grafana/plugins
 112     existingClaim: existing-grafana-claim
 113     readOnly: false
 114 ```
 115
 116 ## Import dashboards
 117
 118 There are a few methods to import dashboards to Grafana. Below are some examples and explanations as to how to use each method:
 119
 120 ```yaml
 121 dashboards:
 122   default:
 123     some-dashboard:
 124       json: |
 125         {
 126           "annotations":
 127
 128           ...
 129           # Complete json file here
 130           ...
 131
 132           "title": "Some Dashboard",
 133           "uid": "abcd1234",
 134           "version": 1
 135         }
 136     custom-dashboard:
 137       # This is a path to a file inside the dashboards directory inside the chart directory
 138       file: dashboards/custom-dashboard.json
 139     prometheus-stats:
 140       # Ref: https://grafana.com/dashboards/2
 141       gnetId: 2
 142       revision: 2
 143       datasource: Prometheus
 144     local-dashboard:
 145       url: https://raw.githubusercontent.com/user/repository/master/dashboards/dashboard.json
 146 ```
 147
 148 ## BASE64 dashboards
 149
 150 Dashboards could be storaged in a server that does not return JSON directly and instead of it returns a Base64 encoded file (e.g. Gerrit)
 151 A new parameter has been added to the url use case so if you specify a b64content value equals to true after the url entry a Base64 decoding is applied before save the file to disk.
 152 If this entry is not set or is equals to false not decoding is applied to the file before saving it to disk.
 153
 154 ### Gerrit use case:
 155 Gerrit API for download files has the following schema: https://yourgerritserver/a/{project-name}/branches/{branch-id}/files/{file-id}/content where {project-name} and
 156 {file-id} usualy has '/' in their values and so they MUST be replaced by %2F so if project-name is user/repo, branch-id is master and file-id is equals to dir1/dir2/dashboard
 157 the url value is https://yourgerritserver/a/user%2Frepo/branches/master/files/dir1%2Fdir2%2Fdashboard/content
 158
 159 ## Sidecar for dashboards
 160
 161 If the parameter `sidecar.dashboards.enabled` is set, a sidecar container is deployed in the grafana pod. This container watches all config maps in the cluster and filters out the ones with a label as defined in `sidecar.dashboards.label`. The files defined in those configmaps are written to a folder and accessed by grafana. Changes to the configmaps are monitored and the imported dashboards are deleted/updated. A recommendation is to use one configmap per dashboard, as an reduction of multiple dashboards inside one configmap is currently not properly mirrored in grafana.
 162 Example dashboard config:
 163 ```
 164 apiVersion: v1
 165 kind: ConfigMap
 166 metadata:
 167   name: sample-grafana-dashboard
 168   labels:
 169      grafana_dashboard: 1
 170 data:
 171   k8s-dashboard.json: |-
 172   [...]
 173 ```
 174
 175 ## Sidecar for datasources
 176
 177 If the parameter `sidecar.datasources.enabled` is set, an init container is deployed in the grafana pod. This container lists all config maps in the cluster and filters out the ones with a label as defined in `sidecar.datasources.label`. The files defined in those configmaps are written to a folder and accessed by grafana on startup. Using these yaml files, the data sources in grafana can be imported. The configmaps must be created before `helm install` so that the datasources init container can list the configmaps.
 178
 179 Example datasource config adapted from [Grafana](http://docs.grafana.org/administration/provisioning/#example-datasource-config-file):
 180 ```
 181 apiVersion: v1
 182 kind: ConfigMap
 183 metadata:
 184   name: sample-grafana-datasource
 185   labels:
 186      grafana_datasource: 1
 187 data:
 188   datasource.yaml: |-
 189     # config file version
 190     apiVersion: 1
 191
 192     # list of datasources that should be deleted from the database
 193     deleteDatasources:
 194       - name: Graphite
 195         orgId: 1
 196
 197     # list of datasources to insert/update depending
 198     # whats available in the database
 199     datasources:
 200       # <string, required> name of the datasource. Required
 201     - name: Graphite
 202       # <string, required> datasource type. Required
 203       type: graphite
 204       # <string, required> access mode. proxy or direct (Server or Browser in the UI). Required
 205       access: proxy
 206       # <int> org id. will default to orgId 1 if not specified
 207       orgId: 1
 208       # <string> url
 209       url: http://localhost:8080
 210       # <string> database password, if used
 211       password:
 212       # <string> database user, if used
 213       user:
 214       # <string> database name, if used
 215       database:
 216       # <bool> enable/disable basic auth
 217       basicAuth:
 218       # <string> basic auth username
 219       basicAuthUser:
 220       # <string> basic auth password
 221       basicAuthPassword:
 222       # <bool> enable/disable with credentials headers
 223       withCredentials:
 224       # <bool> mark as default datasource. Max one per org
 225       isDefault:
 226       # <map> fields that will be converted to json and stored in json_data
 227       jsonData:
 228          graphiteVersion: "1.1"
 229          tlsAuth: true
 230          tlsAuthWithCACert: true
 231       # <string> json object of data that will be encrypted.
 232       secureJsonData:
 233         tlsCACert: "..."
 234         tlsClientCert: "..."
 235         tlsClientKey: "..."
 236       version: 1
 237       # <bool> allow users to edit datasources from the UI.
 238       editable: false
 239
 240 ```