Skip to content

Render manifests from DRY formats (e.g., Helm, Kustomize) in git

ConfigHub can render DRY configuration generation formats such as Helm and Kustomize from git using its standard worker. This page covers two paths:

  1. The unit-level model — how a single renderer unit plus a rendered ("wet") unit works. This is the primitive used by everything else.
  2. cub gitops discover / cub gitops import — the bulk flow that brings an existing Argo CD or Flux cluster under ConfigHub management, inserting ConfigHub into the middle of the GitOps pipeline.

The unit-level model

The high-level model is:

  1. The GitOps tool of your choice (currently Flux or ArgoCD) and the worker must be running in your Kubernetes cluster. For ArgoCD, the worker calls ArgoCD, so ARGOCD_SERVER must be set to the cluster DNS name for ArgoCD's server, such as argocd-server.argocd.svc.cluster.local, ARGOCD_AUTH_TOKEN must be set to a valid token, and ARGOCD_INSECURE should be set to true if targeting the service directly. Flux is not called directly, so the worker doesn't require additional configuration for that.
  2. Create a unit with ToolchainType Kubernetes/YAML containing the KRM resource from the GitOps tool specifying what / how to render. For Flux, this would be a HelmRelease or Kustomization resource and for ArgoCD it would be an Application resource. Any source repository resources referenced must already exist in the cluster. They could be applied using other units.
  3. Attach a Target that supports the corresponding renderer bridge ProviderType, FluxRenderer or ArgoCDRenderer.
  4. Create a corresponding empty unit of ToolchainType Kubernetes/YAML to receive the rendered configuration.
  5. Link the empty unit to the renderer unit using UpdateType MergeUnits and UseLiveState true. For example: 
    cub link create --space "$SPACE" - rendered-unit renderer-unit --use-live-state --auto-update --update-type MergeUnits
  6. Apply the renderer unit. The rendered configuration will automatically be copied to the rendered unit in the case that --auto-update was specified. In the case that the link is not set to auto-update, the rendered unit can be updated as follows: 
    cub unit update --space "$SPACE" --patch --resolve "Link:*" rendered-unit

The merge behavior is the same as for unit upgrades, so changes made to the rendered unit will not be clobbered by subsequent re-renderings by the renderer unit.

Importing a GitOps-managed cluster with cub gitops

If you are already deploying with Argo CD or Flux, cub gitops discover and cub gitops import insert ConfigHub into the middle of the pipeline. The result: manifests are rendered into ConfigHub and then deployed from ConfigHub via Argo CD (or Flux) through an OCI image fetched from ConfigHub. That gives you versioning, validation, policy enforcement, review, and approval on the fully rendered configuration — and modifications made in ConfigHub are preserved across re-renders, similar to patches.

What gets created

cub gitops discover --space <space> <target> queries the cluster through the worker and reports the Argo CD Application resources and/or Flux HelmRelease / Kustomization resources it finds.

cub gitops import --space <space> <target> then:

  • Creates dry units containing those Application / HelmRelease / Kustomization resources. Each dry unit has a Target attached that supports the corresponding renderer bridge (ArgoCDRenderer or FluxRenderer). Dry units are the renderer inputs.
  • Creates corresponding wet units that will hold the rendered manifests, linked to their dry unit via a MergeUnits link with UseLiveState: true. CRDs are split into separate wet units during this process.
  • Sets each wet and CRD unit's ProviderType to ArgoCDOCI or FluxOCI so that applying it deploys through ConfigHub's OCI registry via the GitOps tool. A single Target can carry multiple ConfigTypes (e.g. ArgoCDRenderer and ArgoCDOCI) — the unit's ProviderType selects which bridge on that Target handles the unit, which is why one target slug can serve discovery, rendering, and deployment at once.
  • For Argo CD: disables auto-sync on the imported Application resource (the existing one should remain in the cluster but must not be manually synced or deleted — ConfigHub now owns the rendered output).
  • For Flux: suspends the imported HelmRelease or Kustomization for the same reason.

When a single worker hosts the discovery, renderer, and OCI bridges — e.g. installed with -t kubernetes,argocdrenderer,argocdoci — a single target slug (such as worker-kubernetes-yaml-cluster) is sufficient for all three steps, because the renderer and OCI capabilities register as additional ConfigTypes on that target.

Rendering and deploying

Applying a dry unit invokes its renderer bridge:

  • The ArgoCDRenderer bridge calls Argo CD to render the manifests — similar in effect to argocd app manifests — and returns the result to ConfigHub as LiveState.
  • The FluxRenderer bridge performs the equivalent rendering for HelmRelease / Kustomization resources.

The linked wet unit receives that rendered LiveState as its Data. You can then review, modify, validate, approve, and apply the wet units.

Applying a wet (or CRD) unit deploys the rendered manifests via the ArgoCDOCI or FluxOCI bridge. ConfigHub's worker creates a new Argo CD Application (or Flux HelmRelease / Kustomization) that fetches an OCI image from ConfigHub's OCI registry and deploys it to the cluster. The new GitOps resource takes over the workload that the original, now-suspended resource was managing.

Updating after a git change

After a change is made to DRY configuration in git (helm values, templates, or kustomizations):

  1. Re-apply the corresponding dry unit(s) to re-render. The renderer bridge pulls the latest from git and produces updated manifests.
  2. Review the diff on the linked wet units. Modifications previously made to a wet unit are preserved — the merge behavior matches unit upgrades.
  3. Approve and apply the updated wet units to roll the change out through Argo CD / Flux.

Example walkthrough

A working end-to-end example using Argo CD on a local kind cluster — including worker installation with the three bridges — is available at GitOps Import with ArgoCD and in the confighub/examples/gitops-import repository.