# 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:

```bash
# 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:
  ```bash
  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:
  ```bash
  just flags-help
  ```