Deployment Contract

Deployment Contract

How GloriousFlywheel lands on honey, where managed-resource authority lives, and what still counts only as compatibility.

Active Stack Topology

GloriousFlywheel currently operates four active OpenTofu stacks on the honey cluster.

Stack Namespaces Current backend Purpose
arc-runners arc-systems, arc-runners S3-compatible ARC controller plus GitHub runner scale sets
attic nix-cache plus cnpg-system dependencies where present S3-compatible Attic, RustFS, Bazel cache, and related cache-plane services
gitlab-runners gitlab-runners S3-compatible GitLab compatibility runner deployments
runner-dashboard runner-dashboard S3-compatible internal operator dashboard

attic-cache-dev and GitLab HTTP backend assumptions are not part of the live contract for these stacks anymore.

State Authority

Use this order when reasoning about truth:

  1. repo code plus stack inputs define desired state
  2. S3-compatible OpenTofu state defines managed-resource authority
  3. live cluster state is observed state and may drift

Current proven state keys for ENV=dev:

  • attic -> attic/terraform.tfstate
  • arc-runners -> arc-runners/terraform.tfstate
  • gitlab-runners -> tinyland-infra/gitlab-runners/terraform.tfstate
  • runner-dashboard -> tinyland-infra/runner-dashboard/terraform.tfstate

Manual kubectl edits are drift unless they are an explicit bounded operator action that is expected to reconcile later.

Local Operator Flow

Use the S3-compatible backend path for the four active stacks.

export ENV=dev
export KUBE_CONTEXT=honey
export TOFU_BACKEND_S3_ENDPOINT=...
export TOFU_BACKEND_S3_BUCKET=...
export TOFU_BACKEND_S3_ACCESS_KEY=...
export TOFU_BACKEND_S3_SECRET_KEY=...

just tofu-init arc-runners
just tofu-plan arc-runners

If you prefer checked local backend files, materialize them first:

just tofu-backend-materialize-s3 arc-runners
just tofu-init arc-runners

TF_HTTP_* and just tofu-init-gitlab-legacy <stack> remain compatibility-only.

CI/CD Deployment Flow

Current GitHub-first truth:

  • pull requests run validation and proof workflows
  • Deploy ARC Runners does a PR plan when ARC-related paths change
  • pushes to main run selected proof, build, publish, and deploy workflows
  • only the ARC stack currently has an automated apply workflow on main
  • the other stacks still rely on bounded operator-driven apply paths

ARC runner applies are deliberately more conservative than plans. The mutating job runs on a non-shared heavy Nix lane and drains the shared Nix/Docker/DinD baseline and compute-expansion scale sets before tofu apply. This prevents a scale-set cap change from invalidating the listener for the same shared-label runner currently hosting the apply job.

Do not describe the repo as having one universal plan artifact followed by one universal automatic deploy stage for every stack.

Dependencies

Current dependency order for a fresh or repaired environment:

  1. arc-runners for ARC controller plus shared GitHub runner lanes
  2. attic for the cache and storage plane
  3. gitlab-runners for bounded GitLab compatibility
  4. runner-dashboard for internal operator access

The repo no longer assumes Civo or Liqo-era topology.

Cluster Contract

Target cluster

Property Value
provider shape on-prem
distribution RKE2
active cluster honey
storage-biased node bumble
stateless compute node sting
operator access tailnet-first and private

Important current access rules

  • dashboard ingress is tailnet-only by default on honey
  • cache-plane internals use nix-cache namespace addresses
  • cluster and dashboard hostnames are internal operator details, not public product contract

Compatibility-Only Paths

These still exist in the repo, but they do not define the current deployment contract:

  • GitLab-managed HTTP state for the active stacks
  • attic-cache-dev namespace assumptions
  • Civo deployment assumptions
  • multi-cluster Liqo burst assumptions

GloriousFlywheel