Secret Backends

KeyZero resolves secrets from pluggable backends. Each backend is defined in the backends section of the bundle and referenced by resolvers on resources.

env_file

Read secrets from a local KEY=VALUE file. Use for local development and testing.

Bundle config

backends:
  local:
    type: env_file
    path: ./secrets.env

Resolver config

resolvers:
  - name: password
    mode: direct
    backend: local
    field: DB_PASSWORD       # Key in the env file

File format

# Comments are supported
DB_PASSWORD=super-secret-password
API_KEY=sk-live-abc123
ADMIN_TOKEN=admin-xyz

Required backend field: path -- path to the env file.

Required resolver field: field -- the key to look up in the file.

hashicorp_vault

Fetch secrets from HashiCorp Vault KV v2 engine. Use for production secret storage.

Bundle config

backends:
  vault-prod:
    type: hashicorp_vault
    address: https://vault.example.com

Resolver config

resolvers:
  - name: db-pass
    mode: direct
    backend: vault-prod
    path: secret/data/myapp/db    # Vault KV v2 path
    field: password               # Field within the secret data

Environment variables

How it works

KeyZero makes a GET request to {address}/v1/{path} with the X-Vault-Token header. It expects the KV v2 response structure and extracts the field from data.data.<field>.

Required backend field: address -- Vault server URL.

Required resolver fields: path (Vault path), field (field name within the secret).

aws_secrets_manager

Fetch secrets from AWS Secrets Manager. Use for AWS-native workloads.

Bundle config

backends:
  aws:
    type: aws_secrets_manager
    region: us-east-1            # Optional, uses AWS SDK defaults if omitted

Resolver config

resolvers:
  - name: api-key
    mode: direct
    backend: aws
    secret_id: prod/api-key      # Secret name or ARN (can also use 'path')
    field: api_key               # Optional: extract a field from JSON secret

Authentication

Uses the standard AWS SDK credential chain (environment variables, instance profile, SSO, etc.). No KeyZero-specific auth configuration needed.

Field extraction

• If field is set and the secret value is JSON, the specified field is extracted.
• If field is omitted, the raw secret string is returned.

Required resolver field: secret_id or path -- the secret identifier.

aws_sts

Generate temporary AWS credentials via STS AssumeRole. Use for granting scoped AWS access to workloads.

Bundle config

backends:
  sts:
    type: aws_sts
    region: us-east-1            # Optional

Resolver config

resolvers:
  - name: deploy-creds
    mode: direct
    backend: sts
    role_arn: arn:aws:iam::123456789012:role/deploy
    duration_seconds: 900        # Optional, default: 900 (15 minutes)

Authentication

Uses the standard AWS SDK credential chain. The calling identity must have sts:AssumeRole permission for the target role.

Response format

Returns a JSON string with temporary credentials:

{
  "access_key_id": "ASIA...",
  "secret_access_key": "...",
  "session_token": "..."
}

The ttl is automatically set to the duration_seconds value.

Required resolver field: role_arn -- the IAM role to assume.

onepassword_cli

Fetch secrets from 1Password using the op CLI. Use for team password management workflows.

Bundle config

backends:
  onepass:
    type: onepassword_cli
    vault: Engineering            # Optional: 1Password vault name

Resolver config

resolvers:
  - name: api-token
    mode: direct
    backend: onepass
    path: "API Token"            # 1Password item name
    field: credential            # Field name within the item

Prerequisites

• The op CLI must be installed and authenticated (e.g., via op signin or service account token)
• The OP_SERVICE_ACCOUNT_TOKEN env var works for non-interactive use

How it works

KeyZero runs op item get <path> --fields <field> --format json and extracts the value from the JSON response. If vault is set on the backend, --vault <vault> is added to the command.

Required resolver fields: path (item name), field (field name).