Configuration Reference

Configuration Reference

The config/organization.yaml file is the central configuration source for a GloriousFlywheel deployment. It defines organization identity, logical deployment environments, namespace layout, and optional legacy compatibility inputs.

Schema

Top-Level Structure

organization:
  name: <string>
  full_name: <string>
  group_path: <string>

clusters:
  - name: <logical_env_name>
    role: <development|production|...>
    physical_cluster: <string>
    domain: <string>
    context: <string>
    kubeconfig_path: <string>

namespaces:
  attic:
    dev: <string>
    prod: <string>
  gitlab_runners:
    all: <string>
  arc_systems:
    all: <string>
  arc_runners:
    all: <string>
  dashboard:
    all: <string>

network:
  management_plane: <string>
  private_api_server: <string>
  magicdns_zone: <string>

nodes:
  honey:
    role: <string>
    tailscale_ip: <string>

legacy_compatibility:
  civo:
    context: <string>
    kubeconfig_path: <string>

gitlab:
  url: <string>
  project_id: <string>
  agent_group: <string>

organization

Field Type Description
name string Short organization or installation name
full_name string Human-readable organization name
group_path string Group or namespace path used by compatibility integrations

clusters[]

Each cluster entry names a logical deployment environment. Multiple logical environments can target the same physical cluster.

Field Type Description
name string Logical environment key such as dev or prod
role string Human meaning of the environment
physical_cluster string Underlying cluster identity, such as honey
domain string Base ingress domain for that logical environment
context string Kubeconfig context name, or a legacy GitLab Agent path if still needed
kubeconfig_path string Preferred kubeconfig path for local operators
api_server string Expected cluster API endpoint
management_plane string Access model, such as tailnet-private

Example:

clusters:
  - name: dev
    role: development
    physical_cluster: honey
    domain: dev.example.com
    context: honey
    kubeconfig_path: ~/.kube/kubeconfig-honey.yaml

  - name: prod
    role: production
    physical_cluster: honey
    domain: example.com
    context: honey
    kubeconfig_path: ~/.kube/kubeconfig-honey.yaml

namespaces

Namespace mappings consumed by stack tfvars, generated environment config, and operator docs.

For the current Tinyland honey rollout, the live cache runtime is in nix-cache. The schema still allows per-environment cache namespaces, but the current example config maps all logical environments to that one live cache namespace until the runtime shape changes.

Field Type Description
attic.dev, attic.prod string Cache namespace per logical environment
gitlab_runners.all string Legacy GitLab runner namespace
arc_systems.all string ARC controller namespace
arc_runners.all string ARC runner namespace
dashboard.all string Runner dashboard namespace

network

Field Type Description
management_plane string Access model such as tailnet-private
private_api_server string Private Kubernetes API endpoint
magicdns_zone string Tailnet MagicDNS suffix used by private services
proxy_host string or null Optional compatibility proxy host
proxy_port integer or null Optional compatibility proxy port

nodes

Optional node-role hints for placement and operator documentation.

Field Type Description
<node>.role string Human role label
<node>.tailscale_ip string Tailnet IP for operator access
<node>.placement_bias list of string Intended workload affinity hints

legacy_compatibility.civo (decommissioned April 2026)

Residual cloud compatibility only. The Civo cluster has been decommissioned. This block is retained for schema compatibility but should not be treated as a live deployment target.

gitlab

Field Type Description
url string GitLab base URL for compatibility integrations
project_id string Optional GitLab project ID for HTTP backend compatibility
agent_group string Optional GitLab Agent path for compatibility access

project_id is enough for legacy HTTP state compatibility. agent_group is only required when any cluster context uses GitLab Agent path syntax such as mygroup/kubernetes/agents:dev. Leave both empty if you are not using GitLab compatibility surfaces.

Example:

gitlab:
  url: https://gitlab.com
  project_id: ""
  agent_group: ""

Validation

scripts/validate-org-config.sh validates the config shape used by local workflows. It currently checks:

  • required organization and cluster fields are present
  • cluster contexts are either normal kubeconfig contexts like honey or legacy GitLab Agent paths
  • gitlab.project_id may be set on its own for legacy HTTP state compatibility
  • gitlab.agent_group becomes required only when cluster contexts use GitLab Agent path syntax

GloriousFlywheel