`type: helmfile`

A helmfile Manifest is a Manifest type that renders the equivalent of helmfile template and then applies the result to the cluster for multiple Helm releases described by helmfile.

Internally, Tazuna calls app.Template of the helmfile/helmfile package, converts the output YAML to unstructured objects, and CreateOrUpdates them. Helm release history is not stored on the cluster side (helm rollback becomes unavailable). The stance is that for bootstrapping, declarative regeneration is preferred over rollback.

`path`

Points to the directory containing helmfile.yaml (or other files helmfile recognizes such as helmfile.yaml.gotmpl). Write the path relative to the directory of tazuna.yaml itself.

Specific Fields

Written inside the manifests[].helmfile object.

Field	Type	Required	Default	Description
`vars`	map<string, HelmFileVar>	-	`{}`	Variables passed to helmfile. See vars for details.
`includeCRDs`	bool	-	`false`	Passes the equivalent of `--include-crds` to helmfile template.
`defaultNamespace`	string	-	`""`	The namespace assigned to rendered resources whose `metadata.namespace` is unset.
`extraValueFiles`	[string]	-	`[]`	Additional `--values` files passed to helmfile template.
`wait`	bool	-	`false`	When `true`, wait after `Apply` until the target resources become Ready. See wait behavior for details.
`timeoutSeconds`	int	-	`0`	Maximum wait seconds for `wait`. With `0`, `300` seconds (5 minutes) is used internally.
`kubeVersion`	string	-	`""`	Value passed as `--kube-version` to helmfile template.

`vars`

vars keys are helmfile-side variable names; values are HelmFileVar.

At tazuna.yaml load time, vars are resolved in the following order.

Retrieve the value according to each var’s from (env / static / op).
If a tazuna.hint.yaml is in the same directory, run its validation and default injection.

Sometimes a value is injected via tazuna.hint.yaml’s default even when vars does not specify it. Conversely, violating a tazuna.hint.yaml constraint causes an error here.

HelmFileVar

Field	Type	Required	Description
`from`	string	Yes	Where the value is retrieved from. One of `env` / `static` / `op`.
`env`	string	Conditional (*)	Required when `from: env`. The name of the environment variable to reference.
`static`	string	Conditional (*)	Used when `from: static`. A scalar value.
`staticSlice`	[string]	Conditional (*)	Used when `from: static`. A slice value.
`staticMap`	map<string, string>	Conditional (*)	Used when `from: static`. A map value.
`op`	OnePasswordVaultSelector	Conditional (*)	Required when `from: op`.

(*) Depending on the value of from, one of env / static / op is required. For from: static, exactly one of static / staticSlice / staticMap must be set.

OnePasswordVaultSelector

Field	Type	Required	Description
`key`	string	Yes	Whether to reference the field by `id` or `label`. Either `id` or `label`.
`vault`	string	Yes	1Password vault name.
`item`	string	Yes	1Password item name.
`field`	string	Yes	Field to retrieve. The field ID when `key` is `id`, or the label when `key` is `label`.

`wait` Behavior

When wait: true, after Apply finishes, it waits for all target resources to become Ready. Polling happens at 2-second intervals; exceeding timeoutSeconds (300 by default) is an error.

Ready judgment per Kind:

Kind	Ready condition
`Deployment`	Immediately Ready if `spec.replicas == 0`. Otherwise: `status.readyReplicas == status.replicas` AND `status.availableReplicas == status.replicas` AND `status.replicas > 0`
`StatefulSet`	Immediately Ready if `spec.replicas == 0`. Otherwise: `status.readyReplicas == status.replicas` AND `status.replicas > 0`
`DaemonSet`	`status.numberReady == status.desiredNumberScheduled` AND `status.desiredNumberScheduled > 0`
`Pod`	`status.phase == "Running"` AND `Ready` condition is `True`
Others	Treated as Ready as soon as retrievable (`ConfigMap` / `Secret` / `Service`, etc.)

When you want to express resource-specific conditions that wait cannot handle (such as a CRD’s status), using Test plugin’s WaitUntil (CEL expression) is more flexible.

Behavior

Operation	Internal processing
`Build`	Write the helmfile template output YAML to stdout.
`Apply`	Convert the helmfile template result to unstructured form, supplement `defaultNamespace`, and `CreateOrUpdate` in order. If `wait` is `true`, wait for Ready.
`Destroy`	Convert the helmfile template result to unstructured form, supplement `defaultNamespace`, and delete in order. `wait` is not applied.

All of Apply / Destroy / Build resolve vars at the helmfile template stage. If resolution fails (environment variable unset, field missing in 1Password item, etc.), it fails without touching the cluster.

Examples

manifests:
  - name: cert-manager
    type: helmfile
    path: ./helmfile/cert-manager
    helmfile:
      includeCRDs: true
      wait: true
      timeoutSeconds: 120
      vars:
        clusterIssuerEmail:
          from: env
          env: CLUSTER_ISSUER_EMAIL
        dnsProviderApiToken:
          from: op
          op:
            key: label
            vault: Platform
            item: cert-manager
            field: cloudflare-api-token
        extraLabels:
          from: static
          staticMap:
            managed-by: tazuna
            tier: platform

helmfile.vars constraints: tazuna.hint.yaml schema
Terminology: helmfile / Helm / 1Password

Keyboard shortcuts

Tazuna