NanokitDocs

Appearance

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.

bash
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.

3. Recommended Path Convention ​

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:

hcl
# 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.

yaml
services:
  web-api:
    depends_on:
      - main-db # 🚀 1. Looks in Vault. 2. Falls back to NANOKIT_DB_MAIN_DB env var.