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.

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 cloud provider to use (gcp, aws, azure, openbao).

Project ID

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

Mappings

The mappings 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"

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