Post

Reviewed Kubernetes GitOps monorepo layout for shared controller placement

Reviewed Kubernetes GitOps monorepo layout for shared controller placement

I reviewed the homelab’s Kubernetes GitOps monorepo layout to decide where shared cluster-wide controllers should live. The proposal keeps the existing single-cluster and Terragrunt structure while creating a consistent home for controllers consumed by multiple workloads.

Classifying shared controllers under platform

The new document docs/kubernetes-monorepo-layout-review.md proposes keeping the existing single-cluster layout and Terragrunt deployment roots. It suggests classifying shared controllers consistently under platform/, starting with cert-manager and External Secrets because their cluster-wide contracts are consumed by multiple workloads. Larger moves, including Istio and ingress, are left for separate dependency reviews.

Target structure and workload registration

The review outlines a target structure with .talos/ for node configuration, IaC/ for reusable provisioning and homelab environments, clusters/homelab/ for Argo CD self-management and platform components, and builds/ for image inputs. New workloads should be registered under IaC/homelab/us-west-2/apps/, with runtime sources placed alongside their manifests.

Linking the layout review to GitOps flow documentation

The wiki page openwiki/architecture/gitops-flow.md was updated to reference the monorepo layout review and note that it proposes folder boundaries and lists the paths a future move would affect. This connects the architectural review to the existing GitOps flow documentation.

Verification pending and platform reuse

No runtime verification is complete yet because this push is documentation only. The next check is to validate the proposed paths against an actual cert-manager or External Secrets move before committing the change. A platform team can use the same technique when they need to reorganize shared infrastructure without disrupting workload folders.

This post is licensed under CC BY 4.0 by the author.