Documentation Grafana Cloud Instrument and send data Fleet Management Set up Collector onboarding Standalone installations

Onboard standalone collectors to Fleet Management

Learn how to register your collectors in Grafana Fleet Management when they are installed outside of containers and directly on a host or virtual machine. If you’d like to use Fleet Management for on-premises collectors, refer to the On premises instructions.

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 and is recommended for use with Alloy v1.7.2 or later. If you’re using an earlier version, make sure to include the --stability.level=public-preview flag when running Alloy.
• Understand the key terms and concepts of Fleet Management and how the service works.

Create an access token

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

1. In your Grafana Cloud stack, navigate to Connections > Collector > Configure.
2. Use the tool on this page to create a new token. Give the token a name and click the Create token button. You don’t need to complete the rest of the installation instructions if you’re not installing a new Alloy instance. The generated token comes with predefined scopes for reading remote configurations in Fleet Management and writing telemetry to Grafana Cloud databases.
3. Copy the token and save it in a secure password file. You’ll need the token for the next step, but you won’t be able to view it again once you leave the page.

For more information on creating access policies, refer to Grafana Cloud access policies.

Add remotecfg to local configurations

Enroll your collectors in Fleet Management by adding the remotecfg code block to their local configuration files. Fleet Management does not support use of the remotecfg block in configuration modules. The block must be added to the root configuration. 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      = "<PASSWORD>"
    }

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

None of the arguments in this remotecfg 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 ID.
  • The password is the token you added to your access policy in the previous section. If you prefer to save your token in a secure file, use password_file = "<PASSWORD_FILE_PATH>" instead.
• 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. The collector’s id and attributes are used to determine which configuration pipelines to include in the remote configuration.
  • Attributes defined in remotecfg are local attributes. Fleet Management automatically includes collector.os, collector.version, and collector.ID as attributes. These reserved attributes cannot be overwritten. In addition to these 2 reserved attributes, you can assign up to 13 more local attributes to each collector, for a maximum of 15 attributes in a GetConfig API request.
  • Use the Fleet Management interface to add remote attributes. You can assign up to 100 remote attributes per collector. Remote attributes take precedence over local 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.

Set environment variables

Fleet Management comes with a set of autogenerated configuration pipelines that provide self-monitoring telemetry. The self-monitoring pipelines use environment variables to authenticate to the service and correlate the data with the correct collector. To see self-monitoring logs and metrics in the application, make sure you have set these environment variables wherever each collector is running:

• GCLOUD_RW_API_KEY. This variable should match the Grafana Cloud access token you created for Fleet Management.
• GCLOUD_FM_LOG_PATH. If collecting logs on MacOS, set this variable to the log file location.

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 remote attributes

Collectors are configured remotely in Fleet Management when their attributes match the matching attributes of a configuration pipeline. If you haven’t specified local attributes in the remotecfg blocks of your collector configuration files, or if additional attributes are needed, you can add remote 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 remote attributes to your collectors:

1. In your Grafana Cloud stack, 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 remote attributes.
5. Follow the instructions to add remote attributes to the selected group of collectors.

Check the Attributes column on the Inventory tab to see that your new attribute is assigned to the collectors you chose. Continue assigning remote 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.