Secrets & Environment¶

Plain Environment Variables¶

YAMLPython

components:
  backend:
    type: web
    image: myapp:latest
    port: 8000
    env:
      DEBUG: "false"
      LOG_LEVEL: "info"

backend = web(
    image=image("myapp:latest"),
    port=8000,
    env={
        "DEBUG": "false",
        "LOG_LEVEL": "info",
    },
)

Secret References (secretEnv)¶

Reference a secret that belongs to another component (e.g., the PostgreSQL component creates its own secret):

YAMLPython

components:
  db:
    type: postgresql

  backend:
    type: web
    image: myapp:latest
    port: 8000
    secretEnv:
      DATABASE_URL:
        component: db
        key: DATABASE_URL

from helm_me import postgresql, web, image, secret_ref

db = postgresql()
backend = web(
    image=image("myapp:latest"),
    port=8000,
    secret_refs={"DATABASE_URL": secret_ref(db, "DATABASE_URL")},
)

component — the name of the component that owns the secret (e.g., db for PostgreSQL)
key — the specific key within that secret

Reference an Existing Kubernetes Secret¶

If the secret already exists in the cluster:

YAMLPython

secretEnv:
  API_KEY:
    name: my-external-secret
    key: API_KEY

from helm_me import secret_ref

backend = web(
    ...
    secret_refs={"API_KEY": secret_ref("my-external-secret", "API_KEY")},
)

Use name (not component) for pre-existing secrets.

Inline Secrets¶

Create secrets alongside your app:

YAMLPython

secrets:
  app-credentials:
    strings:
      OPENAI_API_KEY: "sk-..."
      STRIPE_KEY: "pk_test_..."
    reconcile: apply

components:
  backend:
    secretEnv:
      OPENAI_API_KEY:
        name: app-credentials
        key: OPENAI_API_KEY

from helm_me import app, secret, secret_ref, web, image, Reconcile

spec = app(
    name="my-app",
    secrets=[
        secret(
            name="app-credentials",
            strings={"OPENAI_API_KEY": "sk-..."},
            reconcile=Reconcile.APPLY,
        )
    ],
    components=[
        web(
            name="backend",
            image=image("myapp:latest"),
            port=8000,
            secret_refs={"OPENAI_API_KEY": secret_ref("app-credentials", "OPENAI_API_KEY")},
        )
    ],
)

Warning

Inline secret values are stored in plain text in the spec file. For production, use external secret management and reference existing secrets by name.

Service References (serviceEnv)¶

Inject another component's hostname automatically:

YAMLPython

components:
  cache:
    type: redis

  backend:
    type: web
    image: myapp:latest
    port: 8000
    serviceEnv:
      REDIS_HOST:
        component: cache
      REDIS_URL:
        component: cache
        port: 6379

from helm_me import redis, web, image, ServiceRef

cache = redis(name="cache")
backend = web(
    image=image("myapp:latest"),
    port=8000,
    env={
        "REDIS_HOST": ServiceRef("cache"),
        "REDIS_URL": ServiceRef("cache", 6379),
    },
)

This injects the Kubernetes service hostname (e.g., myapp-cache) or host:port format.

Managing Secrets via CLI¶

# Create or update a secret
helm-me secret set my-secret --data API_KEY=sk-abc123

# Inspect a secret
helm-me secret get my-secret