Skip to content

Commit

Permalink
Docs: Improve Helm docs usability (#10059)
Browse files Browse the repository at this point in the history 
* 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 <[email protected]>

* Update docs/sources/helm-charts/mimir-distributed/get-started-helm-charts/gs-external-access.md

Co-authored-by: Dimitar Dimitrov <[email protected]>

* update version substitution syntax

---------

Co-authored-by: Dimitar Dimitrov <[email protected]>
  • Loading branch information
@tacole02 @dimitarvdimitrov
tacole02 and dimitarvdimitrov authored Dec 3, 2024
1 parent ce3bd44 commit 3050e72
Show file tree
Hide file tree
Showing 6 changed files with 217 additions and 195 deletions.
4 changes: 3 additions & 1 deletion docs/sources/helm-charts/mimir-distributed/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,10 @@ cascade:

# Grafana mimir-distributed Helm chart documentation

The mimir-distributed Helm chart for [Grafana Mimir](https://grafana.com/docs/mimir/<MIMIR_VERSION>/) and [Grafana Enterprise Metrics](https://grafana.com/docs/enterprise-metrics/<GEM_VERSION>/) (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/<MIMIR_VERSION>/) and [Grafana Enterprise Metrics](https://grafana.com/docs/enterprise-metrics/<GEM_VERSION>/) (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/).
2 changes: 1 addition & 1 deletion ...es/helm-charts/mimir-distributed/configure/configure-gem-federation-frontend.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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/<GEM_VERSION>/set-up-gem-tenant).

## Deploy the GEM federation-frontend
Expand Down
190 changes: 9 additions & 181 deletions docs/sources/helm-charts/mimir-distributed/get-started-helm-charts/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,19 @@
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
- Kubernetes
- 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

Expand Down Expand Up @@ -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" >}}

Expand Down Expand Up @@ -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: <ingress-host>
paths:
- path: /
pathType: Prefix
tls:
# empty, disabled.
```

Replace _`<ingress-host>`_ 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=<ingress-host>:<kubernetes-cluster-external-address>` command-line flag to define the _`<ingress-host>`_ 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://<ingress-host>/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://<ingress-host>/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 <absolute-path-to>/prometheus.yml:/etc/prometheus/prometheus.yml prom/prometheus
```

> **Note:** On Linux systems, if \<ingress-host\> cannot be resolved by the Prometheus server, use the additional command-line flag `--add-host=<ingress-host>:<kubernetes-cluster-external-address>` 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://<ingress-host>/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://<ingress-host>/api/v1/push"
}
}
```

1. Start Alloy by using Docker:

```bash
docker run -v <absolute-path-to>/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 \<ingress-host\> cannot be resolved by Alloy, use the additional command-line flag `--add-host=<ingress-host>:<kubernetes-cluster-external-address>` to set it up.

For more information about the `prometheus.remote_write` component, refer to [prometheus.remote_write](https://grafana.com/docs/alloy/<ALLOY_VERSION>/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 \<ingress-host\> cannot be resolved by Grafana, use the additional command-line flag `--add-host=<ingress-host>:<kubernetes-cluster-external-address>` 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://\<ingress-host\>/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/<MIMIR_HELM_VERSION>/get-started-helm-charts/gs-external-access).
Loading

0 comments on commit 3050e72

Please sign in to comment.