From 43409e2f55f1045a1857e060dcba2a5d729b31e9 Mon Sep 17 00:00:00 2001 From: nikimanoledaki Date: Wed, 15 Jan 2025 17:15:28 +0100 Subject: [PATCH 1/2] Specify steps to create service account for Grafana auth --- docs/content/configuration.md | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/docs/content/configuration.md b/docs/content/configuration.md index dc9647a6..0dcab0be 100644 --- a/docs/content/configuration.md +++ b/docs/content/configuration.md @@ -30,12 +30,41 @@ in an OS specific location. Grizzly interacts with Grafana via its REST API. For this, you will need to establish authentication credentials. +The minimum requirement is to set the URL of the Grafana instance to be used: ```sh grr config set grafana.url http://localhost:3000 # URL for the root of your Grafana instance -grr config set grafana.user admin # (Optional) Username if using basic auth +``` + +Optionally, set one of the following fields, depending our your authentication method: +a [token or password](#token-or-password-optional) or a [username](#username-optional). + +### Token or password (optional) + +To authenticate using a service account token, first [create a service account in +Grafana](https://grafana.com/docs/grafana/latest/administration/service-accounts/#to-create-a-service-account). +Before creating the service account, ensure that you have added the role that +best suits your use case. A role with `Viewer` permissions would be enough +to view resources. Use `Editor` or `Admin` to be able to edit resources. +Then, +[add a token to the new service account](https://grafana.com/docs/grafana/latest/administration/service-accounts/#add-a-token-to-a-service-account-in-grafana). +Copy the token and set it with Grizzly: + +```sh grr config set grafana.token abcd12345 # Service account token (or basic auth password) ``` +Alternatively, set this field to a password if using [basic authentication](https://grafana.com/docs/grafana/latest/setup-grafana/configure-security/configure-authentication/#basic-authentication). + +Next, consider setting a [context](#using-grizzly-contexts) to save this configuration. + +### Username (optional) + +Optionally, set a username if using [basic authentication](https://grafana.com/docs/grafana/latest/setup-grafana/configure-security/configure-authentication/#basic-authentication). + +```sh +grr config set grafana.user admin # (Optional) Username if using basic auth +``` + ## Grafana Cloud Prometheus To interact with Grafana Cloud Prometheus (aka Mimir), use these settings: From 9fb9ccdea17c9a1dce4bd3d128b247eb8d8bc00d Mon Sep 17 00:00:00 2001 From: nikimanoledaki Date: Thu, 16 Jan 2025 11:40:45 +0100 Subject: [PATCH 2/2] Update auth docs for clarity --- docs/content/configuration.md | 28 ++++++++++++++++------------ docs/content/prometheus.md | 6 +++--- 2 files changed, 19 insertions(+), 15 deletions(-) diff --git a/docs/content/configuration.md b/docs/content/configuration.md index 0dcab0be..e425903e 100644 --- a/docs/content/configuration.md +++ b/docs/content/configuration.md @@ -25,7 +25,7 @@ context first, then explain how to use multiple contexts thereafter. Settings can be configured via Grizzly itself, using `grr config set`. They are stored in an OS specific location. -## Grafana Itself +## Authenticate with a Grafana instance Grizzly interacts with Grafana via its REST API. For this, you will need to establish authentication credentials. @@ -35,14 +35,19 @@ The minimum requirement is to set the URL of the Grafana instance to be used: grr config set grafana.url http://localhost:3000 # URL for the root of your Grafana instance ``` -Optionally, set one of the following fields, depending our your authentication method: -a [token or password](#token-or-password-optional) or a [username](#username-optional). +Optionally, set the following field(s), depending our your [authentication method with the given Grafana instance](https://grafana.com/docs/grafana/latest/setup-grafana/configure-security/configure-authentication/): +- A [token](#token-or-password-optional) if using a [Grafana service account](https://grafana.com/docs/grafana/latest/administration/service-accounts) (recommended) +- A [username](#username-optional) and [password](#token-or-password-optional) if using basic authentication + +Next, consider setting a [context](#using-grizzly-contexts) to save this configuration. + +Once you have configured your authentication method, you are ready to use the [Grizzly server](./server.md) to view and/or edit resources. ### Token or password (optional) -To authenticate using a service account token, first [create a service account in -Grafana](https://grafana.com/docs/grafana/latest/administration/service-accounts/#to-create-a-service-account). -Before creating the service account, ensure that you have added the role that +To authenticate with a Grafana instance using a service account token, first [create a service account in the +Grafana instance](https://grafana.com/docs/grafana/latest/administration/service-accounts/#to-create-a-service-account). +Before clicking `Create` to create the service account, ensure that you have added the role that best suits your use case. A role with `Viewer` permissions would be enough to view resources. Use `Editor` or `Admin` to be able to edit resources. Then, @@ -55,8 +60,6 @@ grr config set grafana.token abcd12345 # Service account token (or basic auth pa Alternatively, set this field to a password if using [basic authentication](https://grafana.com/docs/grafana/latest/setup-grafana/configure-security/configure-authentication/#basic-authentication). -Next, consider setting a [context](#using-grizzly-contexts) to save this configuration. - ### Username (optional) Optionally, set a username if using [basic authentication](https://grafana.com/docs/grafana/latest/setup-grafana/configure-security/configure-authentication/#basic-authentication). @@ -65,8 +68,9 @@ Optionally, set a username if using [basic authentication](https://grafana.com/d grr config set grafana.user admin # (Optional) Username if using basic auth ``` -## Grafana Cloud Prometheus -To interact with Grafana Cloud Prometheus (aka Mimir), use these settings: +## Authenticate with hosted Prometheus + +To interact with [hosted Prometheus / Mimir](./prometheus.md) resources, use these settings: ```sh grr config set mimir.address https://mimir.example.com # URL for Mimir instance or Grafana Cloud Prometheus instance @@ -74,10 +78,10 @@ grr config set mimir.tenant-id myTenant # Tenant ID for your Grafana Cloud Prome grr config set mimir.api-key abcdef12345 # Authentication token (if you are using Grafana Cloud) ``` -**Notes** +**Notes** * Be sure to set `api-key` when you need to interact with Grafana Cloud. -## Grafana Synthetic Monitoring +## Authenticate with Grafana Synthetic Monitoring To interact with Grafana Synthetic Monitoring, you must configure the below settings: ```sh diff --git a/docs/content/prometheus.md b/docs/content/prometheus.md index b5393e16..a5549c0f 100644 --- a/docs/content/prometheus.md +++ b/docs/content/prometheus.md @@ -4,12 +4,12 @@ title: "With Prometheus" --- ## Which Prometheus' are supported? + Prometheus itself requires its configuration to be present in text files on -local disk. As Grizzly focuses on systems that can be managed via HTTP APIs, +local disk. Since Grizzly focuses on systems that can be managed via HTTP APIs, Grizzly cannot (currently) work with Prometheus itself. -Various hosted Prometheus installations, such as Grafana Cloud Prometheus -are supported, as are systems running Mimir. +Various hosted Prometheus installations are supported, such as [Grafana Cloud Prometheus](https://grafana.com/go/grafana-cloud-prometheus-1/). Systems running [Grafana Mimir](https://grafana.com/docs/mimir/latest/) are supported as well. ## Configuring Prometheus Prometheus alert and recording rules are both created using the same `kind`: