97 lines
4 KiB
Markdown
97 lines
4 KiB
Markdown
|
# 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
|
||
|
|
```
|