Configuration

k8s-scheduler is configured through environment variables. Different variables apply to the server and operator components.

Server Configuration

The server (cmd/server) accepts configuration via environment variables or Vault-injected secrets.

Always Required

string

required

PostgreSQL connection string.

DATABASE_DSN="postgres://user:password@localhost:5432/scheduler?sslmode=disable"

For production, enable SSL:

DATABASE_DSN="postgres://user:password@db.example.com:5432/scheduler?sslmode=require"

Required in Production

These can be skipped when DEV_MODE=true for local development.

string

required

Google OAuth2 client ID from Google Cloud Console.

GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"

string

required

Google OAuth2 client secret.

GOOGLE_CLIENT_SECRET="your-client-secret"

string

required

OAuth callback URL. Must match the authorized redirect URI in Google Cloud Console.

GOOGLE_REDIRECT_URL="https://app.example.com/oauth2/callback"

Server Settings

boolean

default:"false"

Enable local development mode. Disables OAuth and auto-logs in as dev@localhost.

DEV_MODE="true"

Never enable in production. This bypasses all authentication.

boolean

default:"false"

Serve embedded React SPA from go:embed.

REACT_UI="true"

Set to false if serving the frontend separately (e.g., via CDN or Vite dev server).

string

default:":8081"

HTTP server listen address.

SERVER_ADDR=":8081"

string

default:"http://localhost:8081"

Public URL of the application. Used for OAuth redirects and email links.

BASE_URL="https://app.example.com"

string

default:"example.com"

Base domain for user deployment ingresses.

DEPLOYMENT_DOMAIN="example.com"

User deployments get subdomains like:

https://user-123-my-app.example.com

boolean

default:"false"

Enable Kubernetes integration (create UserDeployment CRs).

KUBERNETES_ENABLED="true"

Set to false for local development without a K8s cluster.

string

default:"sandbox-%s"

Namespace pattern for user sandboxes. %s is replaced with user ID.

KUBERNETES_NAMESPACE="sandbox-%s"

Examples:

User user-123 → namespace sandbox-user-123
User alice → namespace sandbox-alice

duration

default:"30s"

Interval for reconciling deployment status from Kubernetes.

KUBERNETES_RECONCILE_INTERVAL="30s"

Session Configuration

string

default:"memory"

Session storage backend. Options: memory, postgres, redis.

SESSION_BACKEND="postgres"

memory

In-memory storage (lost on restart).Use for: Local developmentDon’t use: Production

postgres

PostgreSQL-backed sessions.Use for: Production (shared database)Requires: DATABASE_DSN

redis

Redis-backed sessions.Use for: Production (separate cache)Requires: REDIS_ADDR

duration

default:"24h"

Session lifetime before automatic expiration.

SESSION_DURATION="24h"

Supports: 1h, 24h, 168h (7 days), etc.

Cookie name for session identifier.

SESSION_COOKIE_NAME="session_id"

duration

default:"24h"

Session lifetime before expiration.

SESSION_DURATION="24h"

duration

default:"1h"

Interval for cleaning up expired sessions (memory and PostgreSQL backends only).

SESSION_CLEANUP_INTERVAL="1h"

Cookie domain for session cookies. Useful for subdomain sharing.

SESSION_COOKIE_DOMAIN=".example.com"

Cookie name for OAuth state parameter.

STATE_COOKIE_NAME="oauth_state"

Require HTTPS for cookies. Enable in production.

COOKIE_SECURE="true"

string

Redis server address. Required when SESSION_BACKEND=redis.

REDIS_ADDR="localhost:6379"

Secrets Backend

k8s-scheduler supports three secrets backends for user/template/deployment secrets:

string

default:"database"

Secrets storage backend. Options: database, vault, aws.

SECRETS_BACKEND="vault"

database

Encrypted secrets in PostgreSQL.Requires: SECRETS_ENCRYPTION_KEYUse for: Simple deployments

vault

HashiCorp Vault KV v2.Requires: VAULT_ADDR, VAULT_TOKENUse for: Production (recommended)

aws

AWS Secrets Manager.Requires: AWS_REGION, IAM roleUse for: AWS-native deployments

Database Backend

string

Base64-encoded 32-byte encryption key. Required when SECRETS_BACKEND=database.

# Generate a key
openssl rand -base64 32

SECRETS_ENCRYPTION_KEY="your-base64-encoded-key"

Store this key securely. Losing it means all secrets become unrecoverable.

Vault Backend

string

Vault server address.

VAULT_ADDR="http://vault.vault.svc.cluster.local:8200"

string

Vault access token.

VAULT_TOKEN="hvs.your-vault-token"

string

Path to Vault token file (for Vault Agent auto-refresh).

VAULT_TOKEN_FILE="/vault/secrets/token"

Preferred over VAULT_TOKEN in production.

string

default:"secret"

Vault KV mount path.

VAULT_MOUNT_PATH="secret"

AWS Backend

string

AWS region for Secrets Manager.

AWS_REGION="us-east-1"

AWS credentials are auto-discovered from:

Instance metadata (IAM role)
Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
~/.aws/credentials

Optional Integrations

Billing (Stripe)

boolean

default:"false"

Enable Stripe billing integration.

BILLING_ENABLED="true"

string

Stripe secret key (sk_test_... or sk_live_...).

STRIPE_API_KEY="sk_live_..."

string

Stripe webhook signing secret (whsec_...).

STRIPE_WEBHOOK_SECRET="whsec_..."

Used to verify webhook payloads from Stripe.

Email (Invitations)

string

Email provider. Options: smtp, sendgrid.

EMAIL_PROVIDER="smtp"

string

SMTP server hostname.

SMTP_HOST="smtp.gmail.com"

string

default:"587"

SMTP server port.

SMTP_PORT="587"

string

SMTP authentication username.

SMTP_USERNAME="user@example.com"

string

SMTP authentication password.

SMTP_PASSWORD="your-password"

string

SendGrid API key. Required when EMAIL_PROVIDER=sendgrid.

SENDGRID_API_KEY="SG.your-api-key"

AI (Template Generation)

string

Anthropic API key for AI-assisted template generation.

ANTHROPIC_API_KEY="sk-ant-..."

Optional. Enables AI template generation feature in the UI.

Operator Configuration

The operator (cmd/operator) manages UserDeployment custom resources.

Environment Variables

string

required

Base domain for ingress routing.

DEPLOYMENT_DOMAIN="example.com"

Must match the server’s DEPLOYMENT_DOMAIN.

string

ClusterSecretStore name for External Secrets Operator.

CLUSTER_SECRET_STORE="vault-backend"

If empty, the operator skips creating ExternalSecret resources.

boolean

default:"false"

Skip NetworkPolicy creation (for local development).

DISABLE_NETWORK_POLICIES="true"

Useful for clusters without NetworkPolicy support (e.g., kind without Calico).

string

Namespace to watch for UserDeployments. Empty = all namespaces.

WATCH_NAMESPACE=""

Configuration Examples

Production (Vault + PostgreSQL)

.env

# Database
DATABASE_DSN="postgres://user:password@prod-db.example.com:5432/scheduler?sslmode=require"

# OAuth
GOOGLE_CLIENT_ID="prod-client.apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="prod-secret"
BASE_URL="https://app.example.com"
GOOGLE_REDIRECT_URL="https://app.example.com/oauth2/callback"

# Domain
DEPLOYMENT_DOMAIN="example.com"

# Kubernetes
KUBERNETES_ENABLED="true"
KUBERNETES_NAMESPACE="sandbox-%s"

# Secrets
SECRETS_BACKEND="vault"
VAULT_ADDR="http://vault.vault.svc.cluster.local:8200"
VAULT_TOKEN_FILE="/vault/secrets/token"

# Session
SESSION_BACKEND="postgres"
SESSION_DURATION="24h"
COOKIE_SECURE="true"

# Server
REACT_UI="true"
SERVER_ADDR=":8081"

# Billing
BILLING_ENABLED="true"
STRIPE_API_KEY="sk_live_..."
STRIPE_WEBHOOK_SECRET="whsec_..."

# Email
EMAIL_PROVIDER="smtp"
SMTP_HOST="smtp.sendgrid.net"
SMTP_PORT="587"
SMTP_USERNAME="apikey"
SMTP_PASSWORD="SG.your-api-key"

Local Development

.env

# Database (local PostgreSQL)
DATABASE_DSN="postgres://postgres:postgres@localhost:5432/scheduler?sslmode=disable"

# Dev mode (skip OAuth)
DEV_MODE="true"
BASE_URL="http://localhost:8081"

# Domain
DEPLOYMENT_DOMAIN="localhost"

# Disable Kubernetes
KUBERNETES_ENABLED="false"

# Secrets (database)
SECRETS_BACKEND="database"
SECRETS_ENCRYPTION_KEY="your-base64-key"

# Session (in-memory)
SESSION_BACKEND="memory"

# Server
REACT_UI="true"
SERVER_ADDR=":8081"

AWS Deployment (No Vault)

.env

# Database (RDS)
DATABASE_DSN="postgres://user:password@prod.abc123.us-east-1.rds.amazonaws.com:5432/scheduler?sslmode=require"

# OAuth
GOOGLE_CLIENT_ID="prod-client.apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="prod-secret"
BASE_URL="https://app.example.com"
GOOGLE_REDIRECT_URL="https://app.example.com/oauth2/callback"

# Domain
DEPLOYMENT_DOMAIN="example.com"

# Kubernetes
KUBERNETES_ENABLED="true"
KUBERNETES_NAMESPACE="sandbox-%s"

# Secrets (AWS Secrets Manager)
SECRETS_BACKEND="aws"
AWS_REGION="us-east-1"

# Session (Redis)
SESSION_BACKEND="redis"
REDIS_ADDR="prod-redis.abc123.cache.amazonaws.com:6379"
SESSION_DURATION="24h"
COOKIE_SECURE="true"

# Server
REACT_UI="true"
SERVER_ADDR=":8081"

ConfigMap (Helm)

When deploying via Helm, non-secret configuration is stored in a ConfigMap:

charts/k8s-scheduler/templates/configmap-server.yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: k8s-scheduler-server-config
  namespace: {{ .Release.Namespace }}
data:
  BASE_URL: "https://app.{{ .Values.domain }}"
  DEPLOYMENT_DOMAIN: "{{ .Values.domain }}"
  GOOGLE_REDIRECT_URL: "https://app.{{ .Values.domain }}/oauth2/callback"
  KUBERNETES_ENABLED: "true"
  KUBERNETES_NAMESPACE: "{{ .Values.kubernetes.namespaceTemplate }}"
  SESSION_BACKEND: "{{ .Values.session.backend }}"
  SESSION_DURATION: "{{ .Values.session.duration }}"
  COOKIE_SECURE: "{{ .Values.session.cookieSecure }}"
  SECRETS_BACKEND: "vault"
  VAULT_ADDR: "{{ .Values.vault.address }}"
  VAULT_MOUNT_PATH: "{{ .Values.vault.mountPath }}"

Secrets are injected via Vault Agent annotations on the server deployment.

Next Steps

Deployment Guide

Deploy k8s-scheduler to production

Dependencies

Learn about platform dependencies

Getting Started

Core Concepts

Components

Deployment

API Reference

Server Configuration

Always Required

Required in Production

Server Settings

Session Configuration

memory

postgres

redis

Secrets Backend

database

vault

aws

Database Backend

Vault Backend

AWS Backend

Optional Integrations

Billing (Stripe)

Email (Invitations)

AI (Template Generation)

Operator Configuration

Environment Variables

Configuration Examples

Production (Vault + PostgreSQL)

Local Development

AWS Deployment (No Vault)

ConfigMap (Helm)

Next Steps

Deployment Guide

Dependencies

​Server Configuration

​Always Required

​Required in Production

​Server Settings

​Session Configuration

memory

postgres

redis

​Secrets Backend

database

vault

aws

​Database Backend

​Vault Backend

​AWS Backend

​Optional Integrations

​Billing (Stripe)

​Email (Invitations)

​AI (Template Generation)

​Operator Configuration

​Environment Variables

​Configuration Examples

​Production (Vault + PostgreSQL)

​Local Development

​AWS Deployment (No Vault)

​ConfigMap (Helm)

​Next Steps

Deployment Guide

Dependencies

Server Configuration

Always Required

Required in Production

Server Settings

Session Configuration

Secrets Backend

Database Backend

Vault Backend

AWS Backend

Optional Integrations

Billing (Stripe)

Email (Invitations)

AI (Template Generation)

Operator Configuration

Environment Variables

Configuration Examples

Production (Vault + PostgreSQL)

Local Development

AWS Deployment (No Vault)

ConfigMap (Helm)

Next Steps