--- title: "Onboard collectors deployed in Kubernetes to Fleet Management | Grafana Cloud documentation" description: "Learn how to onboard collectors deployed in Kubernetes to Grafana Fleet Management" --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # Onboard collectors deployed in Kubernetes to Fleet Management Learn how to register your collectors in Kubernetes with Grafana Fleet Management. If you’d like to use Fleet Management for self-managed collectors, refer to the [set up instructions](/docs/grafana-cloud/send-data/fleet-management/set-up/connectivity-options/self-managed/). ## Onboard with Grafana Kubernetes Monitoring Helm chart From v2.0.0 of the [Kubernetes Monitoring Helm chart](https://github.com/grafana/k8s-monitoring-helm/tree/main/charts/k8s-monitoring), support for Fleet Management is built in. You can enable Fleet Management while configuring your clusters in Grafana Cloud. 1. In your Grafana Cloud stack, click **Connections** > **Collector Setup** in the left-side menu. 2. Select **Kubernetes** from the platform dropdown. 3. Follow the instructions to identify your cluster and select features. 4. Enter a *unique* cluster name. The cluster name is used to create the `collector_id`, which identifies each Alloy instance and is generated as follows: - For Deployments: `---` - For StatefulSets: `---` - For DaemonSets: `----` Make sure to use a unique name for each cluster to avoid `collector_id` collisions in the Fleet Management application. 5. Generate a new token or include an existing one, which the application automatically adds to the manifest. The token should have the following scopes: - `fleet-management:read` - `logs:write` - `metrics:write` - `metrics:read` - `traces:write` - `profiles:write` If you skip this step, make sure to add your access policy token wherever you see `REPLACE_WITH_ACCESS_POLICY_TOKEN` in the copied manifest. Without the token, your cluster cannot connect to Fleet Management. 6. Before you copy the deployment code, make sure the **Enable Remote Configuration** switch is turned on. 7. Deploy the Kubernetes Monitoring Helm chart to your cluster. 8. Return to your Grafana Cloud stack and click **Connections** > **Fleet Management** to view your collector inventory. ### Onboard existing Kubernetes Monitoring Helm chart deployments If you’ve already got collectors deployed with the Kubernetes Monitoring Helm chart, you can register them with Fleet Management by updating the `values.yaml` file and upgrading Helm. 1. Update your existing `values.yaml` file as follows: 1. Remove the `integrations.alloy` section of the chart, since Fleet Management provides Alloy health data out of the box. 2. Add the required sections for Fleet Management environment variables (`alloy-.alloy.extraEnv`) and remote configuration (`alloy-.remoteConfig`) to each of the `alloy-` sections. You can copy the content for these sections from the Kubernetes Monitoring configuration page in Grafana Cloud: 1. In your Grafana Cloud stack, navigate to **Observability** > **Kubernetes** > **Configuration** in the left-side menu. 2. At the deployment step, make sure the switch to enable remote configuration is on. 3. Find the required sections in the deployment code, copy them, and paste them into your existing `values.yaml` file. 2. Once your `values.yaml` file is updated, upgrade your Helm chart with the following command: shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell helm upgrade -f values.yaml ``` ### Self-monitoring configuration pipelines When you visit the Fleet Management interface in Grafana Cloud, a set of [self-monitoring configuration pipelines](/docs/grafana-cloud/send-data/fleet-management/set-up/configuration-pipelines/self-monitoring-pipelines/) are automatically created and assigned to registered collectors. The internal telemetry collected by the self-monitoring pipelines powers the health dashboards and logs in the collector’s details view in the Fleet Management interface. These pipelines, which begin with `self_monitoring_*`, rely on environment variables to authenticate requests and set `collector_id` labels that match telemetry to collectors. - If you copy the Helm manifest from Grafana Cloud, the environment variables are set for you. - If you opt to create your own manifest, you must set the following variables wherever the collector is running: - `GCLOUD_RW_API_KEY`, the access token for Fleet Management - `NAMESPACE`, the Kubernetes namespace of the running pod - `POD_NAME`, the name of the running pod - `HOSTNAME`, the name of the Kubernetes node hosting the pod The Kubernetes Monitoring Helm chart v4.1 or later requires a new version of the `self_monitoring_logs_kubernetes` pipeline. When you register new collectors with v4.1+ of the chart, the new logs pipeline is created automatically. If you upgrade to v4.1+ after using older self-monitoring pipelines, you must [update your pipelines](/docs/grafana-cloud/send-data/fleet-management/set-up/configuration-pipelines/self-monitoring-pipelines/#update-self-monitoring-pipelines). To update, delete all `self_monitoring_*` pipelines from the **Remote configuration** tab in Fleet Management. Once all autogenerated pipelines are deleted, Fleet Management recreates them with the latest versions. If you use a Kubernetes Monitoring Helm chart earlier than v4.1, existing self-monitoring pipelines continue to work, but you should update them to use the latest defaults. If you use the Grafana Alloy Helm chart, existing self-monitoring pipelines also continue to work, but you should update them and consider migrating to the unified Kubernetes Monitoring Helm chart v4.1 or later. ### Inactive collectors The `collector_id` for singleton deployments includes a unique pod name that changes with each restart, resulting in a new collector instance in Fleet Management. The old collectors are marked [inactive](/docs/grafana-cloud/send-data/fleet-management/manage-fleet/collectors/collector-status/#inactive-collectors) after 3 hours. Inactive collectors don’t count toward a stack’s collector limit. By default, the Fleet Management **Inventory** shows only active collectors. You can change this view using the **Status** dropdown filter. If inactive collectors don’t make a `GetConfig` request or re-register themselves within 30 days of being marked inactive, the Fleet Management application automatically deletes them. DaemonSets and StatefulSets persist their `collector.id` on restarts, so inactive collectors don’t accumulate. ### Versions Fleet Management is not recommended for use with versions of the Kubernetes Monitoring Helm chart earlier than v2.0. If you have previously installed v1.x of the Kubernetes Monitoring Helm chart, you might need to remove legacy cluster roles and cluster role bindings for a clean upgrade. ## Onboard with Grafana Alloy Helm chart You can also use the Alloy Helm chart to onboard and configure your collectors. For Kubernetes fleets, consider migrating to the Kubernetes Monitoring Helm chart v4.1 or later. 1. Create a secret you can use as an access token for Fleet Management. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell kubectl create secret --namespace NAMESPACE generic gc-token --from-literal=token=VALUE ``` 2. [Create a ConfigMap from a file](/docs/grafana-cloud/send-data/alloy/configure/kubernetes/#method-2-create-a-separate-configmap-from-a-file) and add the following `remotecfg` block to the configuration. Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```alloy remotecfg { url = "" id = sys.env("GCLOUD_FM_COLLECTOR_ID") attributes = { "platform" = "kubernetes" } basic_auth { username = "" password = sys.env("GCLOUD_RW_API_KEY") } } ``` Replace `` with the base URL of the Fleet Management service and `` with your instance ID, both of which can be found on the **API** tab in the Fleet Management interface. 3. Update your Helm chart as follows. YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml gc: secret: name: gc-token alloy: configMap: create: false name: alloy-config key: config.alloy extraEnv: - name: NAMESPACE valueFrom: fieldRef: fieldPath: metadata.namespace - name: POD_NAME valueFrom: fieldRef: fieldPath: metadata.name - name: HOSTNAME valueFrom: fieldRef: fieldPath: spec.nodeName - name: GCLOUD_FM_COLLECTOR_ID value: "clusterName-$(NAMESPACE)-$(POD_NAME)" - name: GCLOUD_RW_API_KEY valueFrom: secretKeyRef: name: gc-token key: token ``` In addition to specifying the Alloy configuration file, this chart also sets the following environment variables: - `GCLOUD_FM_COLLECTOR_ID` is set to the unique name `clusterName-$(NAMESPACE)-$(POD_NAME)`, which should match the `remotecfg` `id` argument value. This variable is reset to a new value each time the pod restarts, which causes a new collector to appear in the **Inventory** tab. You can delete old, unused collectors from your inventory, or you can allow the Fleet Management application to clean up the [inactive collectors](/docs/grafana-cloud/send-data/fleet-management/manage-fleet/collectors/collector-status/#inactive-collectors) automatically. By default, inactive collectors are filtered out of the Fleet Management **Inventory** page. - `GCLOUD_RW_API_KEY` is set to the secret you created in step 1. - `NAMESPACE` is set to the Kubernetes namespace of the running pod. - `POD_NAME` is set to the name of the running pod. - `HOSTNAME` is set to the name of the Kubernetes node hosting the pod. These five variables must be set so that the [self-monitoring configuration pipelines](#self-monitoring-configuration-pipelines) are properly assigned. 4. Deploy the Helm chart. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell helm upgrade --install --namespace grafana/alloy -f ``` Replace the following: - ``: The namespace you used for your Alloy installation. - ``: The name you used for your Alloy installation. - ``: The path to the values.yaml file. ## Next steps - [Add attributes](/docs/grafana-cloud/send-data/fleet-management/set-up/onboard-collectors/standalone-installations/#add-remote-attributes) to your collectors for greater control over which configurations are applied and when.