# Import

> Onboard existing Kubernetes config into ConfigHub as Units, from a Helm chart ("cub helm install", "upgrade the chart without losing my edits") or a Kustomize overlay ("import my base + overlays", "kustomize build into Units"). Not for authoring new YAML from scratch (use kubernetes-resources).

- **Type:** Skill
- **Install:** `agentstack add skill-confighub-confighub-skills-import`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [confighub](https://agentstack.voostack.com/s/confighub)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [confighub](https://github.com/confighub)
- **Source:** https://github.com/confighub/confighub-skills/tree/main/skills/import

## Install

```sh
agentstack add skill-confighub-confighub-skills-import
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# import

One onboarding ramp for bringing existing Kubernetes configuration under ConfigHub management. Pick the source, render it into Units, then the rest of the skill set takes over (customize via `cub-mutate`, validate via Triggers, deliver via `cub-apply`).

## Pick the source

| The user has… | Go to |
| --- | --- |
| A Helm chart (`jetstack/cert-manager`, `bitnami/nginx`, a chart repo + version) | **§A Helm** |
| A local `kustomization.yaml` (`base/` + `overlays/`) | **§B Kustomize** |

ArgoCD `Application` / Flux `HelmRelease` GitOps pipelines, and adopting live-cluster resources, are **not** covered by this skill.

## Positioning: this is onboarding, not the destination

Both paths meet the user where they are and get them into ConfigHub without a day-one rewrite. The end state ConfigHub is built for is **configuration as data** — literal-YAML Units + semantic functions for policy and per-environment customization (see `confighub-core`). The chart / overlay is a **bootstrap input**, not an ongoing parameterization surface. After import:

- Customize with `cub-mutate` functions (`set-container-image`, `set-replicas`, `set-env-var`, the defaults functions), not values files or patches.
- Spread across environments by cloning Units upstream→downstream, not per-env values/overlays.
- Re-render (`cub helm upgrade`, re-`kustomize build`) only to pull a deliberate upstream change — a structured, logged event.

Call this trajectory out so the user understands the direction, not just the first command.

Guides: `https://docs.confighub.com/markdown/guide/helm-charts.md` (Helm), `https://docs.confighub.com/markdown/guide/rendered-manifests.md` (DRY rendering model).

## Shared preflight

1. `cub auth status` succeeds — it contacts the server's `/me` endpoint to confirm the token is still valid (not just local login state). If it fails, ask the user to run `cub auth login` (an interactive browser sign-in an agent cannot complete).
2. Target Space exists (`cub space list`) and the user has write permission. **Environments are Spaces, not slug suffixes** (`confighub-core` topology): render each env into its own `-[-]` Space; the Unit slug is the workload, not the env.
3. Confirm the verb and flags with `cub  --help` before composing.

## Granularity

Default to **one Kubernetes resource per Unit** (`confighub-core`). Generator output starts coarser, which is fine as an onboarding step:

- `cub helm install` renders a bundle and auto-splits CRDs into `-crds`. Start there; split further later if ownership/lifecycle/blast-radius diverge.
- A `kustomize build` is one rendered stream — store as one Unit per overlay to start, then split per workload/resource with `cub unit create` + `cub-mutate` (no re-render needed).

**CRDs always stand alone** — apply-order (CRDs established before their CRs at the consumer) and wider blast radius. Slug `-crds`.

---

## §A — Helm chart

### Preflight (additional)

- `helm` is on PATH (`cub helm` shells out to it).
- The chart's repo is added (`helm repo list`); if not, `helm repo add   --force-update && helm repo update`.
- A chart **version is pinned**. Never install without `--version` — unpinned installs can't be audited on upgrade.
- Namespace strategy decided — default to `--namespace ` (below).

### Namespace — default to `--namespace `

Many charts bake the namespace into rendered data (ConfigMap contents, Service hostnames, RoleBinding subjects like `system:serviceaccount::`). With `--namespace`, the chart renders as `helm install` would and ConfigHub stores the literal result — predictable and debuggable. `--use-placeholder` (renders `namespace: confighubplaceholder`, resolved via `cub link create`) only works cleanly for charts with no internal namespace references — reach for it only with a `vet-placeholders` strategy in mind.

### Install

```bash
helm search repo / --versions     # confirm the version exists
cub helm install  / \
  --space - --namespace  --version  [--values ] [--set k=v]
```

This creates `` (main resources, + Namespace if `--namespace`) and `-crds` (if the chart ships CRDs). `cub helm` does **not** accept `--change-desc` — provenance is recorded as Unit labels (`helmrelease`, `helmchart`, `helmversion` — verify exact keys with `-o json`). For a human note, follow up with a `set-annotation` function carrying `--change-desc`.

### Per-environment — two patterns

- **Pattern A (per-env values files):** if the user already runs `helm install -f values-.yaml`, preserve it — run one `cub helm install` per env-Space with that env's values. Migrate values into `cub-mutate` functions over time.
- **Pattern B (single install + clones):** install once into a base Space, then clone per env. Clones keep an `--upstream-unit` link so `cub helm upgrade` on the base propagates via `--upgrade` while preserving per-env edits. **Never edit the base Unit** — edits are clobbered by the next upgrade; customize the clone via `cub-mutate`.

```bash
cub unit create --space -staging  --upstream-unit -base/
cub unit create --dest-space -staging --space -base   # clone the whole base Space (base + crds)
```

### Upgrade

- **Pattern A:** `cub helm upgrade  / --space - --version  --values values-.yaml [--update-crds]` per env-Space.
- **Pattern B:** `cub helm upgrade` the base, then `cub unit update  --space  --upgrade --change-desc "…"` per clone (merge preserves clone edits). Review with `cub unit diff`.

`--update-crds` is off by default — set it only when the chart's CRD schemas changed and you want them in.

### Deliver

Hand off to `cub-apply` for delivery (which publishes the Units to OCI for Argo/Flux to pull, or applies via a ConfigHub Target). When CRDs are present, apply the `-crds` Unit before the workload Unit so the consumer sees the CRDs first; the GitOps tool (Argo sync waves / Flux `dependsOn`) handles establishment ordering at the cluster. `cub-apply` / `verify-apply` own the rollout.

---

## §B — Kustomize overlay

There is no `cub kustomize` — render locally with `kustomize` / `kubectl kustomize`, store via `cub unit create`. If the user's "Kustomize" is actually a **Flux `Kustomization` CRD** (managed in-cluster), this skill doesn't cover that GitOps pipeline.

### Preflight (additional)

- `kustomize` or `kubectl kustomize` on PATH. Prefer standalone `kustomize` for full feature coverage.
- The overlay path actually has a `kustomization.yaml`.
- Which overlays map to which env-Spaces is decided.

### The loop

```bash
# 1. Inventory.
ls overlays/ ; cat overlays//kustomization.yaml

# 2. Render the overlay for this env.
mkdir -p /tmp/kustomize-import
kustomize build overlays/ > /tmp/kustomize-import/.yaml     # or: kubectl kustomize overlays/
```

Inspect the output before uploading: strip `status:` / `creationTimestamp` (`yq 'del(.status, .metadata.creationTimestamp)'`), confirm `namespace:` applied to every namespaced resource, and bail to **§A** if it's a Helm-inflator overlay.

```bash
# 3. Create the Unit in the env-Space (default: one Unit per overlay; split later).
cub unit create --space -  /tmp/kustomize-import/.yaml \
  --change-desc "Import   overlay from Kustomize at .

User prompt: 
Clarifications: , or 'none'>"
```

Record the source ref (git SHA, overlay path) in `--change-desc` — Units carry no pointer back to the Kustomize tree otherwise.

### Promotion (optional)

For merge-preserving dev→staging→prod, render a base once into a base Space and clone per env with `--upstream-unit -base/`. Pull upstream changes later with `cub unit update --space -   --change-desc "…"` (merge preserves in-ConfigHub edits) — or `--upgrade` from the upstream Unit. From here, customize via `cub-mutate` functions instead of new overlays.

Then hand off to `cub-apply` / `verify-apply`.

---

## Tool boundary

- Allowed: `cub helm install/upgrade/template`, `cub unit create/update`, `cub function …`, `cub link create`, `helm repo add/update/list`, `helm search`, `kustomize build`, `kubectl kustomize`; read-only `cub unit get/list/data/diff/tree`.
- Not allowed: `helm install` / `kubectl apply` / `kubectl apply -k` (deploys outside ConfigHub), editing a Pattern-B base Unit, adopting live-cluster or GitOps-tool-managed resources (out of scope for this skill).

## Stop conditions

- §A: repo not added and the user won't add it; install without `--version`; request to edit the base Unit (offer the clone instead); slug collides with an existing Unit (did they mean upgrade?).
- §B: overlay won't `kustomize build` (report the error verbatim, don't "fix" it); Helm-inflator overlay (→ §A).

## Verify chain

- §A: `cub unit list --space  --where "Labels.helmrelease = ''"` (base + crds present); `cub unit diff  -base/ --space -` (clone customizations); after upgrade, `cub revision list ` shows the new version.
- §B: `cub unit get  --space - -o yaml | diff - /tmp/kustomize-import/.yaml`; `cub revision list ` shows Revision 1 with the Kustomize-source change-desc.

## Evidence

- `cub unit get  --space  --web` — the imported Unit in the GUI.
- `cub revision list  --space  --web` — provenance starting at import.

## References

- `cub helm install --help` — authoritative flags.
- `https://docs.confighub.com/markdown/guide/helm-charts.md`, `.../guide/rendered-manifests.md`.
- `references/cub-cli.md` — CLI discipline; `--change-desc`; `-o mutations`.
- `references/functions-catalog.md` — post-import customization functions.
- Companion skills: `confighub-core` (config-as-data doctrine, Space topology, granularity), `cub-mutate` (customize), `target-bind` + `cub-apply` + `verify-apply` (deliver), `triggers-and-applygates` (`vet-placeholders` / `standard-vets`).

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [confighub](https://github.com/confighub)
- **Source:** [confighub/confighub-skills](https://github.com/confighub/confighub-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-confighub-confighub-skills-import
- Seller: https://agentstack.voostack.com/s/confighub
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.