Environments, Overlays, and the CI → Git Handoff

1. 1

   Move manifests into a base

   Move deployment.yaml, service.yaml, and the migrate Job into apps/web/base/ and list them in a kustomization.

   apiVersion: kustomize.config.k8s.io/v1beta1
   kind: Kustomization
   resources:
     - deployment.yaml
     - service.yaml
     - migrate-job.yaml
   labels:
     - pairs: { app.kubernetes.io/part-of: shoplite }

2. 2

   The dev overlay

   The images block is what CI will edit. newTag pins an immutable tag.

   apiVersion: kustomize.config.k8s.io/v1beta1
   kind: Kustomization
   namespace: shoplite-dev
   resources: [../../base]
   images:
     - name: nginxdemos/hello
       newTag: "0.4"
   patches:
     - target: { kind: Deployment, name: web }
       patch: |
         - op: add
           path: /spec/replicas
           value: 1

3. 3

   The prod overlay

   More replicas, bigger requests, a PodDisruptionBudget would go here too. Prod lags dev by one version until it's promoted.

   apiVersion: kustomize.config.k8s.io/v1beta1
   kind: Kustomization
   namespace: shoplite-prod
   resources: [../../base]
   images:
     - name: nginxdemos/hello
       newTag: "0.3"
   patches:
     - target: { kind: Deployment, name: web }
       patch: |
         - op: add
           path: /spec/replicas
           value: 3
         - op: replace
           path: /spec/template/spec/containers/0/resources/requests/cpu
           value: 250m

   terminalcopy cmd

   $ kustomize build apps/web/overlays/prod | grep -E 'namespace|replicas|image:|cpu'

   ── expected output ──

   namespace: shoplite-prod

   replicas: 3

   image: nginxdemos/hello:0.3

   cpu: 250m

4. 4

   Fence it with an AppProject

   ShopLite apps may only come from this repo and the Bitnami chart registry, only deploy to shoplite-* namespaces, and can't create cluster-scoped resources except Namespaces.

   apiVersion: argoproj.io/v1alpha1
   kind: AppProject
   metadata:
     name: shoplite
     namespace: argocd
   spec:
     description: ShopLite workloads
     sourceRepos:
       - https://github.com/<you>/shoplite-gitops.git
       - registry-1.docker.io/bitnamicharts
     destinations:
       - server: https://kubernetes.default.svc
         namespace: shoplite-*
     clusterResourceWhitelist:
       - group: ""
         kind: Namespace

5. 5

   One Application per environment

   Move the Applications into argocd/apps/. web-dev now points at apps/web/overlays/dev with project: shoplite. web-prod is the same with the prod overlay. Prod keeps selfHeal but you may leave prune off there at first, which is a common, cautious choice.

   apiVersion: argoproj.io/v1alpha1
   kind: Application
   metadata:
     name: web-prod
     namespace: argocd
   spec:
     project: shoplite
     source:
       repoURL: https://github.com/<you>/shoplite-gitops.git
       targetRevision: main
       path: apps/web/overlays/prod
     destination:
       server: https://kubernetes.default.svc
       namespace: shoplite-prod
     syncPolicy:
       automated: { prune: false, selfHeal: true }
       syncOptions: [CreateNamespace=true]

6. 6

   A third-party Helm chart, values in Git

   ShopLite's cart cache uses Redis. Argo renders the chart itself (helm template), so there's no Tiller and no helm install state: the Helm release doesn't show in helm list, and Argo tracks the resources instead. Pin targetRevision to an exact chart version. The Stateful Systems course covers running Redis properly.

   apiVersion: argoproj.io/v1alpha1
   kind: Application
   metadata:
     name: redis-dev
     namespace: argocd
   spec:
     project: shoplite
     source:
       repoURL: registry-1.docker.io/bitnamicharts
       chart: redis
       targetRevision: 22.0.7
       helm:
         valuesObject:
           architecture: standalone
           auth: { enabled: true, existingSecret: redis-auth }
           master:
             persistence: { size: 1Gi }
     destination:
       server: https://kubernetes.default.svc
       namespace: shoplite-dev
     syncPolicy:
       automated: { prune: true, selfHeal: true }

7. 7

   The root Application (app of apps)

   The root watches argocd/ recursively: projects and apps. From now on, the only thing you ever kubectl apply is this file, once per cluster. Delete the old Applications you applied by hand; the root recreates them from Git.

   apiVersion: argoproj.io/v1alpha1
   kind: Application
   metadata:
     name: root
     namespace: argocd
   spec:
     project: default
     source:
       repoURL: https://github.com/<you>/shoplite-gitops.git
       targetRevision: main
       path: argocd
       directory:
         recurse: true
         exclude: root.yaml
     destination:
       server: https://kubernetes.default.svc
       namespace: argocd
     syncPolicy:
       automated: { prune: true, selfHeal: true }

   terminalcopy cmd

   $ git add . && git commit -m 'kustomize overlays, project, app-of-apps' && git push

   kubectl apply -f argocd/root.yaml

   argocd app list

   ── expected output ──

   NAME CLUSTER NAMESPACE PROJECT STATUS HEALTH

   root https://kubernetes.default.svc argocd default Synced Healthy

   redis-dev https://kubernetes.default.svc shoplite-dev shoplite Synced Healthy

   web-dev https://kubernetes.default.svc shoplite-dev shoplite Synced Healthy

   web-prod https://kubernetes.default.svc shoplite-prod shoplite Synced Healthy

8. 8

   CI commits the tag instead of deploying

   The last job of the app repo's release workflow (CI/CD course, GitHub Actions). It uses a deploy key or GitHub App token with write access to ONLY the config repo, so there are no cluster credentials anywhere in CI. The commit message links back to the source commit for traceability.

     bump-dev:
       needs: build-and-push          # image shoplite-web:sha-${{ github.sha }} already pushed + signed
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v5
           with:
             repository: <you>/shoplite-gitops
             token: ${{ secrets.GITOPS_REPO_TOKEN }}
         - uses: imranismail/setup-kustomize@v2
         - name: Set dev image tag
           run: |
             cd apps/web/overlays/dev
             kustomize edit set image nginxdemos/hello=ghcr.io/<you>/shoplite-web:sha-${{ github.sha }}
             git config user.name "shoplite-ci"
             git config user.email "ci@shoplite.dev"
             git commit -am "web(dev): deploy ${{ github.sha }} from ${{ github.repository }}"
             git push

9. 9

   Promote to prod with a PR

   Promotion copies the tested tag from dev to prod. A branch-protection rule on main requires an approval for changes under apps/*/overlays/prod/ (CODEOWNERS), so deploys to prod get the same review as code (Git course, branch protection).

   terminalcopy cmd

   $ git switch -c promote-web-0.4

   cd apps/web/overlays/prod && kustomize edit set image nginxdemos/hello=nginxdemos/hello:0.4 && cd -

   git commit -am 'web(prod): promote 0.4' && git push -u origin promote-web-0.4

   gh pr create --fill --reviewer shoplite/platform

   ── expected output ──

   https://github.com/<you>/shoplite-gitops/pull/12

Make each change, run the command, and read the error before revealing the diagnosis. Recognising these messages on sight is what makes you fast on a real team. Undo the change afterwards.