OpenTofu Modules

All reusable infrastructure modules live in tofu/modules/. Each module is designed to be composed by stack root configurations in tofu/stacks/.

There are 20 modules organized by function: runner infrastructure, cache platform, Kubernetes primitives, operators, and spoke-facing modules consumed by tinyland.dev spokes per tinyland-inc/site.scaffold/docs/CI-SCHEMA.md (private).

Runner Infrastructure

arc-controller

Deploys the GitHub Actions Runner Controller (ARC) via Helm chart. The controller watches for workflow_job webhook events and manages runner scale sets. update_strategy defaults to immediate (the upstream default, made explicit at the arc-runners stack call; TIN-2056): a runner-spec change recreates the listener and EphemeralRunnerSet at once and old-generation busy runners finish out, at the cost of a transient overprovision overlap. The historical eventual deviation waited on every running+pending runner before recreating either and deadlocked saturated scale sets (TIN-2055).

• Path: tofu/modules/arc-controller/
• Key variables: namespace, chart_version, image_pull_secrets, update_strategy
• Outputs: namespace, release_name, chart_version

arc-runner

Deploys a GitHub Actions runner scale set via ARC. Supports docker, dind, and nix runner types with scale-to-zero, plus additive lane overrides for placement, host-device mounts, and runner-container security context. Core stack usage should keep runner_label capability-shaped; owner-specific auth, tfvars values, and secondary-overlay registration names belong in implementation overlays.

• Path: tofu/modules/arc-runner/
• Key variables: runner_name, runner_label, runner_scale_set_name, runner_type, github_config_url, github_config_secret, min_runners, max_runners, bazel_cache_endpoint, bazel_executor_endpoint
• Outputs: release_name, runner_label, runner_scale_set_name, runner_type

gitlab-runner

Deploys a GitLab Runner via Helm chart with HPA support. Supports docker, dind, and nix runner types with configurable autoscaling, monitoring, and namespace-per-job isolation.

• Path: tofu/modules/gitlab-runner/
• Key variables: runner_token, runner_name, runner_type, runner_tags, hpa_enabled, hpa_min_replicas, hpa_max_replicas
• Outputs: release_name, runner_type, runner_tags, hpa_enabled

runner-dashboard

Deploys the SvelteKit runner dashboard with mixed-mode access auth, cross-forge monitoring, GitLab-backed compatibility mutation flows, and an optional Caddy sidecar proxy.

• Path: tofu/modules/runner-dashboard/
• Key variables: image, namespace, gitlab_oauth_client_id, gitlab_token, gitlab_group_id, gitlab_project_id, prometheus_url, runners_namespace, arc_namespaces, enable_caddy_proxy
• Outputs: deployment_name, service_endpoint, ingress_url

runner-cleanup

CronJob that reaps orphaned and stuck pods (Terminating, Completed, Failed) in the runner namespace. With runner_cleanup_zombie_reap_enabled it also deploys a second runner-zombie-reap CronJob backstop (TIN-2055) that mounts the same scripts/reap-idle-leaked-ephemeral-runners.sh the managed ARC apply runs and executes it with --stale-generation against every live AutoscalingRunnerSet — covering owner-overlay scale sets with zero overlay changes — so stale-generation zombie EphemeralRunners self-heal between applies. The listener-rollover deadlock this was built for is historical: the controller’s old eventual update strategy blocked listener recreation on those zombies; since TIN-2056 the controller runs immediate and the sweep degrades to a safe no-op backstop.

• Path: tofu/modules/runner-cleanup/
• Key variables: namespace, schedule, terminating_threshold_seconds, runner_cleanup_zombie_reap_enabled, zombie_reap_schedule, zombie_reap_min_age_seconds

runner-namespace-policy

Creates runner namespace admission policy: ResourceQuota for the aggregate machine envelope and LimitRange defaults for pods that omit container requests or limits. This is an in-namespace backstop for finite cluster capacity; it is not a global shared-label concurrency policy.

• Path: tofu/modules/runner-namespace-policy/
• Key variables: namespace, resource_quota_hard, container_default_request, container_default_limit
• Outputs: resource_quota_name, limit_range_name

runner-warm-pool

CronJob-based ARC warm-pool controller that toggles an AutoscalingRunnerSet minRunners value during scheduled windows.

• Path: tofu/modules/runner-warm-pool/
• Key variables: runner_name, autoscaling_runner_set_name, namespace, warm_min_runners, warm_schedule, cold_schedule
• Outputs: warmup_cronjob_name, cooldown_cronjob_name, service_account_name

Cache Platform

hpa-deployment

Generic HPA-enabled deployment module for stateless services with object storage backends. Used by the Attic cache API, and supports Ingress, TLS, Prometheus scraping, and topology spread.

• Path: tofu/modules/hpa-deployment/
• Key variables: name, namespace, image, container_port, enable_hpa, min_replicas, max_replicas, enable_ingress
• Outputs: deployment_name, service_endpoint, ingress_url, hpa_name

bazel-cache

Deploys bazel-remote cache server with an S3-compatible backend. Supports HPA autoscaling, Ingress, Prometheus metrics, and optional node selection for cluster placement.

• Path: tofu/modules/bazel-cache/
• Key variables: name, namespace, s3_endpoint, s3_bucket, s3_secret, max_cache_size_gb, node_selector
• Outputs: service_name, grpc_endpoint, http_endpoint, bazelrc_config

postgresql-cnpg

Production-grade PostgreSQL cluster using CloudNativePG with TLS, network policies, S3 backup, and high availability.

• Path: tofu/modules/postgresql-cnpg/
• Key variables: name, namespace, database_name, instances, storage_size, enable_backup
• Outputs: cluster_name, connection_string_rw, database_url, credentials_secret_name

Operators

cnpg-operator

Installs the CloudNativePG operator via Helm chart for managing PostgreSQL cluster CRDs.

• Path: tofu/modules/cnpg-operator/
• Key variables: namespace, chart_version, operator_replicas
• Outputs: namespace, operator_version

rustfs

Deploys RustFS S3-compatible object storage as a mirror/cache backend.

• Path: tofu/modules/rustfs/
• Key variables: namespace, volume_size, storage_class, statefulset_storage_class, deployment_enabled, deployment_existing_claim_name, service_selector_labels, bootstrap_job_ttl_seconds_after_finished
• Outputs: s3_endpoint, bucket_name

longhorn

Installs Longhorn via Helm for replicated Kubernetes block storage. This is a storage operator module, not the primary runner cache contract by itself.

• Path: tofu/modules/longhorn/
• Key variables: namespace, chart_version, set_default_class, default_replica_count, default_data_locality
• Outputs: namespace, chart_version, operator_ready, storage_class_name

tailscale-operator

Installs the Tailscale Kubernetes operator via Helm for tailnet-first service exposure and optional connector management.

• Path: tofu/modules/tailscale-operator/
• Key variables: namespace, oauth_client_id, oauth_client_secret, default_tags
• Outputs: namespace, chart_version, operator_ready, connector_name

DNS

dns-record

Reusable DNS record management supporting DreamHost API and external-dns annotation strategies.

• Path: tofu/modules/dns-record/
• Key variables: provider_type, domain, records
• Outputs: record_count, ingress_annotations

Spoke modules (consumed by tinyland.dev spokes)

These five modules are composed by every spoke spawned from tinyland-inc/site.scaffold via the spoke’s tofu/main.tf. They implement the §5–§7 contracts of docs/CI-SCHEMA.md in tinyland-inc/site.scaffold (private).

spoke-state-namespace

Allocates an S3-compatible bucket prefix spokes/<slug>/ for a spoke’s OpenTofu state plus an IAM role/policy permitting Blahaj’s env-reaper to enumerate and delete per-PR state objects under the prefix. Hard invariant: state authority is env-owned S3-compatible only. RustFS is valid for OpenTofu state only when it is the operator-selected state substrate for the environment; this does not promote RustFS to RBE CAS/action-cache authority.

• Path: tofu/modules/spoke-state-namespace/
• Key variables: spoke_slug, bucket_name, iam_role_name_prefix, reaper_principal_arn, create_reaper_iam
• Outputs: bucket, prefix, state_key_template, reaper_role_arn, reaper_policy_arn

spoke-dns-pr-env

Provisions the wildcard *.pr.<brand_domain> CNAME for per-PR ephemeral env DNS via external-dns annotations, plus optional stable per-lane CNAMEs for merge_main / release_tag lanes.

• Path: tofu/modules/spoke-dns-pr-env/
• Key variables: spoke_slug, brand_domain, lane_names, ingress_target, provider_type, zone_override, ttl
• Outputs: wildcard_fqdn, stable_lane_fqdns, zone, namespace

spoke-cache-quota

Declares Attic + Bazel cache quota for a single spoke via a labelled ConfigMap. The cache services themselves own enforcement; this module owns the declaration.

• Path: tofu/modules/spoke-cache-quota/
• Key variables: spoke_slug, cache_gib, ttl_days, eviction_policy, cache_services_namespace
• Outputs: attic_namespace, bazel_cache_prefix, configmap_name, configmap_namespace

spoke-runner-binding

Declares which capability-class runner labels a spoke may dispatch to. Hard-deny enforcement at the runner-pool ACL (default enforcement_mode = "deny"). Validates allowed_runner_classes against the master enum at plan time. The master enum is paired with site.scaffold/docs/schemas/lanes.schema.json (private) $defs/runnerClass.

• Path: tofu/modules/spoke-runner-binding/
• Key variables: spoke_slug, github_repository, allowed_runner_classes, enforcement_mode, runner_pool_namespace
• Outputs: runner_pool_label_set, configmap_name, configmap_namespace, enforcement_mode

spoke-blahaj-app-install

Binds a spoke’s GitHub repository to the Blahaj GitHub App installation. Materializes both sides of the dispatch-token contract: a Kubernetes Secret under the Blahaj namespace (consumed by the Blahaj webhook receiver) AND a GitHub Actions repository secret BLAHAJ_DISPATCH_TOKEN on the spoke repo (consumed by the spoke’s lane-dispatch composite action).

• Path: tofu/modules/spoke-blahaj-app-install/
• Key variables: spoke_slug, github_repository, installation_id, blahaj_namespace, create_github_secret
• Outputs: event_type, k8s_secret_name, k8s_secret_namespace, github_secret_name, installation_id (the generated dispatch token is intentionally NOT output)

Related

• Configuration Reference — organization.yaml schema
• Pipeline Overview — how modules are validated and deployed
• Environment Variables — variables consumed by stacks