Quickstart

This walks you through the full round-trip: take an existing namespace, turn it into .kdef files, render it back to YAML, and deploy it.

If you don’t have a cluster handy, skip to API with sidecar which builds a deployment from scratch.

1. Import an existing namespace

Pick a small namespace (maybe a test app — one Deployment, one Service, one Ingress).

kdef import --namespace my-app --output-dir k8s/

kdef reads everything in the namespace and writes idiomatic .kdef files. Open k8s/ and look around:

k8s/
├── vars.kdef
├── images.kdef
├── api.kdef          # one file per deployment
├── configmaps.kdef
└── secrets.kdef      # secret() references, not plaintext

2. Render to YAML

kdef render --dir k8s/

That prints Kubernetes YAML to stdout. Redirect to a file if you want to diff against the original:

kdef render --dir k8s/ > /tmp/rendered.yaml

3. Compare against the live cluster

kdef diff --dir k8s/

This is the one you’ll run before every deploy. It’s kubectl diff-shaped output, but driven by kdef’s renderer — no drift between what you commit and what you ship.

4. Apply

# Dry run first
kdef apply --dir k8s/ --dry-run

# Then for real (server-side apply, --force-conflicts)
kdef apply --dir k8s/

If you’re using GitOps, you’d instead commit k8s/ and let Flux or ArgoCD apply it.

5. Make a change

Open api.kdef and bump a replica count, or add an env var:

deployment "api" {
  // ...
  scale {
    replicas = 3       // was 1
  }

  container "api" {
    // ...
    env {
      APP_ENV      = var.environment
      DATABASE_URL = secret("db-credentials", "url")
      NEW_FLAG     = "true"          // new
    }
  }
}

kdef diff --dir k8s/
# shows: replicas: 1 -> 3, new env var NEW_FLAG

kdef apply --dir k8s/

6. Add environment overrides

Create k8s/environments/production.kdef:

use_vars {
  environment = "production"
  image_tag   = "v1.2.3"
}

override "app" "api" {
  scale {
    replicas = 5
  }
}

Render/apply with the --env flag:

kdef render --dir k8s/ --env production
kdef diff   --dir k8s/ --env production
kdef apply  --dir k8s/ --env production

Where to go next

• Reference → Block types — every kind of resource kdef can generate
• Reference → CLI — all commands, flags, and behaviours
• Guides → Sealed secrets — commit encrypted secrets to git safely
• Tooling → Editors — live diagnostics in VS Code, JetBrains, Neovim