Adopting Existing Apps · ConfigHub Workshop

UNOFFICIAL/EXPERIMENTAL

The goal is:

New to cub? Install the cub CLI first. Public catalog packages pull and render anonymously, and you sign in only once a command saves or changes ConfigHub data.

Keep the app running.
Import or discover the desired state.
Attach ConfigHub labels, links, variants, scans, gates, and receipts.
Only move to a cub installer recipe when the app needs a maintained render path.

Short Answer

Yes, a user should be able to start from an existing app, a group of apps, a platform slice, a stack, rendered manifests, GitOps objects, or a live cluster. The first step should be read-only discovery or import, not a forced rewrite.

The expected first result is:

ConfigHub found the app or objects.
ConfigHub shows source, target, labels, and object inventory.
No cluster change was made yet.
The next decision is keep imported, create a derived variant, or graduate to a
maintained cub installer recipe.

Why This Matters

Most real teams do not start from a blank cluster. They already have:

Argo CD Applications;
Flux HelmReleases;
Flux Kustomizations;
KRM YAML or Kustomize output;
rendered manifests in Git;
manually imported or live Kubernetes resources.

The adoption path must not say "rewrite all of that first." It should let the team upgrade into ConfigHub gradually.

Current Entry Points

Existing source	Current entry point	What ConfigHub should preserve
Argo CD Application	Read the Application and rendered objects through Argo CD or the Kubernetes API, then use `cub variant upload`.	controller ownership, source reference, rendered resources, links, target
Flux HelmRelease	Read the HelmRelease and rendered objects through Flux or the Kubernetes API, then use `cub variant upload`.	chart source, values source, rendered resources, links, target
Flux Kustomization	Read the Kustomization and rendered objects through Flux or the Kubernetes API, then use `cub variant upload`.	Kustomize source, rendered resources, links, target
KRM YAML / rendered manifests	`cub variant upload --component <name> --variant <name> <files-or-oci-ref>`	resource identity, labels, target, provenance, scans
Public Helm chart with no existing app	`helm template` or the `cub installer` catalog path	local Helm render or maintained catalog package depending on intent

A Small Plain YAML Example

The repository includes a four-object application under examples/plain-yaml/acme-web. It has one Namespace, ConfigMap, Deployment, and Service. There is no chart and no render step.

Upload the files as one Unit per Kubernetes object:

cub variant upload \
  --component plain-yaml-acme-web \
  --variant base \
  --space plain-yaml-acme-web-base \
  --granularity per-resource \
  examples/plain-yaml/acme-web

The focused receipt reads the four Units back and compares them with the four files. The source and stored object-set hashes match. The separate README Unit explains the example inside the helm-catalog demo organization.

This proves the import boundary. No cluster apply, promotion, release, or workload observation is claimed by this receipt.

The current cub v0.2.9 command surface does not provide a one-step GitOps discovery/import command. Read the controller objects and desired Kubernetes objects first. Review their source, target, namespace, and ownership, then use cub variant upload for the YAML or literal OCI you chose to store. The upload creates ConfigHub records; it does not change the controller or cluster.

Adoption Levels

Level	What happens	User value
Observe	Import or discover the existing app and record where it came from.	The team can see and search the app in ConfigHub without changing delivery.
Explain	Add component, chart, variant, environment, region, target, and source labels; preserve links.	The app becomes understandable and comparable.
Check	Run scans, schema checks, policy checks, and drift/live observations.	The team gets evidence without rewriting the app.
Variant	Clone/refine post-render ConfigHub state with `cub variant create` where safe.	The team can create environment/customer variants without rerendering Helm when the change is post-render.
Graduate	If the app needs a maintained render path, create a `cub installer` recipe/package/base.	The app gets catalog-grade repeatability, Helm-equivalence proof, receipts, upgrade support, and maintenance policy.

Routing Rule

Use the narrowest adoption path that matches the user's intent:

User says	Route
"I already have Argo managing this app."	Discover/import the Argo app first. Do not force a recipe rewrite.
"I already have Flux HelmRelease or Kustomization objects."	Discover/import Flux first. Preserve the GitOps source and target.
"I have KRM YAML or rendered manifests."	Import as ConfigHub Units, then scan, label, link, and review.
"I want to turn this into a maintained catalog entry."	Create or request a `cub installer` recipe/package and base variants.
"I want prod from dev with target/gates/labels changed."	Use a derived ConfigHub variant after import or upload.
"I want a values file, wrapper chart, or overlay that changes object shape."	Use the installer recipe/base path or managed overlay import.
"My existing Helm release is stuck or risky to upgrade."	Capture Helm's release record, compare it with the candidate render, and keep the result local until it is reviewed.

What Not To Overclaim

Importing an existing app does not automatically prove it is a supported catalog recipe.

Use precise language:

imported into ConfigHub
scanned
linked to source
observed live
variant-created
graduated to maintained recipe

Do not collapse those into one generic "managed" claim.

Product Shape

The user-facing flow should be:

Choose source: Argo, Flux, KRM, Helm, rendered YAML
Preview discovered apps and objects
Select app/component
Import with labels and links
Run checks
Decide: keep imported, create derived variant, or graduate to recipe

The product should make the first step low risk. A team should be able to say:

Show ConfigHub my existing app.
Do not change my cluster yet.
Tell me what you found and what you can prove.

That is how existing Argo, Flux, KRM, and rendered-manifest estates enter the same ConfigHub model without making Helm users start over.