This is documentation for the next version of Alloy. For the latest stable release, go to the latest version.
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 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_
. - The “classic modules”,
module.file
,module.git
,module.http
, andmodule.string
have been removed in favor of import configuration blocks. - The
prometheus.exporter.vsphere
component has been replaced by theotelcol.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
toexperimental
if you are using the following component: - 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 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
) andalloy.storagePath
(default/tmp/alloy
) fields invalues.yaml
.
- The data directory 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 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.