remote on Grafana Labs

remote.http

Mon, 13 Apr 2026 07:37:47 +0000

`remote.http`

remote.http exposes the response body of a URL to other components. The URL is polled for changes so that the most recent content is always available.

The most common use of remote.http is to load discovery targets from an HTTP server.

You can specify multiple remote.http components by giving them different labels.

Usage

remote.http "<LABEL>" {
  url = "<URL_TO_POLL>"
}

Arguments

You can use the following arguments with remote.http:

Name	Type	Description	Default	Required
`url`	`string`	URL to poll.		yes
`body`	`string`	The request body.	`""`	no
`headers`	`map(string)`	Custom headers for the request.	`{}`	no
`is_secret`	`bool`	Whether the response body should be treated as a secret.	`false`	no
`method`	`string`	Define HTTP method for the request	`"GET"`	no
`poll_frequency`	`duration`	Frequency to poll the URL.	`"1m"`	no
`poll_timeout`	`duration`	Timeout when polling the URL.	`"10s"`	no

When remote.http performs a poll operation, an HTTP GET request is made against the URL specified by the url argument. A poll is triggered by the following:

When the component first loads.
Every time the component’s arguments get re-evaluated.
At the frequency specified by the poll_frequency argument.

The poll is successful if the URL returns a 200 OK response code. All other response codes are treated as errors and mark the component as unhealthy. After a successful poll, the response body from the URL is exported.

Blocks

You can use the following blocks with remote.http:

Block	Description	Required
`client`	HTTP client settings when connecting to the endpoint.	no
`client` > `authorization`	Configure generic authorization to the endpoint.	no
`client` > `basic_auth`	Configure `basic_auth` for authenticating to the endpoint.	no
`client` > `oauth2`	Configure OAuth 2.0 for authenticating to the endpoint.	no
`client` > `oauth2` > `tls_config`	Configure TLS settings for connecting to the endpoint.	no
`client` > `tls_config`	Configure TLS settings for connecting to the endpoint.	no

`client`

The client block configures settings used to connect to the HTTP server.

Name	Type	Description	Default	Required
`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 HTTP2 is supported for requests.	`true`	no
`follow_redirects`	`bool`	Whether redirects returned by the server should be followed.	`true`	no
`http_headers`	`map(list(secret))`	Custom HTTP headers to be sent along with each request. The map key is the header name.		no
`proxy_url`	`string`	HTTP proxy to send requests through.		no
`no_proxy`	`string`	Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying.		no
`proxy_from_environment`	`bool`	Use the proxy URL indicated by environment variables.	`false`	no
`proxy_connect_header`	`map(list(secret))`	Specifies headers to send to proxies during CONNECT requests.		no

bearer_token, bearer_token_file, basic_auth, authorization, and oauth2 are mutually exclusive, and only one can be provided inside of a http_client_config 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.

`authorization`

The authorization block configures custom authorization to use when polling the configured URL.

Name	Type	Description	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`

The basic_auth block configures basic authentication to use when polling the configured URL.

Name	Type	Description	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`

The oauth2 block configures OAuth2 authorization to use when polling the configured URL.

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_connect_header should only be configured if proxy_url or proxy_from_environment are configured.

`tls_config`

The tls_config block configures TLS settings for connecting to HTTPS servers.

Name	Type	Description	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)

Exported fields

The following field is exported and can be referenced by other components:

Name	Type	Description	Default	Required
`content`	`string` or `secret`	The contents of the file.		no

If the is_secret argument was true, content is a secret type.

Component health

Instances of remote.http report as healthy if the most recent HTTP GET request of the specified URL succeeds.

Debug information

remote.http doesn’t expose any component-specific debug information.

Debug metrics

remote.http doesn’t expose any component-specific debug metrics.

Example

This example reads a JSON array of objects from an endpoint and uses them as a set of scrape targets:

remote.http "targets" {
  url = sys.env("MY_TARGETS_URL")
}

prometheus.scrape "default" {
  targets    = encoding.from_json(remote.http.targets.content)
  forward_to = [prometheus.remote_write.default.receiver]
}

prometheus.remote_write "default" {
  client {
    url = sys.env("PROMETHEUS_URL")
  }
}

remote.kubernetes.configmap

Mon, 13 Apr 2026 07:37:47 +0000

`remote.kubernetes.configmap`

remote.kubernetes.configmap reads a ConfigMap from the Kubernetes API server and exposes its data for other components to consume.

This can be useful anytime Alloy needs data from a ConfigMap that is not directly mounted to the Alloy Pod.

Usage

remote.kubernetes.configmap "<LABEL>" {
  namespace = "<NAMESPACE_OF_CONFIGMAP>"
  name = "<NAME_OF_CONFIGMAP>"
}

Arguments

You can use the following arguments with remote.kubernetes.configmap:

Name	Type	Description	Default	Required
`name`	`string`	Name of the Kubernetes ConfigMap		yes
`namespace`	`string`	Kubernetes namespace containing the desired ConfigMap.		yes
`poll_frequency`	`duration`	Frequency to poll the Kubernetes API.	`"1m"`	no
`poll_timeout`	`duration`	Timeout when polling the Kubernetes API.	`"15s"`	no

When this component performs a poll operation, it requests the ConfigMap data from the Kubernetes API. A poll is triggered by the following:

When the component first loads.
Every time the component’s arguments get re-evaluated.
At the frequency specified by the poll_frequency argument.

Any error while polling will mark the component as unhealthy. After a successful poll, all data is exported with the same field names as the source ConfigMap.

Blocks

You can use the following blocks with remote.kubernetes.configmap:

Block	Description	Required
`client`	HTTP client settings when connecting to the endpoint.	no
`client` > `authorization`	Configure generic authorization to the endpoint.	no
`client` > `basic_auth`	Configure `basic_auth` for authenticating to the endpoint.	no
`client` > `oauth2`	Configure OAuth 2.0 for authenticating to the endpoint.	no
`client` > `oauth2` > `tls_config`	Configure TLS settings for connecting to the endpoint.	no
`client` > `tls_config`	Configure TLS settings for connecting to the endpoint.	no

`client`

The client block configures the Kubernetes client used to discover ConfigMaps. If the client block isn’t provided, the default in-cluster configuration with the service account of the running Alloy Pod is used.

The following arguments are supported:

Name	Type	Description	Default	Required
`api_server`	`string`	URL of the Kubernetes API server.		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 HTTP2 is supported for requests.	`true`	no
`follow_redirects`	`bool`	Whether redirects returned by the server should be followed.	`true`	no
`http_headers`	`map(list(secret))`	Custom HTTP headers to be sent along with each request. The map key is the header name.		no
`kubeconfig_file`	`string`	Path of the `kubeconfig` file to use for connecting to Kubernetes.		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

At most, one of the following can be provided:

[authorization][authorization] block
[basic_auth][basic_auth] block
[bearer_token_file][client] argument
[bearer_token][client] 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_connect_header should only be configured if proxy_url or proxy_from_environment are configured.

`authorization`

Name	Type	Description	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`

Name	Type	Description	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`

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_connect_header should only be configured if proxy_url or proxy_from_environment are configured.

`tls_config`

Name	Type	Description	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.

"TLS10" (TLS 1.0)
"TLS11" (TLS 1.1)
"TLS12" (TLS 1.2)
"TLS13" (TLS 1.3)

Exported fields

The following fields are exported and can be referenced by other components:

Name	Type	Description
`data`	`map(string)`	Data from the ConfigMap obtained from Kubernetes.

The data field contains a mapping from field names to values.

Component health

Instances of remote.kubernetes.configmap report as healthy if the most recent attempt to poll the kubernetes API succeeds.

Debug information

remote.kubernetes.configmap doesn’t expose any component-specific debug information.

Debug metrics

remote.kubernetes.configmap doesn’t expose any component-specific debug metrics.

Example

This example reads a Secret and a ConfigMap from Kubernetes and uses them to supply remote-write credentials.

remote.kubernetes.secret "credentials" {
  namespace = "monitoring"
  name = "metrics-secret"
}

remote.kubernetes.configmap "endpoint" {
  namespace = "monitoring"
  name = "metrics-endpoint"
}

prometheus.remote_write "default" {
  endpoint {
    url = remote.kubernetes.configmap.endpoint.data["url"]
    basic_auth {
      username = remote.kubernetes.configmap.endpoint.data["username"]
      password = remote.kubernetes.secret.credentials.data["password"]
    }
  }
}

This example assumes that the Secret and ConfigMap have already been created, and that the appropriate field names exist in their data.

remote.kubernetes.secret

Mon, 13 Apr 2026 07:37:47 +0000

`remote.kubernetes.secret`

remote.kubernetes.secret reads a Secret from the Kubernetes API server and exposes its data for other components to consume.

A common use case for this is loading credentials or other information from secrets that aren’t already mounted into the Alloy Pod at deployment time.

Usage

remote.kubernetes.secret "<LABEL>" {
  namespace = "<NAMESPACE_OF_SECRET>"
  name = "<NAME_OF_SECRET>"
}

Arguments

You can use the following arguments with remote.kubernetes.secret:

Name	Type	Description	Default	Required
`name`	`string`	Name of the Kubernetes Secret		yes
`namespace`	`string`	Kubernetes namespace containing the desired Secret.		yes
`poll_frequency`	`duration`	Frequency to poll the Kubernetes API.	`"1m"`	no
`poll_timeout`	`duration`	Timeout when polling the Kubernetes API.	`"15s"`	no

When this component performs a poll operation, it requests the Secret data from the Kubernetes API. A poll is triggered by the following:

When the component first loads.
Every time the component’s arguments get re-evaluated.
At the frequency specified by the poll_frequency argument.

Any error while polling will mark the component as unhealthy. After a successful poll, all data is exported with the same field names as the source Secret.

Blocks

You can use the following blocks with remote.kubernetes.secret:

Block	Description	Required
`client`	HTTP client settings when connecting to the endpoint.	no
`client` > `authorization`	Configure generic authorization to the endpoint.	no
`client` > `basic_auth`	Configure `basic_auth` for authenticating to the endpoint.	no
`client` > `oauth2`	Configure OAuth 2.0 for authenticating to the endpoint.	no
`client` > `oauth2` > `tls_config`	Configure TLS settings for connecting to the endpoint.	no
`client` > `tls_config`	Configure TLS settings for connecting to the endpoint.	no

`client`

The client block configures the Kubernetes client used to discover Secrets. If the client block isn’t provided, the default in-cluster configuration with the service account of the running Alloy Pod is used.

The following arguments are supported:

Name	Type	Description	Default	Required
`api_server`	`string`	URL of the Kubernetes API server.		no
`kubeconfig_file`	`string`	Path of the `kubeconfig` file to use for connecting to Kubernetes.		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 HTTP2 is supported for requests.	`true`	no
`follow_redirects`	`bool`	Whether redirects returned by the server should be followed.	`true`	no
`http_headers`	`map(list(secret))`	Custom HTTP headers to be sent along with each request. The map key is the header name.		no
`proxy_url`	`string`	HTTP proxy to send requests through.		no
`no_proxy`	`string`	Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying.		no
`proxy_from_environment`	`bool`	Use the proxy URL indicated by environment variables.	`false`	no
`proxy_connect_header`	`map(list(secret))`	Specifies headers to send to proxies during CONNECT requests.		no

At most, one of the following can be provided:

[authorization][authorization] block
[basic_auth][basic_auth] block
[bearer_token_file][client] argument
[bearer_token][client] 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_connect_header should only be configured if proxy_url or proxy_from_environment are configured.

`authorization`

Name	Type	Description	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`

Name	Type	Description	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`

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_connect_header should only be configured if proxy_url or proxy_from_environment are configured.

`tls_config`

Name	Type	Description	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.

"TLS10" (TLS 1.0)
"TLS11" (TLS 1.1)
"TLS12" (TLS 1.2)
"TLS13" (TLS 1.3)

Exported fields

The following fields are exported and can be referenced by other components:

Name	Type	Description
`data`	`map(secret)`	Data from the secret obtained from Kubernetes.

The data field contains a mapping from field names to values.

If an individual key stored in data doesn’t hold sensitive data, it can be converted into a string using the convert.nonsensitive function:

convert.nonsensitive(remote.kubernetes.secret.LABEL.data.KEY_NAME)

Using convert.nonsensitive allows for using the exports of remote.kubernetes.secret for attributes in components that don’t support secrets.

Component health

Instances of remote.kubernetes.secret report as healthy if the most recent attempt to poll the kubernetes API succeeds.

Debug information

remote.kubernetes.secret doesn’t expose any component-specific debug information.

Debug metrics

remote.kubernetes.secret doesn’t expose any component-specific debug metrics.

Example

This example reads a Secret and a ConfigMap from Kubernetes and uses them to supply remote-write credentials.

remote.kubernetes.secret "credentials" {
  namespace = "monitoring"
  name = "metrics-secret"
}

remote.kubernetes.configmap "endpoint" {
  namespace = "monitoring"
  name = "metrics-endpoint"
}

prometheus.remote_write "default" {
  endpoint {
    url = remote.kubernetes.configmap.endpoint.data["url"]
    basic_auth {
      username = convert.nonsensitive(remote.kubernetes.configmap.endpoint.data["username"])
      password = remote.kubernetes.secret.credentials.data["password"]
    }
  }
}

This example assumes that the Secret and ConfigMap have already been created, and that the appropriate field names exist in their data.

remote.s3

Mon, 13 Apr 2026 07:37:47 +0000

`remote.s3`

remote.s3 exposes the string contents of a file located in AWS S3 to other components. The file is polled for changes so that the most recent content is always available.

The most common use of remote.s3 is to load secrets from files.

You can specify multiple remote.s3 components by using different name labels. By default, AWS environment variables are used to authenticate against S3. The key and secret arguments inside client blocks can be used to provide custom authentication.

Note
Other S3-compatible systems can be read with remote.s3 but may require specific authentication environment variables. There is no guarantee that remote.s3 will work with non-AWS S3 systems.

Usage

remote.s3 "<LABEL>" {
  path = "<S3_FILE_PATH>"
}

Arguments

You can use the following arguments with remote.s3:

Name	Type	Description	Default	Required
`path`	`string`	Path in the format of `"s3://bucket/file"`.		yes
`is_secret`	`bool`	Marks the file as containing a secret.	`false`	no
`poll_frequency`	`duration`	How often to poll the file for changes. Must be greater than 30 seconds.	`"10m"`	no

Note
path must include a full path to a file. This doesn’t support reading of directories.

Blocks

You can use the following block with remote.s3:

Block	Description	Required
`client`	HTTP client settings when connecting to the endpoint.	no
`client` > `authorization`	Configure generic authorization to the endpoint.	no
`client` > `basic_auth`	Configure `basic_auth` for authenticating to the endpoint.	no
`client` > `oauth2`	Configure OAuth 2.0 for authenticating to the endpoint.	no
`client` > `oauth2` > `tls_config`	Configure TLS settings for connecting to the endpoint.	no
`client` > `tls_config`	Configure TLS settings for connecting to the endpoint.	no

`client`

The client block customizes options to connect to the S3 server.

Name	Type	Description	Default	Required
`key`	`string`	Used to override default access key.		no
`secret`	`secret`	Used to override default secret value.		no
`endpoint`	`string`	Specifies a custom URL to access, used generally for S3-compatible systems.		no
`disable_ssl`	`bool`	Used to disable SSL, generally used for testing.	`false`	no
`use_path_style`	`bool`	Path style is a deprecated setting that’s generally enabled for S3 compatible systems.	`false`	no
`region`	`string`	Used to override default region.		no
`signing_region`	`string`	Used to override the signing region when using a custom endpoint.		no

Exported fields

The following fields are exported and can be referenced by other components:

Name	Type	Description	Default	Required
`content`	`string` or `secret`	The contents of the file.		no

The content field will be secret if is_secret is set to true.

Component health

Instances of remote.s3 report as healthy if the most recent read of the watched file was successful.

Debug information

remote.s3 doesn’t expose any component-specific debug information.

Debug metrics

remote.s3 doesn’t expose any component-specific debug metrics.

Example

remote.s3 "data" {
  path = "s3://test-bucket/file.txt"
}

remote.vault

Mon, 13 Apr 2026 07:37:47 +0000

`remote.vault`

remote.vault connects to a HashiCorp Vault server to retrieve secrets. It can retrieve a secret using the KV v2 secrets engine.

You can specify multiple remote.vault components by giving them different labels.

Usage

remote.vault "<LABEL>" {
  server = "<VAULT_SERVER>"
  path   = "<VAULT_PATH>"
  key    = "<VAULT_KEY>"

  // Alternatively, use one of the other auth.* mechanisms.
  auth.token {
    token = "<AUTH_TOKEN>"
  }
}

Arguments

You can use the following arguments with remote.vault:

Name	Type	Description	Default	Required
`path`	`string`	The path to retrieve a secret from.		yes
`server`	`string`	The Vault server to connect to.		yes
`namespace`	`string`	The Vault namespace to connect to (Vault Enterprise only).		no
`key`	`string`	The key to retrieve a secret from.		no
`reread_frequency`	`duration`	Rate to re-read keys.	`"0s"`	no

Tokens with a lease are automatically renewed roughly two-thirds through their lease duration. If the leased token isn’t renewable, or renewing the lease fails, the token is re-read.

All tokens, regardless of whether they have a lease, are automatically reread at a frequency specified by the reread_frequency argument. Setting reread_frequency to "0s" (the default) disables this behavior.

Blocks

You can use the following blocks with remote.vault:

Block	Description	Required
`client`	HTTP client settings when connecting to the endpoint.	no
`client` > `authorization`	Configure generic authorization to the endpoint.	no
`client` > `basic_auth`	Configure `basic_auth` for authenticating to the endpoint.	no
`client` > `oauth2`	Configure OAuth 2.0 for authenticating to the endpoint.	no
`client` > `oauth2` > `tls_config`	Configure TLS settings for connecting to the endpoint.	no
`client` > `tls_config`	Configure TLS settings for connecting to the endpoint.	no

Exactly one auth.* block must be provided, otherwise the component will fail to load.

`auth.approle`

The auth.approle block authenticates to Vault using the AppRole auth method.

Name	Type	Description	Default	Required
`role_id`	`string`	Role ID to authenticate as.		yes
`secret`	`secret`	Secret to authenticate with.		yes
`mount_path`	`string`	Mount path for the login.	`"approle"`	no
`wrapping_token`	`bool`	Whether to unwrap the token.	`false`	no

`auth.aws`

The auth.aws block authenticates to Vault using the AWS auth method.

Credentials used to connect to AWS are specified by the environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION. The environment variable AWS_SHARED_CREDENTIALS_FILE may be specified to use a credentials file instead.

Name	Type	Description	Default	Required
`type`	`string`	Mechanism to authenticate against AWS with.		yes
`ec2_signature_type`	`string`	Signature to use when authenticating against EC2.	`"pkcs7"`	no
`iam_server_id_header`	`string`	Configures a `X-Vault-AWS-IAM-Server-ID` header.	`""`	no
`mount_path`	`string`	Mount path for the login.	`"aws"`	no
`region`	`string`	AWS region to connect to.	`"us-east-1"`	no
`role`	`string`	Overrides the inferred role name inferred.	`""`	no

The type argument must be set to one of "ec2" or "iam".

The iam_server_id_header argument is required used when type is set to "iam".

If the region argument is explicitly set to an empty string "", the region to connect to will be inferred using an API call to the EC2 metadata service.

The ec2_signature_type argument configures the signature to use when authenticating against EC2. It only applies when type is set to "ec2". ec2_signature_type must be set to either "identity" or "pkcs7".

`auth.azure`

The auth.azure block authenticates to Vault using the Azure auth method.

Credentials are retrieved for the running Azure VM using Managed Identities for Azure Resources.

Name	Type	Description	Default	Required
`role`	`string`	Role name to authenticate as.		yes
`resource_url`	`string`	Resource URL to include with authentication request.		no
`mount_path`	`string`	Mount path for the login.	`"azure"`	no

`auth.custom`

The auth.custom blocks allows authenticating against Vault using an arbitrary authentication path like auth/customservice/login.

Using auth.custom is equivalent to calling vault write PATH DATA on the command line.

Name	Type	Description	Required
`path`	`string`	Path to write to for creating an authentication token.	yes
`data`	`map(secret)`	Authentication data.	yes
`namespace`	`string`	The namespace to authenticate to.	no

All values in the data attribute are considered secret, even if they contain nonsensitive information like usernames.

With Vault Enterprise, you can authenticate against a parent namespace while storing secrets in a child namespace. By specifying the namespace argument in auth.custom, you can authenticate to a namespace different from the one used to retrieve the secrets.

You can also define Vault environment variables, which the clients used by Alloy will automatically load. This approach allows you to use certificate-based authentication by setting the VAULT_CACERT and VAULT_CAPATH environment variables. Refer to the Vault Environment variables documentation for more information.

`auth.gcp`

The auth.gcp block authenticates to Vault using the GCP auth method.

Name	Type	Description	Default	Required
`role`	`string`	Role name to authenticate as.		yes
`type`	`string`	Mechanism to authenticate against GCP with		yes
`iam_service_account`	`string`	IAM service account name to use.		no
`mount_path`	`string`	Mount path for the login.	`"gcp"`	no

The type argument must be set to "gce" or "iam". When type is "gce", credentials are retrieved using the metadata service on GCE VMs. When type is "iam", credentials are retrieved from the file that the GOOGLE_APPLICATION_CREDENTIALS environment variable points to.

When type is "iam", the iam_service_account argument determines what service account name to use.

`auth.kubernetes`

The auth.kubernetes block authenticates to Vault using the Kubernetes auth method.

Name	Type	Description	Default	Required
`role`	`string`	Role name to authenticate as.		yes
`service_account_file`	`string`	Override service account token file to use.		no
`mount_path`	`string`	Mount path for the login.	`"kubernetes"`	no

When service_account_file is not specified, the JWT token to authenticate with is retrieved from /var/run/secrets/kubernetes.io/serviceaccount/token.

`auth.ldap`

The auth.ldap block authenticates to Vault using the LDAP auth method.

Name	Type	Description	Default	Required
`username`	`string`	LDAP username to authenticate as.		yes
`password`	`secret`	LDAP password for the user.		yes
`mount_path`	`string`	Mount path for the login.	`"ldap"`	no

`auth.token`

The auth.token block authenticates each request to Vault using a token.

Name	Type	Description	Default	Required
`token`	`secret`	Authentication token to use.		yes

`auth.userpass`

The auth.userpass block authenticates to Vault using the UserPass auth method.

Name	Type	Description	Default	Required
`username`	`string`	Username to authenticate as.		yes
`password`	`secret`	Password for the user.		yes
`mount_path`	`string`	Mount path for the login.	`"userpass"`	no

`client_options`

The client_options block customizes the connection to vault.

Name	Type	Description	Default	Required
`min_retry_wait`	`duration`	Minimum time to wait before retrying failed requests.	`"1000ms"`	no
`max_retry_wait`	`duration`	Maximum time to wait before retrying failed requests.	`"1500ms"`	no
`max_retries`	`int`	Maximum number of times to retry after a 5xx error.	`2`	no
`timeout`	`duration`	Maximum time to wait before a request times out.	`"60s"`	no

Requests which fail due to server errors (HTTP 5xx error codes) can be retried. The max_retries argument specifies how many times to retry failed requests. The min_retry_wait and max_retry_wait arguments specify how long to wait before retrying. The wait period starts at min_retry_wait and exponentially increases up to max_retry_wait.

Other types of failed requests, including HTTP 4xx error codes, aren’t retried.

If the max_retries argument is set to 0, failed requests aren’t retried.

Exported fields

The following fields are exported and can be referenced by other components:

Name	Type	Description
`data`	`map(secret)`	Data from the secret obtained from Vault.

The data field contains a mapping from data field names to values. There is one mapping for each string-like field stored in the Vault secret.

Vault permits secret engines to store arbitrary data within the key-value pairs for a secret. The remote.vault component is only able to use values which are strings or can be converted to strings. Keys with non-string values are ignored and omitted from the data field.

If an individual key stored in data doesn’t hold sensitive data, it can be converted into a string using the nonsensitive function:

convert.nonsensitive(remote.vault.LABEL.data.KEY_NAME)

Using convert.nonsensitive allows for using the exports of remote.vault for attributes in components that don’t support secrets.

Component health

remote.vault is reported as unhealthy if the latest reread or renewal of secrets was unsuccessful.

Debug information

remote.vault exposes debug information for the authentication token and secret around:

The latest request ID used for retrieving or renewing the token.
The most recent time when the token was retrieved or renewed.
The expiration time for the token (if applicable).
Whether the token is renewable.
Warnings from Vault from when the token was retrieved.

Debug metrics

remote.vault exposes the following metrics:

remote_vault_auth_total (counter): Total number of times the component authenticated to Vault.
remote_vault_secret_reads_total (counter): Total number of times the secret was read from Vault.
remote_vault_auth_lease_renewal_total (counter): Total number of times the component renewed its authentication token lease.
remote_vault_secret_lease_renewal_total (counter): Total number of times the component renewed its secret token lease.

Example

local.file "vault_token" {
  filename  = "/var/data/vault_token"
  is_secret = true
}

remote.vault "remote_write" {
  server = "https://prod-vault.corporate.internal"
  path   = "secret"
  key    = "prometheus/remote_write"

  auth.token {
    token = local.file.vault_token.content
  }
}

metrics.remote_write "prod" {
  remote_write {
    url = "https://onprem-mimir:9009/api/v1/push"
    basic_auth {
      username = remote.vault.remote_write.data.username
      password = remote.vault.remote_write.data.password
    }
  }
}