Grafana Alloy is the new name for our distribution of the OTel collector. Grafana Agent has been deprecated and is in Long-Term Support (LTS) through October 31, 2025. Grafana Agent will reach an End-of-Life (EOL) on November 1, 2025. Read more about why we recommend migrating to Grafana Alloy.

This is documentation for the next version of Agent. For the latest stable release, go to the latest version.

Open source


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

Multiple remote.vault components can be specified by giving them different labels.


remote.vault "LABEL" {
  server = "VAULT_SERVER"
  path   = "VAULT_PATH"

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


The following arguments are supported:

serverstringThe Vault server to connect to.yes
namespacestringThe Vault namespace to connect to (Vault Enterprise only).no
pathstringThe path to retrieve a secret from.yes
reread_frequencydurationRate to re-read keys."0s"no

Tokens with a lease will be automatically renewed roughly two-thirds through their lease duration. If the leased token isn’t renewable, or renewing the lease fails, the token will be 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.


The following blocks are supported inside the definition of remote.vault:

client_optionsclient_optionsOptions for the Vault
auth.tokenauth.tokenAuthenticate to Vault with a
auth.approleauth.approleAuthenticate to Vault using
auth.awsauth.awsAuthenticate to Vault using
auth.azureauth.azureAuthenticate to Vault using
auth.gcpauth.gcpAuthenticate to Vault using
auth.kubernetesauth.kubernetesAuthenticate to Vault using
auth.ldapauth.ldapAuthenticate to Vault using
auth.userpassauth.userpassAuthenticate to Vault using a username and
auth.customauth.customAuthenticate to Vault with custom

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

client_options block

The client_options block customizes the connection to vault.

min_retry_waitdurationMinimum time to wait before retrying failed requests."1000ms"no
max_retry_waitdurationMaximum time to wait before retrying failed requests."1500ms"no
max_retriesintMaximum number of times to retry after a 5xx error.2no
timeoutdurationMaximum 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, are not retried.

If the max_retries argument is set to 0, failed requests are not retried.

auth.token block

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

tokensecretAuthentication token to use.yes

auth.approle block

The auth.token block auhenticates to Vault using the AppRole auth method.

role_idstringRole ID to authenticate as.yes
secretsecretSecret to authenticate with.yes
wrapping_tokenboolWhether to unwrap the token.falseno
mount_pathstringMount path for the login."approle"no block

The 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.

typestringMechanism to authenticate against AWS with.yes
regionstringAWS region to connect to."us-east-1"no
rolestringOverrides the inferred role name inferred.""no
iam_server_id_headerstringConfigures a X-Vault-AWS-IAM-Server-ID header.""no
ec2_signature_typestringSignature to use when authenticating against EC2."pkcs7"no
mount_pathstringMount path for the login."aws"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". block

The block authenticates to Vault using the Azure auth method.

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

rolestringRole name to authenticate as.yes
resource_urlstringResource URL to include with authentication
mount_pathstringMount path for the login."azure"no

auth.gcp block

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

rolestringRole name to authenticate as.yes
typestringMechanism to authenticate against GCP withyes
iam_service_accountstringIAM service account name to
mount_pathstringMount 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 block

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

rolestringRole name to authenticate as.yes
service_account_filestringOverride service account token file to
mount_pathstringMount 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/

auth.ldap block

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

usernamestringLDAP username to authenticate as.yes
passwordsecretLDAP passsword for the user.yes
mount_pathstringMount path for the login."ldap"no

auth.userpass block

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

usernamestringUsername to authenticate as.yes
passwordsecretPasssword for the user.yes
mount_pathstringMount path for the login."userpass"no

auth.custom block

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.

pathstringPath to write to for creating an authentication token.yes
datamap(secret)Authentication data.yes

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

Exported fields

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

datamap(secret)Data from the secret obtained from Vault.

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

Note that 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 will be ignored and omitted from the data field.

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


Using nonsensitive allows for using the exports of remote.vault for attributes in components that do not support secrets.

Component health

remote.vault will be 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.


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

remote.vault "remote_write" {
  server = "https://prod-vault.corporate.internal"
  path   = "secret/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 =
      password =