Helmcraft — Configuration Reference

Reference for the configuration file consumed by the Helmcraft cluster-deployment tool, covering precedence, validation, and supported sources.

File location and format

Helmcraft reads its configuration from a single TOML file resolved in the following precedence order: the path given to `--config`, then `$HELMCRAFT_CONFIG`, then `./helmcraft.toml`, then `~/.config/helmcraft/config.toml`. JSON and YAML formats are not supported — Helmcraft chose TOML to avoid YAML indentation ambiguity. A configuration file may be at most 256 KiB; larger files are rejected with exit code 9.

Required and optional sections

Required top-level sections are `[cluster]` and `[registry]`. Optional sections include `[secrets]`, `[hooks]`, `[telemetry]`, and any number of `[environment.<name>]` tables. The `[cluster].name` field must match the regex `^[a-z][a-z0-9-]{2,62}$`. The `[registry].url` field must be HTTPS; HTTP registry URLs are rejected at parse time, even on the loopback interface, with the exception of `localhost:5000` for development.

Secrets handling

The `[secrets]` section may reference values from environment variables (`env:VAR_NAME`), HashiCorp Vault (`vault://path#field`), AWS Secrets Manager (`asm://arn`), or 1Password Connect (`op://vault/item/field`). Plaintext secret values written directly into the configuration file are accepted but cause Helmcraft to print a warning to stderr on every run and to refuse to upload the configuration to the audit-log endpoint.

Validation and dry-run

Run `helmcraft validate` to type-check and resolve all referenced secrets without applying any changes. The validate command exits 0 on success, 1 on schema violation, 2 on unresolvable secret reference, 3 on unreachable cluster, and 4 on registry authentication failure. The `--dry-run` flag on `helmcraft apply` performs a server-side dry run and prints the would-be diff but does not exercise post-apply hooks.

Key facts

Helmcraft reads configuration only from a TOML file; JSON and YAML are not supported.
Required top-level sections are `[cluster]` and `[registry]`.
Configuration files larger than 256 KiB are rejected with exit code 9.
Config precedence is `--config` then `$HELMCRAFT_CONFIG` then `./helmcraft.toml` then `~/.config/helmcraft/config.toml`.
The `[cluster].name` field must match `^[a-z][a-z0-9-]{2,62}$`.
Secrets may be referenced via env, Vault, AWS Secrets Manager, or 1Password Connect.
HTTP registry URLs are rejected at parse time except for `localhost:5000`.
`helmcraft validate` exits 1 on schema violation, 2 on unresolvable secret, 3 on unreachable cluster, 4 on registry auth failure.
The `--dry-run` flag does not exercise post-apply hooks.

Details