Configure Grafana Alloy on Grafana Labs

Configure Grafana Alloy clustering in an existing installation

Mon, 30 Mar 2026 15:47:22 +0000

Configure Alloy clustering in an existing installation

You can configure Alloy to run with clustering so that individual Alloys can work together for workload distribution and high availability.

This topic describes how to add clustering to an existing installation.

Configure Alloy clustering with Helm Chart

This section guides you through enabling clustering when Alloy is installed on Kubernetes using the Alloy Helm chart.

Before you begin

Ensure that your values.yaml file has controller.type set to statefulset.

Steps

To configure clustering:

Amend your existing values.yaml file to add clustering.enabled=true inside the alloy block.
YAML
```
alloy:
  clustering:
    enabled: true
```
Upgrade your installation to use the new values.yaml file:
Bash
```
helm upgrade <RELEASE_NAME> -f values.yaml
```
Replace the following:
- <RELEASE_NAME>: The name of the installation you chose when you installed the Helm chart.
Use the Alloy UI to verify the cluster status:
1. Click Clustering in the navigation bar.
2. Ensure that all expected nodes appear in the resulting table.

Configure Grafana Alloy on Kubernetes

Mon, 30 Mar 2026 15:47:22 +0000

Configure Grafana Alloy on Kubernetes

This page describes how to apply a new configuration to Alloy when running on Kubernetes with the Helm chart. It assumes that:

You have installed Alloy on Kubernetes using the Helm chart.
You already have a Alloy configuration that you want to apply to your Helm chart installation.

Refer to Collect and forward data for information about configuring Alloy to collect and forward data.

Configure the Helm chart

To modify Alloy’s Helm chart configuration, perform the following steps:

Create a local values.yaml file with a Helm chart configuration.
1. You can use your own copy of the values file or download a copy of the default values.yaml.
2. Make changes to your values.yaml to customize settings for the Helm chart.
  
  Refer to the inline documentation in the default values.yaml for more information about each option.
Run the following command in a terminal to upgrade your Alloy installation:
shell
```
helm upgrade --namespace <NAMESPACE> <RELEASE_NAME> grafana/alloy -f <VALUES_PATH>
```
Replace the following:
- <NAMESPACE>: The namespace you used for your Alloy installation.
- <RELEASE_NAME>: The name you used for your Alloy installation.
- <VALUES_PATH>: The path to your copy of values.yaml to use.

Kustomize considerations

If you are using Kustomize to inflate and install the Helm chart, be careful when using a configMapGenerator to generate the ConfigMap containing the configuration. By default, the generator appends a hash to the name and patches the resource mentioning it, triggering a rolling update.

This behavior is undesirable for Alloy because the startup time can be significant, for example, when your deployment has a large metrics Write-Ahead Log. You can use the Helm chart sidecar container to watch the ConfigMap and trigger a dynamic reload.

The following is an example snippet of a kustomization that disables this behavior:

configMapGenerator:
  - name: alloy
    files:
      - config.alloy
    options:
      disableNameSuffixHash: true

Configure Alloy

This section describes how to modify the Alloy configuration, which is stored in a ConfigMap in the Kubernetes cluster. There are two methods to perform this task.

Method 1: Modify the configuration in the values.yaml file

Use this method if you prefer to embed your Alloy configuration in the Helm chart’s values.yaml file.

Modify the configuration file contents directly in the values.yaml file:

alloy:
  configMap:
    content: |-
      // Write your Alloy config here:
      logging {
        level = "info"
        format = "logfmt"
      }

Run the following command in a terminal to upgrade your Alloy installation:
shell
```
helm upgrade --namespace <NAMESPACE> <RELEASE_NAME> grafana/alloy -f <VALUES_PATH>
```
Replace the following:
- <NAMESPACE>: The namespace you used for your Alloy installation.
- <RELEASE_NAME>: The name you used for your Alloy installation.
- <VALUES_PATH>: The path to your copy of values.yaml to use.

Method 2: Create a separate ConfigMap from a file

Use this method if you prefer to write your Alloy configuration in a separate file.

Write your configuration to a file, for example, config.alloy.

// Write your Alloy config here:
logging {
  level = "info"
  format = "logfmt"
}

Create a ConfigMap called alloy-config from the above file:
shell
```
kubectl create configmap --namespace <NAMESPACE> alloy-config "--from-file=config.alloy=./config.alloy"
```
Replace the following:
- <NAMESPACE>: The namespace you used for your Alloy installation.
Modify Helm Chart’s configuration in your values.yaml to use the existing ConfigMap:
YAML
```
alloy:
  configMap:
    create: false
    name: alloy-config
    key: config.alloy
```
Run the following command in a terminal to upgrade your Alloy installation:
shell
```
helm upgrade --namespace <NAMESPACE> <RELEASE_NAME> grafana/alloy -f <VALUES_PATH>
```
Replace the following:
- <NAMESPACE>: The namespace you used for your Alloy installation.
- <RELEASE_NAME>: The name you used for your Alloy installation.
- <VALUES_PATH>: The path to your copy of values.yaml to use.

Use Grafana Alloy as a proxy or aggregation layer

Mon, 30 Mar 2026 15:47:22 +0000

Use Grafana Alloy as a proxy or aggregation layer

In larger deployments, you can run one or more Alloy instances as proxies in front of other Alloy instances. This pattern reduces direct connections to backends such as Mimir, Loki, and Tempo, while centralizing egress traffic. You can apply consistent relabeling, filtering, or routing logic at the proxy layer, isolating edge instances from backend changes. This architecture also supports sharding and load distribution across multiple proxy instances.

In OpenTelemetry terminology, this deployment model is often referred to as gateway mode.

Note
The proxy configuration described here refers to using Alloy as a telemetry proxy that aggregates and forwards telemetry between instances. It doesn’t cover configuring Alloy to use a corporate HTTP proxy for outbound traffic, such as proxy_url or proxy_from_environment in prometheus.remote_write or loki.write.

Before you begin

Before you begin, ensure you have the following:

A working Alloy installation on your edge nodes.
Access to deploy additional Alloy instances as proxies.
A load balancer or ingress controller for routing traffic to proxy instances.
Network connectivity between edge instances, proxy instances, and backend services.

Architectural patterns

You can use two primary topologies when deploying Alloy as a proxy layer: push to proxy and pull from edge.

Push to proxy

In the push-to-proxy pattern, edge Alloy instances push telemetry to a pool of proxy Alloy instances. This is the most common and recommended pattern because it provides a straightforward mental model, scales cleanly in dynamic environments, and works across networks with NAT or segmented connectivity. You can centralize authentication and routing at the proxy layer, and the pattern is compatible with both Kubernetes and VM environments.

flowchart LR

  EdgeAlloy[Edge Alloy]
  LoadBalancer[Load Balancer]
  ProxyAlloy[Proxy Alloy x N]
  Backend[Backend]

  EdgeAlloy -->|remote_write| LoadBalancer
  LoadBalancer --> ProxyAlloy
  ProxyAlloy --> Backend

  %% Grafana styling
  classDef grafana fill:#ffffff,stroke:#F05A28,stroke-width:2px,rx:8,ry:8,color:#1f2937,font-weight:600;

  class EdgeAlloy,LoadBalancer,ProxyAlloy,Backend grafana

For metrics, edge instances push data using prometheus.remote_write to proxy instances running prometheus.receive_http. For logs, edge instances push data using loki.write to proxy instances running loki.source.api.

Sticky load balancing for metrics

Sticky load balancing ensures that requests with the same identifier, such as a time series or trace ID, are consistently routed to the same backend instance.

For Prometheus prometheus.remote_write traffic, you must ensure consistent routing per time series. When different proxy instances receive samples for the same series, you encounter out-of-order sample errors, increased ingestion load, and write-ahead log (WAL) churn.

Warning
Without sticky load balancing, metrics proxying can result in data loss or ingestion errors.

To avoid these issues, configure your load balancer with sticky sessions, consistent hashing, or L4 hash-based load balancing.

Pull from edge

In the pull-from-edge pattern, proxy Alloy instances scrape targets directly, using sharding such as hashmod to distribute targets across instances.

This pattern works for metrics because Prometheus-style scraping supports deterministic target sharding. For more information on distributing scrape load, refer to Distribute Prometheus metrics scrape load.

Note
The pull model doesn’t apply to logs. Logs must use a push model.

While technically possible for metrics, using proxy instances to scrape other Alloy instances isn’t recommended as a primary aggregation strategy. Push-based aggregation using prometheus.remote_write provides clearer scaling characteristics, simpler configuration management, and better compatibility with dynamic environments.

Configure metrics proxying

You can use the push pattern to proxy metrics between edge and proxy instances.

Configure edge instances for metrics

Edge instances use prometheus.scrape to scrape metrics locally and prometheus.remote_write to push them to proxy instances. The following example configuration scrapes a local Node Exporter and pushes metrics to a proxy:

prometheus.scrape "node" {
  targets = [{
    __address__ = "localhost:9100"
  }]
  forward_to = [prometheus.remote_write.to_proxy.receiver]
}

prometheus.remote_write "to_proxy" {
  endpoint {
    url = "https://<PROXY_LOAD_BALANCER>/api/v1/metrics/write"
  }
}

Replace the following:

<PROXY_LOAD_BALANCER>: The URL of your load balancer in front of the proxy Alloy instances.

Note
<PROXY_LOAD_BALANCER> is the address where edge instances send data. Your load balancer must forward each request path to the port exposed by your proxy Alloy instances.

For example:

Metrics: forward https://<PROXY_LOAD_BALANCER>/api/v1/metrics/write to proxy instances listening on port 12345

Logs: forward https://<PROXY_LOAD_BALANCER>/loki/api/v1/push to proxy instances listening on port 3100

Configure proxy instances for metrics

Proxy instances use prometheus.receive_http to receive metrics from edge instances and prometheus.remote_write to forward them to the backend. The following example configuration receives metrics and forwards them to Mimir:

prometheus.receive_http "ingest" {
  http {
    listen_address = "0.0.0.0"
    listen_port    = 12345
  }
  forward_to = [prometheus.remote_write.to_backend.receiver]
}

prometheus.remote_write "to_backend" {
  endpoint {
    url = "https://<MIMIR_ENDPOINT>/api/v1/push"
  }
}

Replace the following:

<MIMIR_ENDPOINT>: The URL of your Mimir instance.

You can add relabeling, filtering, or tenant routing at the proxy layer by inserting a prometheus.relabel component between the receiver and prometheus.remote_write.

Configure logs proxying

Logs must use a push model because you can’t pull logs from other Alloy instances. Use loki.write on edge instances and loki.source.api on proxy instances.

Configure edge instances for logs

Edge instances use loki.source.file to collect logs and loki.write to push them to proxy instances. The following example configuration collects logs from files and pushes them to a proxy:

loki.source.file "varlogs" {
  targets = [{
    __path__ = "/var/log/*.log"
  }]
  forward_to = [loki.write.to_proxy.receiver]
}

loki.write "to_proxy" {
  endpoint {
    url = "https://<PROXY_LOAD_BALANCER>/loki/api/v1/push"
  }
}

Replace the following:

<PROXY_LOAD_BALANCER>: The URL of your load balancer in front of the proxy Alloy instances.

Configure proxy instances for logs

Proxy instances use loki.source.api to receive logs from edge instances and loki.write to forward them to the backend. The following example configuration receives logs and forwards them to Loki:

loki.source.api "ingest" {
  http {
    listen_address = "0.0.0.0"
    listen_port    = 3100
  }
  forward_to = [loki.write.to_backend.receiver]
}

loki.write "to_backend" {
  endpoint {
    url = "https://<LOKI_ENDPOINT>/loki/api/v1/push"
  }
}

Replace the following:

<LOKI_ENDPOINT>: The URL of your Loki instance.

Configure load balancing

For metrics proxying, configure your load balancer to provide consistent routing so that samples for the same time series always reach the same proxy instance.

The following example shows a simplified NGINX configuration for consistent routing:

upstream alloy_proxies {
    hash $remote_addr consistent;
    server proxy1:12345;
    server proxy2:12345;
    server proxy3:12345;
}

server {
    listen 443 ssl;

    location /api/v1/metrics/write {
        proxy_pass http://alloy_proxies;
    }
}

In production, prefer hashing based on series-identifying headers or use an L4 load balancer with source hashing for better distribution.

Signal support

The following table shows what patterns each signal type supports:

Signal	Push through proxy	Pull with sharding	Notes
Metrics	Supported	Supported	Sticky routing required for push
Logs	Supported	Not supported	Push only
Traces	Depends	Generally no	Use OpenTelemetry-compatible receivers
Profiles	Supported	No	Edge `pyroscope.write`, proxy `pyroscope.receive_http`, backend `pyroscope.write`

For traces, you typically configure edge instances to send data to an OpenTelemetry-compatible receiver, such as otelcol.receiver.otlp, on proxy instances. The proxy instances then export to the backend using an appropriate exporter. Basic trace forwarding doesn’t require sticky routing, but if proxy instances run trace-derived components such as otelcol.connector.spanmetrics or otelcol.connector.servicegraph, you need consistent routing so all spans for a trace or service reach the same instance. You can use otelcol.exporter.loadbalancing on the edge instances to route by trace ID or service name. Alternatively, you can add a unique label per proxy instance and aggregate the resulting metrics in PromQL or Adaptive Metrics.

For profiles, edge instances use pyroscope.write to push to proxy instances running pyroscope.receive_http. Refer to that component for supported ingest endpoints and how it forwards to receivers such as pyroscope.write. For chained pyroscope.write traffic, load balancing multiple receivers, and timeout configuration, refer to the troubleshooting sections on that component and on pyroscope.write.

High availability and replication

When you run multiple proxy instances, ensure consistent routing for prometheus.remote_write traffic to prevent out-of-order errors. Avoid double-writing unless you intentionally want data replicated across backends.

For high availability pairs, configure proper external labels such as cluster and replica so your backend can deduplicate data correctly. Refer to your backend documentation for specific high availability deduplication requirements. For example, Mimir requires specific label configurations to handle replica traffic.

Operational considerations

Capacity planning

Proxy instances handle ingestion, WAL writes for metrics, retries, and fan-out to the backend. Monitor CPU usage, memory usage, queue depth, remote write retries, and out-of-order sample errors to ensure your proxy instances have adequate capacity.

For metrics proxying, memory usage scales with the number of active time series passing through the proxy, even if the proxy doesn’t scrape targets directly. Each proxy instance maintains series state, WAL segments, and retry queues. High-cardinality workloads can require significant memory, and you may need to scale proxy replicas to handle large active series counts.

Resource requirements vary significantly depending on active series count, sample rate, log volume, relabeling complexity, and retry behavior. There is no fixed ratio of series to memory or CPU that applies universally. Always validate sizing assumptions under representative load conditions before production deployment.

Test with realistic production write volume before rollout to establish baseline resource requirements.

Failure modes

When a proxy fails, edge instances retry sending data, which causes WAL growth on the edge instances. Load shifts to the remaining healthy proxies, which may increase their resource usage.

When load balancing isn’t sticky, you encounter out-of-order errors and ingestion amplification as samples for the same series arrive at different proxy instances.

In environments with high ingestion rates, non-sticky routing can also amplify ingestion load on the backend. When samples for the same series arrive at multiple proxy instances, retries and duplicate handling increase overall system pressure. Always validate your load balancer configuration before rolling out proxying in production.

Fleet management compared to proxying

Proxying is an architecture pattern for runtime data flow. Fleet management, which includes centralized configuration distribution, rollout control, and secret management, helps you operate large numbers of Alloy instances but is separate from the proxy behavior.

You can use fleet tooling to deploy proxy instances, manage their configurations, rotate credentials, and scale horizontally. However, proxying itself doesn’t require a fleet management solution.

If you use fleet management to deploy or manage proxy instances, configure prometheus.remote_write endpoints and self-monitoring pipelines consistently across edge and proxy layers. Fleet tooling controls configuration distribution and rollout, but it doesn’t automatically create or enforce a proxy topology. You must explicitly design the data flow, including which instances push to proxies and how load balancing and routing are configured.

For information about configuring a proxy for Fleet Management API traffic in restricted network environments, refer to Custom proxy setup in the Fleet Management documentation.

When to use a proxy layer

A proxy layer is especially useful when you operate large fleets of Alloy instances. Without aggregation, each instance maintains its own outbound connections to backends such as Grafana Cloud, Mimir, Loki, or Tempo. In high-scale environments, this can lead to large numbers of TCP connections from a single network boundary, increasing firewall session load, ephemeral port usage, and operational risk. A proxy layer consolidates outbound connections and reduces connection pressure on shared network infrastructure.

Use proxy Alloy instances when you need to limit backend exposure, centralize relabeling or filtering, or isolate edge instances from backend authentication changes. A proxy layer also helps when you want to reduce outbound internet access from edge nodes or operate in segmented or air-gapped environments.

Avoid adding a proxy layer if you don’t need centralized control, already use a gateway such as the Mimir or Loki gateway, or want the simplest architecture possible.

Next steps

Configure clustering to distribute workload across Alloy instances.
Distribute Prometheus metrics scrape load using clustering and auto-distribution.
Deploy Alloy to learn about other deployment topologies.

Configure Grafana Alloy on Linux

Mon, 30 Mar 2026 15:47:22 +0000

Configure Grafana Alloy on Linux

To configure Alloy on Linux, perform the following steps:

Edit the default configuration file at /etc/alloy/config.alloy.
Run the following command in a terminal to reload the configuration file:
shell
```
sudo systemctl reload alloy
```

To change the configuration file used by the service, perform the following steps:

Edit the environment file for the service:
- Debian or Ubuntu: edit /etc/default/alloy
- RHEL/Fedora or SUSE/openSUSE: edit /etc/sysconfig/alloy
Change the contents of the CONFIG_FILE environment variable to point at the new configuration file.
Restart the Alloy service:
shell
```
sudo systemctl restart alloy
```

Pass additional command-line flags

By default, the Alloy service launches with the run command, passing the following flags:

--storage.path=/var/lib/alloy

To pass additional command-line flags to the Alloy binary, perform the following steps:

Edit the environment file for the service:
- Debian-based systems: edit /etc/default/alloy
- RedHat or SUSE-based systems: edit /etc/sysconfig/alloy
Change the contents of the CUSTOM_ARGS environment variable to specify command-line flags to pass.
Restart the Alloy service:
shell
```
sudo systemctl restart alloy
```

To see the list of valid command-line flags that can be passed to the service, refer to the documentation for the run command.

Expose the UI to other machines

By default, Alloy listens on the local network for its HTTP server. This prevents other machines on the network from being able to access the UI for debugging.

To expose the UI to other machines, complete the following steps:

Follow Pass additional command-line flags to edit command line flags passed to Alloy
Add the following command line argument to CUSTOM_ARGS:
shell
```
--server.http.listen-addr=<LISTEN_ADDR>:12345
```
Replace the following:
- <LISTEN_ADDR>: An IP address which other machines on the network have access to. For example, the IP address of the machine Alloy is running on.
  
  To listen on all interfaces, replace <LISTEN_ADDR> with 0.0.0.0.

Configure Grafana Alloy on macOS

Mon, 30 Mar 2026 15:47:22 +0000

Configure Grafana Alloy on macOS

To configure Alloy on macOS, perform the following steps:

Edit the default configuration file at $(brew --prefix)/etc/alloy/config.alloy.
Run the following command in a terminal to restart the Alloy service:
shell
```
brew services restart  grafana/grafana/alloy
```

Configure the Alloy service

Note
Due to limitations in Homebrew, customizing the service used by Alloy on macOS requires changing the Homebrew formula and reinstalling Alloy.

To customize the Alloy service on macOS, perform the following steps:

Run the following command in a terminal:
shell
```
brew edit grafana/grafana/alloy
```
This opens the Alloy Homebrew Formula in an editor.
Modify the service section as desired to change things such as:
- Location of log files.
Modify the COMMAND in the install section as desired to change things such as:
- The configuration file used by Alloy.
- Flags passed to the Alloy binary.
Save the modified file.
Reinstall the Alloy Formula by running the following command in a terminal:
shell
```
brew reinstall --formula  grafana/grafana/alloy
```
Restart the Alloy service by running the command in a terminal:
shell
```
brew services restart  grafana/grafana/alloy
```

Configure environment variables

You can use environment variables to control the run-time behavior of Alloy. These environment variables are set in $(brew --prefix)/etc/alloy/config.env

To add the environment variables:

Edit the file at $(brew --prefix)/etc/alloy/config.env.
Add the specific environment variables you need.
Restart Alloy.

For example, you can add the following environment variables to $(brew --prefix)/etc/alloy/config.env:

export GCLOUD_RW_API_KEY="glc_xxx"
export GCLOUD_FM_COLLECTOR_ID="my-collector"
export GCLOUD_FM_LOG_PATH="/opt/homebrew/var/log/alloy.err.log"

Configure command line flags

You can use the file at $(brew --prefix)/etc/alloy/extra-args.txt to pass multiple command line flags to Alloy.

To add the command line flags:

Edit the file at $(brew --prefix)/etc/alloy/extra-args.txt.
Add the specific flags you need.
Restart Alloy.

For example, you can add the following command line flag in $(brew --prefix)/etc/alloy/extra-args.txt to enable the experimental components in Alloy.

--stability.level=experimental

Expose the UI to other machines

By default, Alloy listens on the local network for its HTTP server. This prevents other machines on the network from being able to access the UI for debugging.

To expose the UI to other machines, complete the following steps:

Follow Configure the Alloy service steps to edit command line flags passed to Alloy.
Modify the COMMAND line in the install section containing --server.http.listen-addr=127.0.0.1:12345, and replace 127.0.0.1 with the IP address that other machines on the network have access to. For example, the IP address of the machine Alloy is running on.

To listen on all interfaces, replace 127.0.0.1 with 0.0.0.0.

Configure Grafana Alloy on Windows

Mon, 30 Mar 2026 15:47:22 +0000

Configure Grafana Alloy on Windows

To configure Alloy on Windows, perform the following steps:

Edit the default configuration file at %PROGRAMFILES%\GrafanaLabs\Alloy\config.alloy.
Restart the Alloy service:
1. Open the Windows Services manager:
  1. Right click on the Start Menu and select Run.
  2. Type services.msc and click OK.
2. Right click on the service called Alloy.
3. Click on All Tasks > Restart.

Change command-line arguments

By default, the Alloy service will launch and pass the following arguments to the Alloy binary:

run
%PROGRAMFILES%\GrafanaLabs\Alloy\config.alloy
--storage.path=%PROGRAMDATA%\GrafanaLabs\Alloy\data

To change the set of command-line arguments passed to the Alloy binary, perform the following steps:

Open the Registry Editor:
1. Right click on the Start Menu and select Run.
2. Type regedit and click OK.
Navigate to the key at the path HKEY_LOCAL_MACHINE\SOFTWARE\GrafanaLabs\Alloy.
Double-click on the value called Arguments*.
In the dialog box, enter the arguments to pass to the Alloy binary. Make sure that each argument is on its own line.
Restart the Alloy service:
1. Open the Windows Services manager:
  1. Right click on the Start Menu and select Run.
  2. Type services.msc and click OK.
2. Right click on the service called Alloy.
3. Click on All Tasks > Restart.

Change environment variable values

The Go runtime provides several ways to modify the execution of a binary using environment variables.

To change the environment variables used by Alloy, perform the following steps.

Open the Registry Editor:
1. Right click on the Start Menu and select Run.
2. Type regedit and click OK.
Navigate to the key at the path HKEY_LOCAL_MACHINE\SOFTWARE\GrafanaLabs\Alloy.
Double-click on the multi-string value called Environment*.
In the dialog box, enter the environment variable values to pass to the Alloy binary. Make sure that each variable is on its own line.
Restart the Alloy service:
1. Open the Windows Services manager (services.msc):
  1. Right click on the Start Menu and select Run.
  2. Type services.msc and click OK.
2. Right click on the service called Alloy.
3. Click on All Tasks > Restart.

Expose the UI to other machines

By default, Alloy listens on the local network for its HTTP server. This prevents other machines on the network from being able to access the UI for debugging.

To expose the UI to other machines, complete the following steps:

Follow Change command-line arguments to edit command line flags passed to Alloy.
Add the following command line argument:
shell
```
--server.http.listen-addr=LISTEN_ADDR:12345
```
Replace the following:
- <LISTEN_ADDR>: An IP address which other machines on the network have access to. For example, the IP address of the machine Alloy is running on.
  
  To listen on all interfaces, replace <LISTEN_ADDR> with 0.0.0.0.

Configure Windows permissions

To effectively monitor Windows telemetry with Alloy, the user account you use to run Alloy requires specific access permissions. These permissions ensure Alloy can collect the necessary data, manage its local storage, and communicate with other services. The exact permissions depend on your system’s security configuration and the specific telemetry you need to collect.

Windows security groups

To collect common Windows telemetry, for example event logs and performance counters, the user account you use to run Alloy should be a member of the following Windows security groups. These groups provide the minimum required read access.

Event Log Readers

This group allows members to read data from local event logs, including Application, System, Security, and other custom logs. This is essential for any Alloy configuration that collects Windows Event Log data.
Performance Monitor Users

This group allows non-administrator users to access performance counter data. This group is important for Alloy components that collect Windows performance metrics, for example CPU, memory, disk I/O, and network usage.
Performance Log Users

This group is used to schedule logging of performance counter data and manage performance alerts. Performance Log Users is necessary for advanced or historical data collection scenarios, particularly those that involve the Windows Data Collector Sets.

File system and network permissions

Beyond the standard Windows groups, Alloy requires some specific permissions for its operational functions:

Storage directory permissions

Alloy needs read, write, and modify permissions to manage files and directories within its data storage location. The default location for the data storage is %PROGRAMDATA%\GrafanaLabs\Alloy\data.
Application log file read permissions

If you configure Alloy to read application log files directly from disk, the user account you use to run Alloy must have read access to those log files and their containing directories. You may need to modify the Access Control Lists for these resources or add the Alloy service account to a custom group that has these permissions.
Network access for telemetry destinations

Alloy needs network connectivity and, if applicable, proxy configuration, to communicate with its configured telemetry endpoints. This includes source endpoints for scraping metrics from Prometheus exporters and pulling logs from remote APIs and destination endpoints for writing metrics to Prometheus or Grafana Cloud, and sending logs to Loki. Make sure your firewall rules allow outbound connections from the Alloy host to these destinations on the necessary ports.
Registry access

The user account you use to run Alloy may need access to the Windows Registry to configure things like environment variables.
UI port listening permission

If you want to enable the Alloy UI, the user account you use to run Alloy must have permission to listen on the configured UI port. The default port is 12345.
Run as a service permission

By default, Alloy is installed and run as a Windows Service. The user account you use to run Alloy must have the Log on as a service user right.
Temporary directory management

Depending on how you configure components and data processing, Alloy might require permissions to create, read, and write temporary files in the system’s designated temporary directories.
Process and service enumeration

If you are using the process or service collectors within the integrated Windows Exporter, the user account you use to run Alloy must have permissions to enumerate all running processes and services on the system.

Run Alloy as a non-root user in Kubernetes

Mon, 30 Mar 2026 15:47:22 +0000

Run Alloy as a non-root user in Kubernetes

The Alloy Docker image contains two users:

A root user.
A non-root user named alloy with UID 473 and gid 473.

By default, the alloy binary runs as root. This is because some Alloy components like beyla.ebpf require root permissions.

You can configure a non-root user when you deploy Alloy in Kubernetes.

Configure Alloy to run as a non-root user in Kubernetes

Note
Running Alloy as a non-root user won’t work if you are using components like beyla.ebpf that require root rights.

To run Alloy as a non-root user, configure a security context for the Alloy container. If you are using the Grafana Helm chart you can add the following snippet to values.yaml:

alloy:
  securityContext:
    runAsUser: 473
    runAsGroup: 473

configReloader:
  securityContext:
    # this is the UID of the "nobody" user that the configReloader image runs as
    runAsUser: 65534
    runAsGroup: 65534

This configuration makes the Alloy binary run with UID 473 and GID 473 rather than as root. It also runs the config reloader sidecar as UID 65534 and GID 65534.

Is the root user a security risk?

Not really. The Linux kernel prevents Docker containers from accessing host resources. For example, Docker containers see a virtual file system rather than the host filesystem, a virtual network rather than the host network, a virtual process namespace rather than the host’s processes. Even if the user inside the Docker container is root it can’t break out of this virtual environment.

However, if there was a bug in the Linux kernel that allowed Docker containers to break out of the virtual environment, it would likely be easier to exploit this bug with a root user than with a non-root user. It’s worth noting that the attacker would not only need to find such a Linux kernel bug, but would also need to find a way to make Alloy exploit that bug.