`tazuna.hint.yaml` Schema

tazuna.hint.yaml is a hint file that declaratively constrains “what values can be taken” and “which are required” for the vars of a type: helmfile Manifest. Place it in the same directory as the helmfile Manifest; Tazuna consults it during vars resolution.

For the schema of tazuna.yaml itself, see tazuna.yaml schema.

Placement and Loading

Tazuna looks for tazuna.hint.yaml directly under the helmfile Manifest’s path directory.

The file name is fixed as tazuna.hint.yaml.
If absent, it is silently ignored (no error, for backward compatibility).
At most one per helmfile Manifest.

Not read for non-helmfile Manifest types.

Root (`TazunaHint`)

Field	Type	Required	Default	Description
`apiVersion`	string	-	-	Indicates the schema version. The value is currently not validated.
`kind`	string	-	-	Indicates the resource kind. The value is currently not validated.
`vars`	map<string, HintVar>	Yes	-	A collection of declarations keyed by `varName`.
`rules`	[HintRule]	-	`[]`	Top-level validation rules that span vars.

apiVersion / kind are not validated for their values, but by convention writing apiVersion: tazuna.pepabo.com/v1 / kind: TazunaHint makes it easier to align when validation is added later.

Minimal example:

apiVersion: tazuna.pepabo.com/v1
kind: TazunaHint
vars:
  clusterName:
    type: string
    required: true
  replicas:
    type: string
    default: "3"

HintVar

Each entry of vars (one var declaration).

Field	Type	Required	Default	Description
`type`	string	Yes	-	The var’s type. One of `string` / `slice` / `map`.
`required`	bool	-	`false`	Whether the user must provide a value.
`default`	any	-	`null`	Value injected when not provided. Cannot be combined with `required: true`.
`description`	string	-	`""`	Human-facing description. Has no effect on behavior.
`format`	string	-	`""`	Value format-validation rule. Only available when `type: string`. See format for details.
`required_with`	[string]	-	`[]`	Conditional-required meaning “if any of the vars listed here is provided, then this var is also required.” Cannot be combined with `required: true`. References must exist in `vars`.
`required_without`	[string]	-	`[]`	Conditional-required meaning “if all vars listed here are unprovided, then this var is required.” Cannot be combined with `required: true`. References must exist in `vars`.

Behavior When a Value Is Not Provided

After helmfile-Manifest-side vars resolution, each var is processed in this order.

If a value is already provided, use it as-is.
If not provided and required: true, error.
If a default is set, inject that value.
Otherwise, inject the type-specific zero value (string → "", slice → [], map → {}).

Conditional-required (required_with / required_without) evaluation is done against the set of values explicitly provided by the user, not the result after zero-value injection. This is to prevent vars with injected zero values from being mistakenly treated as “provided.”

format

format is string-format validation for type: string vars. If the value is an empty string (including zero-value injection), validation is skipped. Validation runs only when a non-empty string is present.

Value	Validation
`hostname`	RFC 952 / 1123 compliant hostname pattern (alphanumerics / `-` / `.`; each label starts and ends with alphanumerics)
`url`	Parseable with `net/url.ParseRequestURI`, and the scheme must be non-empty
`email`	Simple `user@domain.tld` form (a simple regex)
`ip`	An IPv4 / IPv6 address parseable with `net.ParseIP`
`cidr`	A CIDR notation parseable with `net.ParseCIDR`
`uuid`	RFC 4122 form (hyphen-separated)
`semver`	Semantic version. The `v` prefix is optional. Pre-release / build metadata are supported
`datetime`	A datetime string in `time.RFC3339` format

Specifying any value not listed is a validation error.

HintRule

rules are top-level rules for declaring cross-var validations. They are evaluated after per-var processing is complete.

Field	Type	Required	Default	Description
`type`	string	Yes	-	Rule kind. Currently only `oneof_required`.
`vars`	[string]	Yes	-	Array of var names targeted by the rule. At least 2 entries required. References must exist in `vars`.
`message`	string	-	`""`	Custom message to display on validation error.

`oneof_required`

A rule that errors unless at least one of the vars listed in vars is provided by the user.

rules:
  - type: oneof_required
    vars:
      - certManagerIssuerName
      - certManagerClusterIssuerName
    message: "either certManagerIssuerName or certManagerClusterIssuerName must be set"

The judgment criterion, like conditional-required, is the set of user-provided values before zero-value injection. Vars whose values came from default are not treated as “provided.”

Validation

When tazuna.hint.yaml is loaded, schema-level validation runs first.

vars[*].type must be one of string / slice / map.
vars[*].required: true and vars[*].default must not be combined.
When vars[*].format is set, type: string must also be set.
vars[*].format must be a known value (see format).
References of vars[*].required_with / vars[*].required_without must exist in vars.
vars[*].required: true and required_with / required_without must not be combined.
rules[*].type must be a known value (currently only oneof_required).
rules[*].vars length must be at least 2.
References of rules[*].vars must exist in vars.

After those pass, the following validations run against the result of the helmfile Manifest’s vars resolution (see Behavior When a Value Is Not Provided and format).

The type declared in the hint matches the type of the value passed in on the helmfile side (e.g. an error if a var declared type: slice receives a staticMap).
Required vars (required: true) have a value.
required_with / required_without conditions are satisfied.
For string vars with a format, the value (if non-empty) satisfies the format pattern.
rules are satisfied (e.g., at least one of the vars in oneof_required is provided).

Term: tazuna.hint.yaml
Schema of helmfile.vars: tazuna.yaml manifest-type-specific fields

Keyboard shortcuts

Tazuna