Provider Reference

This page documents every field accepted by each supported secret provider — both the secret_providers connection block and the secrets per-reference lookup block. For an introduction to the model and reference syntax, see Secret Providers.

Each section follows the same shape: provider connection fields, supported auth methods, secret-entry lookup fields, and a copy-paste example showing both blocks together.

---

hashicorp_vault

Reads a field from a Vault KV v1 or v2 secret.

Provider fields (secret_providers)

Field	Required	Description
provider	Yes	"hashicorp_vault"
address	Yes	Vault server URL (e.g., https://vault.internal:8200)
namespace	No	Vault Enterprise namespace
tls.ca_cert	No	Path to a custom CA certificate
tls.client_cert	No	Path to a client certificate (mutual TLS)
tls.client_key	No	Path to a client key (mutual TLS, must pair with client_cert)
tls.skip_verify	No	Disable TLS verification (development only, default: false)
auth	Yes	Authentication is required — Vault has no default credential chain

Auth methods

Method	Required fields	Description
approle	role_id or role_id_file or role_id_env, plus secret_id or secret_id_file or secret_id_env	AppRole authentication. One source per credential.
kubernetes	role; token_file (default: /var/run/secrets/kubernetes.io/serviceaccount/token)	Projected service-account token. role is the Vault role bound to the SA, not a Kubernetes RBAC role.
jwt	role; one of jwt, jwt_file, jwt_env	Generic OIDC/JWT — GitHub Actions, SPIFFE, customer-run OIDC issuer.
static	one of token, token_env, token_file	Static Vault token.
file	path	Reads the token from a file on every refresh.

Secret fields (secrets)

Field	Required	Description
from	Yes	Provider key in secret_providers
mount	Yes	Secret engine mount (e.g., kv, secret)
secret_path	Yes	Path within the mount
field	Yes	JSON field to extract from the secret
engine_version	No	KV engine version: v1 or v2. Default: v2. The /data/ segment for KV v2 is auto-computed.
version	No	Pin a specific version (KV v2 only)
refresh	No	Override refresh interval (e.g., 30m)

Example

secret_providers:
  vault:
    provider: hashicorp_vault
    address: https://vault.internal:8200
    namespace: team-a
    auth:
      method: approle
      role_id_file: /etc/expanso/vault-role-id
      secret_id_file: /etc/expanso/vault-secret-id

secrets:
  DB_PASSWORD:
    from: vault
    mount: kv
    secret_path: database/prod
    field: password
    refresh: 15m

---

aws_secrets_manager

Reads a secret from AWS Secrets Manager, optionally extracting a single JSON field from the value.

Provider fields (secret_providers)

Field	Required	Description
provider	Yes	"aws_secrets_manager"
region	Yes	AWS region (e.g., us-east-1)
profile	No	AWS shared-config profile name
endpoint_url	No	Custom endpoint (LocalStack, PrivateLink, VPC endpoints)
auth	No	Omit for the AWS SDK default credential chain

Auth methods

Method	Required fields	Description
(omitted)	—	SDK default credential chain (env vars, IMDS, IRSA, ECS task role)
kubernetes	role; token_file (optional)	IRSA — IAM Roles for Service Accounts
static	access_key_id, secret_access_key	Static AWS credentials
file	path	Two-line file: access key ID on line 1, secret access key on line 2

Secret fields (secrets)

Field	Required	Description
from	Yes	Provider key in secret_providers
secret_id	Yes	Secret name or ARN
field	No	Extract a single top-level JSON key from the secret value
version_stage	No	Version stage. Default: AWSCURRENT.
version_id	No	Specific version ID. Mutually exclusive with version_stage.
refresh	No	Override refresh interval

Example

secret_providers:
  aws:
    provider: aws_secrets_manager
    region: us-east-1

secrets:
  API_KEY:
    from: aws
    secret_id: prod/third-party-api-key
    field: api_key

---

aws_parameter_store

Reads a parameter from AWS Systems Manager Parameter Store. A lower-cost alternative to Secrets Manager for config-like values.

Provider fields (secret_providers)

Field	Required	Description
provider	Yes	"aws_parameter_store"
region	Yes	AWS region
profile	No	AWS shared-config profile name
endpoint_url	No	Custom endpoint
auth	No	Omit for the AWS SDK default credential chain

Auth methods

Same set as aws_secrets_manager: omitted (default chain), kubernetes, static, file.

Secret fields (secrets)

Field	Required	Description
from	Yes	Provider key in secret_providers
name	Yes	Parameter name or ARN. The suffix syntax name:version or name:label selects a specific version or label.
with_decryption	No	Decrypt SecureString parameters. Default: true. Transparent for String and StringList parameters.
field	No	Extract a top-level JSON key (the parameter value must be JSON)
refresh	No	Override refresh interval

Example

secret_providers:
  ssm:
    provider: aws_parameter_store
    region: us-east-1

secrets:
  DB_HOST:
    from: ssm
    name: /prod/db/host

---

aws_sts

Multi-value provider. Exchanges an identity for temporary AWS credentials via STS AssumeRole. Each secrets entry emits three variables under its key as the prefix: <NAME>_ACCESS_KEY_ID, <NAME>_SECRET_ACCESS_KEY, and <NAME>_SESSION_TOKEN.

When to use this

Use aws_sts when one node runs jobs that must authenticate as different AWS roles. For the single-identity case (one node, one role), the SDK default credential chain is enough — no STS entry needed.

Provider fields (secret_providers)

Field	Required	Description
provider	Yes	"aws_sts"
role_arn	Yes	IAM role ARN to assume
region	Yes	AWS region (regional STS endpoint)
session_name	No	CloudTrail session name. Default: expanso-edge. Appears in the assumed-role ARN.
external_id	No	For sts:ExternalId trust policies
duration_seconds	No	Session duration in seconds, 900–43200. Default: 3600. The role's MaxSessionDuration may cap this lower; STS returns ValidationError if exceeded.
profile	No	AWS shared-config profile name
endpoint_url	No	Custom STS endpoint
auth	No	Omit for the AWS SDK default credential chain

Auth methods

Same set as aws_secrets_manager. With kubernetes auth, the provider uses AssumeRoleWithWebIdentity instead of AssumeRole.

Secret fields (secrets)

Field	Required	Description
from	Yes	Provider key in secret_providers

The entry's map key is the prefix for the three emitted variables. There are no per-reference lookup fields beyond from. Refresh follows the standard cadence; the 70% rule against the STS session expiry usually wins in practice.

Example

secret_providers:
  aws_writer:
    provider: aws_sts
    role_arn: arn:aws:iam::123456789:role/pipeline-writer
    region: us-east-1

secrets:
  AWS:
    from: aws_writer
    # Emits AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN.

Use the emitted variables in any pipeline component that takes AWS credentials:

output:
  aws_s3:
    bucket: pipeline-out
    credentials:
      id: ${AWS_ACCESS_KEY_ID}
      secret: ${AWS_SECRET_ACCESS_KEY}
      token: ${AWS_SESSION_TOKEN}

---

gcp_secret_manager

Reads a secret version from GCP Secret Manager.

Provider fields (secret_providers)

Field	Required	Description
provider	Yes	"gcp_secret_manager"
project	Yes	GCP project ID
location	No	GCP location for regional or CMEK-pinned secrets. Omit for global secrets.
auth	No	Omit for Application Default Credentials (ADC)

Auth methods

Method	Required fields	Description
(omitted)	—	Application Default Credentials
static	service_account_key_file; impersonate_service_account (optional)	Service-account key JSON, with optional impersonation target
file	path	Reads a credential file on every refresh

Secret fields (secrets)

Field	Required	Description
from	Yes	Provider key in secret_providers
secret	Yes	GCP secret name
version	No	Version name. Default: latest.
field	No	Extract a top-level JSON key from the secret value
refresh	No	Override refresh interval

Example

secret_providers:
  gcp:
    provider: gcp_secret_manager
    project: my-project

secrets:
  OPENAI_KEY:
    from: gcp
    secret: openai-api-key

---

azure_key_vault

Reads a secret from Azure Key Vault. Honors the secret's attributes.exp (native TTL) when present.

Provider fields (secret_providers)

Field	Required	Description
provider	Yes	"azure_key_vault"
vault_url	Yes	Key Vault URL (e.g., https://mykv.vault.azure.net)
auth	No	Omit for the DefaultAzureCredential chain

Auth methods

Method	Required fields	Description
(omitted)	—	DefaultAzureCredential (env vars, managed identity, Azure CLI, etc.)
static (managed identity)	managed_identity_client_id	User-assigned managed identity. Required when a VM has multiple user-assigned identities. For system-assigned MI, omit auth and let DefaultAzureCredential handle it.
static (service principal)	tenant_id, client_id, client_secret_env	Service principal with the secret pulled from an env var
file	path	JSON file containing tenant_id, client_id, client_secret

Secret fields (secrets)

Field	Required	Description
from	Yes	Provider key in secret_providers
secret_name	Yes	Azure Key Vault secret name
version	No	Secret version. Default: latest.
field	No	Extract a top-level JSON key from the secret value
refresh	No	Override refresh interval

Example

secret_providers:
  kv:
    provider: azure_key_vault
    vault_url: https://mykv.vault.azure.net

secrets:
  DB_CONN:
    from: kv
    secret_name: database-connection-string

---

file

Reads a value from a local file on the node. Pairs with customer-side credential delivery tools — Vault Agent, Teleport Machine ID, SPIRE, custom scripts — without requiring a dedicated provider per tool.

Provider fields (secret_providers)

Field	Required	Description
provider	Yes	"file"

The file provider has no connection or auth configuration. The provider declaration is still required for schema consistency.

Secret fields (secrets)

Field	Required	Description
from	Yes	Provider key in secret_providers
path	Yes	Absolute file path on the node
encoding	No	raw (default) or base64
refresh	No	Override refresh interval. The file is re-read on each refresh.

Example

secret_providers:
  local:
    provider: file

secrets:
  API_KEY:
    from: local
    path: /run/secrets/api-key

  TLS_CERT:
    from: local
    path: /run/secrets/tls-cert.pem
    encoding: base64
    refresh: 1h

For binary values, store them base64-encoded on disk and use encoding: base64. The lookup function returns a string; downstream pipeline components can decode with |base64decode in a Bloblang expression where binary input is required.

---

See also

• Secret Providers — concept overview, reference syntax, refresh and rotation behavior.
• Interpolation Guide — full syntax for ${VAR} and Bloblang ${! ... !} references.
• Bloblang Guide — language reference for the mapping processor and interpolation expressions.