Design Philosophy and Intended Use Cases

Tazuna is “a CLI for managing the bootstrap lifecycle of multi-cluster Kubernetes.” This page lays out the design stance behind it: why such a tool is needed, what Tazuna takes on, and what it deliberately leaves to others.

The problem we are trying to solve

A Kubernetes cluster is not yet usable just because its API server is up. To get from there to a state you can call “our cluster,” you need to install:

• Infrastructure-layer add-ons such as CNI, Ingress, and cert-manager
• The deployment platform itself, such as ArgoCD or Flux
• Various operators and CRDs

All of these layers must be installed into the cluster in the correct order, preserving their dependencies.

If you substitute manual work, sprawling runbooks, or simple shell scripts for this, you run into problems like:

• Losing track of what has been applied (i.e. “there is no state”)
• The cluster bootstrap procedure going stale

These problems pile up. Tazuna addresses this by bringing in a single declarative configuration file and a unified CLI, explicitly handling just the “bootstrap” phase.

The idea of running Kubernetes clusters immutably

One of the ideas behind Tazuna is to treat the Kubernetes cluster itself as an immutable resource. “Immutable” here means giving up on patching a running cluster in place over time, and instead keeping the cluster in a state where it can always be rebuilt by the same procedure.

When we say “immutable” here, we mean the cluster’s foundation layer. We are not calling it a mutation when an application Pod managed by a Deployment is replaced with a new image, or when HPA changes the replica count. What we have in mind is the infrastructure add-ons such as CNI, Ingress, cert-manager, and ArgoCD, along with the CRDs and operators they depend on — the foundation layer that makes the cluster “a cluster” in the first place. The application layer on top is free to mutate via GitOps.

Over a long operational lifetime, changes like the following slowly accumulate on a cluster:

• Provisional manifests that someone kubectl applyed during an incident response
• CRDs or operators swapped out by hand to investigate a version
• Add-ons installed with a local helm install

As these pile up, the cluster that is actually running and the cluster declared in code drift apart (configuration drift). Once that happens, the cost of rebuilding the cluster shoots up, and you can no longer move when you want to “swap out the whole cluster” — for DR, adding a region, or a Kubernetes version upgrade.

Running clusters immutably means flipping that situation around:

• Assume the cluster’s contents can all be regenerated from declared configuration
• The post-bootstrap add-on layer should come out the same even if the cluster is thrown away and rebuilt from scratch
• Treat anything installed by hand as “fine to disappear at any time,” or fold it back into the declaration

That is the operational stance immutable operation entails. For the application layer, GitOps tools like ArgoCD and Flux already guarantee this. By contrast, the “bootstrap layer” — which includes those GitOps tools themselves — has traditionally relied on runbooks and shell scripts and has been the place where immutability is most easily lost.

Tazuna positions itself as the piece that brings this bootstrap layer onto the same immutable footing.

• By writing the ordering of CNI / Ingress / cert-manager / ArgoCD and so on into a single declarative configuration file, tazuna.yaml, the cluster’s initial state becomes uniquely regenerable from code.
• tazuna apply is the operation that closes the gap between that declaration and the live cluster. “Day one of a new cluster” and “catching up an existing cluster” are both handled by the same command, so a freshly rebuilt cluster and a long-lived one both converge to the same declaration.
• By holding “what is currently installed” in state and pinning down which cluster a declaration belongs to via context_matches, Tazuna structurally prevents “applying to the wrong cluster by mistake” and “not knowing whether something has been applied.”
• Once bootstrap is done, application operations are handed off to ArgoCD / Flux. The baton of immutable operation passes to the application layer, and both the bootstrap layer and the continuous-delivery layer become reproducible from declarations.

Note that Tazuna does not force you to actually rebuild the cluster every time. The strict immutable style — rebuilding and swapping entire clusters — is within scope, but what we care about more is the property one step before that: keeping the cluster in a state where “even if the Kubernetes cluster breaks at any moment, it can be rebuilt automatically by a guaranteed procedure.”

With just this property in place, you can:

• Keep using the same cluster for ordinary day-to-day operations
• Only for DR or major version upgrades, stand up an entirely separate cluster and switch over to it
• Spin up throwaway clusters for verification whenever you need to

— and choose between these options based on the situation at hand.

By concentrating that “guaranteed rebuild procedure” into the code of tazuna.yaml and the single command tazuna apply, Tazuna provides the foundation for continuously keeping immutable operation a viable choice.

What Tazuna does not take on

There are areas Tazuna deliberately stays out of.

• Continuous delivery — Tazuna is not a replacement for ArgoCD or Flux. Its job ends at getting those tools into the cluster; from there, it hands off to ArgoCD/Flux.
• Authoring the manifests themselves — kustomize overlays, helmfile compositions, and Helm chart values are written in each tool’s own idiomatic style. Tazuna only invokes those tools and pushes the result into the cluster.
• Creating the control plane — the cluster itself, built via kubeadm / kops / a managed service, is assumed to already exist. Tazuna connects to that existing cluster via kubeconfig.
• The secret management backend itself — Tazuna declares references to where secrets are stored, but does not store the secrets itself.
• GitOps rollbacks and history management — state represents “what is currently installed,” and historical version control is left to git.

Intended use cases

Concretely, Tazuna shines in roughly the following situations.

• Day one of bringing up a new cluster — when you want to install everything from CNI to the deployment platform in the prescribed order with a single tazuna apply.
• Automatically verifying that a Kubernetes cluster build procedure is sound.
• Standing up multiple clusters with the same role — when you want to bring up similar clusters such as staging / production / dr from nearly the same tazuna.yaml.

Next, in Overall Architecture, we look at the components that make this happen.