Learn how to configure Kuba with the kuba.yaml file and understand advanced features like variable interpolation and secret paths.

Initialize Configuration

Start by creating a configuration file using the kuba init command:

kuba init

This will generate a default kuba.yaml file that you can customize for your needs.

OR

Import from dotenv (.env*)

You can also create a configuration file by importing existing environment variables from a .env file using the following command:

kuba convert --from dotenv --infile .env

See kuba convert --help for more options on importing from different formats.

Basic Structure

The kuba.yaml file is organized into environment sections, each with its own provider and env:

# yaml-language-server: $schema=https://kuba.mwco.app/kuba.schema.json
---
default:
  provider: gcp
  project: 1337
  env:
    DATABASE_URL:
      secret-key: "database-connection-string"
    API_KEY:
      secret-key: "external-api-key"

development:
  provider: gcp
  project: 1337
  env:
    DEV_DATABASE_URL:
      secret-key: "dev-database-connection-string"

production:
  provider: gcp
  project: 1337
  env:
    PROD_DATABASE_URL:
      secret-key: "prod-database-connection-string"

Environment Sections

Each top-level section (like default, development, production) represents a different environment configuration.

Provider Configuration

The provider field specifies which provider to use (gcp, aws, azure, openbao, local).

Project ID

The project field specifies the project ID for the cloud provider (required for GCP and Azure).

Env

The env array defines how secrets are mapped to environment variables.

Individual Secrets (secret-key)

Fetch a single secret from your cloud provider:

env:
  DATABASE_URL:
    secret-key: "database-connection-string"
  API_KEY:
    secret-key: "external-api-key"

Secret Paths (secret-path)

Fetch all secrets under a specific path prefix:

env:
  DB:
    secret-path: "database"
  API:
    secret-path: "external-apis"

This will create environment variables like DB_CONNECTION_STRING, DB_USERNAME, API_STRIPE_KEY, etc.

Hard-coded Values (value)

Set static environment variables:

env:
  APP_ENV:
    value: "production"
  DEBUG:
    value: "false"

Basic Interpolation

Kuba supports environment variable interpolation using ${VAR_NAME} syntax:

env:
  DB_PASSWORD:
    secret-key: "db-password"
  DB_HOST:
    value: "mydbhost"
  DB_CONNECTION_STRING:
    value: "postgresql://user:${DB_PASSWORD}@${DB_HOST}:5432/mydb"

System Environment Variables

Reference system environment variables:

API_URL:
  value: "https://api.${DOMAIN}/v1"

Default Values

Provide fallback values with ${VAR:-default} syntax:

REDIS_URL:
  value: "redis://${REDIS_HOST:-localhost}:${REDIS_PORT:-6379}/0"
Important: Interpolation is processed in order, so you can reference variables defined earlier in the same configuration.

Multiple Cloud Providers

You can fetch secrets from different cloud providers in the same configuration:

default:
  provider: gcp
  project: 1337
  env:
    GCP_PROJECT_ID:
      secret-key: "gcp_project_secret"
    AWS_PROJECT_ID:
      secret-key: "aws_project_secret"
      provider: aws
    AZURE_PROJECT_ID:
      secret-key: "azure_project_secret"
      provider: azure
      project: "my-azure-project"

Full Configuration Example

Here's a comprehensive example showing all features:

# yaml-language-server: $schema=https://kuba.mwco.app/kuba.schema.json
---
default:
  provider: gcp
  project: 1337
  env:
    # Individual secrets
    DATABASE_URL:
      secret-key: "database-connection-string"
    STRIPE_API_KEY:
      secret-key: "stripe-api-key"

    # Secret paths for bulk loading
    DB:
      secret-path: "database"
    API:
      secret-path: "external-apis"

    # Hard-coded values
    APP_ENV:
      value: "development"
    DEBUG:
      value: "true"

    # Interpolated values
    REDIS_URL:
      value: "redis://${REDIS_HOST:-localhost$}:${REDIS_PORT:-6379}/0"
    LOG_LEVEL:
      value: "${LOG_LEVEL:-info}"

development:
  provider: gcp
  project: 1337
  env:
    DEV_DATABASE_URL:
      secret-key: "dev-database-connection-string"
    DEV_STRIPE_API_KEY:
      secret-key: "dev-stripe-api-key"

staging:
  provider: gcp
  project: 1337
  env:
    STAGING_DATABASE_URL:
      secret-key: "staging-database-connection-string"
    STAGING_STRIPE_API_KEY:
      secret-key: "staging-stripe-api-key"

production:
  provider: gcp
  project: 1337
  env:
    PROD_DATABASE_URL:
      secret-key: "prod-database-connection-string"
    PROD_STRIPE_API_KEY:
      secret-key: "prod-stripe-api-key"
    APP_ENV:
      value: "production"
    DEBUG:
      value: "false"

Learn how to configure Kuba itself (globally).

Caching is off by default. To enable caching, run the following command:

kuba config cache --enable --ttl 14d

This will enable caching of secrets locally, with a time-to-live (TTL) of 14 days. You can adjust the TTL as needed.

Check kuba cache --help for more options related to managing the cache.

Organization

  • Use descriptive environment variable names
  • Group related secrets with secret paths
  • Keep environment-specific overrides minimal
  • Document your configuration structure

Security

  • Never commit secrets to version control
  • Use environment-specific configurations
  • Limit access to production secrets
  • Rotate secrets regularly

Maintenance

  • Keep configurations in sync across teams
  • Use consistent naming conventions
  • Test configurations in staging first
  • Version control your configuration templates

Performance

  • Use secret paths for bulk operations
  • Avoid unnecessary cross-provider calls
  • Cache configurations when possible
  • Monitor secret access patterns

Cloud Providers Setup

Configure authentication and permissions for your cloud providers.

Cloud Providers Guide

Usage Examples

See practical examples of how to use your configuration.

Examples Guide