cluster-api-cluster-charts

Helm charts for defining, provisioning, and managing Kubernetes clusters using Cluster API (CAPI).

All charts in this repository are either directly responsible for provisioning a Cluster API cluster or required to make that provisioning succeed.

This repository contains a reusable base chart as well as opinionated application charts used by unbyte to create management and workload clusters. It also includes tightly-coupled helper charts that are required during cluster bootstrapping (e.g. External Secrets Operator configuration).

Charts

Core Cluster Templates

These charts define the primary infrastructure and Cluster API specifications.

The cluster library chart is designed to be reusable outside of unbyte-specific setups, while the application charts provide opinionated defaults used by unbyte.

See the compatibility documentation for supported versions.

Chart Name	Type	Description
cluster	library	Base library providing standardized templates and schemas for Cluster API resources.
management-cluster	application	Opinionated chart for provisioning unbyte-style management clusters.
workload-cluster	application	Opinionated chart for provisioning unbyte-style workload clusters.

Bootstrap & Provisioning Helpers

Helper charts required during the initial cluster lifecycle and secret management, primarily for unbyte-style clusters. These charts are grouped under charts/helpers.

Chart Name	Type	Description
cluster-bootstrap-configs	application	Helper chart for generating ConfigMaps required during cluster bootstrapping.
eso-providers	application	Helper chart for deploying External Secrets Operator providers required during cluster bootstrapping.
eso-secrets	application	Helper chart for deploying External Secrets Operator secrets required during cluster bootstrapping.

Development & Validation

Chart Name	Type	Description
example-workload-cluster	application	Minimal example workload cluster used for validation, testing, and documentation. Not for production use.

Notes

• Application charts depend on the cluster library chart.
• Charts are designed to work with Cluster API–compatible infrastructure providers.
• The example-workload-cluster chart is not intended for production use.

Versioning

All charts in this repository share a single version number and are released in lockstep. Application charts pin the cluster library by an exact version constraint (not a ~ or ^ range), so library bumps always reach consumers through a coordinated release rather than dependency resolution.

When bumping any chart, bump all of them to the same new version in the same PR. The release workflow (.github/workflows/release.yaml) iterates every Chart.yaml and skips versions already published to GHCR, so unchanged charts cost nothing in the pipeline.

Scope & Non-Goals

Scope

This repository focuses on Cluster API cluster provisioning and the minimum set of tightly-coupled helper charts required to bootstrap clusters.

It includes:

• A reusable Cluster API library chart
• Opinionated charts for management and workload clusters
• Helper charts required during cluster bootstrap (e.g. ESO providers and secrets)

Non-Goals

This repository intentionally does not include:

• General-purpose platform add-ons installed after cluster provisioning (e.g. Kyverno policies, network policies, RBAC baselines, shared services)
• Application workloads or tenant-specific deployments
• Charts intended to be reused independently of Cluster API cluster provisioning

Such charts belong in separate, dedicated repositories (e.g. platform add-ons).

Development

Common tasks are wrapped in a justfile. Run just with no arguments to list available recipes.

Linting

# yamlfmt across the repo
just fmt
# pre-commit run --all-files (requires an activated python venv)
just pre-commit
# mirrors .github/workflows/lint.yaml: library chart + all app/helper charts
just lint
# just the cluster library chart
just lint-cluster
# one chart by its path under charts/
just lint-chart workload-cluster
just lint-chart helpers/eso-secrets

When linting fails,

# Let's say failing chart is workload-cluster,
# run linting in verbose mode to see the diffs
just exec just _lint-chart workload-cluster true

devcontainer

Config: .devcontainer/devcontainer.json

# Start a bash shell inside the devcontainer.
just bash
# Stop and remove the devcontainer.
just destroy
# Start Claude Code inside the devcontainer.
just code
# Run an arbitrary command inside the devcontainer.
just exec +CMD

Refs:

• https://containers.dev
• https://code.claude.com/docs/en/sandbox-environments#dev-containers
  • https://code.claude.com/docs/en/devcontainer
  • https://github.com/anthropics/claude-code/tree/main/.devcontainer
• https://zed.dev/docs/dev-containers
• https://code.visualstudio.com/docs/devcontainers/containers