Skip to Content
CLI Referencenkapp import

nkapp import

Ingest existing infrastructure into a nanokit.yml. Today one source is supported: Kubernetes manifests (import k8s) — the offline reverse of export k8s.

nkapp import k8s [options]

import k8s

Reads standard Kubernetes manifests and scaffolds the equivalent nanokit.yml — offline, no cluster or cloud credentials needed. It is the exact inverse of export k8s: it reverse-maps Deployment, Service, Ingress (or a Contour HTTPProxy), ConfigMap, Secret, StatefulSet, and HorizontalPodAutoscaler resources back into Nanokit services, databases, hosts, env, and scale settings — so an existing app can adopt Nanokit without hand-porting its config.

The input may be a single file, a directory of .yaml / .yml files (each may itself be multi-document), or piped on stdin (-).

Options

FlagTypeDefaultDescription
-f, --file <path>string(required)Manifest file, directory of .yaml/.yml files, or - for stdin
-o, --output <path>string./nanokit.ymlWrite the generated config to this file
--stdoutbooleanfalsePrint the YAML to stdout instead of writing a file
--forcebooleanfalseOverwrite an existing nanokit.yml

By default import k8s writes ./nanokit.yml and refuses to overwrite an existing one — pass --force, an explicit --output <path>, or --stdout.

Examples

# Scaffold ./nanokit.yml from a directory of manifests
nkapp import k8s -f ./k8s-manifests
 
# Import a single rendered file, print to stdout (review before saving)
nkapp import k8s -f ./out.yaml --stdout
 
# Round-trip straight from a live cluster's export
kubectl get deploy,svc,ingress,cm,secret,statefulset,hpa -o yaml \
  | nkapp import k8s -f - --stdout
 
# Overwrite an existing config
nkapp import k8s -f ./k8s-manifests --force

Lossy by design

Importing is lossy on purpose: anything that has no nanokit.yml representation is surfaced as a warning on stderr (yellow) rather than being silently dropped. --stdout stays pure YAML — all warnings go to stderr.

What is reduced or normalized on the way back:

  • Secret values are never copied into nanokit.yml. Each Secret key is imported as an env ${VAR} reference (plus a warning); a database root password is dropped with a warning. Set the real values in .env afterward (e.g. nkapp secrets set, nkapp db rotate). This keeps secrets out of the committed config.
  • A service’s expose is recovered as port (the translator folds both into one container port).
  • host is recovered in its normalized array form (the comma-string shorthand is not reconstructed).
  • scale.cpu_threshold is omitted when it equals the export default (80).
  • Unknown / unsupported kinds are warned about and skipped.
  • When manifests carry no nk-* labels (foreign / hand-written YAML), service & database names are recovered by stripping the nk-<project>-<env>- prefix best-effort, with an ambiguity warning. Manifests produced by export k8s carry those labels, so names round-trip exactly.

After importing, review the result, fill in any ${VAR} secrets in .env, then run nkapp plan to preview.

Round-trip with export k8s

import k8s and export k8s are a round-trip pair: import k8s ∘ export k8s reproduces the services, databases, hosts, scale, and (plain) env of the original config — modulo the lossy fields above. The Contour routing mode round-trips too: a config exported with infra.kubernetes.ingress: contour emits HTTPProxy objects, and importing them sets infra.kubernetes.ingress: contour back in the scaffolded config.

[!IMPORTANT] import k8s is an offline scaffolding helper — it never connects to a cluster. For a live Kubernetes deploy, set infra.target: kubernetes in the generated nanokit.yml and run the standard nkapp up / nkapp deploy (routed through the KubernetesExecutionEngine for EKS / GKE / AKS / DOKS). See the export reference for the offline-vs-live comparison.

nkapp hubnkapp infra