Overall Architecture

This page gives an overview of the main components that make up Tazuna and how they cooperate during tazuna apply.

We only cover responsibility boundaries here. Concrete directory layouts and Go package split policies are intentionally out of scope.

Layer diagram

Roughly speaking, Tazuna has a three-layer structure:

+--------------------------------------------------+
|  CLI                                             |
|   apply / build / check / destroy / state ...    |
+--------------------------------------------------+
                         |
                         v
+--------------------------------------------------+
|  Runner                                          |
|   - load tazuna.yaml / expand includes           |
|   - verify context_matches / filter by tags      |
|   - dispatch each manifest to a Manager          |
+--------------------------------------------------+
                         |
           +-------------+-------------+
           v                           v
+---------------------+     +---------------------+
|  Manager            |     |  Test plugin        |
|                     |     |   wait-until /      |
|  kustomize /        |     |   exist-nonexist    |
|  helmfile /         |     +---------------------+
|  oras /             |
|  genesissecret /    |
|  parallel           |
+---------------------+
           |
           v
+---------------------+
|  Kubernetes cluster |
+---------------------+

Each manifest is reflected into the cluster via a single Manager. Pre/post-apply verification is factored out into the Test plugin, which can run per manifest or for the entire tazuna.yaml.

Main components

Internally, Tazuna works by combining the components below. We only describe each component’s responsibility — “what it takes as input and what it produces as output.”

CLI

The entry point for subcommands such as apply, build, check, destroy, state list, state diff, state sync, secret-to-genesissecret, and version. It only parses flags and wires up the Runner; it holds no logic of its own.

Runner

The orchestrator for Tazuna as a whole. It is responsible for the following:

• Loading tazuna.yaml
• Expanding includes
• Converting paths relative to tazuna.yaml into runtime paths
• Filtering by --tags
• Dispatching each manifest to its corresponding Manager
• Running Test plugins after apply

The Runner does not know about the individual manifest types. It only holds a map of “which Manager to use for which type” and delegates everything else to the Manager.

Manager

A component that implements the “actual way to apply” for each manifest type. Every Manager exposes the following three operations:

• Apply — reflect that manifest into the cluster
• Destroy — remove from the cluster what that manifest installed
• Build — generate only what would be installed if applied, without touching the cluster

The Runner treats all manifest types uniformly through just these three operations. For the responsibility split of each individual backend, see the Reference.

Validator

Schema and path-consistency validation that runs immediately after loading tazuna.yaml. Both apply and check go through this first, rejecting malformed YAML or non-existent paths before touching the cluster.

Context guard

Reads context_matches from tazuna.yaml and verifies that the current kubeconfig context name matches those patterns (a list of regular expressions). If it does not match, apply / destroy stops here and never touches the cluster.

State store

The mechanism Tazuna uses to record “fingerprints of the resources it installed” inside the cluster. The storage is an in-cluster ConfigMap; state list / state diff / state sync all operate against it.

Secret provider

A component that abstracts the “source of secret values” referenced by GenesisSecret and helmfile’s vars.op. Currently, a 1Password implementation is bundled.

Test plugin

A verification mechanism that runs after a manifest is applied (or after the entire tazuna.yaml is applied). The following two kinds are available out of the box:

• wait-until — wait until the specified resource exists, becomes Ready, or becomes Available
• exist-nonexist — assert that the specified resource should be present or absent

Hint

An auxiliary component for declaratively validating the type and format of values that helmfile’s vars may take — hostname, URL, email, IP, CIDR, UUID, semver, datetime, and so on.

Prompt

A component that abstracts interactive I/O such as Yes/No confirmations for destructive operations. It exists so that the behavior can be swapped out in non-interactive mode or during tests.

Flow during tazuna apply

Here the steps are laid out from the angle of “which component does what.”

1. CLI parses flags and wires up the Runner.
2. Validator reads tazuna.yaml and verifies the schema and the existence of paths.
3. If spec.context_matches is present, the Context guard verifies the kubeconfig.
4. Runner expands includes and converts manifests[].path into runtime paths.
5. It walks manifests in order and hands each one that is not filtered out by --tags to the corresponding Manager.
6. Each Manager internally invokes kustomize, helmfile, oras pull, 1Password retrieval, and so on, and reflects the result into the cluster. The fingerprint is also written to the State store at this point.
7. If there are per-manifest or whole-file Tests, the Test plugin runs.

tazuna state sync reuses steps 1–4 above, builds a State diff from each Manager’s Build result, and applies only the added or changed entries.