↓ Skip to main content
  1. Runbook/
  2. GitOps/

GitOps Repository Structure

GitOps FluxCD Kustomize Repository Design Kubernetes

Time guide

  • Repository orientation: approximately 5 to 10 minutes
  • Planning a new component: approximately 15 to 30 minutes
  • Reviewing an existing layout: approximately 20 to 45 minutes

Purpose
#

This entry describes a practical GitOps repository structure that separates desired state, cluster registration, operational documentation and historical evidence.

The layout is intended to make changes easier to review, render, reconcile, troubleshoot and recover.

Recommended top-level structure#

apps/
clusters/
docs/
infrastructure/
monitoring/
networking/
security/

Use each area consistently:

  • apps/ contains application-specific Kubernetes resources.
  • clusters/ contains Flux entry points and cluster-level Kustomizations.
  • docs/ contains architecture, decisions, Runbooks and implementation evidence.
  • infrastructure/ contains shared platform components.
  • monitoring/ contains observability resources.
  • networking/ contains ingress, DNS and network-platform resources.
  • security/ contains security platforms, controls and detection content.

Application structure
#

A simple application can use:

apps/<application-name>/
├── namespace.yaml
├── deployment.yaml
├── service.yaml
├── ingress.yaml
└── kustomization.yaml

A Helm-managed application can use:

apps/<application-name>/
├── helmrepository.yaml
├── helmrelease.yaml
├── secret.enc.yaml
└── kustomization.yaml

Only include files that the application actually requires. Avoid empty placeholder files because they create false confidence that a component is fully documented or managed.

Cluster registration
#

Register applications and infrastructure through a cluster-specific directory:

clusters/<cluster-name>/
├── flux-system/
├── applications.yaml
├── infrastructure.yaml
└── kustomization.yaml

A component-level Flux Kustomization should identify:

  • The source
  • The repository path
  • The reconciliation interval
  • Pruning behaviour
  • Dependencies
  • Health checks where appropriate
  • SOPS decryption where encrypted resources are present

Standard change flow
#

  1. Edit the source manifests.
  2. Render the affected Kustomization locally.
  3. Review the Git diff.
  4. Scan staged content for plaintext secrets.
  5. Commit and push the change.
  6. Wait for Flux or trigger reconciliation.
  7. Validate Flux status and Kubernetes resources.
  8. Record reusable procedures or implementation evidence.

Render validation
#

Render a component before committing:

kubectl kustomize apps/<application-name>/ \
  > /tmp/<application-name>-rendered.yaml

Confirm output exists:

test -s /tmp/<application-name>-rendered.yaml

Review resource kinds:

grep '^kind:' /tmp/<application-name>-rendered.yaml

Run a client-side dry run:

kubectl apply \
  --dry-run=client \
  -f /tmp/<application-name>-rendered.yaml

Where appropriate, run a server-side dry run after confirming the cluster context:

kubectl apply \
  --server-side \
  --dry-run=server \
  -f /tmp/<application-name>-rendered.yaml

Remove the temporary render after review:

rm /tmp/<application-name>-rendered.yaml

Git review
#

Check the working tree:

git status --short

Review unstaged changes:

git diff

Review staged changes:

git diff --cached

Search for common secret indicators while excluding encrypted secret files:

grep -R -nEi \
  'password:|token:|api[_-]?key:|BEGIN .*PRIVATE KEY' . \
  --exclude-dir=.git \
  --exclude='*.enc.yaml'

Review every match manually. Documentation and environment-variable references can produce legitimate matches.

Reconciliation checks
#

flux get sources all -A
flux get kustomizations -A
flux get helmreleases -A
kubectl get pods -A

Documentation structure
#

docs/
├── architecture/
├── decisions/
├── phases/
├── runbooks/
├── service-catalogue/
└── disaster-recovery/

Use:

  • Architecture documents for current design.
  • Decision records for why a technology or pattern was selected.
  • Phase documents for historical implementation evidence.
  • Runbooks for reusable operations.
  • Service catalogue pages for ownership and dependencies.
  • Disaster-recovery documents for rebuild and restore procedures.

Safety notes
#

  • Never commit plaintext credentials.
  • Do not assume an encrypted file contains correct plaintext.
  • Preserve the final desired state in Git after an emergency direct change.
  • Treat rendered manifests as potentially sensitive.
  • Review pruning before reconciling a Kustomization.
  • Keep private keys and recovery credentials outside Git.

Related entries#

  • Flux Reconciliation Commands
  • Kustomize Render and Dry-Run Validation
  • SOPS and age Secret Workflow
  • Application GitOps Onboarding
  • GitOps Drift Investigation