GloriousFlywheel Backend Authority Options 2026-04-15

GloriousFlywheel Backend Authority Options 2026-04-15

Snapshot date: 2026-04-15

Purpose

Turn the remaining #169 backend-authority blocker into a repo-grounded decision surface.

This note is intentionally narrower than the broader deployment-authority documents. It focuses only on what the current repo already implements, what it still hard-codes, and which backend-direction choices fit that reality.

Companion notes:

Current Repo Facts

Direct inspection on 2026-04-15 shows:

  • all four active stacks still declare backend "http":
    • tofu/stacks/attic/backend.tf
    • tofu/stacks/arc-runners/backend.tf
    • tofu/stacks/gitlab-runners/backend.tf
    • tofu/stacks/runner-dashboard/backend.tf
  • the root Justfile now supports a generic init contract through TOFU_BACKEND_CONFIG_DIR, TOFU_BACKEND_CONFIG_FILE, or TF_HTTP_*, with just tofu-init-gitlab-legacy <stack> retained as the explicit GitLab compatibility path
  • the repo now includes config/backend.http.example.hcl as the concrete example for per-stack backend config files
  • the ARC deploy workflow now prefers explicit kubeconfig and backend-config secrets, with Civo and GitLab fallback retained for compatibility in .github/workflows/deploy-arc-runners.yml
  • three stack-local Justfiles are still legacy-current direct-stack helpers:
    • tofu/stacks/attic/Justfile
    • tofu/stacks/runner-dashboard/Justfile
    • tofu/stacks/gitlab-runners/Justfile
  • several secondary docs now label GitLab-backed state as compatibility, not as the preferred operator path:
    • docs/getting-started-guide.md
    • docs/infrastructure/overlay-creation.md
    • docs/ci-cd/overlay-pipelines.md
    • docs/guides/cross-forge-ci.md
  • the repo contains real object-storage and cache modules, including MinIO and tofu/modules/rustfs/, but none of those modules are wired into a non-HTTP OpenTofu backend in active stack code

What Is Actually Decided Already

These points are effectively settled by the current repo changes:

  • GitLab HTTP state is legacy-current, not the target operator story
  • the root local operator path is kubeconfig-first, not Civo-first
  • config/organization.yaml is the authoritative cluster_context source for the root Justfile path

That means the remaining backend decision is not whether to keep GitLab as the primary story. It is how to replace the remaining mixed-era surfaces with one non-legacy authority model.

Option Set

Option A: Standardize On A Generic HTTP Backend Contract

What it means:

  • keep backend "http" in the active stacks
  • make one backend config source authoritative for both local and CI paths
  • require both the root Justfile and any retained workflow automation to consume the same backend.hcl or the same TF_HTTP_* contract
  • remove or relabel the stack-local GitLab-specific Justfile recipes

Why it fits the current repo:

  • it matches the backend blocks already present in all active stacks
  • it matches the generic init path already implemented in the root Justfile
  • it avoids a new backend-family migration while the repo is still converging on one operator model

Inference from the current code:

  • this is the smallest viable convergence path because it preserves the existing backend type and only requires the repo to stop hard-coding GitLab as the default authority in local stack helpers, workflow automation, and secondary docs

Main cost:

  • the real backend authority still has to live outside the stack code
  • the repo would still need a concrete operator and CI packaging story for the shared backend config

Option B: Keep GitLab HTTP State As The Official Backend

What it means:

  • reverse the current local-first transition and continue treating GitLab project state as the intended primary path

Why it is a poor fit:

  • it conflicts with the current repo direction already encoded in the root Justfile, quick-start docs, and #169
  • it keeps GloriousFlywheel operationally dependent on a cross-forge authority even while the product is being reframed around GitHub ARC, local deployment, and tailnet-first operation

Inference from the current repo direction:

  • this option is effectively already rejected, even though some secondary surfaces still behave as if it were normal

Option C: Migrate To A New Backend Family

What it means:

  • replace backend "http" in the active stacks with another backend type
  • update local init, workflow automation, and documentation to match
  • define how local and CI credentials reach that backend

Why it is a bigger move:

  • no active stack currently implements a non-HTTP backend block
  • the root Justfile improvements made so far are still centered on generic HTTP backend initialization
  • stack-local helper surfaces and CI would all need another refactor pass

Inference from the current repo contents:

  • this is a legitimate later direction, especially because the repo already has object-storage-adjacent modules, but it is not the shortest path to deployment-authority convergence from the current codebase

Practical Recommendation

Recommended next step:

  • choose Option A first and standardize one generic HTTP backend authority contract across local and CI surfaces

Update from the live honey rollout on 2026-04-16:

  • Option A remains the supported current convergence path because it matches the active stack code
  • but it should now be treated as a transitional execution path rather than the declared target architecture
  • the post-#208 target family is narrowed in the companion note to environment-owned S3-compatible state on honey

Why:

  • it closes the main repo inconsistency without forcing a backend-family migration at the same time
  • it keeps #169 scoped to authority convergence instead of expanding it into a full backend redesign
  • it creates a cleaner boundary for any later move to a different backend family if the team still wants that after the repo is stable

Inference:

  • after Option A convergence, the repo will be in a much better position to evaluate whether a backend-family change is actually needed or whether the real problem was only GitLab/Civo hard-coding

Concrete Convergence Set

The first repo-owned cleanup set for Option A is now partially executed in repo. The remaining gap is narrower:

  • the repo still needs one real non-legacy backend authority to supply the preferred HTTP contract
  • the ARC deploy workflow still relies on legacy-civo.tfvars, so CI does not yet consume a fully local-first environment contract
  • the stack-local direct-stack helpers still carry GitLab compatibility logic even though they are now clearly labeled as secondary entrypoints

Exit condition for this backend-authority slice:

  • no active or default operator surface teaches GitLab project state as the normal deployment backend
  • the repo has exactly one primary init contract for both local and CI use, and that contract is backed by one real authority rather than placeholders

GloriousFlywheel