Integrate External Secret Managers: Vault, AWS, Azure, GCP, and more

Configure Kestra to store and retrieve secrets from an external backend such as AWS Secrets Manager, Azure Key Vault, Google Secret Manager, HashiCorp Vault, and others.

Secrets manager modes

Kestra supports two modes when integrating an external secrets backend. They differ fundamentally in who is the source of truth for secret metadata.

Managed mode (default)

Kestra is the source of truth. You create, edit, and delete secrets from the Kestra UI or via Terraform. When you create a secret, Kestra stores the encrypted value in the external backend and attaches metadata tags (namespace, tenant, key, prefix) automatically.

• Kestra reads the value from the external backend at runtime.
• Tag changes made directly in the external backend are not reflected in Kestra — Kestra ignores external metadata.
• The external backend is encrypted storage only; Kestra controls the index.

Read-only mode

The external system is the source of truth. You populate secrets and their metadata tags in the external backend yourself, and Kestra reads them. Kestra cannot create, edit, or delete secrets — the UI shows a lock icon and hides the Create New Secret button.

Read-only mode is supported for all external secrets backends. For backend-specific requirements such as secret format constraints, see the read-only subsection under the relevant backend below.

Enable globally — add read-only: true to your kestra.secret configuration:

kestra:
  secret:
    type: aws-secret-manager
    read-only: true
    aws-secret-manager:
      region: us-east-1

Enable per tenant — toggle the setting in the Dedicated secrets manager configuration under the tenant settings.

Enable per namespace — toggle the setting in the Dedicated secrets manager section of the namespace Edit tab.

Once enabled, secrets display a lock icon and the Create New Secret button is hidden.

Required tags that must be set externally in read-only mode:

• namespace — the namespace the secret belongs to.
• key — name used to reference the secret in flows via secret('KEY').
• prefix — defaults to kestra when a secret is created inside Kestra; must be set manually in read-only mode.

Configure a secrets manager

Set the backend globally in your Kestra configuration file using kestra.secret.type, or scope it to a specific tenant or namespace via the Dedicated secrets manager setting in the UI. Each backend uses its own sub-key matching the type name.

Supported backends: AWS Secrets Manager · AWS SSM Parameter Store · Azure Key Vault · Google Secret Manager · HashiCorp Vault · CyberArk · Doppler · 1Password · BeyondTrust · Delinea Secret Server · Bitwarden · JDBC · Elasticsearch

AWS Secrets Manager

Permissions

Managed mode — the IAM identity needs: CreateSecret, DeleteSecret, DescribeSecret, GetSecretValue, ListSecrets, PutSecretValue, RestoreSecret, TagResource, UpdateSecret.

Read-only mode — only GetSecretValue, ListSecrets, and DescribeSecret are needed.

Minimum configuration

kestra:
  secret:
    type: aws-secret-manager
    aws-secret-manager:
      region: us-east-1

With explicit credentials:

kestra:
  secret:
    type: aws-secret-manager
    aws-secret-manager:
      access-key-id: YOUR_ACCESS_KEY_ID
      secret-key-id: YOUR_SECRET_KEY_ID
      region: us-east-1

Configuration reference

Credential resolution order

1. access-key-id / secret-key-id (+ optional session-token) in config.
2. STS role assumption using sts-role-arn (chained on top of any resolved identity).
3. AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_DEFAULT_REGION environment variables.
4. AWS CLI profile (~/.aws/credentials).
5. EKS Pod Identity or IRSA (IAM Roles for Service Accounts).
6. EC2/ECS instance metadata profile.

Read-only mode

Secrets must be stored as plain text in AWS Secrets Manager, not as key-value pairs.

kestra:
  secret:
    type: aws-secret-manager
    read-only: true
    aws-secret-manager:
      access-key-id: YOUR_ACCESS_KEY_ID
      secret-key-id: YOUR_SECRET_KEY_ID
      region: us-east-1

Each secret must have the following tags set in AWS:

• namespace — the Kestra namespace this secret belongs to.
• key — the name used in secret('KEY') expressions.
• prefix — typically kestra.

Filter by tags — limit visible secrets to those matching specific tags:

kestra:
  secret:
    type: aws-secret-manager
    read-only: true
    aws-secret-manager:
      filter-on-tags:
        tags:
          application: kestra-production

Filter by prefix — limit visible secrets to those whose names start with a given prefix:

kestra:
  secret:
    type: aws-secret-manager
    read-only: true
    aws-secret-manager:
      filter-on-prefix:
        prefix: prod_
        keep-prefix: true   # set false to strip the prefix from the Kestra key name

AWS SSM Parameter Store

Secrets are stored as SecureString parameters. The parameter name is <prefix>-<hash>; namespace, tenant, and key are stored as parameter tags. In read-only mode, Kestra reads existing parameters by their name, so a Parameter Store already populated outside Kestra can be used directly.

Permissions

Managed mode — the IAM identity needs: ssm:PutParameter, ssm:GetParameter, ssm:DeleteParameter, ssm:DescribeParameters, ssm:AddTagsToResource, ssm:RemoveTagsFromResource, ssm:ListTagsForResource, plus kms:Encrypt and kms:Decrypt on the KMS key used for SecureString encryption.

Read-only mode — only ssm:GetParameter, ssm:DescribeParameters, and ssm:ListTagsForResource are needed.

Minimum configuration

kestra:
  secret:
    type: aws-ssm-parameter-store
    aws-ssm-parameter-store:
      region: us-east-1

Configuration reference

Credential resolution order is identical to AWS Secrets Manager.

Read-only mode

kestra:
  secret:
    type: aws-ssm-parameter-store
    read-only: true
    aws-ssm-parameter-store:
      region: us-east-1

Tag and prefix filtering work the same as for AWS Secrets Manager.

Azure Key Vault

Permissions

Managed mode — the service principal or managed identity needs: Get, List, Set, Delete, Recover, Backup, Restore, Purge.

Read-only mode — only Get and List are needed.

Minimum configuration

kestra:
  secret:
    type: azure-key-vault
    azure-key-vault:
      vault-name: my-vault-name
      client-secret:
        tenant-id: YOUR_TENANT_ID
        client-id: YOUR_CLIENT_ID
        client-secret: YOUR_CLIENT_SECRET

Configuration reference

Connection

Service principal auth

Managed identity auth

Workload identity auth

All auth modes

Credential resolution order

1. client-secret block (service principal with client secret).
2. managed-identity-client-id or managed-identity-resource-id (managed identity).
3. workload-identity-client-id (workload identity / federated credentials).
4. Azure default credential chain — environment variables (AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID), then Azure CLI, then managed identity.

Read-only mode

kestra:
  secret:
    type: azure-key-vault
    read-only: true
    azure-key-vault:
      client-secret:
        tenant-id: YOUR_TENANT_ID
        client-id: YOUR_CLIENT_ID
        client-secret: YOUR_CLIENT_SECRET

Filter by tags:

kestra:
  secret:
    type: azure-key-vault
    read-only: true
    azure-key-vault:
      filter-on-tags:
        tags:
          application: kestra-production

Filter by prefix:

kestra:
  secret:
    type: azure-key-vault
    read-only: true
    azure-key-vault:
      filter-on-prefix:
        prefix: prod_
        keep-prefix: true   # set false to strip the prefix from the Kestra key name

Google Secret Manager

Permissions

Managed mode — the service account needs roles/secretmanager.admin.

Read-only mode — roles/secretmanager.secretAccessor is sufficient.

Minimum configuration

kestra:
  secret:
    type: google-secret-manager
    google-secret-manager:
      project: my-gcp-project-id

With an explicit service account key:

kestra:
  secret:
    type: google-secret-manager
    google-secret-manager:
      project: my-gcp-project-id
      service-account: |
        {
          "type": "service_account",
          "project_id": "my-gcp-project-id",
          "private_key_id": "...",
          "private_key": "...",
          ...
        }

Configuration reference

Credential resolution order

1. service-account JSON key in config.
2. GOOGLE_APPLICATION_CREDENTIALS environment variable pointing to a key file.
3. Google default application credentials (Workload Identity, GCE metadata server, gcloud CLI).

When configuring via the Kestra UI, only project and service-account fields are shown.

Read-only mode

kestra:
  secret:
    type: google-secret-manager
    read-only: true
    google-secret-manager:
      project: my-gcp-project-id
      service-account: |
        Paste the contents of the service account JSON key file here.

Filter by labels:

kestra:
  secret:
    type: google-secret-manager
    read-only: true
    google-secret-manager:
      filter-on-tags:
        tags:
          application: kestra-production

HashiCorp Vault

Kestra supports the KV Secrets Engine v2. Dynamic secrets engines and the Vault Secrets Operator on Kubernetes are not directly supported (the Vault Secrets Operator creates a Kubernetes Secret that Kestra can use with additional steps — contact us for guidance).

Permissions

The token or AppRole must have a Vault policy granting the following capabilities on your secrets engine path. Replace secret with your root-engine value if different.

Managed mode:

path "secret/data/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}
path "secret/metadata/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

Read-only mode:

path "secret/data/*" {
  capabilities = ["read", "list"]
}
path "secret/metadata/*" {
  capabilities = ["read", "list"]
}

Auth methods

Choose one of the following auth methods:

Userpass

kestra:
  secret:
    type: vault
    vault:
      address: "http://localhost:8200"
      password:
        user: john
        password: foo

Token

kestra:
  secret:
    type: vault
    vault:
      address: "http://localhost:8200"
      token:
        token: YOUR_VAULT_TOKEN

AppRole

kestra:
  secret:
    type: vault
    vault:
      address: "http://localhost:8200"
      app-role:
        path: approle
        role-id: YOUR_ROLE_ID
        secret-id: YOUR_SECRET_ID

Kubernetes

kestra:
  secret:
    type: vault
    vault:
      address: "http://localhost:8200"
      kubernetes:
        path: "kubernetes"
        role: "kestra"

Configuration reference

In Vault, secrets created through Kestra are stored under TENANT_ID/NAMESPACE_PARENT/.../NAMESPACE_CHILD/SECRET_NAME. For a tenant internal and namespace company.team, the path would be internal/company/team/SECRET_NAME under the configured root-engine.

Read-only mode

Set read-only: true inside the vault config block (unlike other backends which use kestra.secret.read-only):

kestra:
  secret:
    type: vault
    vault:
      address: https://my-vault:8200/
      root-engine: secret
      secret-path-prefix: app1
      token:
        token: my-vault-access-token
      read-only: true

secret-path-prefix scopes Kestra’s view to a specific path within the engine. In the example above, only secrets under the app1 path are visible. Reference a subkey in a flow with:

{{ secret('my-app', subkey='MY_SUBKEY') }}

For a full end-to-end walkthrough with screenshots, see Use HashiCorp Vault as a Read-Only Secrets Backend.

CyberArk

Kestra integrates with CyberArk Privilege Cloud as a secrets backend using one of two authentication methods:

• PVWA (default) — username and password logon via the CyberArk REST API. Supports read and write.
• CCP — Central Credential Provider (AIM web service), authenticated by IP allowlisting and an Application ID. Read-only. No credentials stored in Kestra configuration.

Permissions

PVWA

Managed mode — the account needs: GetAccounts, AddAccounts, UpdateAccountContent, UpdateAccountProperties, DeleteAccounts, RetrieveAccounts on the target Safe.

Read-only mode — only GetAccounts and RetrieveAccounts are needed.

CCP

CCP uses IP-based authentication — the Kestra server’s IP must be registered in the CyberArk Application ID’s allowed machines list. No CyberArk user account or password is required.

Minimum configuration

PVWA

kestra:
  secret:
    type: cyberark
    cyberark:
      address: https://your-cyberark-host
      username: YOUR_USERNAME
      password: YOUR_PASSWORD
      platform-id: YOUR_PLATFORM_ID
      safe-name: YOUR_SAFE_NAME

CCP

kestra:
  secret:
    type: cyberark
    read-only: true
    cyberark:
      auth-method: CCP
      address: https://your-cyberark-host
      application-id: YOUR_APP_ID
      safe-name: YOUR_SAFE_NAME

Configuration reference

Read-only mode

Set read-only: true to prevent Kestra from creating or modifying secrets.

PVWA read-only — platform-id is not required in this mode.

kestra:
  secret:
    type: cyberark
    read-only: true
    cyberark:
      address: https://your-cyberark-host
      username: YOUR_USERNAME
      password: YOUR_PASSWORD
      safe-name: YOUR_SAFE_NAME

CCP is always read-only and does not support write operations.

Doppler

Kestra integrates with Doppler as a secrets backend. Secrets are accessed at runtime via the Doppler API and kept only in memory.

Minimum configuration

kestra:
  secret:
    type: doppler
    doppler:
      token: YOUR_SERVICE_TOKEN
      project: my-project
      config: production

Configuration reference

Read-only mode

Use a service token with read access only. The project and config values scope Kestra’s view to a single Doppler environment.

kestra:
  secret:
    type: doppler
    read-only: true
    doppler:
      token: YOUR_SERVICE_TOKEN
      project: my-project
      config: production

1Password

Kestra integrates with 1Password via the 1Password Connect API. A running 1Password Connect server is required.

Minimum configuration

kestra:
  secret:
    type: 1password
    1password:
      address: http://localhost:18080
      token: YOUR_CONNECT_TOKEN
      vault-id: YOUR_VAULT_ID

Configuration reference

Read-only mode

The Connect API token needs only read access to the target vault (item:read scope). No special format requirements apply to secrets.

kestra:
  secret:
    type: 1password
    read-only: true
    1password:
      address: http://localhost:18080
      token: YOUR_CONNECT_TOKEN
      vault-id: YOUR_VAULT_ID

BeyondTrust

Kestra integrates with BeyondTrust Password Safe (Secrets Safe) via the Secret Safe API.

Permissions

Managed mode — the API key must have Secrets Safe permissions to retrieve, create, update, and delete secrets in the target folder.

Read-only mode — only Retrieve permissions are needed.

Minimum configuration

kestra:
  secret:
    type: beyondtrust
    beyondtrust:
      address: https://beyondtrust.example.com
      api-key: YOUR_API_KEY
      run-as: domain\\service-account

Configuration reference

Read-only mode

In read-only mode, folder-id, owner-id, and owner-type are not needed — they apply only when Kestra creates new secrets. The API key needs only Retrieve (read) permissions on the target Secrets Safe.

kestra:
  secret:
    type: beyondtrust
    read-only: true
    beyondtrust:
      address: https://beyondtrust.example.com
      api-key: YOUR_API_KEY
      run-as: domain\\service-account

Delinea Secret Server

Kestra integrates with Delinea Secret Server as a secrets backend.

Minimum configuration

kestra:
  secret:
    type: delinea
    delinea:
      address: https://your-delinea-instance.secretservercloud.com
      username: YOUR_USERNAME
      password: YOUR_PASSWORD

Configuration reference

Reading multi-field Delinea secrets

Delinea secrets contain structured credentials — for example, an Active Directory template has a password, username, and domain as separate fields.

By default, secret() returns the password field:

{{ secret('AD_CREDS') }}

Pass full=true to retrieve all fields. The value key holds the password; metadata holds all other non-password, non-notes template fields keyed by their Delinea item slug:

{% set creds = secret('AD_CREDS', full=true) %}
{{ creds.value }}            {# password #}
{{ creds.metadata.username }}
{{ creds.metadata.domain }}

The keys available under creds.metadata depend on the fields defined in your Delinea secret template. The notes field is always excluded.

Read-only mode

In read-only mode, folder-id and secret-template-id are not required — they are only used when Kestra creates new secrets. The Delinea account needs only view access to the target secrets.

kestra:
  secret:
    type: delinea
    read-only: true
    delinea:
      address: https://your-delinea-instance.secretservercloud.com
      username: YOUR_USERNAME
      password: YOUR_PASSWORD

Bitwarden

Kestra integrates with Bitwarden Secrets Manager. Secrets are decrypted client-side by Kestra workers at runtime and kept only in memory. No Bitwarden CLI or native SDK is required.

Minimum configuration

kestra:
  secret:
    type: bitwarden
    bitwarden:
      access-token: YOUR_ACCESS_TOKEN
      organization-id: YOUR_ORGANIZATION_ID

Configuration reference

Read-only mode

The machine account access token must have read access to the Bitwarden project containing the secrets. Read-only mode prevents Kestra from creating or modifying secrets.

kestra:
  secret:
    type: bitwarden
    read-only: true
    bitwarden:
      access-token: YOUR_ACCESS_TOKEN
      organization-id: YOUR_ORGANIZATION_ID

JDBC (PostgreSQL, H2, MySQL)

The JDBC backend stores encrypted secrets in Kestra’s own database. This is the default for open-source deployments.

kestra:
  secret:
    type: jdbc
    jdbc:
      secret: YOUR_ENCRYPTION_KEY

The encryption key must be at least 32 characters. See the Security and Secrets configuration guide for key generation details.

Elasticsearch

The Elasticsearch backend stores secrets with AES encryption in the same Elasticsearch cluster used by Kestra (Kafka/Elastic backend deployments).

kestra:
  secret:
    type: elasticsearch
    elasticsearch:
      secret: "a-secure-32-character-minimum-key"

See the Security and Secrets configuration guide for key generation details.

Shared configuration

Default tags

Each secret backend accepts a tags map. Tags are added to every secret created or updated through Kestra and can be used as read-only mode filters.

kestra:
  secret:
    aws-secret-manager:
      tags:
        application: kestra-production
        environment: prod

Filter secrets by tags (read-only mode)

When integrating an external secrets manager in read-only mode, you can filter which secrets are visible in Kestra by matching tags. Set read-only: true and configure filter-on-tags with the key/value pairs to match.

kestra:
  secret:
    type: aws-secret-manager
    read-only: true
    aws-secret-manager:
      filter-on-tags:
        tags:
          application: kestra-production

kestra:
  secret:
    type: azure-key-vault
    read-only: true
    azure-key-vault:
      filter-on-tags:
        tags:
          application: kestra-production

kestra:
  secret:
    type: google-secret-manager
    read-only: true
    google-secret-manager:
      filter-on-tags:
        tags:
          application: kestra-production

kestra:
  secret:
    type: vault
    read-only: true
    vault:
      filter-on-tags:
        application: kestra-production

kestra:
  secret:
    type: cyberark
    read-only: true
    cyberark:
      filter-on-tags:
        application: kestra-production

kestra:
  secret:
    type: doppler
    read-only: true
    doppler:
      filter-on-tags:
        application: kestra-production

kestra:
  secret:
    type: 1password
    read-only: true
    1password:
      filter-on-tags:
        application: kestra-production

kestra:
  secret:
    type: beyondtrust
    read-only: true
    beyondtrust:
      filter-on-tags:
        application: kestra-production

kestra:
  secret:
    type: delinea
    read-only: true
    delinea:
      filter-on-tags:
        application: kestra-production

Exclude secrets by tags (read-only mode)

Use excluded-tags to hide secrets from Kestra based on their tags. Any secret whose tags match at least one key-value pair in excluded-tags is excluded from Kestra’s view, even if it would otherwise be included by filter-on-tags. This filter applies only when read-only: true is set.

When both filter-on-tags and excluded-tags are configured, a secret must match all entries in filter-on-tags and must not match any entry in excluded-tags.

The following examples exclude secrets tagged hidden: "true" for each supported provider:

kestra:
  secret:
    type: aws-secret-manager
    read-only: true
    aws-secret-manager:
      excluded-tags:
        hidden: "true"

kestra:
  secret:
    type: azure-key-vault
    read-only: true
    azure-key-vault:
      excluded-tags:
        hidden: "true"

kestra:
  secret:
    type: google-secret-manager
    read-only: true
    google-secret-manager:
      excluded-tags:
        hidden: "true"

kestra:
  secret:
    type: vault
    read-only: true
    vault:
      excluded-tags:
        hidden: "true"

kestra:
  secret:
    type: cyberark
    read-only: true
    cyberark:
      excluded-tags:
        hidden: "true"

kestra:
  secret:
    type: doppler
    read-only: true
    doppler:
      excluded-tags:
        hidden: "true"

kestra:
  secret:
    type: 1password
    read-only: true
    1password:
      excluded-tags:
        hidden: "true"

kestra:
  secret:
    type: beyondtrust
    read-only: true
    beyondtrust:
      excluded-tags:
        hidden: "true"

kestra:
  secret:
    type: delinea
    read-only: true
    delinea:
      excluded-tags:
        hidden: "true"

Filter secrets by prefix (AWS, read-only mode)

For AWS Secrets Manager, you can filter secrets by a name prefix when using read-only mode. Use filter-on-prefix.prefix to select secrets whose names start with the given prefix and filter-on-prefix.keep-prefix to control whether the prefix is kept in the Kestra secret key.

kestra:
  secret:
    type: aws-secret-manager
    read-only: true
    aws-secret-manager:
      filter-on-prefix:
        prefix: prod_
        keep-prefix: true

Secret caching

For cloud-backed secrets managers, enable caching to reduce the number of API calls per execution.

kestra:
  secret:
    cache:
      enabled: true
      maximum-size: 1000
      expire-after-write: 60s

Secret isolation

Restrict which Kestra services are permitted to resolve secrets. Use this to prevent components such as the Executor from accessing secret values directly, limiting resolution to Workers only.

kestra:
  secret:
    isolation:
      enabled: true
      denied-services:
        - EXECUTOR

Known limitations

Pre-existing secrets are not migrated when switching backends

When a namespace or tenant switches from Kestra’s internal secret backend (JDBC or Elasticsearch) to an external secrets manager, existing secrets stored in the internal backend are not automatically migrated.

Kestra will attempt to resolve those secret keys against the new external backend. Because the external backend does not hold them, resolution fails silently — the Kestra UI shows no error, but the secret() function fails at runtime when a flow uses one of those keys.

Switching backends requires exporting all existing secrets from the current backend, re-creating them in the new external backend with the correct tags (namespace, key, prefix), and then updating the backend configuration in Kestra.

This also applies when adding a dedicated external backend to a namespace that previously used the instance-level JDBC or Elasticsearch backend.