The architecture decision — when each model fits

The four models in this part - two-repo, monorepo with overlays, multi-repo per environment, and the Source Hydrator / mirror pattern - are not alternatives to be picked by taste. They are answers to specific questions about the team, the regulatory regime, the supply-chain posture, and the cluster topology. The wrong model is expensive to operate and expensive to migrate away from. This lesson is the decision matrix that picks the right model and the migration cost of switching.

The four inputs

The decision matrix has four inputs. Each input is a characteristic of the team or the environment, not a preference.

flowchart TD
    A["Team size and trust boundary"] --> D["Decision"]
    B["Regulatory regime"] --> D
    C["Supply-chain posture"] --> D
    E["Cluster topology and tenancy"] --> D
    D --> M1["Two-repo"]
    D --> M2["Monorepo with overlays"]
    D --> M3["Multi-repo per environment"]
    D --> M4["Source Hydrator / mirror"]

• Team size and trust boundary. A single team writes the application and owns the cluster. Two teams collaborate, with different review rights. Three or more teams, with separate production ownership.
• Regulatory regime. Unregulated. Lightly regulated (SOC 2). Heavily regulated (PCI-DSS, HIPAA, FedRAMP). Each regime imposes different collocation rules.
• Supply-chain posture. Tags are trusted. Digests are pinned. Artifacts are signed. Provenance is attested.
• Cluster topology. Single cluster, shared tenancy. Multiple clusters, shared tenancy. Multi-tenant clusters with per-tenant isolation. Air-gapped clusters.

The decision matrix

The four models map to the four inputs as follows:

The two-repo model is the right default for a single team with no heavy regulatory regime. The two-repo split is the simplest implementation of the trust boundary that an infrastructure team needs, and it scales to two teams as long as the codebase is small.

The monorepo with overlays is the right default when the team size and the topology are both small, and the regulatory regime is light. The single-source-of-truth model is the cleanest for audit, and the overlay-by-overlay promotion is the cleanest for release management. The model fails when the team grows or the regulation tightens.

The multi-repo per environment is the right default when the regulatory regime forbids collocation (PCI-DSS, FedRAMP), or when the team boundaries are sharp (separate SRE, separate platform, separate application teams). The cost is duplicated CI bots and per-environment promotion; the benefit is Git-host enforced isolation.

The Source Hydrator and the mirror pattern is the right default when the supply-chain posture is strong (signing, attestation, provenance) and the cluster topology is segmented (air-gapped, multi-tenant, multi-region). The hydrator is the trust boundary between CI and the cluster, and the generated repo is the controller’s source. The pattern is the strongest GitOps shape available; it is also the most expensive to operate.

The decision document

The decision matrix is the input. The decision document is the output. The decision document is a single page in the team’s runbook that names the model, the reasons for choosing it, and the migration path to the next model if the inputs change.

A canonical decision document for the two-repo model:

The team has chosen the two-repo pattern for the payment-api service. The application repo is github.com/example/payment-api. The environment repo is github.com/example/env-prod. Reasons: the team is two engineers with shared review rights; the regulatory regime is SOC 2; the supply-chain posture is digest-pinned; the cluster topology is a single EKS cluster. Migration path: if the regulatory regime changes to PCI-DSS, migrate to the multi-repo per environment model.

The decision document is not optional. Without it, the next engineer who joins the team will look at the repos and ask “why two?” and the answer will be “because that’s how it’s always been.” The decision document is the team contract that survives the team.

Under the hood

The repository architecture decision is upstream of every other choice in the GitOps design. The CI pipeline architecture, the controller architecture, the secret management architecture, and the audit architecture all depend on the repository architecture. Choosing the model early keeps the downstream choices consistent; choosing the model late forces a migration.

The decision is also upstream of the team’s hiring and onboarding. A team that uses the monorepo with overlays hires engineers who are comfortable with Git, Kustomize, and basic controller operation. A team that uses the multi-repo per environment model hires engineers who are also comfortable with Git host administration, per-repo CI bot management, and the operational footprint of multiple controllers. The repository architecture is, in part, a statement about the team’s operational maturity.

Production discipline

The production rules for the architecture decision:

1. The decision is documented. The decision document is in the team’s runbook, with the chosen model, the inputs, and the migration path. The document is reviewed at every quarterly platform review.
2. The decision is consistent across services. All services in the same regulatory regime use the same model. Mixing models per service multiplies the operational cost and the training cost.
3. The migration path is rehearsed. The team knows what the next model is and what the migration looks like. The migration is not a scramble; it is a planned change.

Cross-course references

• Git, CI/CD & GitOps for Infrastructure Engineers - Parts LXXVI-01 through LXXVI-05 are the four models this lesson decides between. Part LXXVIII (Migration) is the next part, covering how to migrate from one model to another.
• Kubernetes for Production Sysadmins - Part XXVI (Cluster Topology) covers the topology input in the matrix.
• Terraform for Production Sysadmins - Part XXIX (Compliance) covers the regulatory input in the matrix.

Quiz