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.
• パターンは context 名全体に対する 完全一致 として評価されます (内部で ^(?:...)$ で包まれます)。prod が preprod-cluster に マッチすることはありません。部分一致にしたい場合は .*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 and path are required.

name

• Required.
• 使える文字種は小文字英数と - のみ (^[a-z0-9]([a-z0-9-]*[a-z0-9])?$、最大 240 文字)。 Manifest 名は state ConfigMap 名 (tazuna-state-<name>) にそのまま使われるため、 Kubernetes リソース名として不正になる大文字や _ は使えません。
• _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 では name のバリデーションは エラー として扱います。 tazuna apply / build / destroy では移行期間として 警告ログのみ が出る挙動に なっていますが、--sync または dependsOn を使う場合はエラー になります (不正な名前のまま state を書くと誤 prune や誤った依存解決につながるため)。 新規導入時は tazuna check で先に通しておくのが安全です。

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.
• include 先ファイル内の Manifest の path は ルートの tazuna.yaml の ディレクトリ起点 で解決されます。include ファイル自身のディレクトリ起点 ではない点に注意してください。

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.