Opscraft
GitOps with Flux & Argo CD · Lesson 4 of 6 · 3 min read

Repository design and promotion

Typical layout (monorepo)

platform-gitops/
  clusters/
    dev-ap-south-1/       # flux-system + Kustomizations pointing below
    staging-ap-south-1/
    prod-ap-south-1/
  infrastructure/
    controllers/          # HelmReleases: aws-load-balancer-controller, cert-manager, external-secrets, karpenter...
    configs/              # ClusterIssuers, StorageClasses, policies
  apps/
    base/orders/
    dev/                  # overlays per environment
    staging/
    prod/
Enlarge diagramplatform-gitops/clusters/one folder per cluster: flux-system + entry Kustomizationsinfrastructure/controllers/HelmReleases: LB controller, cert-manager, ESO, Karpenterconfigs/ClusterIssuers, StorageClasses, policiesapps/base/orders/shared manifestsdev/ staging/ prod/overlays: tags, replicas, resources
Figure 1. A typical GitOps monorepo: per-cluster entry points, shared infrastructure, and apps with a base plus one overlay per environment.
Swipe sideways to see all of it, or tap to open it full screen.

Alternatives: repo per environment (strong access separation for prod), repo per team (apps) with the platform repo referencing them, or app config living in each service repo (simpler for teams, harder for platform-wide changes). Use directories, not branches, for environments — long-lived env branches drift and make merges painful.

Promotion

  • CI builds image orders:a1b2c3d, pushes to ECR, then opens a commit/PR changing apps/dev/orders tag.
  • Promotion to staging and prod = PRs changing the overlay tag (or a version in a shared file), with required reviews and checks for prod.
  • Or Flux image automation: ImageRepository scans ECR, ImagePolicy selects (semver range or a tag pattern with a timestamp/build number), ImageUpdateAutomation commits the change; markers in YAML tell it what to update:
image: 123456789012.dkr.ecr.ap-south-1.amazonaws.com/orders:a1b2c3d # {"$imagepolicy": "flux-system:orders"}

Typically automated for dev/staging, PR-based for prod. Pin images by digest for full immutability where needed.

Enlarge diagramCIpushesorders:a1b2c3dapps/devimage automationcommitsapps/stagingautomated or PRapps/prodPR + requiredreview
Figure 2. Promotion is a change in Git: the same image tag moves from dev to staging to prod, automatically for lower environments and by reviewed PR for prod.
Swipe sideways to see all of it, or tap to open it full screen.

Progressive delivery

Flagger (Flux) or Argo Rollouts add canary and blue/green with automated analysis: shift 10% → 25% → 50% traffic via the ingress/service mesh, query Prometheus for error rate and latency, promote or roll back automatically. The GitOps commit changes the version; the rollout controller manages the traffic shifting.

Enlarge diagram10%to canary25%to canary50%to canary100%to canarymetrics bad?error rate, latency →roll backEach step waits and checks Prometheus before moving on.
Figure 3. Progressive delivery with Flagger or Argo Rollouts: shift traffic in steps and let metrics decide whether to continue or roll back.
Swipe sideways to see all of it, or tap to open it full screen.