arillso.agent.alloy role – Install and configure Grafana Alloy for monitoring and observability

Note

This role is part of the arillso.agent collection (version 2.1.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it use: ansible-galaxy collection install arillso.agent.

To use it in a playbook, specify: arillso.agent.alloy.

Entry point configure – Configure Grafana Alloy with templates and settings

Synopsis

  • This entry point handles the configuration of Grafana Alloy using templates and variable settings.

Parameters

Parameter

Comments

alloy_cluster_advertise_address

string

Advertise address for cluster communication

Default: ""

alloy_cluster_advertise_port

string

Port for cluster advertisement

Default: ""

alloy_cluster_discover_peers

string

Peer discovery configuration

Default: ""

alloy_cluster_join_peers

list / elements=string

List of peer addresses to join cluster

Default: []

alloy_cluster_name

string

Name of the Grafana Alloy cluster

Default: "alloy-cluster"

alloy_cluster_rejoin_interval

string

Interval for cluster rejoin attempts

Default: ""

alloy_clustering_enabled

boolean

Enables clustering for high availability

Choices:

  • false ← (default)

  • true

alloy_config_file

string

Configuration file path for Grafana Alloy

Default: "/etc/alloy/config.alloy"

alloy_config_template

string

Template path for Grafana Alloy configuration

Default: "etc/alloy/config.alloy.j2"

alloy_custom_exporters

list / elements=dictionary

Custom Prometheus exporters (including Tailscale)

Default: []

basic_auth

dictionary

Basic authentication

password

string / required

Password

username

string / required

Username

bearer_token

string

Bearer token

bearer_token_file

string

Path to bearer token file

enable_http2

boolean

Enable HTTP/2

Choices:

  • false

  • true ← (default)

follow_redirects

boolean

Follow HTTP redirects

Choices:

  • false

  • true ← (default)

job_name

string / required

Job name for Prometheus

metric_relabel_configs

list / elements=dictionary

Metric relabel configurations

metrics_path

string

Path to metrics

Default: "/metrics"

name

string / required

Name of the exporter

params

dictionary

URL parameters for scrape requests

remote_write

string

Remote write endpoint for this exporter

Default: "default"

scheme

string

Scheme for the exporter

Choices:

  • "http" ← (default)

  • "https"

scrape_interval

string

Scrape interval (e.g. ’30s’)

scrape_timeout

string

Scrape timeout (e.g. ’10s’)

targets

list / elements=dictionary / required

List of target addresses

address

string / required

Address of the exporter (host:port)

labels

dictionary

Additional labels for the target

tls_config

dictionary

TLS configuration

ca_file

string

CA certificate file

cert_file

string

Client certificate file

insecure_skip_verify

boolean

Skip TLS certificate verification

Choices:

  • false ← (default)

  • true

key_file

string

Private key file

server_name

string

Server name for TLS verification

alloy_env_file

string

Environment file path for Grafana Alloy service

Default: "/etc/default/alloy"

alloy_env_template

string

Template path for Grafana Alloy environment file

Default: "etc/default/alloy.j2"

alloy_external_labels

dictionary

External labels added to all metrics and logs

Default: {}

alloy_grafana_cloud_fleet_token

string

Grafana Cloud Fleet Management API token, rendered only when alloy_remotecfg_enabled is true. Supply through Ansible Vault.

Default: ""

alloy_grafana_cloud_fleet_user

string

Grafana Cloud Fleet Management username, rendered only when alloy_remotecfg_enabled is true.

Default: ""

alloy_grafana_cloud_loki_token

string

Grafana Cloud Loki API token. Supply through Ansible Vault or the CI environment, never in plain group_vars.

Default: ""

alloy_grafana_cloud_loki_user

string

Grafana Cloud Loki username (instance ID), written to the environment file as GRAFANA_CLOUD_LOKI_USER.

Default: ""

alloy_grafana_cloud_prometheus_token

string

Grafana Cloud Prometheus API token. Supply through Ansible Vault or the CI environment, never in plain group_vars.

Default: ""

alloy_grafana_cloud_prometheus_user

string

Grafana Cloud Prometheus username (instance ID), written to the environment file as GRAFANA_CLOUD_PROMETHEUS_USER.

Default: ""

alloy_group

string

System group for Grafana Alloy service

Default: "alloy"

alloy_grpc_server_enabled

boolean

Enable gRPC server for Alloy clustering and remote calls

Choices:

  • false ← (default)

  • true

alloy_log_format

string

Log format for Grafana Alloy

Choices:

  • "logfmt" ← (default)

  • "json"

alloy_log_level

string

Log level for Grafana Alloy

Choices:

  • "debug"

  • "info" ← (default)

  • "warn"

  • "error"

alloy_loki_clients

list / elements=dictionary

List of Loki client configurations

Default: [{"name": "default", "url": "http://localhost:3100/loki/api/v1/push"}]

basic_auth

dictionary

Basic authentication configuration

password

string / required

Password for basic auth

username

string / required

Username for basic auth

bearer_token

string

Bearer token for authentication

bearer_token_file

string

Path to bearer token file

external_labels

dictionary

External labels for all logs

headers

dictionary

Additional HTTP headers

name

string / required

Name of the Loki client

queue_config

dictionary

Queue configuration for Loki client

capacity

string

Number of logs to buffer (as string with units, e.g. ‘2500MiB’)

drain_timeout

string

Maximum amount of time to wait for the queue to be drained on shutdown (e.g. ’30s’)

tenant_id

string

Tenant ID for multi-tenant Loki instances

tls_config

dictionary

TLS configuration

url

string / required

URL of the Loki endpoint

alloy_loki_enabled

boolean

Enables Loki log collection

Choices:

  • false ← (default)

  • true

alloy_loki_file_sources

list / elements=dictionary

Loki file source configurations

Default: []

alloy_loki_journal_enabled

boolean

Enables systemd journal log collection

Choices:

  • false ← (default)

  • true

alloy_loki_journal_matches

list / elements=string

Journal matches for filtering

Default: []

alloy_loki_journal_max_age

string

Maximum age for journal entries

Default: ""

alloy_loki_journal_relabel_rules

list / elements=dictionary

Relabel rules for journal entries

Default: []

alloy_loki_journal_write_to

string

Write target for journal entries

Default: "default"

alloy_loki_process_configs

list / elements=dictionary

Loki process pipeline configurations

Default: []

alloy_max_cpu

string

Maximum CPU limit for Alloy service (e.g., ‘500m’, ‘1.0’)

Default: ""

alloy_max_memory

string

Maximum memory limit for Alloy service (e.g., ‘256Mi’, ‘1Gi’)

Default: ""

alloy_no_log_config

boolean

no_log toggle for the main config task, which renders the alloy_remotecfg secrets; set false to surface a template error the censored output otherwise hides.

Choices:

  • false

  • true ← (default)

alloy_no_log_env_file

boolean

no_log toggle for the environment file task; set false to surface a template error the censored output otherwise hides.

Choices:

  • false

  • true ← (default)

alloy_otel_enabled

boolean

Enables OpenTelemetry support

Choices:

  • false ← (default)

  • true

alloy_otel_exporters

list / elements=dictionary

List of OpenTelemetry exporters

Default: []

endpoint

string

Endpoint URL of the exporter

headers

dictionary

HTTP headers

name

string / required

Name of the exporter

timeout

string

Timeout for exporter requests

tls

dictionary

TLS configuration

type

string / required

Type of the exporter

Choices:

  • "otlp"

  • "jaeger"

  • "zipkin"

  • "logging"

  • "prometheus"

  • "kafka"

  • "file"

  • "datadog"

alloy_otel_grpc_endpoint

string

gRPC endpoint for OpenTelemetry receiver

Default: "0.0.0.0:4317"

alloy_otel_grpc_tls

dictionary

TLS configuration for gRPC endpoint

Default: {}

alloy_otel_http_endpoint

string

HTTP endpoint for OpenTelemetry receiver

Default: "0.0.0.0:4318"

alloy_otel_http_tls

dictionary

TLS configuration for HTTP endpoint

Default: {}

alloy_otel_processor_attributes

dictionary

Attributes processor configuration

Default: {}

alloy_otel_processor_batch

dictionary

Batch processor configuration

Default: {}

alloy_otel_processor_resource

dictionary

Resource processor configuration

Default: {}

alloy_otel_processors_enabled

boolean

Enables OpenTelemetry processors

Choices:

  • false ← (default)

  • true

alloy_otel_traces_output

string

Output target for OpenTelemetry traces

Default: ""

alloy_prometheus_additional_scrape_configs

list / elements=dictionary

Additional Prometheus scrape configurations

Default: []

alloy_prometheus_enabled

boolean

Enables Prometheus metrics collection

Choices:

  • false ← (default)

  • true

alloy_prometheus_honor_labels

boolean

Honor labels from targets

Choices:

  • false ← (default)

  • true

alloy_prometheus_honor_timestamps

boolean

Honor timestamps from targets

Choices:

  • false

  • true ← (default)

alloy_prometheus_metrics_path

string

Default metrics path for Prometheus

Default: ""

alloy_prometheus_relabel_configs

list / elements=dictionary

List of Prometheus relabeling configurations for advanced label manipulation

Default: []

forward_to

string

The receiver to forward metrics to, typically a prometheus.remote_write component

max_cache_size

integer

Maximum number of entries to keep in the cache for relabeling operations

Default: 100000

name

string / required

Unique name for the relabeling component

rules

list / elements=dictionary / required

List of relabeling rules to apply

action

string

Action to perform on the label

Choices:

  • "replace" ← (default)

  • "keep"

  • "drop"

  • "hashmod"

  • "labelmap"

  • "labeldrop"

  • "labelkeep"

case_sensitive

boolean

Whether regex matching should be case sensitive

Choices:

  • false

  • true

keep_equal

boolean

For replace actions whether to keep the source value if the target and source are equal

Choices:

  • false

  • true

modulus

integer

Modulus for hashmod action

regex

string

Regular expression to extract value from source labels

replacement

string

Replacement for regex matches

separator

string

Separator to join source_label values

source_labels

list / elements=string

List of source labels to use as input

target_label

string

Label to modify with the extracted value

alloy_prometheus_remote_write

list / elements=dictionary

Prometheus remote write configuration

Default: [{"name": "default", "url": "http://localhost:9090/api/v1/write"}]

basic_auth

dictionary

Basic authentication configuration

password

string / required

Password for basic auth

username

string / required

Username for basic auth

bearer_token

string

Bearer token for authentication

bearer_token_file

string

Path to bearer token file

headers

dictionary

Additional HTTP headers

metadata_config

dictionary

Metadata configuration

name

string / required

Name of the remote write target

queue_config

dictionary

Queue configuration for remote write

backoff_factor

integer

Factor to increase backoff for subsequent retries

batch_send_deadline

string

Maximum time samples will wait in buffer (e.g. ‘5s’)

capacity

integer

Number of samples to buffer per shard

max_backoff

string

Maximum retry delay (e.g. ‘1m’)

max_samples_per_send

integer

Maximum number of samples per send

max_shards

integer

Maximum number of shards, i.e. amount of concurrency

min_backoff

string

Initial retry delay (e.g. ‘1s’)

min_shards

integer

Minimum number of shards to keep running

retry_on_http_429

boolean

Retry when an HTTP 429 status code is received

Choices:

  • false

  • true ← (default)

sample_age_limit

string

Maximum age of samples to send (e.g. ‘2m’)

Default: "0s"

timeout

string

Timeout for remote write requests

tls_config

dictionary

TLS configuration

url

string / required

URL of the remote write endpoint

alloy_prometheus_scrape_interval

string

Default scrape interval for Prometheus

Default: ""

alloy_prometheus_scrape_timeout

string

Default scrape timeout for Prometheus

Default: ""

alloy_remotecfg

dictionary

Remote configuration using the remotecfg block (only one per config file)

Default: {}

attributes

dictionary

A set of self-reported attributes (excludes collector.* prefix)

Default: {}

authorization

dictionary

Configure generic authorization for the endpoint

credentials

string

Secret value of the authorization credentials

credentials_file

string

File containing the authorization credentials

type

string

Authorization type, for example Bearer

basic_auth

dictionary

Configure basic_auth for authenticating to the endpoint

password

string

Basic auth password

password_file

string

File containing the basic auth password

username

string / required

Basic auth username

bearer_token

string

Bearer token to authenticate with

bearer_token_file

string

File containing a bearer token to authenticate with

enable_http2

boolean

Whether HTTP2 is supported for requests

Choices:

  • false

  • true ← (default)

follow_redirects

boolean

Whether redirects returned by the server should be followed

Choices:

  • false

  • true ← (default)

id

string

A self-reported ID (defaults to random UUID if not set)

name

string

A human-readable name for the collector

Default: ""

oauth2

dictionary

Configure OAuth2 for authenticating to the endpoint

client_id

string

OAuth2 client ID

client_secret

string

OAuth2 client secret

client_secret_file

string

File containing the OAuth2 client secret

endpoint_params

dictionary

Optional parameters to append to the token URL

no_proxy

string

Comma-separated hosts that bypass the proxy

proxy_connect_header

dictionary

Specifies headers to send to proxies during CONNECT requests

proxy_from_environment

boolean

Use the proxy URL from the environment variables

Choices:

  • false

  • true

proxy_url

string

HTTP proxy to send requests through

scopes

list / elements=string

List of scopes to authenticate with

tls_config

dictionary

Configure TLS settings for the OAuth2 token request

ca_file

string

CA certificate to validate the server with

ca_pem

string

CA PEM-encoded text to validate the server with

cert_file

string

Certificate file for client authentication

cert_pem

string

Certificate PEM-encoded text for client authentication

insecure_skip_verify

boolean

Disables validation of the server certificate

Choices:

  • false

  • true

key_file

string

Key file for client authentication

key_pem

string

Key PEM-encoded text for client authentication

min_version

string

Minimum acceptable TLS version

server_name

string

ServerName extension to indicate the name of the server

token_url

string

URL to fetch the OAuth2 token from

poll_frequency

string

How often to poll the API for new configuration (minimum 10s)

Default: "1m"

tls_config

dictionary

Configure TLS settings for connecting to the endpoint

ca_file

string

CA certificate to validate the server with

ca_pem

string

CA PEM-encoded text to validate the server with

cert_file

string

Certificate file for client authentication

cert_pem

string

Certificate PEM-encoded text for client authentication

insecure_skip_verify

boolean

Disables validation of the server certificate

Choices:

  • false

  • true

key_file

string

Key file for client authentication

key_pem

string

Key PEM-encoded text for client authentication

min_version

string

Minimum acceptable TLS version

server_name

string

ServerName extension to indicate the name of the server

url

string

The address of the API to poll for configuration (required when alloy_remotecfg_enabled is true)

alloy_remotecfg_enabled

boolean

Enable Grafana remote configuration management via remotecfg block

Choices:

  • false ← (default)

  • true

alloy_server_grpc_listen_address

string

gRPC listen address for Grafana Alloy server

Default: "0.0.0.0"

alloy_server_grpc_max_recv_msg_size

string

Maximum receive message size for gRPC server

Default: ""

alloy_server_grpc_max_send_msg_size

string

Maximum send message size for gRPC server

Default: ""

alloy_server_http_listen_address

string

HTTP listen address for Grafana Alloy server

Default: "0.0.0.0"

alloy_server_http_pprof_enabled

boolean

Enables pprof performance profiling

Choices:

  • false ← (default)

  • true

alloy_server_log_level

string

Log level for server component

Default: ""

alloy_server_log_source_ips

boolean

Logs source IP addresses in server logs

Choices:

  • false ← (default)

  • true

alloy_service_name

string

Name of the systemd service

Default: "alloy"

alloy_service_override_dir

string

Directory for systemd service overrides

Default: "/etc/systemd/system/alloy.service.d"

alloy_service_override_file

string

File path for systemd service override

Default: "/etc/systemd/system/alloy.service.d/override.conf"

alloy_service_override_template

string

Template path for systemd service override

Default: "etc/systemd/system/alloy.service.d/override.conf.j2"

alloy_textfile_collector_directory

string

Directory the textfile collector scripts write .prom files to; created unconditionally by the role. Defaults to alloy_node_exporter_config.textfile_directory so it stays in sync with the path prometheus.exporter.unix actually scrapes. Override only if scripts must write somewhere other than what Alloy reads.

Default: "/var/lib/node_exporter/textfile_collector"

alloy_textfile_script_directory

string

Filesystem location for textfile-collector scripts deployed by this role.

Default: "/usr/local/lib/node-textfile"

alloy_textfile_scripts

list / elements=dictionary

Scripts deployed as oneshot systemd .service + .timer pairs that write .prom files into alloy_textfile_collector_directory.

Default: []

description

string

Human-readable description for the systemd Unit Description= field.

interval

string

systemd OnUnitActiveSec= value (e.g. ’30s’).

Default: "60s"

name

string / required

Identifier; used as systemd unit suffix and script basename.

on_boot_sec

string

systemd OnBootSec= value.

Default: "15s"

src

string / required

Script source path, resolved via Ansible’s files/ search path.

alloy_user

string

System user for Grafana Alloy service

Default: "alloy"

alloy_web_server_enabled

boolean

Enable HTTP web server for Alloy UI and API

Choices:

  • false

  • true ← (default)

Authors

  • Simon Bärlocher

Entry point install – Install Grafana Alloy package and dependencies

Synopsis

  • This entry point only handles the installation of Grafana Alloy package and required dependencies without configuration.

Parameters

Parameter

Comments

alloy_config_file

string

Configuration file path for Grafana Alloy

Default: "/etc/alloy/config.alloy"

alloy_grafana_gpg_key_url

string

URL for Grafana GPG key (OS-specific)

alloy_grafana_keyring_path

string

Path for Grafana GPG keyring (Debian/Ubuntu only)

alloy_grafana_repository

string

Grafana repository configuration (APT for Debian/Ubuntu, RPM for RedHat/CentOS)

alloy_group

string

System group for Grafana Alloy service

Default: "alloy"

alloy_log_file

string

Log file for Grafana Alloy (empty for stdout)

Default: ""

alloy_package_dependencies

list / elements=string

OS-specific package dependencies for Grafana Alloy installation

alloy_package_name

string

Name of the Grafana Alloy package

Default: "alloy"

alloy_package_only

boolean

Install only the package without repository setup (for distributions with Alloy in default repos)

Choices:

  • false ← (default)

  • true

alloy_package_state

string

State of the Grafana Alloy package

Choices:

  • "present" ← (default)

  • "latest"

  • "absent"

alloy_service_name

string

Name of the systemd service

Default: "alloy"

alloy_storage_path

string

Storage path for Grafana Alloy data

Default: "/var/lib/alloy"

alloy_user

string

System user for Grafana Alloy service

Default: "alloy"

Authors

  • Simon Bärlocher

Entry point main – Install and configure Grafana Alloy for monitoring and observability

Synopsis

  • This role installs and configures Grafana Alloy via official package sources for collecting, transforming, and forwarding telemetry data.

Parameters

Parameter

Comments

alloy_advanced_node_exporter_enabled

boolean

Enable advanced Node Exporter integration with customized configuration

Choices:

  • false ← (default)

  • true

alloy_cluster_advertise_address

string

Advertise address for cluster communication

Default: ""

alloy_cluster_advertise_port

string

Port for cluster advertisement

Default: ""

alloy_cluster_discover_peers

string

Peer discovery configuration

Default: ""

alloy_cluster_join_peers

list / elements=string

List of peer addresses to join cluster

Default: []

alloy_cluster_name

string

Name of the Grafana Alloy cluster

Default: "alloy-cluster"

alloy_cluster_rejoin_interval

string

Interval for cluster rejoin attempts

Default: ""

alloy_clustering_enabled

boolean

Enables clustering for high availability

Choices:

  • false ← (default)

  • true

alloy_config_file

string

Configuration file path for Grafana Alloy

Default: "/etc/alloy/config.alloy"

alloy_config_template

string

Template path for Grafana Alloy configuration

Default: "etc/alloy/config.alloy.j2"

alloy_custom_exporters

list / elements=dictionary

Custom Prometheus exporters (including Tailscale)

Default: []

basic_auth

dictionary

Basic authentication

password

string / required

Password

username

string / required

Username

bearer_token

string

Bearer token

bearer_token_file

string

Path to bearer token file

enable_http2

boolean

Enable HTTP/2

Choices:

  • false

  • true ← (default)

follow_redirects

boolean

Follow HTTP redirects

Choices:

  • false

  • true ← (default)

job_name

string / required

Job name for Prometheus

metric_relabel_configs

list / elements=dictionary

Metric relabel configurations

metrics_path

string

Path to metrics

Default: "/metrics"

name

string / required

Name of the exporter

params

dictionary

URL parameters for scrape requests

remote_write

string

Remote write endpoint for this exporter

Default: "default"

scheme

string

Scheme for the exporter

Choices:

  • "http" ← (default)

  • "https"

scrape_interval

string

Scrape interval (e.g. ’30s’)

scrape_timeout

string

Scrape timeout (e.g. ’10s’)

targets

list / elements=dictionary / required

List of target addresses

address

string / required

Address of the exporter (host:port)

labels

dictionary

Additional labels for the target

tls_config

dictionary

TLS configuration

ca_file

string

CA certificate file

cert_file

string

Client certificate file

insecure_skip_verify

boolean

Skip TLS certificate verification

Choices:

  • false ← (default)

  • true

key_file

string

Private key file

server_name

string

Server name for TLS verification

alloy_default_queue_config

dictionary

Default queue configuration to prevent undefined variable errors

Default: {}

alloy_enabled

boolean

Master switch: set to false to skip the role entirely

Choices:

  • false

  • true ← (default)

alloy_env_file

string

Environment file path for Grafana Alloy service

Default: "/etc/default/alloy"

alloy_env_template

string

Template path for Grafana Alloy environment file

Default: "etc/default/alloy.j2"

alloy_external_labels

dictionary

External labels added to all metrics and logs

Default: {}

alloy_grafana_cloud_fleet_token

string

Grafana Cloud Fleet Management API token, rendered only when alloy_remotecfg_enabled is true. Supply through Ansible Vault.

Default: ""

alloy_grafana_cloud_fleet_user

string

Grafana Cloud Fleet Management username, rendered only when alloy_remotecfg_enabled is true.

Default: ""

alloy_grafana_cloud_loki_token

string

Grafana Cloud Loki API token. Supply through Ansible Vault or the CI environment, never in plain group_vars.

Default: ""

alloy_grafana_cloud_loki_user

string

Grafana Cloud Loki username (instance ID), written to the environment file as GRAFANA_CLOUD_LOKI_USER.

Default: ""

alloy_grafana_cloud_prometheus_token

string

Grafana Cloud Prometheus API token. Supply through Ansible Vault or the CI environment, never in plain group_vars.

Default: ""

alloy_grafana_cloud_prometheus_user

string

Grafana Cloud Prometheus username (instance ID), written to the environment file as GRAFANA_CLOUD_PROMETHEUS_USER.

Default: ""

alloy_grafana_gpg_key_url

string

URL for Grafana GPG key (OS-specific)

alloy_grafana_keyring_path

string

Path for Grafana GPG keyring (Debian/Ubuntu only)

alloy_grafana_repository

string

Grafana repository configuration (APT for Debian/Ubuntu, RPM for RedHat/CentOS)

alloy_group

string

System group for Grafana Alloy service

Default: "alloy"

alloy_grpc_port

integer

gRPC port for Grafana Alloy server

Default: 12346

alloy_grpc_server_enabled

boolean

Enable gRPC server for Alloy clustering and remote calls

Choices:

  • false ← (default)

  • true

alloy_health_check_enabled

boolean

Enables health check after installation

Choices:

  • false

  • true ← (default)

alloy_journal_config

dictionary

Journal module configuration for log collection from systemd journal

Default: {"max_age": "12h0m0s", "relabel_rules": [{"source_labels": ["__journal__systemd_unit"], "target_label": "unit"}, {"source_labels": ["__journal__boot_id"], "target_label": "boot_id"}, {"source_labels": ["__journal__transport"], "target_label": "transport"}, {"source_labels": ["__journal_priority_keyword"], "target_label": "level"}]}

max_age

string

Maximum age of journal entries to read

Default: "12h0m0s"

relabel_rules

list / elements=dictionary

Relabel rules for journal entries

source_labels

list / elements=string

List of source labels to use as input

target_label

string

Label to set with the extracted value

alloy_journal_monitoring_enabled

boolean

Enable journal monitoring for log collection

Choices:

  • false ← (default)

  • true

alloy_log_file

string

Log file for Grafana Alloy (empty for stdout)

Default: ""

alloy_log_format

string

Log format for Grafana Alloy

Choices:

  • "logfmt" ← (default)

  • "json"

alloy_log_level

string

Log level for Grafana Alloy

Choices:

  • "debug"

  • "info" ← (default)

  • "warn"

  • "error"

alloy_loki_clients

list / elements=dictionary

List of Loki client configurations

Default: [{"name": "default", "url": "http://localhost:3100/loki/api/v1/push"}]

basic_auth

dictionary

Basic authentication configuration

password

string / required

Password for basic auth

username

string / required

Username for basic auth

bearer_token

string

Bearer token for authentication

bearer_token_file

string

Path to bearer token file

external_labels

dictionary

External labels for all logs

headers

dictionary

Additional HTTP headers

name

string / required

Name of the Loki client

queue_config

dictionary

Queue configuration for Loki client

capacity

string

Number of logs to buffer (as string with units, e.g. ‘2500MiB’)

drain_timeout

string

Maximum amount of time to wait for the queue to be drained on shutdown (e.g. ’30s’)

tenant_id

string

Tenant ID for multi-tenant Loki instances

tls_config

dictionary

TLS configuration

url

string / required

URL of the Loki endpoint

alloy_loki_enabled

boolean

Enables Loki log collection

Choices:

  • false ← (default)

  • true

alloy_loki_file_sources

list / elements=dictionary

Loki file source configurations

Default: []

alloy_loki_journal_enabled

boolean

Enables systemd journal log collection

Choices:

  • false ← (default)

  • true

alloy_loki_journal_matches

list / elements=string

Journal matches for filtering

Default: []

alloy_loki_journal_max_age

string

Maximum age for journal entries

Default: ""

alloy_loki_journal_relabel_rules

list / elements=dictionary

Relabel rules for journal entries

Default: []

alloy_loki_journal_write_to

string

Write target for journal entries

Default: "default"

alloy_loki_process_configs

list / elements=dictionary

Loki process pipeline configurations

Default: []

alloy_max_cpu

string

Maximum CPU limit for Alloy service (e.g., ‘500m’, ‘1.0’)

Default: ""

alloy_max_memory

string

Maximum memory limit for Alloy service (e.g., ‘256Mi’, ‘1Gi’)

Default: ""

alloy_no_log_config

boolean

no_log toggle for the main config task, which renders the alloy_remotecfg secrets; set false to surface a template error the censored output otherwise hides.

Choices:

  • false

  • true ← (default)

alloy_no_log_env_file

boolean

no_log toggle for the environment file task; set false to surface a template error the censored output otherwise hides.

Choices:

  • false

  • true ← (default)

alloy_node_exporter_config

dictionary

Advanced configuration for the integrated Node Exporter

Default: {"disable_collectors": ["ipvs", "btrfs", "infiniband", "xfs", "zfs"], "filesystem": {"fs_types_exclude": "^(autofs|binfmt_misc|bpf|cgroup2?|configfs|debugfs|devpts|devtmpfs|tmpfs|fusectl|hugetlbfs|iso9660|mqueue|nsfs|overlay|proc|procfs|pstore| rpc_pipefs|securityfs|selinuxfs|squashfs|sysfs|tracefs)$", "mount_points_exclude": "^/(dev|proc|run/credentials/.+|sys|var/lib/docker/.+)($|/)", "mount_timeout": "5s"}, "netclass": {"ignored_devices": "^(veth.*|cali.*|[a-f0-9]{15})$"}, "netdev": {"device_exclude": "^(veth.*|cali.*|[a-f0-9]{15})$"}, "procfs_path": "", "sysfs_path": "", "systemd": {"enable_restarts_metrics": true, "enable_start_time_metrics": true, "enable_task_metrics": false, "unit_exclude": [], "unit_include": []}, "textfile_directory": "/var/lib/node_exporter/textfile_collector"}

disable_collectors

list / elements=string

List of Node Exporter collectors to disable

environment

string

Environment tag for node metrics (e.g. production, staging)

filesystem

dictionary

Configuration for filesystem collector

fs_types_exclude

string

Regexp of filesystem types to exclude from collection

mount_points_exclude

string

Regexp of mount points to exclude from collection

mount_timeout

string

Timeout for collecting filesystem metrics

instance

string

Instance identifier override (defaults to ansible_facts[‘hostname’])

netclass

dictionary

Configuration for netclass collector

ignored_devices

string

Regexp of net devices to ignore for netclass collector

netdev

dictionary

Configuration for netdev collector

device_exclude

string

Regexp of net devices to exclude from collection

node_type

string

Node type tag for categorizing server roles (e.g. gateway, controller)

procfs_path

string

Path to procfs filesystem (used in container environments)

region

string

Region tag for geographic location of the node

sysfs_path

string

Path to sysfs filesystem (used in container environments)

systemd

dictionary

Configuration for systemd collector

enable_restarts_metrics

boolean

Enable restart metrics for systemd units

Choices:

  • false

  • true

enable_start_time_metrics

boolean

Enable start time metrics for systemd units

Choices:

  • false

  • true

enable_task_metrics

boolean

Enable task metrics for systemd units

Choices:

  • false

  • true

unit_exclude

list / elements=string

List of systemd units to exclude from metrics collection

unit_include

list / elements=string

List of systemd units to include in metrics collection

textfile_directory

string

Directory to read custom metrics files from

textfile_directory_pattern

string

Pattern of files to be read from textfile directory

alloy_node_exporter_metric_allowlist

list / elements=string

List of metrics to keep, filtering out all others to reduce network and storage usage

Default: []

alloy_otel_enabled

boolean

Enables OpenTelemetry support

Choices:

  • false ← (default)

  • true

alloy_otel_exporters

list / elements=dictionary

List of OpenTelemetry exporters

Default: []

endpoint

string

Endpoint URL of the exporter

headers

dictionary

HTTP headers

name

string / required

Name of the exporter

timeout

string

Timeout for exporter requests

tls

dictionary

TLS configuration

type

string / required

Type of the exporter

Choices:

  • "otlp"

  • "jaeger"

  • "zipkin"

  • "logging"

  • "prometheus"

  • "kafka"

  • "file"

  • "datadog"

alloy_otel_grpc_endpoint

string

gRPC endpoint for OpenTelemetry receiver

Default: "0.0.0.0:4317"

alloy_otel_grpc_tls

dictionary

TLS configuration for gRPC endpoint

Default: {}

alloy_otel_http_endpoint

string

HTTP endpoint for OpenTelemetry receiver

Default: "0.0.0.0:4318"

alloy_otel_http_tls

dictionary

TLS configuration for HTTP endpoint

Default: {}

alloy_otel_processor_attributes

dictionary

Attributes processor configuration

Default: {}

alloy_otel_processor_batch

dictionary

Batch processor configuration

Default: {}

alloy_otel_processor_resource

dictionary

Resource processor configuration

Default: {}

alloy_otel_processors_enabled

boolean

Enables OpenTelemetry processors

Choices:

  • false ← (default)

  • true

alloy_otel_traces_output

string

Output target for OpenTelemetry traces

Default: ""

alloy_package_dependencies

list / elements=string

OS-specific package dependencies for Grafana Alloy installation

alloy_package_name

string

Name of the Grafana Alloy package

Default: "alloy"

alloy_package_only

boolean

Install only the package without repository setup (for distributions with Alloy in default repos)

Choices:

  • false ← (default)

  • true

alloy_package_state

string

State of the Grafana Alloy package

Choices:

  • "present" ← (default)

  • "latest"

  • "absent"

alloy_port

integer

HTTP port for Grafana Alloy server

Default: 12345

alloy_prometheus_additional_scrape_configs

list / elements=dictionary

Additional Prometheus scrape configurations

Default: []

alloy_prometheus_enabled

boolean

Enables Prometheus metrics collection

Choices:

  • false ← (default)

  • true

alloy_prometheus_honor_labels

boolean

Honor labels from targets

Choices:

  • false ← (default)

  • true

alloy_prometheus_honor_timestamps

boolean

Honor timestamps from targets

Choices:

  • false

  • true ← (default)

alloy_prometheus_metrics_path

string

Default metrics path for Prometheus

Default: ""

alloy_prometheus_relabel_configs

list / elements=dictionary

List of Prometheus relabeling configurations for advanced label manipulation

Default: []

forward_to

string

The receiver to forward metrics to, typically a prometheus.remote_write component

max_cache_size

integer

Maximum number of entries to keep in the cache for relabeling operations

Default: 100000

name

string / required

Unique name for the relabeling component

rules

list / elements=dictionary / required

List of relabeling rules to apply

action

string

Action to perform on the label

Choices:

  • "replace" ← (default)

  • "keep"

  • "drop"

  • "hashmod"

  • "labelmap"

  • "labeldrop"

  • "labelkeep"

case_sensitive

boolean

Whether regex matching should be case sensitive

Choices:

  • false

  • true

keep_equal

boolean

For replace actions whether to keep the source value if the target and source are equal

Choices:

  • false

  • true

modulus

integer

Modulus for hashmod action

regex

string

Regular expression to extract value from source labels

replacement

string

Replacement for regex matches

separator

string

Separator to join source_label values

source_labels

list / elements=string

List of source labels to use as input

target_label

string

Label to modify with the extracted value

alloy_prometheus_remote_write

list / elements=dictionary

Prometheus remote write configuration

Default: [{"name": "default", "url": "http://localhost:9090/api/v1/write"}]

basic_auth

dictionary

Basic authentication configuration

password

string / required

Password for basic auth

username

string / required

Username for basic auth

bearer_token

string

Bearer token for authentication

bearer_token_file

string

Path to bearer token file

headers

dictionary

Additional HTTP headers

metadata_config

dictionary

Metadata configuration

name

string / required

Name of the remote write target

queue_config

dictionary

Queue configuration for remote write

backoff_factor

integer

Factor to increase backoff for subsequent retries

batch_send_deadline

string

Maximum time samples will wait in buffer (e.g. ‘5s’)

capacity

integer

Number of samples to buffer per shard

max_backoff

string

Maximum retry delay (e.g. ‘1m’)

max_samples_per_send

integer

Maximum number of samples per send

max_shards

integer

Maximum number of shards, i.e. amount of concurrency

min_backoff

string

Initial retry delay (e.g. ‘1s’)

min_shards

integer

Minimum number of shards to keep running

retry_on_http_429

boolean

Retry when an HTTP 429 status code is received

Choices:

  • false

  • true ← (default)

sample_age_limit

string

Maximum age of samples to send (e.g. ‘2m’)

Default: "0s"

timeout

string

Timeout for remote write requests

tls_config

dictionary

TLS configuration

url

string / required

URL of the remote write endpoint

alloy_prometheus_scrape_interval

string

Default scrape interval for Prometheus

Default: ""

alloy_prometheus_scrape_timeout

string

Default scrape timeout for Prometheus

Default: ""

alloy_remotecfg

dictionary

Remote configuration using the remotecfg block (only one per config file)

Default: {}

attributes

dictionary

A set of self-reported attributes (excludes collector.* prefix)

Default: {}

authorization

dictionary

Configure generic authorization for the endpoint

credentials

string

Secret value of the authorization credentials

credentials_file

string

File containing the authorization credentials

type

string

Authorization type, for example Bearer

basic_auth

dictionary

Configure basic_auth for authenticating to the endpoint

password

string

Basic auth password

password_file

string

File containing the basic auth password

username

string / required

Basic auth username

bearer_token

string

Bearer token to authenticate with

bearer_token_file

string

File containing a bearer token to authenticate with

enable_http2

boolean

Whether HTTP2 is supported for requests

Choices:

  • false

  • true ← (default)

follow_redirects

boolean

Whether redirects returned by the server should be followed

Choices:

  • false

  • true ← (default)

id

string

A self-reported ID (defaults to random UUID if not set)

name

string

A human-readable name for the collector

Default: ""

oauth2

dictionary

Configure OAuth2 for authenticating to the endpoint

client_id

string

OAuth2 client ID

client_secret

string

OAuth2 client secret

client_secret_file

string

File containing the OAuth2 client secret

endpoint_params

dictionary

Optional parameters to append to the token URL

no_proxy

string

Comma-separated hosts that bypass the proxy

proxy_connect_header

dictionary

Specifies headers to send to proxies during CONNECT requests

proxy_from_environment

boolean

Use the proxy URL from the environment variables

Choices:

  • false

  • true

proxy_url

string

HTTP proxy to send requests through

scopes

list / elements=string

List of scopes to authenticate with

tls_config

dictionary

Configure TLS settings for the OAuth2 token request

ca_file

string

CA certificate to validate the server with

ca_pem

string

CA PEM-encoded text to validate the server with

cert_file

string

Certificate file for client authentication

cert_pem

string

Certificate PEM-encoded text for client authentication

insecure_skip_verify

boolean

Disables validation of the server certificate

Choices:

  • false

  • true

key_file

string

Key file for client authentication

key_pem

string

Key PEM-encoded text for client authentication

min_version

string

Minimum acceptable TLS version

server_name

string

ServerName extension to indicate the name of the server

token_url

string

URL to fetch the OAuth2 token from

poll_frequency

string

How often to poll the API for new configuration (minimum 10s)

Default: "1m"

tls_config

dictionary

Configure TLS settings for connecting to the endpoint

ca_file

string

CA certificate to validate the server with

ca_pem

string

CA PEM-encoded text to validate the server with

cert_file

string

Certificate file for client authentication

cert_pem

string

Certificate PEM-encoded text for client authentication

insecure_skip_verify

boolean

Disables validation of the server certificate

Choices:

  • false

  • true

key_file

string

Key file for client authentication

key_pem

string

Key PEM-encoded text for client authentication

min_version

string

Minimum acceptable TLS version

server_name

string

ServerName extension to indicate the name of the server

url

string

The address of the API to poll for configuration (required when alloy_remotecfg_enabled is true)

alloy_remotecfg_enabled

boolean

Enable Grafana remote configuration management via remotecfg block

Choices:

  • false ← (default)

  • true

alloy_server_grpc_listen_address

string

gRPC listen address for Grafana Alloy server

Default: "0.0.0.0"

alloy_server_grpc_max_recv_msg_size

string

Maximum receive message size for gRPC server

Default: ""

alloy_server_grpc_max_send_msg_size

string

Maximum send message size for gRPC server

Default: ""

alloy_server_http_listen_address

string

HTTP listen address for Grafana Alloy server

Default: "0.0.0.0"

alloy_server_http_pprof_enabled

boolean

Enables pprof performance profiling

Choices:

  • false ← (default)

  • true

alloy_server_log_level

string

Log level for server component

Default: ""

alloy_server_log_source_ips

boolean

Logs source IP addresses in server logs

Choices:

  • false ← (default)

  • true

alloy_service_file

string

Path to the systemd service file for Grafana Alloy

Default: "/etc/systemd/system/alloy.service"

alloy_service_name

string

Name of the systemd service

Default: "alloy"

alloy_service_override_dir

string

Directory for systemd service overrides

Default: "/etc/systemd/system/alloy.service.d"

alloy_service_override_file

string

File path for systemd service override

Default: "/etc/systemd/system/alloy.service.d/override.conf"

alloy_service_override_template

string

Template path for systemd service override

Default: "etc/systemd/system/alloy.service.d/override.conf.j2"

alloy_storage_path

string

Storage path for Grafana Alloy data

Default: "/var/lib/alloy"

alloy_textfile_collector_directory

string

Directory the textfile collector scripts write .prom files to; created unconditionally by the role. Defaults to alloy_node_exporter_config.textfile_directory so it stays in sync with the path prometheus.exporter.unix actually scrapes. Override only if scripts must write somewhere other than what Alloy reads.

Default: "/var/lib/node_exporter/textfile_collector"

alloy_textfile_script_directory

string

Filesystem location for textfile-collector scripts deployed by this role.

Default: "/usr/local/lib/node-textfile"

alloy_textfile_scripts

list / elements=dictionary

Scripts deployed as oneshot systemd .service + .timer pairs that write .prom files into alloy_textfile_collector_directory.

Default: []

description

string

Human-readable description for the systemd Unit Description= field.

interval

string

systemd OnUnitActiveSec= value (e.g. ’30s’).

Default: "60s"

name

string / required

Identifier; used as systemd unit suffix and script basename.

on_boot_sec

string

systemd OnBootSec= value.

Default: "15s"

src

string / required

Script source path, resolved via Ansible’s files/ search path.

alloy_user

string

System user for Grafana Alloy service

Default: "alloy"

alloy_version

string

Version of the Grafana Alloy package to pin on apt and dnf hosts. Every run moves the host to exactly this version, downgrades included. An empty string installs whatever the repository offers and leaves later upgrades to the host.

Default: "1.21.3"

alloy_web_server_enabled

boolean

Enable HTTP web server for Alloy UI and API

Choices:

  • false

  • true ← (default)

Authors

  • Simon Bärlocher

Entry point service – Manage Grafana Alloy systemd service

Synopsis

  • This entry point manages the systemd service for Grafana Alloy, including starting, stopping, and health checks.

Parameters

Parameter

Comments

alloy_config_file

string

Configuration file path for Grafana Alloy

Default: "/etc/alloy/config.alloy"

alloy_group

string

System group for Grafana Alloy service

Default: "alloy"

alloy_grpc_port

integer

gRPC port for Grafana Alloy server

Default: 12346

alloy_health_check_enabled

boolean

Enables health check after installation

Choices:

  • false

  • true ← (default)

alloy_port

integer

HTTP port for Grafana Alloy server

Default: 12345

alloy_service_name

string

Name of the systemd service

Default: "alloy"

alloy_user

string

System user for Grafana Alloy service

Default: "alloy"

alloy_version

string

Version of the Grafana Alloy package to pin on apt and dnf hosts. Every run moves the host to exactly this version, downgrades included. An empty string installs whatever the repository offers and leaves later upgrades to the host.

Default: "1.21.3"

Authors

  • Simon Bärlocher