From 3050e72641187ecaf84792036d23843d37f8cbce Mon Sep 17 00:00:00 2001 From: Taylor C <41653732+tacole02@users.noreply.github.com> Date: Tue, 3 Dec 2024 10:27:39 -0800 Subject: [PATCH] Docs: Improve Helm docs usability (#10059) * restructures getting started content * docs: more helm docs structure updates * docs: rename deploy gem topic * docs: outdated headers * docs: outdated headers * add alias for old configure gem topic * additional updates to get started chapter * fixes inbound link * add make doc output * docs: update link to gem content * update Secret to k8s convention * Update docs/sources/helm-charts/mimir-distributed/get-started-helm-charts/gs-external-access.md Co-authored-by: Dimitar Dimitrov * Update docs/sources/helm-charts/mimir-distributed/get-started-helm-charts/gs-external-access.md Co-authored-by: Dimitar Dimitrov * update version substitution syntax --------- Co-authored-by: Dimitar Dimitrov --- .../helm-charts/mimir-distributed/_index.md | 4 +- .../configure-gem-federation-frontend.md | 2 +- .../get-started-helm-charts/_index.md | 190 +----------------- .../gs-external-access.md | 189 +++++++++++++++++ .../gs-gem.md} | 25 ++- .../_index.md | 2 +- 6 files changed, 217 insertions(+), 195 deletions(-) create mode 100644 docs/sources/helm-charts/mimir-distributed/get-started-helm-charts/gs-external-access.md rename docs/sources/helm-charts/mimir-distributed/{configure/configure-grafana-enterprise-metrics.md => get-started-helm-charts/gs-gem.md} (51%) diff --git a/docs/sources/helm-charts/mimir-distributed/_index.md b/docs/sources/helm-charts/mimir-distributed/_index.md index d73456a9203..8271fea916c 100644 --- a/docs/sources/helm-charts/mimir-distributed/_index.md +++ b/docs/sources/helm-charts/mimir-distributed/_index.md @@ -15,8 +15,10 @@ cascade: # Grafana mimir-distributed Helm chart documentation -The mimir-distributed Helm chart for [Grafana Mimir](https://grafana.com/docs/mimir//) and [Grafana Enterprise Metrics](https://grafana.com/docs/enterprise-metrics//) (GEM) allows you to configure, install, and upgrade Grafana Mimir or Grafana Enterprise Metrics within a Kubernetes cluster. +The mimir-distributed Helm chart allows you to install, configure, and upgrade [Grafana Mimir](https://grafana.com/docs/mimir//) and [Grafana Enterprise Metrics](https://grafana.com/docs/enterprise-metrics//) (GEM) within a Kubernetes cluster. > **Note:** By default, the mimir-distributed Helm chart documentation applies to both Grafana Mimir and GEM. If it only applies to GEM, it is explicitly stated. {{< section menuTitle="true" >}} + +To learn more about Helm, refer to the [Helm home page](https://helm.sh/). diff --git a/docs/sources/helm-charts/mimir-distributed/configure/configure-gem-federation-frontend.md b/docs/sources/helm-charts/mimir-distributed/configure/configure-gem-federation-frontend.md index 2de1e10a506..8e8e1914ce5 100644 --- a/docs/sources/helm-charts/mimir-distributed/configure/configure-gem-federation-frontend.md +++ b/docs/sources/helm-charts/mimir-distributed/configure/configure-gem-federation-frontend.md @@ -14,7 +14,7 @@ This guide focuses specifically on deploying the federation-frontend component a ## Before you begin -1. Set up a GEM cluster: For information about setting up and configuring a GEM deployment, refer to [Configure Grafana Enterprise Metrics]({{< relref "./configure-grafana-enterprise-metrics" >}}) and [Get started with Grafana Mimir using the Helm chart]({{< relref "../get-started-helm-charts" >}}). +1. Set up a GEM cluster: For information about setting up and configuring a GEM deployment, refer to [Deploy Grafana Enterprise Metrics using the Helm chart](https://grafana.com/docs/helm-charts/mimir-distributed/latest/get-started-helm-charts/gs-gem/). 2. Provision an access token with the `metrics:read` scope for each cluster that you want to query. For more information, refer to [Set up a GEM tenant](https://grafana.com/docs/enterprise-metrics//set-up-gem-tenant). ## Deploy the GEM federation-frontend diff --git a/docs/sources/helm-charts/mimir-distributed/get-started-helm-charts/_index.md b/docs/sources/helm-charts/mimir-distributed/get-started-helm-charts/_index.md index ed6a6adc38f..eb47ad5ceac 100644 --- a/docs/sources/helm-charts/mimir-distributed/get-started-helm-charts/_index.md +++ b/docs/sources/helm-charts/mimir-distributed/get-started-helm-charts/_index.md @@ -2,9 +2,9 @@ aliases: - /docs/mimir/latest/operators-guide/deploying-grafana-mimir/getting-started-helm-charts/ - /docs/helm-charts/mimir-distributed/latest/get-started/ -description: Learn how to get started with Grafana Mimir using the Helm chart. +description: Learn how to get started with Grafana Mimir and GEM using the Helm chart. menuTitle: Get started -title: Get started with Grafana Mimir using the Helm chart +title: Get started with Grafana Mimir and GEM using the Helm chart weight: 20 keywords: - Helm chart @@ -12,9 +12,9 @@ keywords: - Grafana Mimir --- -# Get started with Grafana Mimir using the Helm chart +# Get started with Grafana Mimir and GEM using the Helm chart -The Grafana Mimir [Helm](https://helm.sh/) chart allows you to configure, install, and upgrade Grafana Mimir within a Kubernetes cluster. +The mimir-distributed Helm chart allows you to install, configure, and upgrade Grafana Mimir and Grafana Enterprise Metrics (GEM) within a Kubernetes cluster. ## Before you begin @@ -136,7 +136,7 @@ Using a custom namespace solves problems later on because you do not have to ove 1. Wait until all of the pods have a status of `Running` or `Completed`, which might take a few minutes. -## Generate some test metrics +## Generate test metrics {{< docs/shared source="alloy" lookup="agent-deprecation.md" version="next" >}} @@ -199,182 +199,10 @@ In the example that follows, metamonitoring scrapes metrics about Grafana Mimir You should be able to query metrics in [Grafana Explore](/docs/grafana/latest/explore/), as well as create dashboard panels by using your newly configured `Mimir` data source. -## Advanced setup with external access +## Deploy Grafana Enterprise Metrics -In this procedure you'll set up external access for Grafana Mimir to allow writing and quering metrics from outside the Kubernetes cluster. -You'll set up an [ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) that enables you to externally access a Kubernetes cluster. +For additional GEM-specific configurations, refer to [Deploy Grafana Enterprise Metrics](https://grafana.com/docs/helm-charts/mimir-distributed/latest/get-started-helm-charts/gs-gem). -### Before you begin +## Enable external access to Grafana Mimir -Verify that an ingress controller is set up in the Kubernetes cluster, for example [ingress-nginx](https://kubernetes.github.io/ingress-nginx/) - -### Set up ingress - -1. Configure an ingress: - - b. Add the following to your `custom.yaml` Helm values file: - - ```yaml - nginx: - ingress: - enabled: true - ingressClassName: nginx - hosts: - - host: - paths: - - path: / - pathType: Prefix - tls: - # empty, disabled. - ``` - - Replace _``_ with a suitable hostname that DNS can resolve - to the external IP address of the Kubernetes cluster. - For more information, see [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/). - - > **Note:** On Linux systems, and if it is not possible for you set up local DNS resolution, you can use the `--add-host=:` command-line flag to define the _``_ local address for the `docker` commands in the examples that follow. - - > **Note:** To see all of the configurable parameters for a Helm chart installation, use `helm show values grafana/mimir-distributed`. - -1. Upgrade Grafana Mimir by using the `helm` command: - - ```bash - helm -n mimir-test upgrade mimir grafana/mimir-distributed -f custom.yaml - ``` - - The output of the command should contain the URL to use for querying Grafana Mimir from the outside, for example: - - ```bash - From outside the cluster via ingress: - http://myhost.mynetwork/prometheus - ``` - -### Configure Prometheus to write to Grafana Mimir - -You can either configure Prometheus to write to Grafana Mimir or [configure Grafana Alloy to write to Mimir](#configure-grafana-alloy-to-write-to-grafana-mimir). Although you can configure both, you don't need to. - -Make a choice based on whether or not you already have a Prometheus server set up: - -- For an existing Prometheus server: - - 1. Add the following YAML snippet to your Prometheus configuration file: - - ```yaml - remote_write: - - url: http:///api/v1/push - ``` - - In this case, your Prometheus server writes metrics to Grafana Mimir, based on what is defined in the existing `scrape_configs` configuration. - - 1. Restart the Prometheus server. - -- For a Prometheus server that does not exist yet: - - 1. Write the following configuration to a `prometheus.yml` file: - - ```yaml - remote_write: - - url: http:///api/v1/push - - scrape_configs: - - job_name: prometheus - honor_labels: true - static_configs: - - targets: ["localhost:9090"] - ``` - - In this case, your Prometheus server writes metrics to Grafana Mimir that it scrapes from itself. - - 1. Start a Prometheus server by using Docker: - - ```bash - docker run -p 9090:9090 -v /prometheus.yml:/etc/prometheus/prometheus.yml prom/prometheus - ``` - - > **Note:** On Linux systems, if \ cannot be resolved by the Prometheus server, use the additional command-line flag `--add-host=:` to set it up. - -### Configure Grafana Alloy to write to Grafana Mimir - -You can either configure Grafana Alloy to write to Grafana Mimir or [configure Prometheus to write to Mimir](#configure-prometheus-to-write-to-grafana-mimir). Although you can configure both, you don't need to. - -Make a choice based on whether you already have Alloy set up: - -- For an existing Alloy: - - 1. Add the following configuration snippet for the `prometheus.remote_write` component to your Alloy configuration file: - - ``` - prometheus.remote_write "LABEL" { - endpoint { - url = http:///api/v1/push - } - } - ``` - - 1. Add `forward_to = [prometheus.remote_write.LABEL.receiver]` to an existing pipeline. - - 1. Restart Alloy. - -- For a new Alloy: - - 1. Write the following configuration to a `config.alloy` file: - - ``` - prometheus.exporter.self "self_metrics" { - } - - prometheus.scrape "self_scrape" { - targets = prometheus.exporter.self.self_metrics.targets - forward_to = [prometheus.remote_write.mimir.receiver] - } - - prometheus.remote_write "mimir" { - endpoint { - url = "http:///api/v1/push" - } - } - ``` - - 1. Start Alloy by using Docker: - - ```bash - docker run -v /config.alloy:/etc/alloy/config.alloy -p 12345:12345 grafana/alloy:latest run --server.http.listen-addr=0.0.0.0:12345 --storage.path=/var/lib/alloy/data /etc/alloy/config.alloy - ``` - - > **Note:** On Linux systems, if \ cannot be resolved by Alloy, use the additional command-line flag `--add-host=:` to set it up. - -For more information about the `prometheus.remote_write` component, refer to [prometheus.remote_write](https://grafana.com/docs/alloy//reference/components/prometheus/prometheus.remote_write) in the Grafana Alloy documentation. - -### Query metrics in Grafana - -You can use the Grafana installed in Kubernetes in the [Start Grafana in Kubernetes and query metrics](#start-grafana-in-kubernetes-and-query-metrics) section as well or follow the instructions bellow. - -> **Note:** If you have the port-forward running for Grafana from an earlier step, stop it. - -First install Grafana, and then add Mimir as a Prometheus data source. - -1. Start Grafana by using Docker: - - ```bash - docker run --rm --name=grafana -p 3000:3000 grafana/grafana - ``` - - > **Note:** On Linux systems, if \ cannot be resolved by Grafana, use the additional command-line flag `--add-host=:` to set it up. - -1. In a browser, go to the Grafana server at [http://localhost:3000](http://localhost:3000). -1. Sign in using the default username `admin` and password `admin`. -1. On the left-hand side, go to **Configuration** > **Data sources**. -1. Configure a new Prometheus data source to query the local Grafana Mimir cluster, by using the following settings: - - | Field | Value | - | ----- | ---------------------------------- | - | Name | Mimir | - | URL | http://\/prometheus | - - To add a data source, see [Add a data source](/docs/grafana/latest/datasources/add-a-data-source/). - -1. Verify success: - - You should be able to query metrics in [Grafana Explore](http://localhost:3000/explore), - as well as create dashboard panels by using your newly configured `Mimir` data source. - For more information, see [Monitor Grafana Mimir]({{< relref "../run-production-environment-with-helm/monitor-system-health.md" >}}). +To enable write and query access to Grafana Mimir from outside the Kubernetes cluster, refer to [Enable external access to Grafana Mimir](https://grafana.com/docs/helm-charts/mimir-distributed//get-started-helm-charts/gs-external-access). diff --git a/docs/sources/helm-charts/mimir-distributed/get-started-helm-charts/gs-external-access.md b/docs/sources/helm-charts/mimir-distributed/get-started-helm-charts/gs-external-access.md new file mode 100644 index 00000000000..a4fafe7bae3 --- /dev/null +++ b/docs/sources/helm-charts/mimir-distributed/get-started-helm-charts/gs-external-access.md @@ -0,0 +1,189 @@ +--- +description: Learn how to enable external access to Grafana Mimir from outside the Kubernetes cluster. +menuTitle: Enable external access +title: Enable external access to Grafana Mimir +weight: 50 +keywords: + - Helm chart + - Kubernetes + - Grafana Mimir +--- + +# Enable external access to Grafana Mimir + +Set up external access to Grafana Mimir to allow writing and quering metrics from outside the Kubernetes cluster. You can set up an [ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) that enables you to externally access a Kubernetes cluster. + +## Before you begin + +Verify that an ingress controller is set up in the Kubernetes cluster, for example [ingress-nginx](https://kubernetes.github.io/ingress-nginx/) + +## Set up ingress + +1. Configure an ingress: + + b. Add the following to your `custom.yaml` Helm values file: + + ```yaml + nginx: + ingress: + enabled: true + ingressClassName: nginx + hosts: + - host: + paths: + - path: / + pathType: Prefix + tls: + # empty, disabled. + ``` + + Replace _``_ with a suitable hostname that DNS can resolve + to the external IP address of the Kubernetes cluster. + For more information, refer to [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/). + + > **Note:** On Linux systems, and if it is not possible for you set up local DNS resolution, you can use the `--add-host=:` command-line flag to define the _``_ local address for the `docker` commands in the examples that follow. + + > **Note:** To see all of the configurable parameters for a Helm chart installation, use `helm show values grafana/mimir-distributed`. + +1. Upgrade Grafana Mimir by using the `helm` command: + + ```bash + helm -n mimir-test upgrade mimir grafana/mimir-distributed -f custom.yaml + ``` + + The output of the command should contain the URL to use for querying Grafana Mimir from the outside, for example: + + ```bash + From outside the cluster via ingress: + http://myhost.mynetwork/prometheus + ``` + +## Configure Prometheus to write to Grafana Mimir + +You can either configure Prometheus to write to Grafana Mimir or [configure Grafana Alloy to write to Mimir](#configure-grafana-alloy-to-write-to-grafana-mimir). Although you can configure both, you don't need to. + +Make a choice based on whether or not you already have a Prometheus server set up: + +- For an existing Prometheus server: + + 1. Add the following YAML snippet to your Prometheus configuration file: + + ```yaml + remote_write: + - url: http:///api/v1/push + ``` + + In this case, your Prometheus server writes metrics to Grafana Mimir, based on what is defined in the existing `scrape_configs` configuration. + + 1. Restart the Prometheus server. + +- For a Prometheus server that does not exist yet: + + 1. Write the following configuration to a `prometheus.yml` file: + + ```yaml + remote_write: + - url: http:///api/v1/push + + scrape_configs: + - job_name: prometheus + honor_labels: true + static_configs: + - targets: ["localhost:9090"] + ``` + + In this case, your Prometheus server writes metrics to Grafana Mimir that it scrapes from itself. + + 1. Start a Prometheus server by using Docker: + + ```bash + docker run -p 9090:9090 -v /prometheus.yml:/etc/prometheus/prometheus.yml prom/prometheus + ``` + + > **Note:** On Linux systems, if \ cannot be resolved by the Prometheus server, use the additional command-line flag `--add-host=:` to set it up. + +## Configure Grafana Alloy to write to Grafana Mimir + +You can either configure Grafana Alloy to write to Grafana Mimir or [configure Prometheus to write to Mimir](#configure-prometheus-to-write-to-grafana-mimir). Although you can configure both, you don't need to. + +Make a choice based on whether you already have Alloy set up: + +- For an existing Alloy: + + 1. Add the following configuration snippet for the `prometheus.remote_write` component to your Alloy configuration file: + + ``` + prometheus.remote_write "LABEL" { + endpoint { + url = http:///api/v1/push + } + } + ``` + + 1. Add `forward_to = [prometheus.remote_write.LABEL.receiver]` to an existing pipeline. + + 1. Restart Alloy. + +- For a new Alloy: + + 1. Write the following configuration to a `config.alloy` file: + + ``` + prometheus.exporter.self "self_metrics" { + } + + prometheus.scrape "self_scrape" { + targets = prometheus.exporter.self.self_metrics.targets + forward_to = [prometheus.remote_write.mimir.receiver] + } + + prometheus.remote_write "mimir" { + endpoint { + url = "http:///api/v1/push" + } + } + ``` + + 1. Start Alloy by using Docker: + + ```bash + docker run -v /config.alloy:/etc/alloy/config.alloy -p 12345:12345 grafana/alloy:latest run --server.http.listen-addr=0.0.0.0:12345 --storage.path=/var/lib/alloy/data /etc/alloy/config.alloy + ``` + + > **Note:** On Linux systems, if \ cannot be resolved by Alloy, use the additional command-line flag `--add-host=:` to set it up. + +For more information about the `prometheus.remote_write` component, refer to [prometheus.remote_write](https://grafana.com/docs/alloy//reference/components/prometheus/prometheus.remote_write) in the Grafana Alloy documentation. + +## Query metrics in Grafana + +You can use the Grafana installed in Kubernetes in the [Start Grafana in Kubernetes and query metrics](https://grafana.com/docs/helm-charts/mimir-distributed//get-started-helm-charts/#start-grafana-in-kubernetes-and-query-metrics) documentation, or follow the instructions below. + +> **Note:** If you have the port-forward running for Grafana from an earlier step, stop it. + +First install Grafana, and then add Mimir as a Prometheus data source. + +1. Start Grafana by using Docker: + + ```bash + docker run --rm --name=grafana -p 3000:3000 grafana/grafana + ``` + + > **Note:** On Linux systems, if \ cannot be resolved by Grafana, use the additional command-line flag `--add-host=:` to set it up. + +1. In a browser, go to the Grafana server at [http://localhost:3000](http://localhost:3000). +1. Sign in using the default username `admin` and password `admin`. +1. On the left-hand side, go to **Configuration** > **Data sources**. +1. Configure a new Prometheus data source to query the local Grafana Mimir cluster, by using the following settings: + + | Field | Value | + | ----- | ---------------------------------- | + | Name | Mimir | + | URL | http://\/prometheus | + + To add a data source, refer to [Add a data source](/docs/grafana/latest/datasources/add-a-data-source/). + +1. Verify success: + + You should be able to query metrics in [Grafana Explore](http://localhost:3000/explore), + as well as create dashboard panels by using your newly configured `Mimir` data source. + For more information, refer to [Monitor Grafana Mimir]({{< relref "../run-production-environment-with-helm/monitor-system-health.md" >}}). diff --git a/docs/sources/helm-charts/mimir-distributed/configure/configure-grafana-enterprise-metrics.md b/docs/sources/helm-charts/mimir-distributed/get-started-helm-charts/gs-gem.md similarity index 51% rename from docs/sources/helm-charts/mimir-distributed/configure/configure-grafana-enterprise-metrics.md rename to docs/sources/helm-charts/mimir-distributed/get-started-helm-charts/gs-gem.md index 6a6e2735098..2e646dfed2f 100644 --- a/docs/sources/helm-charts/mimir-distributed/configure/configure-grafana-enterprise-metrics.md +++ b/docs/sources/helm-charts/mimir-distributed/get-started-helm-charts/gs-gem.md @@ -1,26 +1,29 @@ --- -title: "Configure Grafana Enterprise Metrics" -menuTitle: "Enterprise Metrics" -description: "Learn how to enable Grafana Enterprise Metrics." +aliases: + - /docs/helm-charts/mimir-distributed/latest/configure/configure-grafana-enterprise-metrics/ +description: Learn how to deploy Grafana Enterprise Metrics using the Helm chart. +menuTitle: Deploy GEM +title: Deploy Grafana Enterprise Metrics using the Helm chart +weight: 40 --- -# Configure Grafana Enterprise Metrics +# Deploy Grafana Enterprise Metrics using the Helm chart -From the Grafana Helm chart point of view, the main differences between Grafana Mimir and Grafana Enterprise Metrics (GEM) are: +Use the mimir-distributed Helm chart to deploy Grafana Enterprise Metrics (GEM) on Kubernetes. Here are the main differences in using the Helm chart for GEM, as compared to Grafana Mimir: - GEM requires a valid license. - Instead of using NGINX as the router of requests to internal components, GEM deploys its own enterprise gateway component that authenticates and routes requests. -- More mandatory and optional components are available, such as the admin API and various proxies. +- GEM has more mandatory and optional components, such as the Admin API and various proxies. ## Before you begin - Follow the instructions and [Choose a name for your GEM cluster](https://grafana.com/docs/enterprise-metrics//setup/#choose-a-name-for-your-gem-cluster). - It is recommended, but not required to use the same name as the Helm release. For example if the cluster name is `mygem`, you'd install the chart with `helm install mygem grafana/mimir-distributed`. + It is recommended to use the same name as the Helm release. For example, if the cluster name is `mygem`, you'd install the chart with `helm install mygem grafana/mimir-distributed`. -- Follow the instruction in [Get a GEM license](https://grafana.com/docs/enterprise-metrics//setup/#get-a-gem-license) to acquire a license. +- Follow the instructions in [Get a GEM license](https://grafana.com/docs/enterprise-metrics//setup/#get-a-gem-license) to acquire a license. -## Handling the license file +## Provide the license file There are two options: @@ -35,7 +38,7 @@ There are two options: - Store the license in a Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret/). - In this case use the following custom values: + In this case, use the following custom values: ```yaml license: @@ -52,7 +55,7 @@ enterprise: enabled: true ``` -If you want to use a different cluster name for the license and a different Helm release name on the command line, also set: +If you want to use a different cluster name for the license and a different Helm release name on the command line, also set the following: ```yaml mimir: diff --git a/docs/sources/helm-charts/mimir-distributed/run-production-environment-with-helm/_index.md b/docs/sources/helm-charts/mimir-distributed/run-production-environment-with-helm/_index.md index df6aca5b9f6..93997ee1717 100644 --- a/docs/sources/helm-charts/mimir-distributed/run-production-environment-with-helm/_index.md +++ b/docs/sources/helm-charts/mimir-distributed/run-production-environment-with-helm/_index.md @@ -286,7 +286,7 @@ Your Grafana Mimir cluster can now ingest metrics in production. ## Configure clients to write metrics to Mimir -To configure each client to remote-write metrics to Mimir, refer to [Configure Prometheus to write to Grafana Mimir]({{< relref "../get-started-helm-charts#configure-prometheus-to-write-to-grafana-mimir" >}}) +To configure each client to remote-write metrics to Mimir, refer to [Configure Prometheus to write to Grafana Mimir](https://grafana.com/docs/helm-charts/mimir-distributed//get-started-helm-charts/gs-external-access/#configure-prometheus-to-write-to-grafana-mimir) and [Configure Grafana Alloy to write to Grafana Mimir](https://grafana.com/docs/helm-charts/mimir-distributed/latest/get-started-helm-charts/#configure-grafana-alloy-to-write-to-grafana-mimir). ## Set up redundant Prometheus or Grafana Alloy instances for high availability