--- title: "remotecfg | Grafana Alloy documentation" description: "Learn about the remotecfg configuration block" --- # `remotecfg` `remotecfg` is an optional configuration block that enables Alloy to fetch and load the configuration from a remote endpoint. You specify `remotecfg` without a label and can only include it once per configuration file. The [API definition](https://github.com/grafana/alloy-remote-config) for managing and fetching configuration that the `remotecfg` block uses is available under the Apache 2.0 license. > Note > > The `remotecfg` block requires a compatible remote configuration management server that implements the \[alloy-remote-config API]\[API definition]. The server dynamically decides which configuration to serve based on the collector’s `id` and `attributes`. > > If you want to load a static configuration file from an HTTP server, use [import.http](../import.http/) instead. Refer to [Load configuration from remote sources](../../configure/load-remote-configuration/) for more information. ## Usage Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```alloy remotecfg { } ``` ## Arguments You can use the following arguments with `remotecfg`: Expand table | Name | Type | Description | Default | Required | |--------------------------|---------------------|--------------------------------------------------------------------------------------------------|-----------|----------| | `attributes` | `map(string)` | A set of self-reported attributes. | `{}` | no | | `bearer_token_file` | `string` | File containing a bearer token to authenticate with. | | no | | `bearer_token` | `secret` | Bearer token to authenticate with. | | no | | `enable_http2` | `bool` | Whether to enable HTTP2 for requests. | `true` | no | | `follow_redirects` | `bool` | Whether to follow redirects returned by the server. | `true` | no | | `http_headers` | `map(list(secret))` | Custom HTTP headers to send with each request. The map key is the header name. | | no | | `id` | `string` | A self-reported ID. | see below | no | | `name` | `string` | A human-readable name for the collector. | `""` | no | | `no_proxy` | `string` | Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying. | `""` | no | | `poll_frequency` | `duration` | How often to poll the API for configuration updates. | `"1m"` | no | | `proxy_connect_header` | `map(list(secret))` | Specifies headers to send to proxies during CONNECT requests. | | no | | `proxy_from_environment` | `bool` | Use the proxy URL indicated by environment variables. | `false` | no | | `proxy_url` | `string` | HTTP proxy to send requests through. | `""` | no | | `url` | `string` | The address of the API to poll for configuration. | `""` | no | If you don’t set the `url`, the `remotecfg` block has no effect. If you don’t set `id`, Alloy generates a random, anonymous unique ID (UUID) and stores it in an `alloy_seed.json` file in the Alloy storage path. This allows the ID to persist across restarts. You can use the `name` field to set a human-friendly identifier for the Alloy instance. Alloy includes the `id` and `attributes` fields in periodic requests to the remote endpoint so the API can decide what configuration to serve. The `attributes` map keys can include any custom value except the reserved prefix `collector.`. The reserved label prefix is for automatic system attributes. You can’t override this prefix. - `collector.os`: The operating system where Alloy is running. - `collector.version`: The version of Alloy. You must set `poll_frequency` to at least `"10s"`. You can provide at most one of the following: - [`authorization`](#authorization) block - [`basic_auth`](#basic_auth) block - [`bearer_token_file`](#arguments) argument - [`bearer_token`](#arguments) argument - [`oauth2`](#oauth2) block `no_proxy` can contain IPs, CIDR notations, and domain names. IP and domain names can contain port numbers. `proxy_url` must be configured if `no_proxy` is configured. `proxy_from_environment` uses the environment variables HTTP\_PROXY, HTTPS\_PROXY, and NO\_PROXY (or the lowercase versions thereof). Requests use the proxy from the environment variable matching their scheme, unless excluded by NO\_PROXY. `proxy_url` and `no_proxy` must not be configured if `proxy_from_environment` is configured. `proxy_connect_header` should only be configured if `proxy_url` or `proxy_from_environment` are configured. ## Blocks You can use the following blocks with `remotecfg`: Expand table | Block | Description | Required | |-------------------------------------------|------------------------------------------------------------|----------| | [`authorization`](#authorization) | Configure generic authorization to the endpoint. | no | | [`basic_auth`](#basic_auth) | Configure `basic_auth` for authenticating to the endpoint. | no | | [`oauth2`](#oauth2) | Configure OAuth 2.0 for authenticating to the endpoint. | no | | `oauth2` > [`tls_config`](#tls_config) | Configure TLS settings for connecting to the endpoint. | no | | [`tls_config`](#tls_config) | Configure TLS settings for connecting to the endpoint. | no | The > symbol indicates deeper levels of nesting. For example, `oauth2` > `tls_config` refers to a `tls_config` block defined inside an `oauth2` block. ### `authorization` Expand table | Name | Type | Description | Default | Required | |--------------------|----------|--------------------------------------------|---------|----------| | `credentials_file` | `string` | File containing the secret value. | | no | | `credentials` | `secret` | Secret value. | | no | | `type` | `string` | Authorization type, for example, “Bearer”. | | no | `credential` and `credentials_file` are mutually exclusive, and only one can be provided inside an `authorization` block. > Warning > > Using `credentials_file` causes the file to be read on every outgoing request. Use the `local.file` component with the `credentials` attribute instead to avoid unnecessary reads. ### `basic_auth` Expand table | Name | Type | Description | Default | Required | |-----------------|----------|------------------------------------------|---------|----------| | `password_file` | `string` | File containing the basic auth password. | | no | | `password` | `secret` | Basic auth password. | | no | | `username` | `string` | Basic auth username. | | no | `password` and `password_file` are mutually exclusive, and only one can be provided inside a `basic_auth` block. > Warning > > Using `password_file` causes the file to be read on every outgoing request. Use the `local.file` component with the `password` attribute instead to avoid unnecessary reads. ### `oauth2` Expand table | Name | Type | Description | Default | Required | |--------------------------|---------------------|--------------------------------------------------------------------------------------------------|---------|----------| | `client_id` | `string` | OAuth2 client ID. | | no | | `client_secret_file` | `string` | File containing the OAuth2 client secret. | | no | | `client_secret` | `secret` | OAuth2 client secret. | | no | | `endpoint_params` | `map(string)` | Optional parameters to append to the token URL. | | no | | `no_proxy` | `string` | Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying. | | no | | `proxy_connect_header` | `map(list(secret))` | Specifies headers to send to proxies during CONNECT requests. | | no | | `proxy_from_environment` | `bool` | Use the proxy URL indicated by environment variables. | `false` | no | | `proxy_url` | `string` | HTTP proxy to send requests through. | | no | | `scopes` | `list(string)` | List of scopes to authenticate with. | | no | | `token_url` | `string` | URL to fetch the token from. | | no | `client_secret` and `client_secret_file` are mutually exclusive, and only one can be provided inside an `oauth2` block. > Warning > > Using `client_secret_file` causes the file to be read on every outgoing request. Use the `local.file` component with the `client_secret` attribute instead to avoid unnecessary reads. The `oauth2` block may also contain a separate `tls_config` sub-block. `no_proxy` can contain IPs, CIDR notations, and domain names. IP and domain names can contain port numbers. `proxy_url` must be configured if `no_proxy` is configured. `proxy_from_environment` uses the environment variables HTTP\_PROXY, HTTPS\_PROXY, and NO\_PROXY (or the lowercase versions thereof). Requests use the proxy from the environment variable matching their scheme, unless excluded by NO\_PROXY. `proxy_url` and `no_proxy` must not be configured if `proxy_from_environment` is configured. `proxy_connect_header` should only be configured if `proxy_url` or `proxy_from_environment` are configured. ### `tls_config` Expand table | Name | Type | Description | Default | Required | |------------------------|----------|----------------------------------------------------------|---------|----------| | `ca_pem` | `string` | CA PEM-encoded text to validate the server with. | | no | | `ca_file` | `string` | CA certificate to validate the server with. | | no | | `cert_pem` | `string` | Certificate PEM-encoded text for client authentication. | | no | | `cert_file` | `string` | Certificate file for client authentication. | | no | | `insecure_skip_verify` | `bool` | Disables validation of the server certificate. | | no | | `key_file` | `string` | Key file for client authentication. | | no | | `key_pem` | `secret` | Key PEM-encoded text for client authentication. | | no | | `min_version` | `string` | Minimum acceptable TLS version. | | no | | `server_name` | `string` | ServerName extension to indicate the name of the server. | | no | The following pairs of arguments are mutually exclusive and can’t both be set simultaneously: - `ca_pem` and `ca_file` - `cert_pem` and `cert_file` - `key_pem` and `key_file` When configuring client authentication, both the client certificate (using `cert_pem` or `cert_file`) and the client key (using `key_pem` or `key_file`) must be provided. When `min_version` isn’t provided, the minimum acceptable TLS version is inherited from Go’s default minimum version, TLS 1.2. If `min_version` is provided, it must be set to one of the following strings: - `"TLS10"` (TLS 1.0) - `"TLS11"` (TLS 1.1) - `"TLS12"` (TLS 1.2) - `"TLS13"` (TLS 1.3) ## Example Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```alloy remotecfg { url = "" basic_auth { username = "" password_file = "" } id = constants.hostname attributes = {"cluster" = "dev", "namespace" = "otlp-dev"} poll_frequency = "5m" } ``` ## Troubleshooting If Alloy fails to load configuration using `remotecfg`, check the following: - `401` or `403` errors: Verify that authentication settings are correct, such as `basic_auth`, `authorization`, OAuth2, or bearer token. - `404` errors: Confirm that the configured `url` points to a server implementing the alloy-remote-config API. Static HTTP servers can’t serve configuration for `remotecfg`. - `415 Unsupported Media Type` errors: Ensure the server implements the \[alloy-remote-config API]\[[API definition](https://github.com/grafana/alloy-remote-config)] and returns the expected response format. - Connection timeouts: Check network connectivity, proxy settings, and firewall rules between the collector and the remote server. If you only want to load a static configuration file from an HTTP server, use [`import.http`](../import.http/) instead.