Menu

This is documentation for the next version of Alloy. For the latest stable release, go to the latest version.

Documentationbreadcrumb arrow Grafana Alloybreadcrumb arrow Set upbreadcrumb arrow Migratebreadcrumb arrow Migrate from Agent Flow
Open source

Migrate from Grafana Agent Flow to Grafana Alloy

This topic describes how to perform a live migration from Grafana Agent Flow to Grafana Alloy with minimal downtime.

Note

This procedure is only required for live migrations from a Grafana Agent Flow install to Alloy.

If you want a fresh start with Alloy, you can uninstall Grafana Agent Flow and install Alloy.

Before you begin

  • You must have a Grafana Agent Flow configuration to migrate.
  • You must be running Grafana Agent Flow version v0.40 or later.
  • If you use auto-scaling make sure you disable auto-scaling for your Grafana Agent Flow deployment to prevent it from scaling during the migration.

Differences between Grafana Agent Flow and Alloy

  • Only functionality marked Generally available may be used by default. You can enable functionality in Experimental and Public preview by setting the --stability.level flag in run.
  • The default value of --storage.path has changed from data-agent/ to data-alloy/.
  • The default value of --server.http.memory-addr has changed from agent.internal:12345 to alloy.internal:12345.
  • Debug metrics reported by Alloy are prefixed with alloy_ instead of agent_.
  • The “classic modules”, module.file, module.git, module.http, and module.string have been removed in favor of import configuration blocks.
  • The prometheus.exporter.vsphere component has been replaced by the otelcol.receiver.vcenter component.

Steps

Prepare your Grafana Agent Flow configuration

Alloy uses the same configuration format as Grafana Agent Flow, but some functionality has been removed.

Before migrating, modify your Grafana Agent Flow configuration to remove or replace any unsupported components:

  • The “classic modules” in Grafana Agent Flow have been removed in favor of the modules introduced in v0.40:
    • module.file is replaced by the import.file configuration block.
    • module.git is replaced by the import.git configuration block.
    • module.http is replaced by the import.http configuration block.
    • module.string is replaced by the import.string configuration block.
  • prometheus.exporter.vsphere is replaced by the otelcol.receiver.vcenter component.

Deploy Alloy with a default configuration

Follow the installation instructions for Alloy, using the default configuration file. The configuration file is customized in the following steps.

When deploying Alloy, be aware of the following settings:

  • Alloy should be deployed with topology that’s the same as Grafana Agent Flow. The CPU, and storage limits should match.
  • Custom command-line flags configured in Grafana Agent Flow should be reflected in your Alloy installation.
  • Alloy may need to be deployed with the --stability.level flag in run to enable non-stable components:
    • Set --stability.level to experimental if you are using the following component:
    • Otherwise, --stability.level may be omitted or set to the default value (generally-available).
  • When installing on Kubernetes, update your values.yaml file to rename the agent key to alloy.
  • If you are deploying Alloy as a cluster:
    • Set the number of instances to match the number of instances in your Grafana Agent Flow cluster.
    • Don’t enable auto-scaling until the migration is complete.

Migrate Grafana Agent Flow data to Alloy

Migrate your Grafana Agent Flow data to Alloy by copying the contents of the Grafana Agent Flow data directory to the Alloy data directory.

  • Linux installations: copy the contents of /var/lib/grafana-agent-flow to /var/lib/alloy/data.
  • macOS installations: copy the contents of $(brew --prefix)/etc/grafana-agent-flow/data to $(brew --prefix)/etc/alloy/data.
  • Windows installations: copy the contents of %ProgramData%\Grafana Agent Flow\data to %ProgramData%\GrafanaLabs\Alloy\data.
  • Docker: copy the contents of mounted volumes to a new directory, and then mount the new directory when running Alloy.
  • Kubernetes: use kubectl cp to copy the contents of the data directory on Flow pods to the data directory on Alloy pods.
    • The data directory is determined by the agent.storagePath (default /tmp/agent) and alloy.storagePath (default /tmp/alloy) fields in values.yaml.

Migrate pipelines that receive data over the network

Telemetry pipelines which receive data over the network (for example, pipelines using otelcol.receiver.otlp or prometheus.receive_http) should be configured in Alloy first:

  1. Configure Alloy with all pipelines where telemetry data is received over the network.
  2. Reconfigure applications to send telemetry data to Alloy instead of Grafana Agent Flow.

Migrate the remaining pipelines

Migrate remaining pipelines from Grafana Agent Flow to Alloy:

  1. Disable remaining pipelines in Grafana Agent Flow to prevent Flow and Alloy from processing the same data.
  2. Configure Alloy with the remaining pipelines.

Note

This process results in minimal downtime as remaining pipelines are moved from Grafana Agent Flow to Alloy.

To completely eliminate downtime, configure remaining pipelines in Alloy before disabling them in Grafana Agent Flow. This alternative approach results in some duplicate data being sent to backends during the migration period.

Uninstall Grafana Agent Flow

After you have completed the migration, you can uninstall Grafana Agent Flow.

Cleanup temporary changes

You can enable auto-scaling in your Alloy deployment if you disabled it during the migration process.