DocumentationGrafana AlloyTasksMigrateMigrate from Grafana Agent Flow

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.

Before you begin

• You must have an existing Grafana Agent Flow configuration to migrate.
• You must be running Grafana Agent Flow version v0.40 or later.
• If auto-scaling is used:
  • 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. Functionality in Experimental and Public preview can be enabled 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_.
• “Classic modules” (module.file, module.git, module.http, and module.string) has been removed in favor of import configuration blocks.
• The prometheus.exporter.vsphere component has been replaced by the otelcol.receiver.vcenter component.

Steps

Prepare the 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:

• Flow’s “classic modules” have been removed in favor of the new 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 identical topology 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 public-preview if you are using any of these components:
    • discovery.process
    • pyroscope.ebpf
    • pyroscope.java
    • pyroscope.scrape
    • pyroscope.write
  • Set --stability.level to experimental if you are using any of the following components:
    • otelcol.receiver.vcenter
  • 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 deploying Alloy as a cluster:
  • Set the number of instances to match the number of instances in your Grafana Agent Flow cluster.
  • Do not 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 direrctory 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.

Uninstall Grafana Agent Flow

After following the sections above, you can uninstall Grafana Agent Flow.

Cleanup temporary changes

Auto-scaling may be re-enabled in your Alloy deployment if it was disabled during the migration process.