Menu

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

Open source

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

alloy
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

The following arguments are supported:

NameTypeDescriptionDefaultRequired
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
keystringThe key to retrieve a secret from.no
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.

Blocks

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

HierarchyBlockDescriptionRequired
client_optionsclient_optionsOptions for the Vault client.no
auth.tokenauth.tokenAuthenticate to Vault with a token.no
auth.approleauth.approleAuthenticate to Vault using AppRole.no
auth.awsauth.awsAuthenticate to Vault using AWS.no
auth.azureauth.azureAuthenticate to Vault using Azure.no
auth.gcpauth.gcpAuthenticate to Vault using GCP.no
auth.kubernetesauth.kubernetesAuthenticate to Vault using Kubernetes.no
auth.ldapauth.ldapAuthenticate to Vault using LDAP.no
auth.userpassauth.userpassAuthenticate to Vault using a username and password.no
auth.customauth.customAuthenticate to Vault with custom authentication.no

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.

NameTypeDescriptionDefaultRequired
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, aren’t retried.

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

auth.token block

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

NameTypeDescriptionDefaultRequired
tokensecretAuthentication token to use.yes

auth.approle block

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

NameTypeDescriptionDefaultRequired
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

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.

NameTypeDescriptionDefaultRequired
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".

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.

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

auth.gcp block

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

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

NameTypeDescriptionDefaultRequired
rolestringRole name to authenticate as.yes
service_account_filestringOverride service account token file to use.no
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/kubernetes.io/serviceaccount/token.

auth.ldap block

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

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

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

NameTypeDescriptionDefaultRequired
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:

NameTypeDescription
datamap(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][nonsensitive]:

alloy
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 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

alloy
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
    }
  }
}