Operator handbook

This page is a map, not a duplicate — every topic below already has its own detailed page or in-repo runbook; this page is the order you walk them in when you're the one running OrbitalReg, from a first install through steady-state operation.

1. Install

Pick a shape based on how much of the platform you're standing up:

• Evaluating, demoing, or a small internal install — single-node k3s. Cheapest to stand up, not an HA topology.
• Production — multi-node (three worker nodes minimum, one per AZ) via the Helm chart.

Both shapes, the trade-offs between them, and the concrete k3s/Helm commands: Installation → k3s: single-node vs. multi-node. For a production install specifically, size it against Multi-AZ / multi-node deployment before you provision nodes.

2. Upgrade

Once installed, Upgrading covers the version-to-version story: the supported N-1 → N path, what forward compatibility guarantees hold within a major version, and how to plan a zero-downtime rollout so the upgrade doesn't cost you a maintenance window.

3. Back up and be ready to restore

Backups only count if you've proven the restore works. Read these together, not just the first one:

• Postgres on CloudNativePG — how the primary datastore gets PITR + Barman-managed S3 backups.
• Disaster recovery — the full-cluster and per-dependency restore runbook.
• Backup verification — the scheduled job that proves the last backup is actually restorable, not just present.

4. Wire up SSO

Single sign-on (SAML) covers the SP configuration model and has tested, step-by-step guides for the four IdPs most deployments use: authentik, Okta, Keycloak, AD FS. If your IdP is Azure Entra ID, the Customer test runbook (Phase 4) walks a real Entra app registration end to end (App Role → admin group claim, ACS URL, reply-URL gotchas).

5. Size the install

Sizing starts with the Multi-AZ / multi-node deployment reference architecture — node counts, per-dependency HA story, and a starting point for request/replica sizing. A dedicated load-test baseline (roadmap item 231) is still open; until it ships, size conservatively from that starting point and revisit after your own load test.

6. Troubleshoot

Two different troubleshooting surfaces exist today, for two different failure classes:

• Running-system alerts — the ten bundled PrometheusRule alerts each have a dedicated playbook (what it means, likely causes, diagnosis, fixes, escalation) at Runbooks.

• Kubernetes-operator reconcile failures (if you manage OrbitalReg resources via the Kubernetes operator) — keyed off status.conditions[type=Synced] reason codes at Operator troubleshooting.

• Rollout-time findings — the kind that show up once, during install or upgrade, not as a steady-state alert (NetworkPolicy default-deny blocking a sibling service, image-tag caching after a rebuild, stale PVC credentials after a reinstall, SAML binding/ACS mismatches) — consolidated from the in-repo runbooks' own "Gotchas" sections at Rollout troubleshooting.

Where to go next

• Architecture — how the pieces fit together before you operate them
• Observability — metrics, traces, logs
• Security headers and Air-gapped mode — hardening once the install is live