`tazuna.yaml` Schema

This page describes the spec of tazuna.yaml, Tazuna’s only input file. We do not go deep into manifest-type-specific fields (kustomize / helmfile / genesissecret / parallel / oras) or Test plugin fields here. Those are covered on their own dedicated reference pages.

Root (`Tazuna`)

The root object of tazuna.yaml. Like a Kubernetes manifest, it has three fields: apiVersion / kind / spec.

Field	Type	Required	Default	Description
`apiVersion`	string	-	-	When set, must be exactly `tazuna.pepabo.com/v1`. May be omitted.
`kind`	string	-	-	When set, must be exactly `Tazuna`. May be omitted.
`spec`	TazunaSpec	Yes	-	The body that defines Tazuna’s behavior.

Minimal example:

apiVersion: tazuna.pepabo.com/v1
kind: Tazuna
spec:
  manifests:
    - name: nginx
      type: kustomize
      path: ./kustomize/nginx

TazunaSpec

Field	Type	Required	Default	Description
`manifests`	[Manifest]	Yes	-	The array of Manifests Tazuna processes in order. An empty array is not allowed.
`context_matches`	[string]	-	`[]`	An array of regular expressions that the current kubeconfig context name must match. If non-empty, it is evaluated before `apply` / `destroy`.
`context_match_mode`	string	-	`or`	Evaluation mode for `context_matches`. Either `or` (match any) or `and` (match all).
`tests`	[TestPluginSpec]	-	`[]`	An array of Test plugins to run after all Manifests have been applied.

`context_matches`

Each element must be a regular expression compilable with Go’s regexp package. Compilation failure is caught at the tazuna check stage.
If empty or unset, the context check is skipped.
When set, tazuna apply / tazuna destroy verify current-context before touching the cluster. Mismatch aborts processing.

`context_match_mode`

or (default): matching any one of context_matches is enough.
and: must match all of context_matches.
Any other value is a validation error.

Example:

spec:
  context_matches:
    - ^staging-
    - -tokyo$
  context_match_mode: and
  manifests: []

Manifest

Each element of spec.manifests[]. One Manifest corresponds to “one unit to install into the cluster” handled by one backend (kustomize / helmfile / others).

Field	Type	Required	Default	Description
`name`	string	Yes	-	Manifest identifier. Must match `^[a-zA-Z0-9_-]+$` and be unique across all Manifests after `includes` expansion. `_metadata` is reserved and cannot be used.
`description`	string	-	`""`	Human-facing description. Has no effect on behavior.
`type`	string	Conditional (*)	-	One of `kustomize` / `helmfile` / `genesissecret` / `parallel` / `oras`.
`path`	string	Conditional (*)	-	A path relative to the directory in which `tazuna.yaml` itself resides.
`tags`	[string]	-	`[]`	Tags used for filtering by `tazuna apply --tags ...` and so on. OR evaluation.
`includes`	[IncludeFile]	-	`[]`	An entry that loads another `tazuna.yaml`. When set, the other Manifest-specific fields are ignored. See Using includes for details.
`kustomize`	ManifestKustomize	-	`null`	Options referenced when `type: kustomize`.
`helmfile`	ManifestHelmfile	-	`null`	Options referenced when `type: helmfile`.
`genesisSecret`	object	-	`null`	Options referenced when `type: genesissecret`. Currently an empty object.
`parallel`	ManifestParallel	-	`null`	Options referenced when `type: parallel`. Write nested Manifests under `children[]`.
`oras`	ManifestORAS	-	`null`	Options referenced when `type: oras`.
`tests`	[TestPluginSpec]	-	`[]`	An array of Test plugins to run after this Manifest is applied.

(*) When specifying includes, type / path are not required. Otherwise, type and path are required.

`name`

Required.
Allowed characters are ^[a-zA-Z0-9_-]+$.
_metadata is reserved for internal use and cannot be used as a Manifest name.
Must be unique across all Manifests after includes expansion. Duplicates fail at tazuna check.

tazuna check treats name validation as an error, but tazuna apply / build / destroy only emit a warning log during the transition period. When adopting Tazuna for the first time, it is safer to run tazuna check first.

`path`

Required when not using includes.
Interpreted as a path relative to the directory in which tazuna.yaml itself resides, not the cwd from which the command was run.
Existence is checked at tazuna check time.
What path should point to differs by type.

`type`	What `path` points to
`kustomize`	A directory containing `kustomization.yaml`
`helmfile`	A directory containing `helmfile.yaml`
`genesissecret`	The GenesisSecret definition YAML file (not a directory)
`parallel`	Not used in practice. The `path` from `children[]` is used. It cannot be empty due to validation.
`oras`	Not used in practice. Cannot be empty due to validation, so write any directory.

See each Manifest-type page for details.

`type`

Required when not using includes.
See Manifest type for the value list.
Unsupported values raise a validation error.

`tags`

An array of strings. Tazuna itself does not interpret the contents.
When filtering with the --tags flag, only Manifests with at least one of the specified tags are targeted (OR evaluation).

IncludeFile

Each element of manifests[].includes[]. Loads another tazuna.yaml and expands its manifests[].

Field	Type	Required	Default	Description
`path`	string	Yes	-	Path to the `tazuna.yaml` to load. Written relative to the calling `tazuna.yaml`.

Using includes

spec:
  manifests:
    - name: infra
      includes:
        - path: ./infra/tazuna.yaml
        - path: ./addons/tazuna.yaml

Manifests that have includes have their own “Manifest-body” fields (type / path / tags, etc.) ignored.
includes is non-nestable. Even if the included tazuna.yaml has its own includes, those are not expanded.
names of Manifests defined in the include target must also be unique across all final Manifests.

Manifest-Type-Specific Fields

The fields corresponding to type (kustomize / helmfile / genesisSecret / parallel / oras) are each broken out to their own dedicated reference page.

Here we only indicate their existence and minimum role.

Field	Role
`kustomize`	Options for `type: kustomize`. Has `defaultNamespace`.
`helmfile`	Options for `type: helmfile`. Has `vars` / `includeCRDs` / `wait` / `kubeVersion` and so on.
`genesisSecret`	Extension point for `type: genesissecret`. An empty object in the current version.
`parallel`	Options for `type: parallel`. Has `children[]`.
`oras`	Options for `type: oras`. Has `reference` / `delegate`.

`tests` Field

For the detailed spec of TestPluginSpec (the element type of spec.tests and manifests[].tests), see Test plugin. Here we only describe placement and timing.

Overall tests (spec.tests): executed after all Manifests have been applied.
Per-Manifest tests (manifests[].tests): executed immediately after that Manifest is applied.

Validation Summary

Below is the list of validations tazuna check performs against tazuna.yaml. No cluster access is involved, and anything that fails here is caught in advance.

If apiVersion / kind are set, they must equal the canonical values exactly.
For each element of spec.manifests[]:
- When includes is absent: path and type must be set.
- type must be a known value (kustomize / helmfile / genesissecret / parallel / oras).
- The location pointed to by path must exist.
spec.manifests[].name must be present, use allowed characters, be unique, and not be a reserved word.
spec.context_matches must be compilable as regular expressions.
spec.context_match_mode must be one of or / and / unset.
For type: helmfile: each value in helmfile.vars must satisfy one of env / static / op (see the helmfile reference page).
For type: parallel: parallel.children[] must be non-empty and each child must be a valid Manifest.
For type: oras: oras.reference is required, and oras.delegate.type must be either helmfile or kustomize.
When specifying includes: each include.path is required and the file must exist.

Keyboard shortcuts

Tazuna