installer

Kubernetes off-the-shelf component installer using configuration as data.

This tool is intended to play the role of an installer wizard and a package dependency manager.

This installer aims to present only the minimal number of high-level decisions, such as which components to install and where to install them. It is recommended to set reasonable defaults as much as possible.

There's a local "fact collection" extension point. This can be used to collect details about the workload being deployed, verify existence of dependencies, and/or to retrieve or generate secrets and convert them to Kubernetes secrets. For cases where installation decisions depend on hardware, operating system, networking, or other details of the target cluster, Target Facts can be used, and can also be collected (assuming permission and access to the cluster) using cub k8s collect <target>.

As with installer wizards for systems other than Kubernetes, changes to detailed default settings are deferred until after installation. Configuration as data makes this possible by storing the configuration data rather than re-rendering from scratch. That decouples configuration authoring from configuration editing. Changes can be merged.

This enables customizations that would need to all be combined a single generator in configuration as code to be decoupled. For example, configuration can be initially authored using whatever tools are most effective. Subsequently, installation can customize the configuration. Then additional changes can be made post-installation, during and after variant creation, and then operationally. Changes made at a later stage can be preserved while merging updates from upstream sources. Edits can be automated with tools, as well.

More explanation of the tool's approach can be found in Design principles.

With the configuration-as-data approach, code that operates on configuration is separate from the data, which is plain YAML (and other formats in the future). The "code" lives in the installer.

This tool leverages kustomize for its foundational composition and customization. It adds a Package manifest named installer.yaml that declares bases, available components, dependencies, and inputs. It also contains a sequence of ConfigHub functions executed at install (render) time locally via the SDK.

Output from the rendering process goes to plain YAML files that can be uploaded to ConfigHub for delivery via ArgoCD or Flux, or could be committed to git to be deployed by ArgoCD, Flux, or other Kubernetes applier or deployment tool.

For post-installation customization, ConfigHub's function suite includes functions for changing commonly changed Kubernetes resource properties, such as set-container-image, set-container-resources, set-replicas, set-env, and set-hostname, and general-purpose editing functions, such as yq-i, set-string-path, delete-path, and set-starlark.

Why not just kustomize, or kpt? Neither tool was really designed to be a full-blown installer, and package management was explicitly out of scope for kustomize and kubectl. As shown in the kpt guide, together they can enable simplifying the installation process, and ConfigHub's function suite provides more capabilities out than kustomize's built-in transformers and kpt's function catalog.

Additionally, a lot was learned from kustomize and kpt, but starting afresh made it easier to experiment with different design choices, such as pushing packages to OCI, storing rendered configuration somewhere other than git, and so on.

Status

Working:

• Package authoring + distribution. installer package (deterministic bundle), push / pull / inspect / list / tag / login / logout (OCI artifacts), sign / verify (cosign keyed + keyless) with a ~/.config/installer/policy.yaml trust policy that gates pull and deps update.
• Dependencies. SemVer resolver + lock (deps update, deps tree), multi-package render into per-dep subtrees, upload into per-dep Spaces with cross-Space Links.
• Install lifecycle. installer setup (the one-shot consumer entry point: optional pull, wizard with high-level component presets minimal / default / all / selected, render). Interactive + non-interactive. Prior-state re-entry from ConfigHub (via the persisted installer-record Unit) or local out/spec/, organization + server sanity-check against the active cub context.
• Day-2 lifecycle. installer setup and installer upload auto-detect first-install vs upgrade vs reconcile via the presence of prior spec files / out/spec/upload.yaml. Re-running setup with --pull <new-ref> runs the schema-diff machinery (carry forward existing values, adopt new defaults, prompt for new required-without-default). Re-running upload against an already- uploaded work-dir opens a ChangeSet and reconciles updates / adds / deletes. installer plan previews the reconcile diff read-only. --merge-external-source is the change predicate, so post-install ConfigHub edits survive re-render.
• Image overrides. installer setup --set-image applies kustomize edit set image before render. Overrides round-trip via Inputs.Spec.ImageOverrides and carry forward across re-renders / upgrades. The chosen base must declare an images: block; render fails fast otherwise.

Stubbed: installer preflight — cluster-side constraint checks.

Build

make build       # writes bin/installer

The binary is named installer so the cub plugin protocol exposes it as cub installer ... (cub names plugins after the entrypoint basename in cub-plugin.yaml). installer shells out to kustomize for kustomize build. Install it from kubernetes-sigs/kustomize or brew install kustomize.

Quick start

End to end against the included example, no ConfigHub server required:

# 1. Inspect what's in the package.
bin/installer doc ./examples/hello-app

# 2. Setup: pull (here: a local dir), pick base + components, supply
#    inputs, and render. One command replaces pull + wizard + render.
mkdir -p /tmp/hello && cd /tmp/hello
bin/installer setup \
  --pull ./examples/hello-app \
  --non-interactive \
  --select monitoring --select ingress \
  --namespace demo

# 3. Upload to ConfigHub. Records the destination Space(s) in
#    out/spec/upload.yaml so subsequent commands re-enter the same
#    Space without re-typing.
bin/installer upload --space my-greeter

# 4. Day-2: edit a rendered file, see what upload would do, apply.
$EDITOR out/manifests/deployment-demo-hello-app.yaml
bin/installer plan                       # read-only diff vs ConfigHub
bin/installer upload --yes               # reconcile (ChangeSet-wrapped)

# 5. Upgrade: re-pull (atomic), re-render via setup, then upload.
bin/installer setup --pull ./examples/hello-app \
  --set-image nginxdemos/hello=nginxdemos/hello:plain-text-v2
bin/installer upload --yes

The wizard's --select is closed under each component's requires: list, so selecting ingress-tls automatically pulls in ingress. Conflicts and validForBases are enforced at solve time.

setup auto-detects whether the work-dir is a fresh install (no out/spec/) or a re-entry (prior state present, possibly with a newer package). On re-entry it runs the schema-diff machinery: silently carry prior values, adopt new defaults, drop removed inputs, prompt or fail-fast on newly-required inputs.

The granular commands (pull, wizard, render) are still available when you want step-by-step control — see consumer-guide.md.

Working directory layout

After setup (or wizard + render), the working dir looks like:

<work-dir>/
├── package/                  # what 'pull' fetched
│   ├── installer.yaml
│   ├── bases/
│   └── components/
└── out/
    ├── manifests/            # per-resource YAML, ready to upload
    │   ├── deployment-<ns>-<name>.yaml
    │   ├── service-<ns>-<name>.yaml
    │   └── ...
    ├── compose/              # the synthesized kustomization driving render
    │   ├── kustomization.yaml    # references the chosen base + components
    │   ├── transformers.yaml     # resolved ConfigHubTransformers (chain)
    │   ├── validators.yaml       # resolved ConfigHubValidators (if any)
    │   └── installer-transformer.sh   # exec wrapper kustomize invokes
    └── spec/                 # the "installer record" (also uploadable as Units)
        ├── selection.yaml    # base + closure-resolved components
        ├── inputs.yaml       # validated wizard answers
        ├── function-chain.yaml   # the resolved chain that ran (audit copy)
        └── manifest-index.yaml   # filename → kind/name/namespace

out/compose/ is durable, not a temp dir. You can cd out/compose && kustomize build --enable-exec --enable-alpha-plugins . to reproduce the render byte-for-byte outside the installer.

The two spec docs (selection.yaml, inputs.yaml) are the load-bearing inputs to re-render: edit them, re-run installer render, get a deterministic new set of manifests.

Package format

A package is a kustomize tree wrapped with an installer.yaml:

apiVersion: installer.confighub.com/v1alpha1
kind: Package
metadata:
  name: my-package
installerMetadata:
  version: 0.1.0
spec:
  bases: # alternative top-level kustomize trees
    - { name: default, path: bases/default, default: true }
  components: # opt-in kustomize Components (kind: Component)
    - { name: monitoring, path: components/monitoring }
    - { name: ingress, path: components/ingress }
    - name: ingress-tls
      path: components/ingress-tls
      requires: [ingress]
      externalRequires:
        - {
            kind: WebhookCertProvider,
            name: cert-manager,
            issuerKind: ClusterIssuer,
          }
  externalRequires: [] # cluster preconditions not provided by this package
  provides: [] # cluster-scope resources this package installs (CRDs, etc.)
  clusterSingleton: [] # leader-election leases this package claims
  externalManifests: [] # remote release-tarball manifests to fetch + merge
  inputs: [] # wizard prompts
  transformers: # one or more groups of function invocations
    - toolchain: Kubernetes/YAML
      whereResource: ""
      invocations:
        - name: set-namespace
          args: ["{{ .Namespace }}"]

See examples/hello-app/ for a complete working package.

The transformers: list is resolved with Go text/template syntax — {{ .Namespace }}, {{ .Inputs.* }}, {{ .Selection.* }}, {{ .Facts.* }}, {{ .Package.* }} — then emitted as a ConfigHubTransformers KRM function config that kustomize invokes through the installer transformer exec plugin. Each group's toolchain and whereResource are applied per-group, so a single chain can mutate raw Kubernetes manifests with Kubernetes/YAML and AppConfig-carried files (AppConfig/Properties, AppConfig/Env, …) in the same render. Components can carry their own transformers: and validators: lists; they append to the package-wide chain only when the component is selected.

Plugin install

The binary doubles as a cub plugin. After publishing a release that includes a platform binary at the path bin/installer, install with:

cub plugin install confighub/installer

The cub-plugin.yaml at the repo root tells cub the entry point. Once installed, the same commands work via cub installer ....

Layout

.
├── cmd/installer/main.go       # CLI entry point
├── internal/
│   ├── cli/                    # cobra subcommands
│   ├── pkg/                    # package load + OCI pull (oras-go)
│   ├── bundle/                 # deterministic tarball for `installer package`
│   ├── selection/              # required-deps closure + conflict detection
│   ├── wizard/                 # interactive + non-interactive answer collection,
│   │                           # prior-state load, schema diff for upgrades
│   ├── collector/              # in-package fact collectors run by the wizard
│   ├── render/                 # kustomize compose + chain execution + split,
│   │                           # --set-image (kustomize edit) + image extraction
│   ├── deps/                   # SemVer resolver + lock writer
│   ├── upload/                 # discover Spaces, build/split installer-record,
│   │                           # write upload.yaml, intra-Space link inference
│   ├── diff/                   # plan compute (cub list + dry-run mutations) +
│   │                           # apply (with ChangeSet) + image footer
│   ├── changeset/              # cub changeset open + restore-command formatter
│   ├── cubctx/                 # active cub context (org / server) + sanity check
│   └── sign/                   # cosign sign + verify
├── pkg/api/                    # Package, Selection, Inputs, FunctionChain,
│                               # Lock, Upload schemas
├── packages/                   # "published" packages bundled in this repo
│   ├── kubernetes-resources/   # 11 canonical resource templates with
│   │                           # per-type defaults (used by `installer new`)
│   └── worker/                 # ConfigHub bridge worker
├── examples/                   # test fixtures for the e2e + unit tests
│   ├── hello-app/              # single-package end-to-end test package
│   ├── example-base/           # multi-package: shared base
│   └── example-stack/          # multi-package: depends on example-base
├── docs/                       # design + implementation plans (see below)
└── cub-plugin.yaml             # cub plugin manifest

The packages/ subdirectory holds packages that are intended for publication; we'll move them to a separate repo as the catalog grows. examples/ stays in this repo as test fixtures the e2e and unit tests exercise.

User docs

For people using the installer (writing packages, installing them, or managing day-2 changes). These are how-to and reference; the design docs below explain why the installer works the way it does.

• Author guide — for package authors. Schema reference for installer.yaml, file organization, how the install pipeline consumes your declarations, authoring best practices, publishing, signing, and version-to-version evolution.
• Author tutorial — hands-on walkthrough of building a small package from an empty directory to a signed OCI artifact. ~30 minutes. Read this before the author guide if you prefer learning by example.
• Consumer guide — for operators consuming packages. Find a package, install it, make day-2 changes, upgrade, revert. Plus a troubleshooting section for the common errors.

Design docs

For contributors to the installer itself. If you're using or authoring packages, the user docs above are what you want.

• Design principles — the seven principles the installer is anchored to (package files are read-only; spec is the round-trippable source of truth; two layers of override; optimize for the zero-override case; image management; defer to ConfigHub for what ConfigHub does well; configuration as data, not templates).
• Package and dependency management + implementation plan — spec and phased build plan for bundling, OCI publish, dependency declaration and resolution, and signing. Phases 0–8 shipped.
• Day-2 lifecycle: interactive wizard, plan, update, upgrade
  • implementation plan — spec and phased build plan for the interactive wizard, prior-state re-entry, plan vs ConfigHub, ChangeSet-wrapped update, staged upgrade with schema-diff, and --set-image overrides. Phases A–E shipped.
• Kustomize transformer plugin and AppConfig support — design for the installer transformer exec plugin (folds the function chain into kustomize), durable out/compose/, component-scoped function-chain mixins, and AppConfig support via configMapGenerator round-trip. Not yet implemented.

Multi-package example

examples/example-stack depends on examples/example-base. To exercise the full pipeline locally:

test/e2e/package-and-deps.sh

That script starts registry:2, pushes example-base, runs wizard → deps update → render, asserts the output layout + digest stability, and (when INSTALLER_E2E_CONFIGHUB=1) drives the full day-2 flow against the live server: upload → plan (clean) → edit → plan (diff) → update → update (no-op) → upgrade (edit) → upgrade-apply → upgrade (carry-forward) → upgrade --set-image → upgrade (override carries forward) → upgrade --set-image preflight rejection. Spaces created with the installer-e2e-* prefix are cleaned on exit.

Roadmap

• Better Secrets support. Currently we generate secrets during fact collection. Explicit support for ESO and CSI, and possibly "drop" and "stub" options.
• installer preflight — evaluate externalRequires against a live cluster.
• More packages: Flux, llm-d, KServe, vLLM production stack (KubeRay and Gateway API Inference Extension shipped — see examples/).
• TBD: More comprehensive hooks, in-cluster and local.