Dependencies

k8s-scheduler takes an opinionated approach to infrastructure. This page documents all platform dependencies, why they’re needed, and how they integrate.

Dependency Overview

Required

Must be installed for basic functionality

Optional

Additional features and integrations

Conditional

Required only in specific scenarios

Required Dependencies

These components are required for k8s-scheduler to function.

PostgreSQL

database

required

Relational database for persistent storage.Version: 12+Why: Stores users, organizations, teams, deployments, templates, billing plans, sessionsIntegration points:

Server connects via DATABASE_DSN
Optional session backend (SESSION_BACKEND=postgres)
Database migrations run via migrate tool

Managed options:

AWS RDS for PostgreSQL
Google Cloud SQL
Azure Database for PostgreSQL
Self-hosted (via Helm chart)

Configuration:

DATABASE_DSN="postgres://user:password@db-host:5432/scheduler?sslmode=require"

Traefik

ingress

required

Ingress controller for routing wildcard subdomains to user deployments.Version: v2.10+Why: Routes *.domain.com traffic to individual user deployment servicesIntegration points:

Operator creates Ingress resources with ingressClassName: traefik
Handles routing for user deployments like user-123-myapp.example.com
Works alongside AWS ALB Controller (server uses ALB, user deployments use Traefik)

Installation:

helm repo add traefik https://traefik.github.io/charts
helm install traefik traefik/traefik -n traefik --create-namespace

Why not ALB for user deployments?

ALB has a limit of 100 rules per load balancer
Users may create hundreds/thousands of deployments
Traefik handles unlimited ingress rules efficiently

cert-manager

certificates

required

Automatic TLS certificate provisioning and renewal.Version: v1.12+Why: Provisions TLS certificates for server and all user deploymentsIntegration points:

Operator creates Ingress resources with cert-manager annotations
Automatically requests certificates from Let’s Encrypt
Supports DNS01 challenge via Cloudflare

Installation:

helm repo add jetstack https://charts.jetstack.io
helm install cert-manager jetstack/cert-manager \
  -n cert-manager --create-namespace \
  --set installCRDs=true

ClusterIssuer configuration:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: [email protected]
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
      - dns01:
          cloudflare:
            apiTokenSecretRef:
              name: cloudflare-api-token
              key: api-token

External DNS

dns

required

Automatic DNS record creation from Kubernetes resources.Version: v0.13+Why: Auto-creates DNS records for server and user deployment ingressesIntegration points:

Watches Ingress resources with annotation external-dns.alpha.kubernetes.io/hostname
Creates DNS records in Cloudflare (or Route53, etc.)
Syncs on ingress create/update/delete

Installation:

helm repo add external-dns https://kubernetes-sigs.github.io/external-dns/
helm install external-dns external-dns/external-dns \
  -n external-dns --create-namespace \
  --set provider=cloudflare \
  --set cloudflare.apiToken=<token>

Cloudflare

dns-provider

required

DNS provider for External DNS and cert-manager.Why: Manages DNS records and DNS01 challenge for TLS certificatesIntegration points:

External DNS creates A/CNAME records
cert-manager uses DNS01 challenge for wildcard certificates

Configuration:

Create API token with permissions:
- Zone → DNS → Edit
- Zone → Zone → Read

Store in Kubernetes Secret:

kubectl create secret generic cloudflare-api-token \
  -n cert-manager \
  --from-literal=api-token=your-cloudflare-token

Alternatives: Route53 (AWS), Cloud DNS (GCP), Azure DNS

Conditional Dependencies

Required only in specific deployment scenarios.

AWS Load Balancer Controller

ingress

Provisions AWS Application Load Balancers from Kubernetes Ingress resources.Version: v2.6+Required when: Deploying on AWS EKSWhy: Creates ALB for the server ingress (ingressClassName: alb)Integration points:

Server Helm chart creates Ingress with ALB annotations
Controller provisions ALB, target groups, listeners
Supports internal ALBs (Tailscale VPN access)

Installation:

helm repo add eks https://aws.github.io/eks-charts
helm install aws-load-balancer-controller eks/aws-load-balancer-controller \
  -n kube-system \
  --set clusterName=<cluster-name> \
  --set serviceAccount.create=true \
  --set serviceAccount.annotations."eks\.amazonaws\.com/role-arn"=<iam-role-arn>

Not required when: Using Traefik or NGINX for all ingress (non-AWS deployments)

Recommended Dependencies

Strongly recommended for production deployments.

HashiCorp Vault

secrets

Centralized secrets management.Version: v1.14+Why: Securely stores and manages secrets for users, templates, and deploymentsIntegration points:

Server: Vault Agent injects secrets (database, OAuth, Stripe, email) into pod
Secrets API: Stores user/template/deployment secrets in Vault KV v2
External Secrets Operator: Syncs Vault secrets to Kubernetes Secrets for user pods

Secret paths:

secret/k8s-scheduler/
├── database              # Server credentials
├── google                # OAuth credentials
├── email                 # SMTP/SendGrid config
├── ai                    # Anthropic API key
├── stripe                # Billing keys
└── secrets               # Observability passwords

secret/users/{userId}/
├── secrets/              # User-level secrets
├── templates/{name}/     # Template secrets
└── deployments/{name}/   # Deployment secrets

Installation:

helm repo add hashicorp https://helm.releases.hashicorp.com
helm install vault hashicorp/vault \
  -n vault --create-namespace \
  --set server.ha.enabled=true \
  --set server.ha.replicas=3

Setup:

Initialize and unseal Vault

Enable KV v2 secrets engine:

vault secrets enable -path=secret kv-v2

Run setup script:
```
./scripts/setup-vault.sh
```

Alternatives:

AWS Secrets Manager (SECRETS_BACKEND=aws)
Database encryption (SECRETS_BACKEND=database, requires SECRETS_ENCRYPTION_KEY)

External Secrets Operator

secrets-sync

Syncs external secrets (Vault, AWS) into Kubernetes Secrets.Version: v0.9+Required when: Using Vault or AWS Secrets ManagerWhy: Pulls user secrets from Vault/AWS and creates Kubernetes Secrets for deployment podsIntegration points:

Operator creates ExternalSecret resources for each deployment
ESO watches these resources and syncs from Vault
Creates/updates corresponding Secret resources
Pods mount these secrets as files or environment variables

Installation:

helm repo add external-secrets https://charts.external-secrets.io
helm install external-secrets external-secrets/external-secrets \
  -n external-secrets --create-namespace

ClusterSecretStore: Created by k8s-scheduler Helm chart:

apiVersion: external-secrets.io/v1beta1
kind: ClusterSecretStore
metadata:
  name: vault-backend
spec:
  provider:
    vault:
      server: http://vault.vault.svc:8200
      path: secret
      version: v2
      auth:
        kubernetes:
          mountPath: kubernetes
          role: k8s-scheduler
          serviceAccountRef:
            name: k8s-scheduler
            namespace: scheduler-system

Vault Agent Injector

secrets-injection

Mutating webhook that injects Vault Agent sidecars into pods.Version: Bundled with Vault Helm chartRequired when: Using Vault for server secretsWhy: Injects database credentials, OAuth secrets, and API keys into server podIntegration points:

Server deployment has Vault annotations:

vault.hashicorp.com/agent-inject: "true"
vault.hashicorp.com/role: "k8s-scheduler"
vault.hashicorp.com/agent-inject-secret-env: "secret/data/k8s-scheduler/database"

Vault Agent runs as sidecar container
Renders secrets to /vault/secrets/env
Server sources this file on startup

Installation: Included with Vault Helm chart

helm install vault hashicorp/vault \
  --set injector.enabled=true

Optional Dependencies

Additional features and integrations.

Stripe

billing

Payment processing and subscription management.Why: Enables tiered billing (Free, Business, Enterprise)Integration points:

Server integrates with Stripe API for:
- Creating subscriptions
- Managing payment methods
- Handling upgrades/downgrades
Webhook endpoint /api/stripe/webhook for events
Tier limits enforced based on subscription status

Configuration:

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

Required secrets:

vault kv put secret/k8s-scheduler/stripe \
  api_key="sk_live_..." \
  webhook_secret="whsec_..."

SMTP / SendGrid

Email delivery for team invitations.Why: Send invitation emails when users invite team membersIntegration points:

Server sends emails via SMTP or SendGrid API
Email templates for invitations
Configurable sender address

SMTP Configuration:

EMAIL_PROVIDER="smtp"
SMTP_HOST="smtp.gmail.com"
SMTP_PORT="587"
SMTP_USERNAME="[email protected]"
SMTP_PASSWORD="your-password"

SendGrid Configuration:

EMAIL_PROVIDER="sendgrid"
SENDGRID_API_KEY="SG.your-api-key"

Redis

cache

In-memory data store for sessions.Version: 6+Why: Distributed session storage across multiple server replicasIntegration points:

Server uses Redis as session backend when SESSION_BACKEND=redis
Faster than PostgreSQL for session lookups
Enables horizontal scaling of server pods

Configuration:

SESSION_BACKEND="redis"
REDIS_ADDR="redis.redis.svc.cluster.local:6379"

Installation:

helm repo add bitnami https://charts.bitnami.com/bitnami
helm install redis bitnami/redis \
  -n redis --create-namespace \
  --set auth.enabled=false

Alternatives: PostgreSQL sessions (SESSION_BACKEND=postgres)

Prometheus

monitoring

Metrics collection and alerting.Version: v2.40+Why: Monitor server and operator health, deployment metricsIntegration points:

Server exposes metrics on :9090/metrics
Operator exposes controller-runtime metrics
Helm chart creates ServiceMonitor (requires Prometheus Operator)

Metrics exposed:

scheduler_deployments_total - Total deployments created
scheduler_deployments_by_state - Deployments by state (running/stopped)
scheduler_api_request_duration_seconds - API latency
Controller-runtime reconcile metrics

Installation:

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm install prometheus prometheus-community/kube-prometheus-stack \
  -n monitoring --create-namespace

Enable in k8s-scheduler:

helm install k8s-scheduler ./charts/k8s-scheduler \
  --set monitoring.enabled=true

Grafana

observability

Metrics visualization and dashboards.Version: v9+Why: Visualize deployment metrics, server health, operator reconciliation loopsIntegration points:

Connects to Prometheus data source
Create custom dashboards for deployment metrics and operator status
Alerting for operator errors

Installation: Included with kube-prometheus-stack

Dependency Matrix

Component	Required	AWS	GCP	On-Prem	Notes
PostgreSQL	Yes	RDS	Cloud SQL	Helm	Any managed or self-hosted
Traefik	Yes	✓	✓	✓	Wildcard ingress routing
cert-manager	Yes	✓	✓	✓	TLS certificates
External DNS	Yes	✓	✓	✓	Automatic DNS records
Cloudflare	Yes	✓	✓	✓	Or Route53, Cloud DNS, etc.
ALB Controller	AWS only	✓	—	—	Server ingress on EKS
Vault	Recommended	✓	✓	✓	Centralized secrets
External Secrets	If Vault	✓	✓	✓	Syncs secrets to K8s
Vault Agent	If Vault	✓	✓	✓	Injects server secrets
Stripe	Optional	✓	✓	✓	Subscription billing
SMTP/SendGrid	Optional	✓	✓	✓	Team invitations
Redis	Optional	ElastiCache	Memorystore	Helm	Session storage
Prometheus	Optional	✓	✓	✓	Metrics collection
Grafana	Optional	✓	✓	✓	Metrics visualization

Getting Started

Core Concepts

Components

Deployment

API Reference

Dependency Overview

Required

Recommended

Optional

Conditional

Required Dependencies

PostgreSQL

Traefik

cert-manager

External DNS

Cloudflare

Conditional Dependencies

AWS Load Balancer Controller

Recommended Dependencies

HashiCorp Vault

External Secrets Operator

Vault Agent Injector

Optional Dependencies

Stripe

SMTP / SendGrid

Redis

Prometheus

Grafana

Dependency Matrix

Architecture Diagram

Next Steps

Deployment Guide

Configuration

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Components

Deployment

API Reference

​Dependency Overview

Required

Recommended

Optional

Conditional

​Required Dependencies

​PostgreSQL

​Traefik

​cert-manager

​External DNS

​Cloudflare

​Conditional Dependencies

​AWS Load Balancer Controller

​Recommended Dependencies

​HashiCorp Vault

​External Secrets Operator

​Vault Agent Injector

​Optional Dependencies

​Stripe

​SMTP / SendGrid

​Redis

​Prometheus

​Grafana

​Dependency Matrix

​Architecture Diagram

​Next Steps

Deployment Guide

Configuration

Build docs developers (and LLMs) love

Dependency Overview

Required Dependencies

PostgreSQL

Traefik

cert-manager

External DNS

Cloudflare

Conditional Dependencies

AWS Load Balancer Controller

Recommended Dependencies

HashiCorp Vault

External Secrets Operator

Vault Agent Injector

Optional Dependencies

Stripe

SMTP / SendGrid

Redis

Prometheus

Grafana

Dependency Matrix

Architecture Diagram

Next Steps