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

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

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.

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: path and type must be set.
  • type must be a known value (kustomize / helmfile / genesissecret / 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.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.