Skip to content
Documentation Background

Application organisation and GitOps

A single kubectl apply -f deployment.yaml works for one workload in one cluster. Real applications run in several environments, with the same shape and a few different values: replica counts, resource limits, hostnames, image tags. How those manifests are organised decides whether the differences stay small and visible or turn into copies that drift apart.

This page covers the organisation of the manifests. Delivering them from Git to the cluster is the job of a GitOps controller, covered in the GitOps section.


Three approaches cover most teams.

ApproachHow environments differStrengthWatch out for
Plain YAML per environmentSeparate copies of every fileNothing to learn, easy to readCopies drift. Fine for one or two small workloads
Kustomize base and overlaysOverlays patch a shared baseNo templating language, output is plain YAML, diffs are smallPatches can become hard to follow when stacked deeply
Helm chart with values filesOne values file per environment feeds a templatePackaging, versioning, and a large public chart ecosystemTemplates are harder to review than plain YAML

A common split: Kustomize for the applications a team writes itself, and Helm for third-party software such as cert-manager or an ingress controller, with the environment’s values kept in Git.


Keep deployment configuration in its own repository, separate from application source, and give each environment a directory:

deploy-config/
├── apps/
│ └── catalog-api/
│ ├── base/
│ │ ├── kustomization.yaml
│ │ ├── deployment.yaml
│ │ ├── service.yaml
│ │ └── pdb.yaml
│ └── overlays/
│ ├── staging/
│ │ └── kustomization.yaml
│ └── prod/
│ └── kustomization.yaml
└── platform/
└── cert-manager/
├── values-staging.yaml
└── values-prod.yaml

Directories beat long-lived branches because every environment is visible in one checkout, and a change to the base is one commit instead of a merge per branch.

The base holds everything that is the same everywhere, and it is written to production standards from the start: resource requests and limits, probes, a restricted security context, and a disruption budget.

apps/catalog-api/base/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: catalog-api
labels:
app.kubernetes.io/name: catalog-api
app.kubernetes.io/part-of: shop
spec:
replicas: 2
selector:
matchLabels:
app.kubernetes.io/name: catalog-api
template:
metadata:
labels:
app.kubernetes.io/name: catalog-api
app.kubernetes.io/part-of: shop
spec:
securityContext:
runAsNonRoot: true
seccompProfile:
type: RuntimeDefault
containers:
- name: api
image: registry.example.com/shop/catalog-api:1.4.2
ports:
- containerPort: 8080
resources:
requests: { cpu: 100m, memory: 128Mi }
limits: { memory: 256Mi }
readinessProbe:
httpGet: { path: /healthz/ready, port: 8080 }
livenessProbe:
httpGet: { path: /healthz/live, port: 8080 }
securityContext:
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
capabilities:
drop: [ALL]
apps/catalog-api/base/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- deployment.yaml
- service.yaml
- pdb.yaml

An overlay names the base and states only what changes:

apps/catalog-api/overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: catalog
resources:
- ../../base
images:
- name: registry.example.com/shop/catalog-api
newTag: 1.4.2 # the only line a release changes
replicas:
- name: catalog-api
count: 4
patches:
- target:
kind: Deployment
name: catalog-api
patch: |-
- op: replace
path: /spec/template/spec/containers/0/resources/limits/memory
value: 512Mi

Preview the result before committing it:

Terminal window
kubectl kustomize apps/catalog-api/overlays/prod

Use the recommended labels on every object. Tools and dashboards group workloads by them.

LabelMeaningExample
app.kubernetes.io/nameThe applicationcatalog-api
app.kubernetes.io/instanceThe instance of itcatalog-api-prod
app.kubernetes.io/versionThe deployed version1.4.2
app.kubernetes.io/componentThe role inside the applicationdatabase
app.kubernetes.io/part-ofThe larger systemshop
  • One namespace per application per environment, or one per team, but not a shared default.
  • Pin image tags or digests. A latest tag makes the manifest in Git say nothing about what runs.
  • Keep secrets out of the repository. Commit a reference to an external secret store, or an encrypted form.

With this layout a release is a small commit. The pipeline that builds catalog-api:1.4.3 opens a pull request that changes newTag in the staging overlay. Once staging is verified, a second pull request changes it in the prod overlay. Review, approval, and history come from Git, and a rollback is reverting the commit.


Without a controller, someone or something still has to run kubectl apply -k for each environment, and nothing notices when the cluster later changes by hand. A GitOps controller closes that gap. In Argo CD, the prod overlay becomes the source of one Application:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: catalog-api-prod
namespace: argocd
spec:
project: shop
source:
repoURL: https://git.example.com/shop/deploy-config.git
targetRevision: main
path: apps/catalog-api/overlays/prod
destination:
name: prod-eu
namespace: catalog
syncPolicy:
automated:
prune: true
selfHeal: true

Argo CD finds the kustomization.yaml, renders the overlay, compares the result with the cluster, and keeps them equal.