Operations¶
Operator-facing references for the two roles that run GitHub Actions Gateway (GAG): the platform engineer who owns the cluster and the Gateway Manager Controller (GMC), and the tenant operator who owns one namespace's Actions Gateway Controller (AGC), runner sets, and the workflows that target them. Who owns what defines every role and what each cannot do.
| Doc | Personas | Purpose |
|---|---|---|
| personas.md | All | Who owns what: each role defined by what it owns and what it cannot do, the external contributor as a threat-model actor rather than an audience, and how persona tags are recorded. |
| runbook.md | Platform engineer | Production runbook: high-level operational procedures. For initial setup see Getting Started. |
| backup-restore.md | Platform engineer | Backup posture (GitOps + etcd) and a recovery runbook for restoring a deleted or corrupted ActionsGateway custom resource. |
| velero-backup-restore.md | 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 | Platform engineer, Tenant operator | Symptom → diagnosis → remediation, organised by observable failure mode. |
| observability.md | Platform engineer, Tenant operator | Observability guide hub: links to the metrics reference, scraping setup, alerting & SLOs, Grafana dashboards, and logging & tracing. |
| cost-attribution.md | 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 | Tenant operator, 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 | 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 | Platform engineer, 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. |
| runner-template-library.md | Platform engineer, Tenant operator | Adopt one of the three shipped worker pod shapes (plain, kata-dind, privileged-dind) instead of hand-authoring one: which entry fits which jobs, the cluster prerequisites each needs, and how to fork one safely. |
| in-runner-image-builds.md | Platform engineer, Tenant operator | 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 | 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 | 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 CustomResourceDefinition 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.