GloriousFlywheel Deployment Authority Decision 2026-04-15

Snapshot date: 2026-04-15

Purpose

Define the remaining critical-path decision that was originally captured inside #169 and TIN-128.

This document is GloriousFlywheel-only. It does not try to redesign adjacent repos. It only defines what this repo should treat as authoritative for:

• OpenTofu state authority
• Kubernetes access authority
• local versus CI deployment ownership
• the local-first dev and prod operating contract

Historical note:

• GitHub issue #169 closed on 2026-04-16
• this document remains the canonical repo-local decision note for the deployment-authority question until a new rollout issue is opened
• live GitHub rollout owner is now #208
• backend target-direction companion note: gloriousflywheel-backend-target-state-2026-04-16.md

Corrected On-Prem Cluster Truth

Authoritative target for the current on-prem deployment push:

• one Kubernetes cluster: honey
• primary context: honey
• primary kubeconfig: ~/.kube/kubeconfig-honey.yaml
• current API server: https://100.113.89.12:6443
• bumble and sting are node-role inputs inside honey, not separate clusters
• operator SSH and Kubernetes management should remain tailnet-first and private
• Kubernetes API should remain private and tailnet-only
• transitional cloud context tinyland-civo-dev remains residual compatibility only

Implication:

• GloriousFlywheel dev and prod are logical deployment environments
• they can both target honey
• bumble and sting belong in placement guidance, not cluster targeting

Repo-Grounded Current State

1. State Authority

Current implementation:

• all four active stacks still declare backend "http" in tofu/stacks/attic/backend.tf, tofu/stacks/arc-runners/backend.tf, tofu/stacks/gitlab-runners/backend.tf, and tofu/stacks/runner-dashboard/backend.tf
• the most detailed backend comments still describe GitLab managed state as the active collaboration model in tofu/stacks/attic/backend.tf
• root operator entrypoints still initialize that same GitLab HTTP backend in Justfile:228-260
• quick-start docs still tell operators to create .env, set TF_HTTP_PASSWORD, and run just tofu-init <stack> against the GitLab backend in docs/infrastructure/quick-start.md:83-97

Meaning:

• GitLab HTTP state is the only implemented backend authority today
• any local-first or RustFS-backed state story is still future intent, not current truth

2. Kubernetes Access Authority

Current implementation:

• the stacks already support explicit kubeconfig-driven access through k8s_config_path plus cluster_context
• tofu/stacks/arc-runners/main.tf, tofu/stacks/attic/main.tf, tofu/stacks/runner-dashboard/main.tf, and tofu/stacks/gitlab-runners/main.tf all set provider config_path from var.k8s_config_path when present
• the Attic stack comment explicitly says empty k8s_config_path falls back to KUBECONFIG

Meaning:

• the Terraform or OpenTofu layer is already capable of local kubeconfig-driven operation
• the current blockage is not provider capability; it is the operator workflow wrapped around it

3. Workflow And Example Drift

Current implementation:

• .github/workflows/deploy-arc-runners.yml is now explicitly a legacy-current compatibility workflow, but it still installs the Civo CLI, generates kubeconfig through civo kubernetes config, and initializes GitLab backend state with GITLAB_PAT
• tofu/stacks/arc-runners/legacy-civo.tfvars still encodes a Civo-era cluster name and remains the workflow-selected compatibility tfvars file
• docs/infrastructure/quick-start.md, Justfile, and config/organization.example.yaml now describe the target kubeconfig-first operator contract, while still retaining clearly labeled legacy-current compatibility paths where needed

Meaning:

• the repo still retains a legacy Civo-plus-GitLab CI workflow alongside a kubeconfig-capable local operator model
• that mixed model is the current execution blocker for #169

Decision

1. State Authority Decision

Decision:

• GloriousFlywheel should stop treating GitLab HTTP state as the target authority for its dev and prod stacks
• the target authority should be an environment-owned remote backend controlled by the GloriousFlywheel deployment environment, not by GitLab project state

Interpretation:

• this is a target decision, not a claim that migration is already complete
• until a replacement backend is implemented, GitLab HTTP state remains the current runtime truth and must be labeled as legacy-current, not future-state

Implementation direction:

• prefer a single backend family across stacks
• prefer a backend that can be operated from the same local-first environment as the target cluster
• do not require GitLab project ownership or GITLAB_PAT as the normal operator credential for GloriousFlywheel infrastructure
• for the current honey rollout, the target family is now narrowed further: environment-owned S3-compatible state on the local cluster once that backend is implemented, with current generic HTTP init kept as the transitional supported path

2. Kubernetes Access Decision

Decision:

• the primary operator path should be explicit kubeconfig plus cluster context
• k8s_config_path or ambient KUBECONFIG should be the first-class contract for local operators
• CI should only deploy if it consumes the same kubeconfig and context contract, not a separate Civo-specific bootstrap path

Interpretation:

• civo kubernetes config should not remain the primary deployment mechanism
• stack examples and operator docs should describe local or tailnet-reachable kubeconfig contexts instead of Civo-era context names
• the primary examples should now use honey
• docs should stop modeling bumble or sting as alternate cluster contexts

3. Deployment Ownership Decision

Decision:

• GloriousFlywheel dev and prod stack deployment should be local-first
• the root Justfile plus per-stack {env}.tfvars remains the right operator entry surface, but it needs to be reworked around the new backend and kubeconfig contract
• GitHub Actions deployment should be treated as secondary until it can operate with the same backend and kubeconfig authority as local operators

Interpretation:

• GitHub Actions can still validate, plan, or later apply, but it should not define a separate deployment truth model
• the repo should have one deployment contract, not one local contract and one CI-only contract

Historical Issue Ownership

#169 / TIN-128

Owns:

• backend authority across tofu/stacks/*/backend.tf
• operator init path in Justfile
• deployment workflow authority in .github/workflows/deploy-arc-runners.yml
• deployment guidance in docs/infrastructure/quick-start.md
• example environment and context shape in config/organization.example.yaml
• removal or reclassification of legacy-civo.tfvars as a primary deploy input

#167 / TIN-125

Does not own:

• backend migration
• kubeconfig source of truth
• local versus CI deployment authority

It still owns:

• cache endpoint and publication contract work
• Attic, Bazel, FlakeHub, and RustFS role definitions

Required Repo Changes Before Execution Can Claim Success

1. Write the target backend choice into stack and operator docs without pretending it is already migrated.
2. Refactor Justfile so tofu-init no longer assumes GitLab HTTP backend and TF_HTTP_PASSWORD.
3. Replace or demote .github/workflows/deploy-arc-runners.yml until it uses the same backend and kubeconfig contract as local operators.
4. Replace legacy-civo.tfvars as the primary ARC workflow input with environment tfvars that match the documented local-first path, or keep it explicitly classified as legacy compatibility only.
5. Rewrite quick-start guidance so backend authority and kubeconfig source are described explicitly and consistently.
6. Update configuration examples so cluster contexts are no longer GitLab-agent or Civo-default shaped in the primary path.
7. Rewrite primary operator docs so honey is the only physical cluster target and bumble or sting only appear as placement inputs.

Exit Criteria

The decision is only truly implemented when all of the following are true:

• operators can initialize and deploy stacks without GitLab-specific backend credentials as the default path
• stack docs and workflow automation use the same kubeconfig and context model
• no primary GloriousFlywheel deployment surface depends on Civo CLI bootstrap
• dev and prod deployment authority is described once and reused everywhere
• no primary deployment surface models bumble or sting as separate clusters

Deferred Until After This Decision

These are adjacent but should not block the decision itself:

• the final publication policy for FlakeHub and clean derivations
• the full tailnet-first operator auth model for dashboard and control-plane APIs
• ARC topology and multi-org enrollment refinements

Those belong primarily to #171, #172, and #170 after deployment authority is grounded.