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.
Choosing how to share manifests
Section titled “Choosing how to share manifests”Three approaches cover most teams.
| Approach | How environments differ | Strength | Watch out for |
|---|---|---|---|
| Plain YAML per environment | Separate copies of every file | Nothing to learn, easy to read | Copies drift. Fine for one or two small workloads |
| Kustomize base and overlays | Overlays patch a shared base | No templating language, output is plain YAML, diffs are small | Patches can become hard to follow when stacked deeply |
| Helm chart with values files | One values file per environment feeds a template | Packaging, versioning, and a large public chart ecosystem | Templates 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.
A layout for several environments
Section titled “A layout for several environments”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.yamlDirectories 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
Section titled “The base”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.
apiVersion: apps/v1kind: Deploymentmetadata: name: catalog-api labels: app.kubernetes.io/name: catalog-api app.kubernetes.io/part-of: shopspec: 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]apiVersion: kustomize.config.k8s.io/v1beta1kind: Kustomizationresources:- deployment.yaml- service.yaml- pdb.yamlAn overlay
Section titled “An overlay”An overlay names the base and states only what changes:
apiVersion: kustomize.config.k8s.io/v1beta1kind: Kustomizationnamespace: catalogresources:- ../../baseimages:- name: registry.example.com/shop/catalog-api newTag: 1.4.2 # the only line a release changesreplicas:- name: catalog-api count: 4patches:- target: kind: Deployment name: catalog-api patch: |- - op: replace path: /spec/template/spec/containers/0/resources/limits/memory value: 512MiPreview the result before committing it:
kubectl kustomize apps/catalog-api/overlays/prodConventions that pay off
Section titled “Conventions that pay off”Use the recommended labels on every object. Tools and dashboards group workloads by them.
| Label | Meaning | Example |
|---|---|---|
app.kubernetes.io/name | The application | catalog-api |
app.kubernetes.io/instance | The instance of it | catalog-api-prod |
app.kubernetes.io/version | The deployed version | 1.4.2 |
app.kubernetes.io/component | The role inside the application | database |
app.kubernetes.io/part-of | The larger system | shop |
- One namespace per application per environment, or one per team, but not a shared
default. - Pin image tags or digests. A
latesttag 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.
Promoting between environments
Section titled “Promoting between environments”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.
Handing off to GitOps
Section titled “Handing off to GitOps”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/v1alpha1kind: Applicationmetadata: name: catalog-api-prod namespace: argocdspec: 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: trueArgo CD finds the kustomization.yaml, renders the overlay, compares the result with the cluster, and keeps them equal.