Documentation Grafana Cloud Instrument and send data Fleet Management Onboard existing collectors

Onboard your collectors to Fleet Management

Grafana Fleet Management is a Grafana Cloud feature that centralizes monitoring, configuration, and management of all your collectors. Learn how to onboard your existing collectors to Fleet Management so you can proactively manage your observability setup.

Before you begin

To onboard collectors to Fleet Management, you must:

• Have a Grafana Cloud account.
• Have administrator privileges and the ability to create and edit access policies.
• Update Grafana Alloy to the most current version. Fleet Management must be used with Alloy collectors.
• Understand the key terms and concepts of Fleet Management and how the service works.

Create an access policy

To begin the onboarding process, you must authorize Fleet Management to access your collectors.

1. In your Grafana Cloud portal, select the stack where you want to configure Fleet Management. You can only query collectors within the same stack.
2. In the left-side navigation, select Access Policies under the Security heading.
3. Create a new access policy or edit an existing access policy. Make sure to add the scope fleet-management:read to the policy. We recommend that you also enable metrics:write and logs:write on the same policy so that a single token can be used. For more information on creating access policies, refer to Grafana Cloud access policies.
4. After setting up the access policy, click Add token and follow the prompts to add a new token to the policy. Make sure to copy the token to your clipboard and save it in a secure password file. You’ll need it for the next step, but you won’t be able to view it again once you close the confirmation window.

Add remotecfg to local configurations

Enroll your collectors in Fleet Management by adding the remotecfg code block to their local configuration files. For help, refer to the Alloy configuration documentation.

Here is an example of a remotecfg code block:

alloy Copy

remotecfg {
    url = <SERVICE_URL>
    basic_auth {
        username      = <USERNAME>
        password_file = <PASSWORD_FILE>
    }

    id             = constants.hostname
    attributes     = {"cluster" = "dev", "namespace" = "otlp-dev"}
    poll_frequency = "5m"
}

Let’s take a closer look at the arguments in this remotecfg. None of these arguments are required.

• url: Set this value to the base URL of the Fleet Management service. If url is unset, the service is non-operational.

  You can find the base URL in the Grafana Cloud Fleet Management interface. In your Grafana Cloud stack, click Connections > Collector > Fleet Management in the left-side menu and switch to the API tab. Find the remotecfg URL in the Base URL section. It looks like the following URL, where <CLUSTER_NAME> is the production cluster of your stack:

Copy

https://fleet-management-<CLUSTER_NAME>.grafana.net/

• basic_auth: Use this block to authenticate to the service.
  • The username is the same as your stack’s ID.
  • The password_file points to the location of the token you added to your access policy in the previous section.
• id: Set this value to a unique identifier for the collector. If the collector is deployed with persistent storage, id is reused across restarts.
  • If unset, id defaults to a universally unique identifier (UUID) that is stored on the collector’s data path. By default this path is data-alloy/alloy_seed.json.
  • If overridden, id must be set to some uniquely identifiable value, such as a unique hostname or a ${cluster}_${namespace}_${podname} value. If the value of id is not unique, collectors might be assigned different configurations than expected and be indistinguishable in the Fleet Management interface.
• attributes: Use this argument to assign a set of key-value pairs that meaningfully characterize the collector.
  • attributes defined in remotecfg are system attributes. Fleet Management automatically includes collector.os and collector.version as system attributes, which cannot be overwritten.
  • Use the Fleet Management interface to add custom attributes. You can assign up to 100 custom attributes per collector, but only 15 attributes can be used in a GetConfig API request. Custom attributes take precedence over system attributes.
  • Both attribute sets are merged together and used for configuration assignment and filtering.
• poll_frequency: Use this argument to define how often to poll the API for new configurations.

For the full list of supported arguments, refer to the remotecfg reference documentation.

Run your collectors

Follow the instructions to start running your Alloy collectors. If your collectors are already running, restart them so the new configuration takes effect. Check that you’re running the latest version of Alloy.

Test that the remotecfg block is working by pinging the collector’s root /metrics endpoint and looking for remotecfg_* metrics, such as remotecfg_load_attempts_total.

Add custom attributes

Collectors are configured remotely in Fleet Management when their attributes match the matching attributes of a configuration pipeline. If you haven’t specified system attributes in the remotecfg blocks of your collectors, or if additional attributes are needed, you can add custom attributes directly through the Fleet Management interface. You have greater control over configurations when your collectors are well categorized with meaningful attributes. Here’s how to add custom attributes to your collectors:

1. In your Grafana Cloud instance, click Connections > Collector > Fleet Management.
2. From the Inventory tab, select a group of collectors.
3. Click the Edit icon. The bulk edit tool appears on screen.
4. Click Add custom attributes.
5. Follow the instructions to add custom attributes to the selected group of collectors.

Check the Custom Attributes column on the Inventory tab to see that your new attribute is assigned to the collectors you chose. Continue assigning custom attributes based on your configuration needs.

Next steps

You have registered your collectors with Fleet Management and assigned attributes to them. Learn how to configure them remotely.