docs/operations/¶
Operator-facing references. Audience: on-call SRE and platform engineers running the Gateway Manager Controller (GMC) and per-tenant Actions Gateway Controllers (AGCs).
| Doc | Personas | Purpose |
|---|---|---|
| runbook.md | SRE | Production runbook — high-level operational procedures. For initial setup see Getting Started. |
| backup-restore.md | SRE, Platform engineer | Backup posture (GitOps + etcd) and a recovery runbook for restoring a deleted or corrupted ActionsGateway CR. |
| velero-backup-restore.md | SRE, Platform engineer | Velero-specific how-to — namespace-level backup/restore commands grounded in GAG's ownership model, with the selector that skips GMC-owned children so the controllers rebuild them. |
| troubleshooting.md | SRE, Platform engineer | Symptom → diagnosis → remediation, organised by observable failure mode. |
| observability.md | SRE, Platform engineer | Observability guide hub — links to the metrics reference, scraping setup, alerting & SLOs, Grafana dashboards, and logging & tracing. |
| cost-attribution.md | SRE, Platform engineer, Budget owner | Live per-tenant cost attribution — map GAG's tenant namespaces and app.kubernetes.io/* labels to OpenCost/Kubecost allocation queries for real $/tenant. |
| worker-rightsizing.md | SRE, Platform engineer | Right-size worker requests/limits from the gateway's built-in per-RunnerSet usage metrics — read the peak distribution, derive values, validate. |
| node-shutdown-budgets.md | SRE, Platform engineer | How much shutdown time each platform actually grants — graceful-node-shutdown and preemption-notice defaults for GKE/EKS/AKS/RKE2/Kubespray/OpenShift, drain timeouts, and why proxy pools should stay off spot capacity. |
| security-operations.md | SRE, Security | Abuse-detection runbook — maps the threat model's abuse heuristics to operator alerts and compromise-response playbooks. |
| admission-policies.md | Platform engineer, Security | Kyverno/Gatekeeper compatibility matrix — whether GAG pods comply with common cluster admission policies, plus sample enforce/exception policies. |
| tenant-onboarding.md | Platform engineer | Step-by-step checklist for onboarding a new tenant team. |
| resourcequota-sizing.md | Platform engineer | Turn runner shapes and concurrency ceilings into the namespace ResourceQuota numbers — what the quota actually counts (native sidecars, Kata overhead, PVCs), which keys are safe to constrain, and a worked DinD example. |
| in-runner-image-builds.md | Platform engineer, Tenant owner | Map each in-runner image-build approach (BuildKit rootless, Kaniko, Sysbox, Kata, privileged DinD) to the right securityProfile/PSA level, with a decision table. |
| kata-dind-workloads.md | Platform engineer | Run DinD / image-build jobs under Kata Containers (KVM micro-VM) at securityProfile: baseline — nested-virt node prerequisites, the Kata DaemonSet + RuntimeClass setup, and the worker podTemplate runtimeClassName. |
| p2p-image-distribution.md | Platform engineer, SRE | Recommended scale companion — adding a peer-to-peer image mirror (Spegel/Dragonfly) to survive ephemeral-worker pull storms, and the imagePullPolicy/digest-pin interplay. |
| service-mesh-coexistence.md | Platform engineer, SRE | Running GAG alongside Istio/Linkerd/ambient — injection opt-out, sidecar lifecycle, and egress exclusions so the per-tenant proxy is honored. |
| migration-from-arc.md | Platform engineer | Coming from Actions Runner Controller (ARC) scale-set mode — concept mapping, behavioral differences, and a worked one-runner-group migration. |
| install.md | Platform engineer | Install the GMC with the actions-gateway Helm chart — prerequisites, digest pinning, healthy-install verification, uninstall. |
| air-gapped-install.md | Platform engineer | Install on an air-gapped / egress-restricted cluster — relocate the images and OCI chart to a private registry (digests preserved), set per-image registry overrides + image-pull Secrets, wire pull Secrets for the runtime AGC/proxy/worker pods. |
| gitops.md | Platform engineer | Install the OCI chart declaratively via Argo CD or Flux — Application / HelmRelease examples with the CRD-pruning gotcha handled, plus sourcing the GitHub App credential Secret with External Secrets Operator or Sealed Secrets (raw key never committed). |
| v1alpha1-deprecation.md | Platform engineer, Tenant operator | Standing deprecation notice: what the v2.0.0 release removes (v1alpha1, v2alpha1, Classic acquisition), what keeps working until then, and the pre-upgrade checklist. |
| migration-v1-to-v2.md | Platform engineer | Move a tenant off the deprecated v1alpha1 API with the gag-migrate one-shot fan-out: dry-run → review → --apply, coexistence, rollback, teardown. |
| upgrade.md | Platform engineer | Upgrade and rollback procedures. Strategy intent lives in §2.6 of the architecture doc. |
| release.md | Maintainer | How to cut a release: tag → publish (build, push, keyless-sign, SBOM-attest) → verify → record digests → bump the chart. |
| kata-ci-spike-runbook.md | Platform engineer, Security | Live go/no-go runbook for the Q226 Kata-on-GKE spike — run an unprivileged dockerd+kind runner inside a Kata micro-VM, step-by-step against the six acceptance criteria. Applies the artifacts in deploy/kata-ci/. |
| ../design/08-glossary.md | All | Canonical definitions for project terms (GMC, AGC, ActionsGateway, RunnerGroup, broker protocol identifiers). |
When adding a new failure mode an operator might observe, add a section to troubleshooting.md.