Skip to Content
ConfigurationVault Setup

HashiCorp Vault (Enterprise Mode)

While Nanokit provides a powerful built-in secrets system based on environment variables, it also supports HashiCorp Vault as an advanced, optional engine for enterprise-grade security.

1. Why use Vault?

By default, Nanokit is infrastructure-agnostic and works “out of the box” using the host environment to resolve secrets. You should consider enabling Vault if:

  • You need a centralized, audited secret management cluster.
  • You require dynamic short-lived credentials (e.g., dynamic AWS or DB users).
  • Your organization already mandates Vault for production deployments.

2. Configuration

To enable the Vault provider, set the standard Vault environment variables on your machine or CI runner. Nanokit will detect them and automatically activate Enterprise Mode.

export VAULT_ADDR="https://vault.yourcompany.com:8200"
export VAULT_TOKEN="hvs.your-secure-token"

[!NOTE] When these variables are present, Nanokit will prioritize Vault for resolving vault:// URIs and searching for transparent database credentials.

Nanokit follows a strict path convention to enable Zero-Config Transparent Secrets. We recommend organizing your secrets as follows:

Application Secrets

secret/nanokit/<project>/<environment>/<service>/<variable>

Database Complex Keys

secret/nanokit/<project>/<environment>/databases/<database-name>

[!IMPORTANT] Database Complex Keys should be stored as JSON objects in Vault. Nanokit will automatically pull the entire object and inject each key as a prefixed environment variable (e.g., DB_NAME_URL, DB_NAME_PASSWORD).

4. Policy Example

Here is a sample Vault policy that grants Nanokit read access to your project’s secrets:

# Allow read access to all secrets for the "my-app" project
path "secret/data/nanokit/my-app/*" {
  capabilities = ["read"]
}
 
# Explicit access to the databases mount
path "secret/data/nanokit/my-app/+/databases/*" {
  capabilities = ["read"]
}

5. Transparent Failback

If Vault is enabled but a specific project secret is missing, Nanokit will gracefully fall back to its Built-in Secrets Provider. This allows for a hybrid setup where some secrets are in Vault and others are provided via traditional environment variables.

services:
  web-api:
    depends_on:
      - main-db # 🚀 1. Looks in Vault. 2. Falls back to NK_DB_MAIN_DB env var.
Secrets & Env VariablesNetworks