---
title: "remote.vault | Grafana Alloy documentation"
description: "Learn about remote.vault"
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# `remote.vault`

`remote.vault` connects to a [HashiCorp Vault](https://www.vaultproject.io/) server to retrieve secrets. It can retrieve a secret using the [KV v2](https://www.vaultproject.io/docs/secrets/kv/kv-v2) secrets engine.

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

## Usage

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

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

You can use the following arguments with `remote.vault`:

Expand table

| 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 Enterprise namespace to connect to. |         | 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.

The retrieved secret is automatically reread at a frequency specified by the `reread_frequency` argument, regardless of whether it has a lease. The default value of `reread_frequency`, `"0s"`, disables this behavior.

## Blocks

You can use the following blocks with `remote.vault`:

No valid configuration blocks found.

You must provide exactly one `auth.*` block, or the component fails to load.

### `auth.approle`

The `auth.approle` block authenticates to Vault using the [AppRole auth method](https://www.vaultproject.io/docs/auth/approle).

Expand table

| 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](https://www.vaultproject.io/docs/concepts/response-wrapping) the token. | `false`     | no       |

### `auth.aws`

The `auth.aws` block authenticates to Vault using the [AWS auth method](https://www.vaultproject.io/docs/auth/aws).

The environment variables `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` specify the credentials used to connect to AWS. You can specify the environment variable `AWS_SHARED_CREDENTIALS_FILE` to use a credentials file instead.

Expand table

| 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.                 | `""`          | no       |

Set the `type` argument to `"ec2"` or `"iam"`.

You can set `iam_server_id_header` when `type` is `"iam"`.

If you explicitly set the `region` argument to an empty string `""`, `remote.vault` infers the region 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 `"ec2"`. Set `ec2_signature_type` to `"identity"` or `"pkcs7"`.

### `auth.azure`

The `auth.azure` block authenticates to Vault using the [Azure auth method](https://www.vaultproject.io/docs/auth/azure).

`remote.vault` retrieves credentials for the running Azure VM using Managed Identities for Azure Resources.

Expand table

| Name           | Type     | Description                                          | Default                           | Required |
|----------------|----------|------------------------------------------------------|-----------------------------------|----------|
| `role`         | `string` | Role name to authenticate as.                        |                                   | yes      |
| `resource_url` | `string` | Resource URL to include with authentication request. | `"https://management.azure.com/"` | 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.

Expand table

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

`remote.vault` considers all values in the `data` attribute 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 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](https://developer.hashicorp.com/vault/docs/commands#configure-environment-variables) documentation for more information.

### `auth.gcp`

The `auth.gcp` block authenticates to Vault using the [GCP auth method](https://www.vaultproject.io/docs/auth/gcp).

Expand table

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

Set the `type` argument to `"gce"` or `"iam"`. When `type` is `"gce"`, `remote.vault` retrieves credentials using the metadata service on GCE VMs. When `type` is `"iam"`, `remote.vault` retrieves credentials from the file that the `GOOGLE_APPLICATION_CREDENTIALS` environment variable points to.

When `type` is `"iam"`, you must set the `iam_service_account` argument to the service account name to use. `remote.vault` fails validation if `iam_service_account` isn’t set when `type` is `"iam"`.

### `auth.kubernetes`

The `auth.kubernetes` block authenticates to Vault using the [Kubernetes auth method](https://www.vaultproject.io/docs/auth/kubernetes).

Expand table

| Name                   | Type     | Description                                 | Default                                                 | Required |
|------------------------|----------|---------------------------------------------|---------------------------------------------------------|----------|
| `role`                 | `string` | Role name to authenticate as.               |                                                         | yes      |
| `service_account_file` | `string` | Override service account token file to use. | `"/var/run/secrets/kubernetes.io/serviceaccount/token"` | no       |
| `mount_path`           | `string` | Mount path for the login.                   | `"kubernetes"`                                          | no       |

When `service_account_file` isn’t specified, `remote.vault` retrieves the JWT token to authenticate with from `/var/run/secrets/kubernetes.io/serviceaccount/token`.

### `auth.ldap`

The `auth.ldap` block authenticates to Vault using the [LDAP auth method](https://www.vaultproject.io/docs/auth/ldap).

Expand table

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

Expand table

| 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](https://www.vaultproject.io/docs/auth/userpass).

Expand table

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

Expand table

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

`remote.vault` can retry requests that fail with an HTTP 5xx server error. 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 you set the `max_retries` argument to `0`, `remote.vault` doesn’t retry failed requests.

## Exported fields

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

Expand table

| 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 can use values that are strings or byte slices. It ignores and omits keys with other value types from the `data` field.

If an individual key stored in `data` doesn’t hold sensitive data, you can convert it into a string using [the `nonsensitive` function](../../../stdlib/convert/):

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

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

Use `convert.nonsensitive` to pass the exports of `remote.vault` to attributes in components that don’t support secrets.

## Component health

`remote.vault` reports as unhealthy if the most recent reread or renewal of secrets was unsuccessful.

## Debug information

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

- The most recent request ID used for retrieving or renewing the token.
- The most recent time `remote.vault` retrieved or renewed the token.
- The token’s expiration time, if applicable.
- Whether the token is renewable.
- Warnings from Vault when it retrieved the token.

## Debug metrics

The following Prometheus metrics are exposed:

Expand table

| Name                                      | Type      | Description                                                                 |
|-------------------------------------------|-----------|-----------------------------------------------------------------------------|
| `remote_vault_auth_total`                 | `counter` | Total number of times the component authenticated to Vault.                 |
| `remote_vault_secret_reads_total`         | `counter` | Total number of times `remote.vault` read the secret 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 lease.               |

## Examples

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

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

prometheus.remote_write "prod" {
  endpoint {
    url = "https://onprem-mimir:9009/api/v1/push"
    basic_auth {
      username = convert.nonsensitive(remote.vault.remote_write.data.username)
      password = remote.vault.remote_write.data.password
    }
  }
}
```