tazuna.yaml Schema

This page describes the spec of tazuna.yaml, Tazuna’s only input file. We do not go deep here into manifest-type-specific fields (kustomize / helmfile / genesissecret / oras) or Test plugin fields. 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.

Minimal example:

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

TazunaSpec

minimumSupportedTazunaVersion

• Declares, in semver form, the minimum version of the tazuna binary that can safely process this tazuna.yaml (e.g. 1.4.0). A leading v is accepted (v1.4.0 also works).
• On any operation that loads tazuna.yaml (apply / destroy / plan / build / check / status / tags / state *, etc.), if the running tazuna’s version is below this value it exits with an error. This prevents accidentally processing a tazuna.yaml that requires newer syntax with an old binary.
• When unset (empty string), there is no constraint.
• If the value is not a valid semver, it is a configuration error.
• When the running tazuna is a local build (a non-semver version such as dev), the comparison is skipped, so that local development is not blocked by this gate.

spec:
  minimumSupportedTazunaVersion: "1.4.0"
  manifests: []

context_matches

• Each element must be a regular expression compilable with Go’s regexp package. Compilation failure is caught at the tazuna check stage.
• The pattern is evaluated as an exact match against the entire context name (it is wrapped with ^(?:...)$ internally). prod never matches preprod-cluster. If you want a partial match, write it explicitly like .*prod.*.
• 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: []

environments

environments is a map keyed by environment name. When you select an environment with the -e/--environment <name> flag, the selected environment’s values are used instead of the top-level context_matches / context_match_mode. It is the mechanism for safely reusing the same tazuna.yaml across multiple clusters such as staging / production.

Each entry (EnvironmentSpec) has the following fields.

Resolution rules:

• If you do not pass -e, environments is ignored and the top-level context_matches / context_match_mode are used (the conventional behavior).
• If you pass -e <name>, environments.<name> is used. The top-level context_matches is not referenced.
• If the environment corresponding to -e <name> is not declared under environments, apply / destroy / check exit with an error.
• If environments.<name>.context_matches is empty (or unset), no context check is performed for that environment.

-e also becomes the value of the {{ .Environment }} template variable at the same time (see Template variables). Combined with environments, you can, for example, substitute manifest values by environment name while allowing only the contexts intended for that environment.

Example:

spec:
  # used for local runs where -e is not passed
  context_matches:
    - ^kind-
  environments:
    staging:
      context_matches:
        - ^staging-tokyo$
        - ^staging-osaka$
      context_match_mode: or
    production:
      context_matches:
        - ^prod-tokyo$
      context_match_mode: and
  manifests:
    - name: app
      type: kustomize
      path: ./overlays/{{ .Environment }}

# staging クラスタに向けて apply（current-context が ^staging-* でないと中断）
$ tazuna apply -e staging

# production クラスタに向けて apply
$ tazuna apply -e production

Template Variables

tazuna.yaml (and files loaded via includes) is rendered once as a Go text/template before being parsed as YAML. This lets you inject different values per environment from a single file.

How It Works

1. tazuna loads the specified tazuna.yaml.
2. The entire file is interpreted as a Go template and rendered by applying the variables described below.
3. The rendered string is parsed as YAML.
4. Files loaded via includes are rendered the same way, with the same variables.

Rendering happens for every operation that reads tazuna.yaml, such as apply / destroy / build / plan / check / status / tags / state *. If you do not pass -e, {{ .Environment }} expands to an empty string.

Supported Variables

Notes

• Rendering is performed on the entire file. If you want to output {{ or }} literally as YAML values, escape them like {{ "{{" }} / {{ "}}" }}.
• Referencing a nonexistent variable (e.g. {{ .Unknown }}) causes an error during rendering.
• Helmfile value files and Helm chart templates are not rendered by tazuna (they are handled by helmfile / helm). Only the tazuna.yaml body itself and files targeted by includes are rendered.

Use Cases

• Switching overlays: switch the manifest path by environment name, as in path: ./overlays/{{ .Environment }}.
• Substituting namespaces or labels: e.g. defaultNamespace: {{ .Environment }}.
• Combining with environments: substitute values with {{ .Environment }} while limiting target clusters via that environment’s context_matches, preventing application to the wrong cluster.

Manifest

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

(*) When specifying includes, type / path are not required. Otherwise type is required, and path is also required in principle — except for type: oras, which does not use path.

name

• Required.
• Allowed characters are lowercase alphanumerics and - only (^[a-z0-9]([a-z0-9-]*[a-z0-9])?$, max 240 characters). The Manifest name is used as-is in the state ConfigMap name (tazuna-state-<name>), so uppercase letters and _, which are invalid in Kubernetes resource names, cannot be used.
• _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. tazuna apply / build / destroy only emit a warning log during the transition period, but it becomes an error when --sync or dependsOn is used (writing state under an invalid name could lead to wrong pruning or wrong dependency resolution). When adopting Tazuna, it is safest to pass tazuna check first.

path

• Required unless includes is used or type is oras. type: oras does not use path, so it can be omitted.
• 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.

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).

dependsOn

• An array of Manifest names that must have completed before this Manifest is applied.
• Must be a name contained in the full set of Manifests after includes expansion.
• It cannot include itself (self-dependency is rejected as a special case of a cycle).
• The overall dependency graph must not contain a cycle.
• If even one dependsOn is used in tazuna.yaml, the Runner switches to DAG mode and runs Manifests at the same dependency depth in parallel. If none is used, it runs one at a time in declaration order as before.

See DAG Execution via dependsOn for details and motivation.

Example:

spec:
  manifests:
    - name: cni
      type: kustomize
      path: ./cni
    - name: cert-manager
      type: helmfile
      path: ./cert-manager
      dependsOn: [cni]
    - name: ingress
      type: helmfile
      path: ./ingress
      dependsOn: [cni]
    - name: app
      type: kustomize
      path: ./app
      dependsOn: [cert-manager, ingress]

Providers

spec.providers[] is the list of Secret provider declarations referenced by GenesisSecret. Write it when you use something other than the built-in default-op (1Password), or when you want to line up multiple providers and select between them.

spec:
  providers:
    - name: primary-op
      type: onepassword
      onepassword: {}
    - name: ops-envfile
      type: envfile
      envfile:
        path: ./secrets/ops.env

See Secret provider for details.

IncludeFile

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

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.
• A Manifest’s path inside an included file is resolved relative to the directory of the root tazuna.yaml. Note that it is not the include file’s own directory.

Manifest-Type-Specific Fields

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

Here we only indicate their existence and minimum role.

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.
• If spec.minimumSupportedTazunaVersion is set, it must be a valid semver and the running tazuna’s version must be at least that value (local builds skip the comparison). Note that this check runs not only on check but on every operation that loads tazuna.yaml.
• For each element of spec.manifests[]:
  • When includes is absent: type must be set, and path must be set except for type: oras (oras does not need path).
  • type must be a known value (kustomize / helmfile / genesissecret / oras).
  • The location pointed to by path must exist (except for type: oras).
• spec.manifests[].name must be present, use allowed characters, be unique, and not be a reserved word.
• spec.manifests[].dependsOn must reference only existing Manifest names and contain no self-reference or circular dependency.
• spec.context_matches must be compilable as regular expressions.
• spec.context_match_mode must be one of or / and / unset.
• For each element of spec.providers[]: name must be unique and non-empty, must not be default-op, type must be one of onepassword / envfile, and it must have config consistent with type.
• For type: helmfile: each value in helmfile.vars must satisfy one of env / static / op (see the helmfile reference page).
• 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.