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 an existing 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 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 fromdata-agent/
todata-alloy/
. - The default value of
--server.http.memory-addr
has changed fromagent.internal:12345
toalloy.internal:12345
. - Debug metrics reported by Alloy are prefixed with
alloy_
instead ofagent_
. - “Classic modules” (
module.file
,module.git
,module.http
, andmodule.string
) has been removed in favor of import configuration blocks. - The
prometheus.exporter.vsphere
component has been replaced by theotelcol.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
topublic-preview
if you are using any of these components: - Set
--stability.level
toexperimental
if you are using any of the following components: - Otherwise,
--stability.level
may be omitted or set to the default value (generally-available
).
- Set
- When installing on Kubernetes, update your
values.yaml
file to rename theagent
key toalloy
. - 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
) andalloy.storagePath
(default/tmp/alloy
) fields invalues.yaml
.
- The data direrctory is determined by the
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:
- Configure Alloy with all pipelines where telemetry data is received over the network.
- 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:
- Disable remaining pipelines in Grafana Agent Flow to prevent Flow and Alloy from processing the same data.
- 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 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.