GitHub

Import from cluster

Turn an existing namespace into .kdef files with one command, and migrate incrementally.

kdef import reads live Kubernetes resources and writes idiomatic .kdef files. It's the fastest way to adopt kdef in an existing project: run it, review the output, commit, done.

From a live namespace

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

What ends up in k8s/:

k8s/
├── api.kdef          ← one file per deployment, daemonset or statefulset
├── worker.kdef       ← worker-style (no service {})
├── configmaps.kdef
├── cronjobs.kdef
└── pvcs.kdef

Image references are written out literally (image = "registry.example.com/api:1.4.2"); move them into an images {} block afterwards if you want image().

From YAML files

If the resources live in YAML (e.g. helm template output, or a vendor's manifests), point --from-file at them:

helm template my-chart > manifests.yaml
kdef import --from-file manifests.yaml --output-dir k8s/

What the importer handles

  • Deployments with Service+Ingress → deployment block with nested service and ingress
  • Deployments without a Service → worker-style deployment (no service {})
  • DaemonSets, StatefulSets (including volumeClaimTemplates), CronJobs
  • ConfigMaps, PersistentVolumeClaims
  • ClusterRoles + ClusterRoleBindings (from YAML files, written to rbac.kdef)
  • Secret references in env vars → secret() calls
  • Downward-API env vars → field_ref() calls
  • Tolerations, node_selector, privileged contexts, host_path, init containers, sidecars, volumes, multi-host ingresses, probes

Preview first

Pipe to stdout to review before writing:

kdef import --namespace my-app

Migrating incrementally

You don't have to convert everything at once.

  1. Import one namespace or one app.
  2. kdef render --dir k8s/ > rendered.yaml and diff against what's live.
  3. Commit the .kdef files alongside existing YAML. Run both.
  4. Switch ownership resource-by-resource using kdef apply (server-side apply, --force-conflicts).
  5. Delete the legacy YAML once kdef is the source of truth.

Things the importer can't guess

  • Variables. The importer produces literal values. After importing, decide which values should be variables (image tags, replica counts, hostnames) and extract them into vars.kdef.
  • Environment overrides. If the cluster has staging + production copies of the same app, import one and create an environments/staging.kdef for the other; don't import both into separate trees.
  • Plain text secrets. The importer keeps secret references intact but will not pull secret values. For new secrets, use sealedsecret.

Adding the git hook

Once you're committed to kdef for a project, install the pre-commit hook so every commit runs kdef validate:

kdef install-hook            # creates .git/hooks/pre-commit
kdef install-hook --append   # appends safely to an existing hook