Docs: Refactor administration docs (#50592)

* Move data source management to administration * Move RBAC to administration * Move team management up a docs org level * Combine and rename admin preferences docs * Move plugin management to administration * Combine plugin management docs * Combine API key docs * Combine service account docs * Combine server user management docs * Move datasource management to administration * Move enterprise licenses to administration * Move CLI out of admin, update links to admin * Merge org user management docs * Restructure to Torkel's plan * Fix typo * Weigh admin topics for navigation * Weigh administration topics and align to Torkel's plan * Move server user management from server admin to admin/user management * Move configure docker image to setup guide * Move the remaining server admin docs to the root admin directory * Reweight docker config
2022-06-16 21:09:16 +02:00
parent c043a8818a
commit 845cebdee2
105 changed files with 1602 additions and 1710 deletions
@@ -0,0 +1,104 @@
+---
+aliases:
+  - /docs/grafana/latest/administration/configure-docker/
+  - /docs/grafana/latest/installation/configure-docker/
+description: Guide for configuring the Grafana Docker image
+keywords:
+  - grafana
+  - configuration
+  - documentation
+  - docker
+title: Configure Docker image
+weight: 1800
+---
+
+# Configure a Grafana Docker image
+
+If you are running Grafana in a Docker image, then you configure Grafana using [environment variables]({{< relref "../../administration/setup-grafana/configure-grafana/#configure-with-environment-variables" >}}) rather than directly editing the configuration file. If you want to save your data, then you also need to designate persistent storage or bind mounts for the Grafana container.
+
+> **Note:** These examples use the Grafana Enterprise docker image. You can use the Grafana Open Source edition by changing the docker image to `grafana/grafana-oss`.
+
+## Save your Grafana data
+
+If you do not designate a location for information storage, then all your Grafana data disappears as soon as you stop your container. To save your data, you need to set up persistent storage or bind mounts for your container.
+
+### Run Grafana container with persistent storage (recommended)
+
+```bash
+# create a persistent volume for your data in /var/lib/grafana (database and plugins)
+docker volume create grafana-storage
+
+# start grafana
+docker run -d -p 3000:3000 --name=grafana -v grafana-storage:/var/lib/grafana grafana/grafana-enterprise
+```
+
+### Run Grafana container using bind mounts
+
+You may want to run Grafana in Docker but use folders on your host for the database or configuration. When doing so, it becomes important to start the container with a user that is able to access and write to the folder you map into the container.
+
+```bash
+mkdir data # creates a folder for your data
+ID=$(id -u) # saves your user id in the ID variable
+
+# starts grafana with your user id and using the data folder
+docker run -d --user $ID --volume "$PWD/data:/var/lib/grafana" -p 3000:3000 grafana/grafana-enterprise:8.2.1
+```
+
+## Default paths
+
+The following settings are hard-coded when launching the Grafana Docker container and can only be overridden using environment variables, not in `conf/grafana.ini`.
+
+| Setting               | Default value             |
+| --------------------- | ------------------------- |
+| GF_PATHS_CONFIG       | /etc/grafana/grafana.ini  |
+| GF_PATHS_DATA         | /var/lib/grafana          |
+| GF_PATHS_HOME         | /usr/share/grafana        |
+| GF_PATHS_LOGS         | /var/log/grafana          |
+| GF_PATHS_PLUGINS      | /var/lib/grafana/plugins  |
+| GF_PATHS_PROVISIONING | /etc/grafana/provisioning |
+
+## Logging
+
+Logs in the Docker container go to standard out by default, as is common in the Docker world. Change this by setting a different [log mode]({{< relref "../../administration/setup-grafana/configure-grafana/#mode" >}}).
+
+Example:
+
+```bash
+# Run Grafana while logging to both standard out and /var/log/grafana/grafana.log
+docker run -p 3000:3000 -e "GF_LOG_MODE=console file" grafana/grafana-enterprise
+```
+
+## Configure Grafana with Docker Secrets
+
+> Only available in Grafana v5.2 and later.
+
+It's possible to supply Grafana with configuration through files. This works well with [Docker Secrets](https://docs.docker.com/engine/swarm/secrets/) as the secrets by default gets mapped into `/run/secrets/<name of secret>` of the container.
+
+You can do this with any of the configuration options in conf/grafana.ini by setting `GF_<SectionName>_<KeyName>__FILE` to the path of the file holding the secret.
+
+For example, you could set the admin password this way:
+
+- Admin password secret: `/run/secrets/admin_password`
+- Environment variable: `GF_SECURITY_ADMIN_PASSWORD__FILE=/run/secrets/admin_password`
+
+## Configure AWS credentials for CloudWatch Support
+
+```bash
+docker run -d \
+-p 3000:3000 \
+--name=grafana \
+-e "GF_AWS_PROFILES=default" \
+-e "GF_AWS_default_ACCESS_KEY_ID=YOUR_ACCESS_KEY" \
+-e "GF_AWS_default_SECRET_ACCESS_KEY=YOUR_SECRET_KEY" \
+-e "GF_AWS_default_REGION=us-east-1" \
+grafana/grafana-enterprise
+```
+
+You may also specify multiple profiles to `GF_AWS_PROFILES` (e.g.
+`GF_AWS_PROFILES=default another`).
+
+Supported variables:
+
+- `GF_AWS_${profile}_ACCESS_KEY_ID`: AWS access key ID (required).
+- `GF_AWS_${profile}_SECRET_ACCESS_KEY`: AWS secret access key (required).
+- `GF_AWS_${profile}_REGION`: AWS region (optional).
@@ -26,7 +26,7 @@ If you installed Grafana using the `deb` or `rpm` packages, then your configurat

 ### Docker

-Refer to [Configure a Grafana Docker image]({{< relref "../../administration/configure-docker/" >}}) for information about environmental variables, persistent storage, and building custom Docker images.
+Refer to [Configure a Grafana Docker image]({{< relref "../configure-docker/" >}}) for information about environmental variables, persistent storage, and building custom Docker images.

 ### Windows

@@ -170,7 +170,7 @@ Override log path using the command line argument `cfg:default.paths.logs`:

 ### plugins

-Directory where Grafana automatically scans and looks for plugins. For information about manually or automatically installing plugins, refer to [Install Grafana plugins]({{< relref "../../plugins/installation/" >}}).
+Directory where Grafana automatically scans and looks for plugins. For information about manually or automatically installing plugins, refer to [Install Grafana plugins]({{< relref "../../administration/plugins/installation/" >}}).

 **macOS:** By default, the Mac plugin location is: `/usr/local/var/lib/grafana/plugins`.

@@ -1269,7 +1269,7 @@ The interval string is a possibly signed sequence of decimal numbers, followed b

 ## [unified_alerting.screenshots]

-For more information about screenshots, refer to [Images in notifications]({{< relref "../../alerting/images-in-notifications" >}}).
+For more information about screenshots, refer to [Images in notifications]({{< relref "../../alerting/images-in-notifications/" >}}).

 ### capture

@@ -1722,13 +1722,13 @@ Set to `true` if you want to test alpha plugins that are not yet ready for gener

 Enter a comma-separated list of plugin identifiers to identify plugins to load even if they are unsigned. Plugins with modified signatures are never loaded.

-We do _not_ recommend using this option. For more information, refer to [Plugin signatures]({{< relref "../../plugins/plugin-signatures/" >}}).
+We do _not_ recommend using this option. For more information, refer to [Plugin signatures]({{< relref "../../administration/plugin-management/" >}}).

 ### plugin_admin_enabled

 Available to Grafana administrators only, enables installing / uninstalling / updating plugins directly from the Grafana UI. Set to `true` by default. Setting it to `false` will hide the install / uninstall / update controls.

-For more information, refer to [Plugin catalog]({{< relref "../../plugins/catalog/" >}}).
+For more information, refer to [Plugin catalog]({{< relref "../../administration/plugins/catalog/" >}}).

 ### plugin_admin_external_manage_enabled

@@ -2000,4 +2000,4 @@ Refer to the [dashboards previews]({{< relref "../../dashboards/previews/" >}})

 ## [rbac]

-Refer to [Role-based access control]({{< relref "../../enterprise/access-control/about-rbac/" >}}) for more information.
+Refer to [Role-based access control]({{< relref "../../administration/roles-and-permissions/access-control/about-rbac/" >}}) for more information.
@@ -9,7 +9,7 @@ weight: 100

 # Configure Grafana Enterprise

-This page describes Grafana Enterprise-specific configuration options that you can specify in a `.ini` configuration file or using environment variables. Refer to [Configuration]({{< relref "./" >}}) for more information about available configuration options.
+This page describes Grafana Enterprise-specific configuration options that you can specify in a `.ini` configuration file or using environment variables. Refer to [Configuration]({{< relref "/" >}}) for more information about available configuration options.

 ## [enterprise]

@@ -42,7 +42,7 @@ Users with the Viewer role can enter _any possible query_ in _any_ of the data s

 To address this vulnerability, you can restrict data source query access in the following ways:

- Create multiple data sources with some restrictions added in data source configuration that restrict access (like database name or credentials). Then use the [Data Source Permissions]({{< relref "../../enterprise/datasource_permissions/" >}}) Enterprise feature to restrict user access to the data source in Grafana.
+- Create multiple data sources with some restrictions added in data source configuration that restrict access (like database name or credentials). Then use the [Data Source Permissions]({{< relref "../../administration/data-source-management/datasource-permissions/" >}}) Enterprise feature to restrict user access to the data source in Grafana.
 - Create a separate Grafana organization, and in that organization, create a separate data source. Make sure the data source has some option/user/credentials setting that limits access to a subset of the data. Not all data sources have an option to limit access.

 ## Implications of enabling anonymous access to dashboards
@@ -308,4 +308,4 @@ a login token and cookie. You only have to configure your auth proxy to provide
 Requests via other routes will be authenticated using the cookie.

 Use settings `login_maximum_inactive_lifetime_duration` and `login_maximum_lifetime_duration` under `[auth]` to control session
-lifetime. [Read more about login tokens]({{< relref "./#login-and-short-lived-tokens" >}})
+lifetime. [Read more about login tokens]({{< relref "/#login-and-short-lived-tokens" >}})
@@ -18,7 +18,7 @@ Grafana encrypts these secrets before they are written to the database, by using
 Since Grafana v9.0, it uses [envelope encryption](#envelope-encryption) by default, which adds a layer of indirection to the
 encryption process that represents an [**implicit breaking change**](#implicit-breaking-change) for older versions of Grafana.

-For further details about how to operate a Grafana instance with envelope encryption, see the [Operational work]({{< relref "./#operational-work" >}}) section below.
+For further details about how to operate a Grafana instance with envelope encryption, see the [Operational work]({{< relref "/#operational-work" >}}) section below.

 > **Note:** In Grafana Enterprise, you can also choose to [encrypt secrets in AES-GCM mode]({{< relref "#changing-your-encryption-mode-to-aes-gcm" >}}) instead of AES-CFB.

@@ -25,7 +25,7 @@ You can use an encryption key from AWS Key Management Service to encrypt secrets
 3. Create a [programmatic credential](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys) (access key ID and secret access key), which has permission to view the key that you created.
   <br><br>In AWS, you can control access to your KMS keys by using [key policies](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html), [IAM policies](https://docs.aws.amazon.com/kms/latest/developerguide/iam-policies.html), and [grants](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html). You can also create [temporary credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html), which must provide a session token along with an access key ID and a secret access key.

-4. From within Grafana, turn on [envelope encryption]({{< relref "./#envelope-encryption" >}}).
+4. From within Grafana, turn on [envelope encryption]({{< relref "/#envelope-encryption" >}}).
 5. Add your AWS KMS details to the Grafana configuration file; depending on your operating system, it is usually named `grafana.ini`:
   <br><br>a. Add a new section to the configuration file, with a name in the format of `[security.encryption.awskms.<KEY-NAME>]`, where `<KEY-NAME>` is any name that uniquely identifies this key among other provider keys.
   <br><br>b. Fill in the section with the following values:
@@ -26,7 +26,7 @@ You can use an encryption key from Azure Key Vault to encrypt secrets in the Gra

 5. In the Key Permissions section, set encrypt and decrypt permissions, and click **Save**.

-6. From within Grafana, turn on [envelope encryption]({{< relref "./" >}}).
+6. From within Grafana, turn on [envelope encryption]({{< relref "/" >}}).

 7. Add your Azure Key Vault details to the Grafana configuration file; depending on your operating system, is usually named `grafana.ini`:
   <br><br>a. Add a new section to the configuration file, with a name in the format of `[security.encryption.azurekv.<KEY-NAME>]`, where `<KEY-NAME>` is any name that uniquely identifies this key among other provider keys.
@@ -24,7 +24,7 @@ You can use an encryption key from Google Cloud Key Management Service to encryp

 4. [Create a service account key and save its JSON file](https://cloud.google.com/iam/docs/creating-managing-service-account-keys#creating) to you computer, for example, as `~/.config/gcloud/sample-project-credentials.json`.

-5. From within Grafana, turn on [envelope encryption]({{< relref "./#envelope-encryption" >}}).
+5. From within Grafana, turn on [envelope encryption]({{< relref "/#envelope-encryption" >}}).

 6. Add your Google Cloud KMS details to the Grafana configuration file; depending on your operating system, is usually named `grafana.ini`:
   <br><br>a. Add a new section to the configuration file, with a name in the format of `[security.encryption.azurekv.<KEY-NAME>]`, where `<KEY-NAME>` is any name that uniquely identifies this key among other provider keys.
@@ -22,7 +22,7 @@ You can use an encryption key from Hashicorp Vault to encrypt secrets in the Gra

 3. [Create a periodic service token](https://learn.hashicorp.com/tutorials/vault/tokens#periodic-service-tokens).

-4. From within Grafana, turn on [envelope encryption]({{< relref "./#envelop-encryption" >}}).
+4. From within Grafana, turn on [envelope encryption]({{< relref "/#envelop-encryption" >}}).

 5. Add your Hashicorp Vault details to the Grafana configuration file; depending on your operating system, is usually named `grafana.ini`:
   <br><br>a. Add a new section to the configuration file, with a name in the format of `[security.encryption.hashicorpvault.<KEY-NAME>]`, where `<KEY-NAME>` is any name that uniquely identifies this key among other provider keys.