Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Documentation Grafana Agent Flow mode Reference Components reference remote.vault

remote.vault

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.

Usage

river Copy

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

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

Arguments

The following arguments are supported:

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.

Blocks

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

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.

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.

auth.approle block

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

auth.aws block

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.

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 block

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.

auth.gcp block

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

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.

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 block

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

auth.userpass block

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

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.

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:

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:

river Copy

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

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.

Example

river Copy

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 = remote.vault.remote_write.data.username
      password = remote.vault.remote_write.data.password
    }
  }
}