kubernetes docs improvements (#6187)

* WIP * feedback, ty * feedback * Write about config changes to agent using helm chart * generic install done * generic configure done * wip * simplify * cleanup * Update docs/sources/flow/get-started/install/kubernetes.md Co-authored-by: Clayton Cornell <[email protected]> * Clayton's review, thanks! Co-authored-by: Clayton Cornell <[email protected]> * Update docs/sources/flow/get-started/install/kubernetes.md Co-authored-by: Clayton Cornell <[email protected]> --------- Co-authored-by: Clayton Cornell <[email protected]>
grafana · Mar 18, 2024 · c68ec7c · c68ec7c
1 parent 9d65d9f
commit c68ec7c
Show file tree

Hide file tree

Showing 4 changed files with 149 additions and 26 deletions.
diff --git a/docs/sources/flow/get-started/install/kubernetes.md b/docs/sources/flow/get-started/install/kubernetes.md
@@ -20,7 +20,12 @@ weight: 200
 
 # Deploy {{% param "PRODUCT_NAME" %}} on Kubernetes
 
-{{< param "PRODUCT_NAME" >}} can be deployed on Kubernetes by using the Helm chart for {{< param "PRODUCT_ROOT_NAME" >}}.
+You can use a Helm chart to deploy {{< param "PRODUCT_NAME" >}} on Kubernetes.
+
+{{< admonition type="note" >}}
+These instructions show you how to install using a generic [Helm chart](https://github.com/grafana/agent/tree/main/operations/helm/charts/grafana-agent) for {{< param "PRODUCT_NAME" >}}.
+You can deploy {{< param "PRODUCT_ROOT_NAME" >}} either in static mode or flow mode. The Helm chart deploys {{< param "PRODUCT_NAME" >}} by default.
+{{< /admonition >}}
 
 ## Before you begin
 
@@ -30,11 +35,6 @@ weight: 200
 
 ## Deploy
 
-{{< admonition type="note" >}}
-These instructions show you how to install the generic [Helm chart](https://github.com/grafana/agent/tree/main/operations/helm/charts/grafana-agent) for {{< param "PRODUCT_NAME" >}}.
-You can deploy {{< param "PRODUCT_ROOT_NAME" >}} either in static mode or flow mode. The Helm chart deploys {{< param "PRODUCT_NAME" >}} by default.
-{{< /admonition >}}
-
 To deploy {{< param "PRODUCT_ROOT_NAME" >}} on Kubernetes using Helm, run the following commands in a terminal window:
 
 1. Add the Grafana Helm chart repository:
@@ -48,24 +48,49 @@ To deploy {{< param "PRODUCT_ROOT_NAME" >}} on Kubernetes using Helm, run the fo
    ```shell
    helm repo update
    ```
+1. Create a namespace for {{< param "PRODUCT_NAME" >}}:
+
+   ```shell
+   kubectl create namespace <NAMESPACE>
+   ```
+
+   Replace the following:
+
+   - _`<NAMESPACE>`_: The namespace to use for your {{< param "PRODUCT_NAME" >}}
+     installation, such as `agent`.
 
 1. Install {{< param "PRODUCT_ROOT_NAME" >}}:
 
    ```shell
-   helm install <RELEASE_NAME> grafana/grafana-agent
+   helm install --namespace <NAMESPACE> <RELEASE_NAME> grafana/grafana-agent
    ```
 
    Replace the following:
 
-   -  _`<RELEASE_NAME>`_: The name to use for your {{< param "PRODUCT_ROOT_NAME" >}} installation, such as `grafana-agent-flow`.
+   - _`<NAMESPACE>`_: The namespace created in the previous step.
+   - _`<RELEASE_NAME>`_: The name to use for your {{< param "PRODUCT_ROOT_NAME" >}} installation, such as `grafana-agent-flow`.
 
-For more information on the {{< param "PRODUCT_ROOT_NAME" >}} Helm chart, refer to the Helm chart documentation on [Artifact Hub][].
+1. Verify that the {{< param "PRODUCT_NAME" >}} pods are running:
 
-[Artifact Hub]: https://artifacthub.io/packages/helm/grafana/grafana-agent
+   ```shell
+   kubectl get pods --namespace <NAMESPACE>
+   ```
+
+   Replace the following:
+
+   - _`<NAMESPACE>`_: The namespace used in the previous step.
+
+You have successfully deployed {{< param "PRODUCT_NAME" >}} on Kubernetes,
+using default Helm settings. To configure {{< param "PRODUCT_NAME" >}},
+see the [Configure {{< param "PRODUCT_NAME" >}} on Kubernetes][Configure] guide.
 
 ## Next steps
 
-- [Configure {{< param "PRODUCT_NAME" >}}][Configure]
+- [Configure {{< param "PRODUCT_NAME" >}} on Kubernetes][Configure]
+
+- Refer to the [{{< param "PRODUCT_NAME" >}} Helm chart documentation on Artifact Hub][Artifact Hub] for more information about Helm chart.
+
+[Artifact Hub]: https://artifacthub.io/packages/helm/grafana/grafana-agent
 
 [Helm]: https://helm.sh
 

diff --git a/docs/sources/flow/tasks/configure/_index.md b/docs/sources/flow/tasks/configure/_index.md
@@ -14,7 +14,7 @@ canonical: https://grafana.com/docs/agent/latest/flow/tasks/configure/
 description: Configure Grafana Agent Flow after it is installed
 menuTitle: Configure
 title: Configure Grafana Agent Flow
-weight: 90
+weight: 70
 ---
 
 # Configure {{% param "PRODUCT_NAME" %}}

diff --git a/docs/sources/flow/tasks/configure/configure-kubernetes.md b/docs/sources/flow/tasks/configure/configure-kubernetes.md
@@ -19,36 +19,62 @@ weight: 200
 
 # Configure {{% param "PRODUCT_NAME" %}} on Kubernetes
 
-To configure {{< param "PRODUCT_NAME" >}} on Kubernetes, perform the following steps:
+This page describes how to apply a new configuration to {{< param "PRODUCT_NAME" >}}
+when running on Kubernetes with the Helm chart. It assumes that:
 
-1. Download a local copy of [values.yaml][] for the Helm chart.
+- You have [installed {{< param "PRODUCT_NAME" >}} on Kubernetes using the Helm chart][k8s-install].
+- You already have a new {{< param "PRODUCT_NAME" >}} configuration that you
+  want to apply to your Helm chart installation.
 
-1. Make changes to your copy of `values.yaml` to customize settings for the
-   Helm chart.
+If instead you're looking for help in configuring {{< param "PRODUCT_NAME" >}} to perform a specific task,
+consult the following guides instead:
+- [Collect and forward Prometheus metrics][prometheus],
+- [Collect OpenTelemetry data][otel],
+- or the [tasks section][tasks] for all the remaining configuration guides.
 
-   Refer to the inline documentation in the `values.yaml` for more information about each option.
+[prometheus]: ../../collect-prometheus-metrics/
+[otel]: ../../collect-opentelemetry-data/
+[tasks]: ../
+[k8s-install]: ../../../get-started/install/kubernetes/
+
+## Configure the Helm chart
+
+To modify {{< param "PRODUCT_NAME" >}}'s Helm chart configuration, perform the following steps:
+
+1. Create a local `values.yaml` file with a new Helm chart configuration.
+
+   1. You can use your own copy of the values file or download a copy of the
+      default [values.yaml][].
+
+   1. Make changes to your `values.yaml` to customize settings for the
+      Helm chart.
+
+      Refer to the inline documentation in the default [values.yaml][] for more
+      information about each option.
 
 1. Run the following command in a terminal to upgrade your {{< param "PRODUCT_NAME" >}} installation:
 
    ```shell
-   helm upgrade RELEASE_NAME grafana/grafana-agent -f VALUES_PATH
+   helm upgrade --namespace <NAMESPACE> <RELEASE_NAME> grafana/grafana-agent -f <VALUES_PATH>
    ```
-
-   1. Replace `RELEASE_NAME` with the name you used for your {{< param "PRODUCT_NAME" >}} installation.
-
-   1. Replace `VALUES_PATH` with the path to your copy of `values.yaml` to use.
+   Replace the following:
+   - _`<NAMESPACE>`_: The namespace you used for your {{< param "PRODUCT_NAME" >}} installation.
+   - _`<RELEASE_NAME>`_: The name you used for your {{< param "PRODUCT_NAME" >}} installation.
+   - _`<VALUES_PATH>`_: The path to your copy of `values.yaml` to use.
 
 [values.yaml]: https://raw.githubusercontent.com/grafana/agent/main/operations/helm/charts/grafana-agent/values.yaml
 
-## Kustomize considerations
+### Kustomize considerations
 
 If you are using [Kustomize][] to inflate and install the [Helm chart][], be careful
 when using a `configMapGenerator` to generate the ConfigMap containing the
 configuration. By default, the generator appends a hash to the name and patches
 the resource mentioning it, triggering a rolling update.
 
-This behavior is undesirable for {{< param "PRODUCT_NAME" >}} because the startup time can be significant depending on the size of the Write-Ahead Log.
-You can use the [Helm chart][] sidecar container to watch the ConfigMap and trigger a dynamic reload.
+This behavior is undesirable for {{< param "PRODUCT_NAME" >}} because the
+startup time can be significant, for example, when your deployment has a large
+metrics Write-Ahead Log. You can use the [Helm chart][] sidecar container to
+watch the ConfigMap and trigger a dynamic reload.
 
 The following is an example snippet of a `kustomization` that disables this behavior:
 
@@ -61,5 +87,77 @@ configMapGenerator:
       disableNameSuffixHash: true
 ```
 
+## Configure the {{< param "PRODUCT_NAME" >}}
+
+This section describes how to modify the {{< param "PRODUCT_NAME" >}} configuration, which is stored in a ConfigMap in the Kubernetes cluster.
+There are two methods to perform this task.
+
+### Method 1: Modify the configuration in the values.yaml file
+Use this method if you prefer to embed your {{< param "PRODUCT_NAME" >}} configuration in the Helm chart's `values.yaml` file.
+
+1. Modify the configuration file contents directly in the `values.yaml` file:
+
+   ```yaml
+   agent:
+     configMap:
+       content: |-
+         // Write your Agent config here:
+         logging {
+           level = "info"
+           format = "logfmt"
+         }
+   ```
+
+1. Run the following command in a terminal to upgrade your {{< param "PRODUCT_NAME" >}} installation:
+
+   ```shell
+   helm upgrade --namespace <NAMESPACE> <RELEASE_NAME> grafana/grafana-agent -f <VALUES_PATH>
+   ```
+   Replace the following:
+   - _`<NAMESPACE>`_: The namespace you used for your {{< param "PRODUCT_NAME" >}} installation.
+   - _`<RELEASE_NAME>`_: The name you used for your {{< param "PRODUCT_NAME" >}} installation.
+   - _`<VALUES_PATH>`_: The path to your copy of `values.yaml` to use.
+
+### Method 2: Create a separate ConfigMap from a file
+Use this method if you prefer to write your {{< param "PRODUCT_NAME" >}} configuration in a separate file.
+
+1. Write your configuration to a file, for example, `config.river`.
+
+   ```river
+   // Write your Agent config here:
+   logging {
+     level = "info"
+     format = "logfmt"
+   }
+   ```
+
+1. Create a ConfigMap called `agent-config` from the above file:
+
+   ```shell
+   kubectl create configmap --namespace <NAMESPACE> agent-config "--from-file=config.river=./config.river"
+   ```
+   Replace the following:
+   - _`<NAMESPACE>`_: The namespace you used for your {{< param "PRODUCT_NAME" >}} installation.
+
+1. Modify Helm Chart's configuration in your `values.yaml` to use the existing ConfigMap:
+
+   ```yaml
+     agent:
+     configMap:
+       create: false
+       name: agent-config
+       key: config.river
+   ```
+
+1. Run the following command in a terminal to upgrade your {{< param "PRODUCT_NAME" >}} installation:
+
+   ```shell
+   helm upgrade --namespace <NAMESPACE> <RELEASE_NAME> grafana/grafana-agent -f <VALUES_PATH>
+   ```
+   Replace the following:
+   - _`<NAMESPACE>`_: The namespace you used for your {{< param "PRODUCT_NAME" >}} installation.
+   - _`<RELEASE_NAME>`_: The name you used for your {{< param "PRODUCT_NAME" >}} installation.
+   - _`<VALUES_PATH>`_: The path to your copy of `values.yaml` to use.
+
 [Helm chart]: https://github.com/grafana/agent/tree/main/operations/helm/charts/grafana-agent
 [Kustomize]: https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/
diff --git a/docs/sources/flow/tasks/migrate/_index.md b/docs/sources/flow/tasks/migrate/_index.md
@@ -8,7 +8,7 @@ canonical: https://grafana.com/docs/agent/latest/flow/tasks/migrate/
 description: How to migrate to Grafana Agent Flow
 menuTitle: Migrate
 title: Migrate to Grafana Agent Flow
-weight: 100
+weight: 80
 ---
 
 # How to migrate to {{% param "PRODUCT_NAME" %}}