APISIX Vault Integration#

APISIX integrates with HashiCorp Vault as a pluggable external secret manager, keeping sensitive values — TLS certificates, private keys, API keys, plugin credentials — out of etcd plain text. APISIX supports only Vault KV engine version V1 1. Alongside Vault, APISIX also supports environment variables, AWS Secrets Manager, and GCP Secrets Manager through the same abstraction 2.

How It Works#

Secrets stored in Vault are referenced anywhere in plugin or SSL configurations via a URI of the form:

$secret://vault/<confid>/<secret_name>/<key>

• vault — the manager name, maps to apisix/secret/vault.lua
• <confid> — the ID of the APISIX Secret resource (registered via Admin API)
• <secret_name> — path within Vault's KV store (relative to the configured prefix)
• <key> — the field within the Vault secret JSON object

At runtime, fetch_by_uri() parses the URI via parse_secret_uri(), looks up the named Secret resource from etcd (/secrets/{manager}/{confid}), then calls the manager's get() function. The resolution is cached in an LRU cache with a 300-second TTL and 512-entry cap 3.

The URI prefix $secret:// is validated by check_secret_uri() 4. The schema enforces this pattern on SSL cert, key, certs, and keys fields as an alternative to direct PEM values 5.

Vault HTTP Client (apisix/secret/vault.lua)#

The full implementation lives in apisix/secret/vault.lua. Key behaviors:

• Schema — requires uri, prefix, and token; namespace is optional for Vault Enterprise / HCP Vault 6.
• Request construction — the HTTP path is {uri}/v1/{prefix}/{secret_name} 7, using GET with an X-Vault-Token header 8.
• Namespace header — if namespace is set, X-Vault-Namespace is added per Vault Enterprise namespace rules 9.
• Token from env — the token value can itself be an $ENV:// reference; env.fetch_by_uri() is attempted first 10.
• Key splitting — the key argument must be in the form main_key/sub_key. The function fetches main_key from Vault and extracts sub_key from the response's data object 11.
• Default timeout — 5 seconds 12.

Registering a Vault Secret Resource#

Register a Vault connection via the Admin API (PUT /apisix/admin/secrets/vault/{id}) 13:

curl http://127.0.0.1:9180/apisix/admin/secrets/vault/1 \
  -H "X-API-KEY: $admin_key" -X PUT -d '{
    "uri": "https://127.0.0.1:8200",
    "prefix": "apisix",
    "token": "root"
  }'

For standalone mode, add to apisix.yaml 14:

secrets:
  - id: vault/1
    prefix: apisix
    token: root
    uri: 127.0.0.1:8200

The Admin API resource handler is apisix/admin/secrets.lua. On PUT, it dynamically loads apisix.secret.vault, validates the request body against the Vault schema, and rejects unknown managers 15. POST is not supported 16.

Using Vault Secrets in SSL Objects#

cert and key fields on an SSL object accept either inline PEM or a $secret:// URI 17. During the TLS certificate phase, _M.set() detects secret URIs and fetches the actual PEM values before calling ngx_ssl.set_cert() / ngx_ssl.set_priv_key() 18.

Example — store a TLS cert in Vault then reference it from an SSL object:

# Write to Vault
vault kv put apisix/my-cert cert=@server.pem key=@server.key

# Create SSL object referencing Vault
curl http://127.0.0.1:9180/apisix/admin/ssls/1 \
  -H "X-API-KEY: $admin_key" -X PUT -d '{
    "sni": "example.com",
    "cert": "$secret://vault/1/my-cert/cert",
    "key": "$secret://vault/1/my-cert/key"
  }'

(Pattern adapted from How to Use Vault to Manage Certificates in APISIX)

The same pattern applies to plugin fields — for example, key-auth's key field: "$secret://vault/1/jack/auth-key" 19.

Key Files#