Environment Variables

This document lists the environment variables that shape the current GloriousFlywheel operator path.

Backend Initialization

Use one of these paths for just tofu-init <stack>.

The root entrypoint now follows the active backend family declared in each stack’s backend.tf. On current main, all four active stacks now use the environment-owned S3-compatible backend on honey.

Variable	Required	Description
`TOFU_BACKEND_CONFIG_FILE`	Preferred if set	Absolute path to one backend HCL file for the stack you are initializing.
`TOFU_BACKEND_CONFIG_DIR`	Preferred if set	Directory containing per-stack backend files named `<stack>-<env>.hcl`, for example `attic-dev.hcl`.
`TF_HTTP_ADDRESS`	Compatibility-only	State URL for a legacy generic HTTP backend path.
`TF_HTTP_LOCK_ADDRESS`	Compatibility-only	Lock URL for that same legacy HTTP backend path.
`TF_HTTP_UNLOCK_ADDRESS`	Compatibility-only	Unlock URL for that same legacy HTTP backend path.
`TF_HTTP_LOCK_METHOD`	No	Lock method for the HTTP backend. Commonly `POST`.
`TF_HTTP_UNLOCK_METHOD`	No	Unlock method for the HTTP backend. Commonly `DELETE`.
`TF_HTTP_USERNAME`	Compatibility-only	Username for a legacy generic HTTP backend path, or optional override for the GitLab legacy path.
`TF_HTTP_PASSWORD`	Compatibility-only	Password/token for a legacy generic HTTP backend path. Also used by the GitLab legacy path if you still use it.

If these values are already exported and you want to persist them into the local stack files, use:

just tofu-backend-materialize-http <stack>

Current note:

all four active stacks now use the live environment-owned S3-compatible state path on honey
TF_HTTP_* remains compatibility-only for legacy or archived HTTP backend repair paths
repo tooling can still scaffold and materialize backend files when you need a checked local operator default

S3-Compatible Cutover Preparation

These variables are the live init path for the four active stacks on current main, and they also let you write a local S3-compatible backend file as a checked operator default.

Once a stack actually uses backend "s3", the preferred root entrypoint just tofu-init <stack> can also consume these variables directly without first writing a checked-in backend file.

Variable	Required	Description
`TOFU_BACKEND_S3_ENDPOINT`	Yes	S3-compatible endpoint URL for the future environment-owned state authority.
`TOFU_BACKEND_S3_BUCKET`	Yes	Bucket that will own OpenTofu state.
`TOFU_BACKEND_S3_REGION`	No	Region string for the S3 backend. Defaults to `us-east-1`.
`TOFU_BACKEND_S3_ACCESS_KEY`	Yes	Access key for that S3-compatible state authority.
`TOFU_BACKEND_S3_SECRET_KEY`	Yes	Secret key for that S3-compatible state authority.
`TOFU_BACKEND_S3_KEY`	Sometimes	Exact object key to use when the stack/env does not have a locked canonical S3 key yet.
`TOFU_BACKEND_S3_KEY_PREFIX`	Fallback	Temporary prefix fallback used only when no canonical key is locked and no explicit `TOFU_BACKEND_S3_KEY` is set.
`TOFU_BACKEND_S3_USE_PATH_STYLE`	No	Path-style toggle written into the local backend file. Defaults to `true`.
`AWS_ACCESS_KEY_ID`	Fallback	Fallback for `TOFU_BACKEND_S3_ACCESS_KEY`.
`AWS_SECRET_ACCESS_KEY`	Fallback	Fallback for `TOFU_BACKEND_S3_SECRET_KEY`.

If these values are already exported and you want to persist them into the local stack files, use:

just tofu-backend-materialize-s3 <stack>

This writes config/backends/<stack>-<env>.hcl. For the four active stacks on current main, that file can be the live local default. For historical HTTP-family compatibility paths, materializing S3 values does not change the archived stack code by itself.

Current proven honey baseline key map 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

For any other environment or key layout, set TOFU_BACKEND_S3_KEY explicitly.

Legacy GitLab Compatibility

If you still use GitLab-managed HTTP state for an archived or external compatibility path, initialize with:

just tofu-init-gitlab-legacy <stack>

That path is compatibility-only and depends on gitlab.url and gitlab.project_id in config/organization.yaml. The four active main stacks now use backend "s3".

Local Operator Selection

Variable	Required	Description
`ENV`	No	Environment name used by root recipes. Defaults to `dev`.
`KUBE_CONTEXT`	No	Overrides the cluster context from `config/organization.yaml` for `tofu plan`, `tofu destroy`, and `tofu refresh`.
`HTTPS_PROXY`	Off-site only	SOCKS5 proxy URL when you must reach the cluster through a local proxy.
`GHCR_USERNAME`	Optional for `arc-runners`	Username for local `arc-runners` plan/refresh/destroy when `GHCR_TOKEN` is set and OpenTofu should create or rotate an explicitly configured GHCR pull secret.
`GHCR_TOKEN`	Optional for `arc-runners`	Token for local `arc-runners` plan/refresh/destroy when OpenTofu should create or rotate an explicitly configured GHCR pull secret. Public-image lanes can leave both unset.

Tofu Provider / Stack Inputs

Variable	Required	Description
`TF_VAR_gitlab_token`	GitLab surfaces only	GitLab provider token for legacy GitLab runner or dashboard integrations.
`TF_VAR_gitlab_oauth_client_id`	Dashboard auth path	GitLab OAuth application client ID for the dashboard.
`TF_VAR_gitlab_oauth_client_secret`	Dashboard auth path	GitLab OAuth application client secret for the dashboard.
`SESSION_SECRET`	Recommended for dashboard auth	Enables signed dashboard session cookies.
`PROXY_AUTH_DEFAULT_ROLE`	Tailnet/mTLS operator path	Default role for trusted proxy-header identities. Defaults to `operator`.
`AUTH_ADMIN_IDENTITIES`	Optional	Comma-separated usernames or emails that should resolve to `admin`.
`AUTH_OPERATOR_IDENTITIES`	Optional	Comma-separated usernames or emails that should resolve to `operator`.
`AUTH_VIEWER_IDENTITIES`	Optional	Comma-separated usernames or emails that should resolve to `viewer`.

Cache And Runner Runtime

Variable	Required	Description
`ATTIC_SERVER`	Nix runner path	URL of the Attic server used by Nix-capable runners.
`ATTIC_CACHE`	Nix runner path	Attic cache name used by those runners.

These are runtime hints for acceleration. They do not, by themselves, install Nix or imply any publication path.

Dashboard Runtime

The runner dashboard reads DASHBOARD_ variables at runtime.

Variable	Required	Description
`DASHBOARD_GITLAB_API_URL`	Compatibility control plane	Base GitLab API URL used by the dashboard’s compatibility mutation and pipeline surfaces.
`DASHBOARD_GITLAB_TOKEN`	Compatibility control plane	GitLab token used by the dashboard for compatibility runner and pipeline queries.
`DASHBOARD_GITLAB_GROUP_ID`	Compatibility control plane	GitLab group ID displayed by the dashboard for compatibility runner control.

Tailnet / Proxy Identity

When TRUST_PROXY_HEADERS=true, request auth now prefers trusted proxy identity headers over stored interactive sessions. That is the current tailnet-first operator contract.

Local Files That Matter

Item	Description
`.env`	Local environment file loaded by direnv.
`config/organization.yaml`	Cluster and namespace mapping used by the root `Justfile`.
`config/backend.http.example.hcl`	Template for generic HTTP backend config files.
`config/backend.s3.example.hcl`	Template for migration-prep S3-compatible backend files.
`tofu/stacks/<stack>/<env>.tfvars`	Per-stack per-environment OpenTofu inputs.