gitops-deploy-workflow

name	gitops-deploy-workflow
description	Sets up GitOps delivery with ArgoCD or Flux CD — declarative app definitions, app-of-apps/Kustomize overlays, sync policies, progressive delivery (canary/blue-green), and drift reconciliation. Triggers when configuring ArgoCD/Flux, structuring a GitOps repo, or debugging out-of-sync/drift.
when_to_use	ตั้ง/แก้ ArgoCD หรือ Flux, จัดโครง GitOps repo, app out-of-sync/drift, ทำ progressive delivery

When to Use

• ตั้งหรือแก้ ArgoCD / Flux CD ครั้งแรก หรือ refactor โครง GitOps repo
• App ค้าง OutOfSync / Degraded หรือ manifest จริงใน cluster ถูกแก้มือ (drift)
• เพิ่ม env ใหม่ (dev/staging/prod) หรือ wire promotion path
• ทำ progressive delivery (canary / blue-green) แทน rolling update ตรงๆ

SKIP ถ้าเป็น push-based CI deploy (kubectl apply ใน pipeline) — นั่นไม่ใช่ GitOps, อย่าฝืนใส่ controller

Steps

1. เลือก controller + วาง repo layout ก่อนเขียน manifest แรก

	ArgoCD	Flux CD
Source of truth	Application CRD	Kustomization + GitRepository CRD
UI	มี (web)	ไม่มี (CLI flux)
เหมาะกับ	ทีมที่อยาก see/diff ใน UI	GitOps-native, multi-tenant, น้อย human

โครง repo แยก config ออกจาก app source (คนละ repo หรืออย่างน้อยคนละ dir). Per-env overlay ด้วย Kustomize:

clusters/<cluster>/        # bootstrap: app-of-apps หรือ Flux Kustomization root
apps/<app>/base/           # kustomization.yaml + deployment/service/hpa
apps/<app>/overlays/dev/   # patch image tag, replicas, resources
apps/<app>/overlays/staging/
apps/<app>/overlays/prod/

ห้าม copy-paste manifest เต็มต่อ env — base + patchesStrategicMerge เท่านั้น. env ต่างกันที่ image tag / replicas / resource / ingress host

2. App-of-apps (ArgoCD) — root Application ชี้ไปยังโฟลเดอร์ที่มี child Applications

• Root Application.spec.source.path → dir ที่มี Application manifest ของแต่ละ app
• Child Application แต่ละตัวชี้ overlay ของ env นั้น (overlays/prod)
• ได้ bootstrap ทั้ง cluster ด้วย kubectl apply -f root-app.yaml ครั้งเดียว
• Flux เทียบเท่า: root Kustomization ชี้ clusters/<cluster>/ ที่มี child Kustomization per app

3. Sync policy — เปิด automation แบบมี guard

• ArgoCD syncPolicy.automated: prune: true (ลบ resource ที่หายจาก Git), selfHeal: true (revert drift ใน cluster), syncOptions: [CreateNamespace=true]
• prod ที่ต้อง gate → ใช้ manual sync หรือ sync window แทน auto, อย่าเปิด selfHeal ถ้ายังมีคนแก้มือเป็นปกติ (จะตีกัน)
• Flux: Kustomization.spec.prune: true + interval: 1m + wait: true (รอ health ก่อนถือว่าสำเร็จ)
• ใส่ ignoreDifferences สำหรับ field ที่ controller อื่นเขียน (HPA แก้ replicas, webhook inject sidecar) ไม่งั้น OutOfSync ตลอด

4. Env promotion path: dev → staging → prod

• Promote = เปลี่ยน image tag ใน overlay ของ env ถัดไป ผ่าน Git commit/PR (ไม่ใช่ kubectl set image)
• ใช้ digest pinning (@sha256:...) ไม่ใช่ mutable tag เช่น latest — กัน drift เงียบเมื่อ tag ถูก repush
• Auto image update: ArgoCD Image Updater หรือ Flux ImagePolicy + ImageUpdateAutomation เขียน tag ใหม่กลับ Git ให้ (write-back ต้องมี deploy key/PAT แบบ write)
• prod ผ่าน PR + required review เสมอ; dev auto-promote ได้

5. Progressive delivery — แทน rolling update

• ArgoCD → Argo Rollouts: เปลี่ยน Deployment เป็น Rollout, ใส่ strategy.canary.steps (setWeight + pause) หรือ strategy.blueGreen (activeService/previewService)
• Flux → Flagger: สร้าง Canary CRD ชี้ target Deployment, กำหนด analysis.metrics (success-rate/latency จาก Prometheus) + stepWeight + threshold
• ผูก analysis เข้า metric จริง — canary ที่ไม่มี metric gate = blue-green ปลอม. ตั้ง maxWeight/threshold ให้ rollback อัตโนมัติเมื่อ error rate เกิน

6. RBAC + secrets — ห้าม commit plain secret ลง Git เด็ดขาด

• ใช้ Sealed Secrets (encrypt ด้วย controller public key, commit ciphertext ได้) หรือ External Secrets Operator (sync จาก Vault/cloud secret manager) หรือ SOPS + age/KMS
• ArgoCD RBAC: policy.csv map group → role: + จำกัด applications, sync ต่อ project; ใช้ AppProject คุม source repo/dest namespace ที่อนุญาต
• Flux: multi-tenancy ผ่าน Kustomization.spec.serviceAccountName + impersonation, แยก namespace ต่อ tenant
• ถ้าเจอ secret ดิบใน manifest → หยุด, แจ้ง, แนะนำ rotate ทันที (committed = leaked แม้ลบทีหลัง)

7. Verify sync + health (ดู ## Verify)

Common Errors

• OutOfSync ไม่หาย แต่ diff ว่าง → controller (HPA/sidecar injector/webhook) เขียน field ที่ Git ไม่มี → เพิ่ม ignoreDifferences (ArgoCD) หรือ exclude ใน Flux, อย่า force replicas ใน manifest
• selfHeal ตีกับ HPA → manifest hardcode replicas + auto-sync revert ค่าที่ HPA ตั้ง ทุก loop → ลบ replicas ออกจาก manifest หรือ ignore field นั้น
• ComparisonError: app path does not exist → source.path ผิด หรือ targetRevision ชี้ branch/tag ที่ไม่มีไฟล์ — เช็ก path สัมพัทธ์จาก repo root, ไม่ใช่จาก cluster dir
• Prune ลบ resource ที่ไม่ได้ตั้งใจ → resource ถูกสร้างนอก Git (manual / helm hook) → mark Prune=false annotation หรือย้ายเข้า Git; อย่าเปิด prune ครั้งแรกบน cluster ที่มี resource เก่าค้าง — dry-run ก่อน
• Image tag latest → ไม่ trigger sync → Git ไม่เปลี่ยน controller ไม่ rollout แม้ image ใหม่ → pin digest หรือใช้ Image Updater เขียน tag กลับ Git
• Flux reconcile เงียบ ไม่ apply → GitRepository auth fail (deploy key) หรือ Kustomization dependsOn ค้างที่ dependency ยัง not-ready — เช็ก flux get sources git ก่อน
• Canary ไม่ promote / ค้าง progressing → metric provider (Prometheus) ไม่ตอบ หรือ query คืน no-data → Flagger ตีเป็น fail → verify metric query แยกก่อนผูก
• Secret ใน Git history → ลบไฟล์ไม่พอ, ยังอยู่ใน history → rotate ค่าจริง + ใช้ Sealed/External Secrets แทน

Verify

# ArgoCD
argocd app get <app>                  # Sync Status = Synced, Health = Healthy
argocd app diff <app>                  # ต้องว่าง (no diff = no drift)
argocd app sync <app> --dry-run        # ก่อน sync จริงครั้งแรก/หลังเปิด prune
kubectl get applications -n argocd     # ทุก app ไม่ค้าง OutOfSync/Degraded

# Flux
flux get sources git                   # READY=True, ไม่มี auth error
flux get kustomizations                # READY=True, ไม่ค้าง dependency
flux get helmreleases                  # ถ้าใช้ helm
flux reconcile kustomization <name> --with-source   # force reconcile + ดูผล

# Progressive delivery
kubectl argo rollouts get rollout <name>            # canary steps + weight
kubectl describe canary <name>                       # Flagger: phase Succeeded, ไม่ใช่ Failed

ผ่านเมื่อ: Synced/Healthy ทุก app · app diff ว่าง · ไม่มี plain secret ใน Git (grep password:|token:|sk-|AKIA|BEGIN PRIVATE KEY ใน repo ต้องไม่เจอ) · canary promote ถึง 100% หรือ rollback อัตโนมัติเมื่อ metric เกิน threshold (ทดสอบด้วย bad image ครั้งหนึ่ง) · selfHeal revert drift ได้จริง (ลอง kubectl edit resource แล้วดูมัน revert)