This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Specifications

1 - Infra flux

1.1 - Flux infrastructure specification

Describe the Flux management cluster’s VM definition, K3s configuration, and Git reconciliation entry points owned by infra/flux. The tf_setup, ansible, and cl packages implement stages of this owner. This is a checked-in source baseline; no cluster health or successful deployment was observed for this specification.

Baseline revision: 550d7e79b1f5fdbc2b6017b75178471d6914082f. Observed: 2026-09-08. Sources: owner README, BUILD, and the implementation links below.

Terraform setup SHALL declare a Proxmox VM in the src_infra_flux pool with two cores, 4096 MiB memory, and separate 20 GiB boot, K3s data, and K3s storage disks. The deployment playbook SHALL apply the shared host and K3s roles, and the K3s configuration SHALL enable secrets encryption and disable the bundled Traefik component.

Sources: VM definition, deployment playbook, and K3s configuration.

  • WHEN a maintainer evaluates the setup and deployment source
  • THEN VM provisioning, host configuration, and K3s configuration are separate stages with the recorded compute and disk allocation
  • AND the K3s configuration enables secrets encryption at rest

The cluster’s root Kustomization SHALL include the Flux and Harbor reconciliation trees. Flux’s reconciliation resources SHALL read the flux-git-src GitRepository and use SOPS decryption through flux-sops-secret, with pruning enabled and forced replacement disabled. The Harbor tree SHALL include its remote-cluster configuration and Harbor’s Flux manifests.

Sources: root Kustomization, Flux reconciliation, and Harbor reconciliation tree.

  • WHEN the checked-in root Kustomization is traversed
  • THEN both src-infra-flux-cl and src-infra-harbor-cl are included
  • AND the Flux reconciliation resources retain their Git source, decryption reference, and explicit prune and force settings

The cluster package SHALL provide repository-configured Flux, Flux operator, kubectl, Helm, certificate-manager, and SOPS command wrappers. Its Flux instance SHALL declare source, Kustomize, Helm, notification, image-reflector, image-automation, and source-watcher controllers, with network policy enabled.

Sources: cluster BUILD and Flux instance.

Scenario: Select a repository operator entry point

  • WHEN an operator selects a declared cluster command target
  • THEN the target supplies the packaged tool and the Flux owner’s al configuration
  • AND the controller source records the enabled components without asserting that they are currently available in a live cluster

2 - Owned dns

2.1 - owned-dns Specification

Define Flux DNS management through the owner’s tf_setup root, including canonical declarations, scoped credentials, and offline source checks before adopting live records.

The tf_setup root SHALL consume this owner’s canonical dnsconfig.json through the shared DNS Terraform module, preserving declared record identities and views. DNS resources SHALL default to disabled before adoption and SHALL remain enabled by default after authorized adoption. Adoption SHALL bind existing provider records to the owner’s state without adding, changing, replacing, or deleting DNS records. Subsequent reconciliation of unchanged declarations SHALL preserve owned and unrelated records.

  • WHEN the checked-in root is evaluated with default inputs before adoption
  • THEN it reads this owner’s declaration and disables managed DNS records
  • AND the package contains the module and declaration inputs
  • WHEN the adopted root is evaluated with default inputs
  • THEN it reads this owner’s declaration and enables managed DNS records
  • AND the package contains the module and declaration inputs
  • WHEN the owner applies a reviewed saved import plan through //infra/flux/tf_setup:dns.apply
  • THEN the owner state binds each declared record to its existing provider identity
  • AND the reviewed adoption plan proposes no record additions, changes, replacements, or deletions
  • WHEN the adopted root plans and applies unchanged declarations through its //infra/flux/tf_setup wrappers
  • THEN it makes no DNS resource changes
  • AND owned records retain their declared values and views while unrelated records remain unchanged

The DNS wrappers SHALL select src_infra_flux through the repository AL flow and keep secret values in injected variables. The dns.plan, dns.show, and dns.apply targets SHALL select dns=1 and retain the owner’s setup backend; plans SHALL target module.dns and apply SHALL require a reviewed saved plan. Ordinary setup wrappers SHALL retain their service authentication behavior. Real DNS credentials and Vault policy grants SHALL be prerequisites for operational Terraform calls. RouterOS DNS credentials SHALL remain isolated from unrelated RouterOS resources. The package SHALL expose a format test without live credentials. DNS-targeted validation SHALL NOT establish unrelated VM or service health.

  • WHEN the package format test executes
  • THEN it checks the packaged Terraform configuration without live credentials
  • AND existing non-DNS authentication and backend paths remain unchanged
  • WHEN an authorized operator selects the owner’s DNS wrapper
  • THEN it selects DNS credential injection through the owner AppRole and setup backend
  • AND its scoped plan and saved-plan apply cover DNS and its dependencies
  • AND disabled DNS resources do not imply offline provider configuration