Skip to content

How it works

The CLI (and the in-cluster agent to come, cmd/agent) are thin shells around one pipeline (pkg/pipeline):

collect -> redact -> (inventory) -> hygiene -> ownership -> lifecycle -> platform -> provenance -> normalize -> snapshot -> emit
Package Role
pkg/collect Lists every listable resource with each API group’s preferred version, using paginated calls, several types at once. Skips runtime state (Nodes, Leases, metrics, CSRs and similar). High-volume child types (Pods, ReplicaSets, ControllerRevisions, Jobs, EndpointSlices) are listed metadata-only first; only those with no exported controller owner are fetched in full. Controller owners missing from the lists are looked up, to tell a rollout in progress from a deleted owner. An API error for one type skips that type with a LIST_FAILED finding; credential and connection errors abort. With -n, the Namespace objects are exported too. FileSource reads manifests from a directory (or a repository checkout) for tests and offline runs.
pkg/redact Replaces Secret values and strips last-applied-configuration. Image pull secrets get valid JSON placeholders that keep nothing of the value, not even the registry names. Service account token data is removed, as the token controller writes it. Always runs first, enforced by Pipeline. The emitter keeps redacted resources out of the applied set.
pkg/inventory Records what restoring the cluster needs that the manifests do not hold: each claim’s volume (volume ID, driver, zone, reclaim policy, including StatefulSet claims) and the addresses load balancers were given. Runs right after redaction, before later stages drop those objects and status.
pkg/awsinventory With --aws: reads the cluster’s settings held in AWS (OIDC issuer, Pod Identity associations, IRSA role trust, access entries, add-ons and whether each has configuration, never its values, EBS volume details), read-only, for RESTORE.md.
pkg/hygiene Report-only cleanup suggestions: terminated Pods per namespace by what keeps them, standalone Jobs without ttlSecondsAfterFinished, CronJobs whose history limits exceed the defaults, and objects stuck in deletion behind a finalizer. Runs before ownership so it sees child objects.
pkg/ownership Keeps top-level objects only, dropping anything controller-owned by another exported object, garbage whose owner was deleted, and objects the cluster generates itself (kube-root-ca.crt, default RBAC, Endpoints of Services with a selector, dynamically provisioned volumes and others).
pkg/lifecycle Drops finished or temporary objects: objects being deleted (and everything in a Namespace being deleted), terminated Pods and Helm or Argo CD hooks. Finished standalone Jobs stay in the snapshot as a record of what ran, but are never written to the export (applying one runs it again); RESTORE.md lists them with their result, image and command, to re-run by hand if a new cluster needs one, with a per-namespace count in the snapshot findings. Flags running Pods that have no controller, and Jobs and run-once Pods that a GitOps tool would re-run.
pkg/platform Classifies the platform from weighed evidence (kubeconfig, API server, nodes, the cluster’s objects, --aws) with a confidence; conflicting evidence means no classification.
pkg/provenance Classifies each object as Argo CD, Flux, Helm, CI/CD (the setdrift.io/source-* annotations, or --ci-field-manager), operator, platform or unmanaged, and flags objects whose manager is gone from the cluster. Drops Helm’s release records.
pkg/normalize Strips server-owned state so the export round-trips cleanly: fields only Kubernetes’ controllers own (from managedFields), values equal to the API server’s defaults, owner references, status and server-set metadata, kubectl rollout restart timestamps, and the markers Argo CD, Flux and Helm stamp on what they apply (the snapshot keeps them as provenance evidence).
pkg/snapshot The versioned snapshot (proto), the contract between the CLI, the agent and the control plane. Protobuf is canonical; JSON is for inspection.
pkg/emit/kustomize Writes a snapshot as a Kustomize repository: the generic set, the platform’s set, the README’s overview, the ExternalSecrets and RESTORE.md. Resources with redacted values go to redacted/, outside every kustomization; objects the platform manages are left out.
pkg/diff Compares two snapshots: pairs resources by group, kind, namespace and name (with namespace mapping), compares the normalized manifests field by field (lists of named items, such as containers, by name), sets aside each cluster’s own values (name, region, account, mapped namespaces), and gives what the snapshots tell about why: the manager on each side, the Helm chart versions, the API versions. Platform objects are not compared.
pkg/verify The acceptance test: a server-side dry-run apply of every exported resource, compared with the live object. Passes when at least 95% (--threshold) would not change and every remaining diff is explained. Groups the differences by cause, with values, who owns each differing field (managedFields) and who wrote the object after the export, and names the likely cause: the cluster changed since, a different cluster, one field set on many resources, or deleted resources. Reports custom resources whose CRD the cluster lacks.

pkg/ must not depend on CLI concerns; command-line code lives in cmd/. The module path is setdrift.io/setdrift-engine (docs/vanity-import.md).