GloriousFlywheel Backend Target State 2026-04-16

GloriousFlywheel Backend Target State 2026-04-16

Snapshot date: 2026-04-16

Historical rollout owner: #208

Purpose

Turn the remaining backend-authority blocker into an explicit target-state note for the current honey rollout.

This note answers a narrower question than the broader deployment-authority docs:

  • what backend path the repo supports today
  • what backend family the on-prem rollout should converge toward
  • what operators should and should not infer from the current HTTP examples

Current Repo Truth

From direct repo inspection:

  • all four active stacks still declare backend "http"
  • the root Justfile supports backend init via:
    • TOFU_BACKEND_CONFIG_FILE
    • TOFU_BACKEND_CONFIG_DIR
    • TF_HTTP_*
  • config/backend.http.example.hcl is the current concrete bootstrap example
  • just tofu-init-gitlab-legacy <stack> remains the explicit GitLab compatibility path

Meaning:

  • the current implemented init surface is generic HTTP
  • GitLab-managed HTTP state is no longer the preferred story, but it still survives as a compatibility path
  • the repo does not yet implement an S3-style backend block in active stack code

Legacy GitLab Discovery Reality

Targeted GitLab discovery on 2026-04-16 did turn up one real compatibility surface:

  • archived tinyland/gf-overlay (project_id 79706605) is the current legacy GitLab state owner that still answers for this repo
  • attic-dev exists there
  • arc-runners-dev exists there
  • runner-dashboard-dev does not exist there
  • gitlab-runners-dev does not exist there

Meaning:

  • this checkout now has a confirmed legacy GitLab state owner for part of the repo
  • the surviving legacy state surface is partial, not comprehensive
  • the legacy GitLab materialization path can produce truthful local plans for attic and arc-runners
  • archived gf-overlay is still compatibility only, not a durable target backend authority for GloriousFlywheel

Current local convergence read from that surviving state:

  • ENV=dev just tofu-preflight arc-runners passes
  • ENV=dev just tofu-init arc-runners passes against 79706605
  • ENV=dev just tofu-plan arc-runners now yields a real 1 to add, 5 to change plan instead of a fake greenfield create
  • that plan creates tinyland-nix-heavy, restores repo-owned cache env to the baseline Nix and Docker lanes, and no longer tries to recreate Longhorn or downgrade live ARC back to 0.13.1
  • ARC on honey currently does not use imagePullSecrets on the baseline lanes, so the repo now stops assuming a pull secret by default
  • the remaining extra in-place churn is the cleanup of stale imagePullSecrets values still recorded in Helm release state even though the live ARC specs no longer use them
  • GHCR_USERNAME / GHCR_TOKEN are only needed when the operator explicitly wants OpenTofu to create or rotate a GHCR pull secret

Current On-Prem Runtime Truth

From the live honey validation and adjacent local-cluster planning:

  • honey is the only physical cluster target
  • bumble is the durable storage-aligned worker inside that cluster
  • the live cache runtime already exists on honey in namespace nix-cache
  • the local-cluster planning surface in ../blahaj already tracks later replacement of transitional GitLab-backed state with RustFS-backed S3-compatible state once the local cluster is stable
  • ../blahaj explicitly treats that RustFS-backed S3 backend as post-baseline work, not as a prerequisite that is already live
  • ../blahaj also keeps historical tofu-state/ out of the live cache object store until a separate backend lane is chosen on purpose

Inference:

  • the post-#208 backend direction should be environment-owned S3-compatible state on the local honey environment
  • durable backend data should bias toward bumble, not toward new Civo-owned state
  • this is a target direction derived from the adjacent cluster program and live runtime posture, not a claim that migration is already complete in this repo

Decision For Primary Docs

Primary GloriousFlywheel docs should now say all three of these things at once:

  1. the current supported init path is generic HTTP backend config
  2. GitLab HTTP state is compatibility only
  3. the target backend family is environment-owned S3-compatible state on honey, likely backed by the local RustFS storage direction once that path is implemented

That keeps the repo honest without pretending the migration is finished.

What Operators Should Do Today

For current local work:

  • keep using TOFU_BACKEND_CONFIG_FILE, TOFU_BACKEND_CONFIG_DIR, or TF_HTTP_* because that is what the repo actually supports today
  • treat config/backend.http.example.hcl as a transitional bootstrap example
  • keep just tofu-init-gitlab-legacy <stack> only for true legacy compatibility cases
  • do not assume Civo is the long-term authority for state
  • do not assume the HTTP example endpoints are the final steady-state model

What Is Still Missing

The repo still does not have:

  • a concrete non-legacy backend endpoint committed into local operator config
  • an S3-style backend block implemented in active stack code
  • a checked-in local config/organization.yaml
  • a checked-in local backend config file under config/backends/
  • a live non-legacy backend that covers all four active stacks
  • a live RustFS-backed tofu-state lane that operators can safely target today

So a real local apply is still blocked in this checkout even though cluster reachability is working. The blocker is no longer “find any legacy state owner at all”; it is deciding what to do with a partial archived legacy state surface while the repo converges toward a non-legacy backend.

Cutover Prerequisites

There is one important implementation boundary to keep explicit:

  • OpenTofu backend family is fixed in stack configuration
  • the current stacks declare backend "http"
  • that means a future S3-compatible cutover cannot be achieved only by adding a new backend HCL example or changing environment variables

Practical consequence:

  • backend-family migration will require coordinated edits across every active stack backend.tf
  • root init docs and helper output will need to change at the same time
  • CI compatibility flows will need the same backend-family cutover, not just local operators

That is why the current repo work should distinguish:

  1. honest current HTTP-path cleanup
  2. target-direction documentation
  3. later backend-family migration once a real local S3 endpoint and bucket contract exist

Current Non-Goal

This repo should not yet:

  • pretend a RustFS-backed tofu-state bucket already exists live on honey
  • imply that current HTTP backend examples can be swapped to S3 without stack code changes
  • merge cache/object-store historical state import decisions into the immediate GloriousFlywheel local-apply path

Exit Condition

This target-state note is only fully implemented when:

  • local and CI paths converge on one non-legacy backend authority
  • that authority is owned by the local honey environment rather than GitLab project state
  • primary docs no longer make generic HTTP sound like the architectural destination

GloriousFlywheel