Operator flags — catalog component ops

Cross-component env vars that govern any catalog component op (cluster or taskserv). They are read by diagnostics.sh (sourced by every component's install script) and propagated via the workspace just recipe into the deploy bundle's _credentials.env (so the same flag works from your shell or from a recipe).

Each flag has a canonical name (PROVISIONING_*) and a short alias (PRVNG_*). Both accept 1, true, yes (case-insensitive) as truthy; anything else is falsy.

Flags

Canonical	Alias	Effect
`PROVISIONING_VERBOSE`	`PRVNG_VERBOSE`	Stream every `kubectl apply`/`scp`/`ssh` line. Off by default (only the `→ phase` step markers, warnings, errors, and the final summary are shown).
`PROVISIONING_FORCE`	`PRVNG_FORCE`	Delete the workload (Deployment/StatefulSet) before re-applying, instead of relying on rollout. Use when a k0s/k3s/RKE2 rollout hangs or pods get stuck pre-Ready. Drastic but reliable.
`PROVISIONING_DEBUG`	`PRVNG_DEBUG`	Preserve the deploy bundle (local `mktemp` + remote `/tmp/<component>-bundle/`) on both success and failure. Also prints raw values (e.g. malformed JSON) inside error messages that otherwise stay structured.

Combinability

Flags are independent — combine freely:

# default (silent except for phase markers + errors)
just fleet-daemon-up

# every kubectl line (debug a manifest)
PRVNG_VERBOSE=true just fleet-daemon-up

# delete + apply (skip the rollout dance on k0s)
PRVNG_FORCE=true just fleet-daemon-up

# preserve /tmp bundle for post-mortem inspection
PRVNG_DEBUG=true just fleet-daemon-up

# verbose + force + preserve — full transparency
PRVNG_VERBOSE=true PRVNG_FORCE=true PRVNG_DEBUG=true just fleet-daemon-up

# canonical names work identically
PROVISIONING_DEBUG=true PROVISIONING_FORCE=true just fleet-daemon-up

What's always shown

Independent of flags, the install script ALWAYS prints:

Phase step markers (→ namespace + service account, → secrets, ...).
Warnings (WARN: PrometheusRule CRD not installed — skipping ...).
Errors (any non-zero kubectl exit prints stderr).
The final success/failure summary block.
A diagnostic post-mortem (describe or logs --tail=N --previous) when the workload fails to become ready. Smart selection: if pod logs are accessible the daemon HAS started and logs are the source of truth, so describe is skipped. If logs are unavailable, describe + events are shown (image pull failures, scheduling errors, etc.).

Bundle layout (what gets shipped)

Every kube_workload component renders a single tarball, scp'd once to the operator host. Contents:

<component>-bundle/
├── install-<component>.sh    ← entry point (bash)
├── <component>-lib.sh        ← component-specific helpers
├── diagnostics.sh            ← THIS lib (ERR trap + flag helpers + force helpers)
└── _credentials.env          ← sops-decrypted secrets + flag propagation (mode 0600)

The bundle is chmod 0700 on disk. The credentials file is chmod 0600. Both are removed after the op completes (unless PRVNG_DEBUG=true, in which case they're kept at:

local : /var/folders/.../tmp.XXXXXX (path printed at end of run)
remote: /tmp/<component>-bundle/).

Secrets never touch disk via --from-literal= + kubectl apply -f - from stdin — the bundle's _credentials.env carries them, but the install script sources it into env vars and pipes Secret manifests through stdin to the cluster, never writing materialised Secret YAML to the filesystem.

Where this is wired

Library: provisioning/catalog/components/_renderer/lib/diagnostics.sh
Per-component install scripts source it via:
```
source "${SCRIPT_DIR}/diagnostics.sh"
```
Just recipes propagate flags into the bundle via _credentials.env, see e.g. libre-forge/justfiles/deploy.just::_fleet-daemon-op.
Display this file via the flags-help recipe in any workspace:
```
just flags-help
```

4 KiB Raw Blame History