GitOps dan Argo CD Cheat Sheet

#Prinsip GitOps

GitOps adalah cara mengelola infrastruktur di mana Git jadi satu-satunya sumber kebenaran. Kamu mendeklarasikan state yang diinginkan di repository, lalu sebuah controller yang berjalan di dalam cluster yang menyinkronkan state nyata ke deklarasi itu. Perubahan produksi terjadi lewat pull request, bukan lewat kubectl apply manual dari laptop seseorang.

Empat prinsip yang biasa dirujuk (dari OpenGitOps):

1. Deklaratif: sistem yang dikelola harus dinyatakan deklaratif, misalnya manifest Kubernetes atau Helm chart.
2. Versioned dan immutable: deklarasi disimpan di storage yang menyimpan riwayat penuh, Git adalah pilihan standar.
3. Pulled automatically: software agent menarik deklarasi dari repo dan menerapkannya ke sistem. Bukan manusia yang push.
4. Continuously reconciled: agent terus membandingkan state nyata dengan state yang diinginkan, lalu memperbaiki deviasinya.

Push vs pull, ini perbedaan yang sering bikin bingung:

Dengan model pull, CI hanya bertugas build, test, dan mengupdate manifest (misalnya image tag baru di repo config). Deploy adalah urusan controller di dalam cluster.

#Argo CD Dasar

Argo CD adalah controller Kubernetes yang mengimplementasikan GitOps. Dia watch repo Git, bandingkan manifest dengan state live cluster, lalu tampilkan statusnya sebagai Synced atau OutOfSync. Instalasi standar lewat manifest resmi di namespace argocd.

kubectl create namespace argocd
kubectl apply -n argocd \
  -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
 
# Password admin awal disimpan di secret ini
kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath='{.data.password}' | base64 -d

CLI argocd dipakai untuk operasi sehari-hari: login, buat aplikasi, sync, dan lihat status.

argocd login localhost:8080 --username admin --insecure
argocd app list
argocd app get guestbook
argocd app sync guestbook

#Application Spec

Application adalah CRD utama Argo CD. Satu Application memetakan satu path di repo Git ke satu destination namespace di cluster.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://gitlab.com/my-group/gitops-config.git
    targetRevision: main
    path: apps/guestbook
  destination:
    server: https://kubernetes.default.svc
    namespace: guestbook
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Tabel field penting di spec:

Sumber manifest yang didukung: plain YAML directory (kustomize tanpa konfigurasi), Kustomize, Helm charts, Jsonnet, dan plugin lainnya via config management plugins. Untuk Helm, konfigurasi values bisa langsung di spec:

source:
  repoURL: https://gitlab.com/my-group/charts.git
  path: charts/guestbook
  helm:
    releaseName: guestbook
    valueFiles:
      - values.yaml
      - values-prod.yaml
    parameters:
      - name: image.tag
        value: v1.4.2

Argo CD tidak render helm template berulang-ulang tiap reconcile. Dia merender sekali lalu membandingkan hasil render dengan cluster, jadi behavior helm upgrade (seperti state di Secret untuk release) tidak berlaku di sini.

#Sync Status vs Health Status

Dua istilah ini beda dan sering tertukar. Sync status menjawab: apakah live state cocok dengan Git? Health status menjawab: apakah aplikasi itu hidup dan sehat?

Argo CD punya built-in health check untuk tipe standar: Deployment, StatefulSet, Service, DaemonSet, ReplicaSet, Pod, PDB, dan lainnya. Contoh Deployment dianggap Healthy kalau semua replica up to date dan tersedia. Untuk CRD (seperti Argo Rollouts atau cert-manager Certificate), kamu bisa definisikan health check sendiri via Lua script di ConfigMap argocd-cm:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  resource.customizations.health.example.com_MyCRD: |
    hs = {}
    if obj.status ~= nil and obj.status.ready == true then
      hs.status = "Healthy"
    else
      hs.status = "Progressing"
    end
    return hs

Health aggregate Application dihitung dari semua resource anaknya. Satu resource Degraded bikin seluruh app Degraded, dan status resource Missing dihitung lebih ringan daripada Degraded.

#Sync Policies

Sync policy menentukan seberapa banyak Argo CD bertindak otomatis. Defaultnya manual: kamu klik Sync di UI atau jalankan argocd app sync. Sync otomatis dinyalakan lewat syncPolicy.automated.

syncPolicy:
  automated:
    prune: true     # hapus resource yang hilang dari Git
    selfHeal: true  # kembalikan perubahan manual di cluster
    allowEmpty: false

Perilaku penting yang perlu kamu ingat:

• Tanpa prune: true, resource yang dihapus dari Git tidak dihapus dari cluster. App jadi OutOfSync terus dengan resource extra. Penghapusan baru terjadi saat manual sync dengan centang prune.
• selfHeal: true membatalkan perubahan manual di cluster (misalnya kubectl scale) dan mengembalikan ke state Git. Tanpa ini, edit manual bikin app OutOfSync tapi dibiarkan sampai sync berikutnya.
• allowEmpty: true mengizinkan app punya nol resource, misalnya saat path di Git dikosongkan sengaja. Defaultnya false sebagai pengaman supaya salah hapus file tidak menghapus semua workload.
• Sync otomatis hanya terjadi kalau app OutOfSync. Kalau commit sama sudah pernah disync, sync tidak diulang kecuali selfHeal aktif.

#Sync Options

Sync options mengatur perilaku detail saat sync berjalan, level Application atau per resource:

syncPolicy:
  syncOptions:
    - CreateNamespace=true
    - PruneLast=true
    - ApplyOutOfSyncOnly=true
    - Validate=false
    - PrunePropagationPolicy=foreground

Untuk menghindari resource tertentu di-prune, annotasi di resource itu:

metadata:
  annotations:
    argocd.argoproj.io/sync-options: Prune=false

#Sync Windows dan Rollback

Untuk batasi kapan deploy boleh terjadi (misalnya cuma jam kerja), pakai sync windows yang didefinisikan di AppProject. Rollback ke versi sebelumnya bisa lewat UI atau CLI:

argocd app rollback guestbook 42   # rollback ke history id 42

Catatan: rollback menonaktifkan auto-sync sementara supaya tidak langsung ditimpa kembali oleh Git.

#Sync Waves dan Hooks

Dalam satu sync, resource bisa diurutkan pakai annotasi argocd.argoproj.io/sync-wave. Angka kecil diterapkan lebih dulu, dan Argo CD menunggu resource sehat sebelum lanjut ke wave berikutnya. Default wave adalah 0.

# Namespace dan CRD dulu (wave -2, -1)
apiVersion: v1
kind: Namespace
metadata:
  name: guestbook
  annotations:
    argocd.argoproj.io/sync-wave: "-2"
---
# Database sebelum aplikasi (wave 0)
apiVersion: apps/v1
kind: Deployment
metadata:
  name: postgres
  annotations:
    argocd.argoproj.io/sync-wave: "0"
---
# Aplikasi terakhir (wave 1)
apiVersion: apps/v1
kind: Deployment
metadata:
  name: guestbook
  annotations:
    argocd.argoproj.io/sync-wave: "1"

Sync hooks memakai annotasi argocd.argoproj.io/hook dengan fase PreSync, Sync, PostSync, SyncFail, atau Skip. Job dengan hook PreSync jalan sebelum resource lain diterapkan, cocok untuk migrasi database:

apiVersion: batch/v1
kind: Job
metadata:
  name: db-migrate
  annotations:
    argocd.argoproj.io/hook: PreSync

#App-of-Apps Pattern

Kalau kamu punya puluhan Application, kelola semuanya dari satu Application induk yang berisi manifest Application lain. Ini namanya app-of-apps, dan induknya sering disebut root app.

# root-app.yaml: Application yang menunjuk ke direktori berisi Application lain
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: root
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://gitlab.com/my-group/gitops-config.git
    targetRevision: main
    path: bootstrap
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Direktori bootstrap/ berisi file Application untuk tiap app (guestbook, monitoring, ingress, dan seterusnya). Root app mensync manifest tersebut, efeknya Argo CD membuat atau mengubah Application anak. Satu git push bisa menambah atau menghapus seluruh app di cluster.

Keterbatasan yang perlu kamu tahu: health check bawaan untuk CRD Application dihapus sejak Argo CD 1.8. Kalau kamu ingin root app menunggu anak-anaknya sehat (berguna digabung dengan sync wave), tambahkan Lua health check untuk argoproj.io/Application di ConfigMap argocd-cm, contohnya ada di docs bagian Resource Health.

Untuk membuat banyak app sekaligus dengan template (misalnya satu app per cluster atau per environment), ApplicationSet adalah penerus modern dari app-of-apps. Generatornya (list, git, cluster, matrix, dan lainnya) bikin satu ApplicationSet bisa menghasilkan ratusan Application dengan parameter berbeda.

#Projects dan Multi-Tenancy

AppProject membatasi apa yang bisa dilakukan sekumpulan Application: repo mana yang boleh jadi sumber, cluster mana yang boleh jadi tujuan, namespace mana yang diizinkan, dan objek Kubernetes apa saja yang bisa dibuat. Ini kontrol penting saat banyak tim berbagi satu Argo CD.

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: team-frontend
  namespace: argocd
spec:
  description: Aplikasi milik tim frontend
  sourceRepos:
    - https://gitlab.com/frontend/*
  destinations:
    - server: https://kubernetes.default.svc
      namespace: frontend-*
  clusterResourceWhitelist:
    - group: ''
      kind: Namespace

#Multiple Clusters

Argo CD bisa mengelola banyak cluster sekaligus. Daftarkan cluster dengan argocd cluster add, lalu pilih destination di Application. Secrets koneksi cluster disimpan sebagai Secret di namespace argocd dengan label argocd.argoproj.io/secret-type: cluster.

argocd cluster add my-context --label env=prod
argocd cluster list

#Secrets: Bahaya dan Pola yang Benar

Masalah klasik GitOps: kalau Git sumber kebenaran, dan secrets tidak boleh masuk Git, bagaimana secrets sampai ke cluster? Jawabannya jangan pernah commit secret polos ke repo config. Enkripsi atau injeksi saat runtime.

Pola yang umum dipakai:

Contoh paling sederhana pakai Sealed Secrets:

# Install controller dulu di cluster
kubectl apply -f \
  https://github.com/bitnami-labs/sealed-secrets/releases/download/v0.27.3/controller.yaml
 
# Bikin sealed secret yang aman di-commit
echo -n 's3cr3t-value' | kubectl create secret generic api-key \
  --from-file=api-key=/dev/stdin --dry-run=client -o yaml > secret.yaml
kubeseal -f secret.yaml -w sealed-secret.yaml
# Commit sealed-secret.yaml ke repo GitOps, hapus secret.yaml

Argo CD sendiri punya beberapa batasan soal secrets yang jarang diberitahu:

• Secret yang dibuat manual di cluster (bukan dari Git) akan terdeteksi OutOfSync kalau app memakai Prune=true atau selfHeal=true. Pola yang benar: kelola Secret lewat tool khusus (di atas), lalu exclude dari Argo CD dengan ignoreDifferences atau masukkan resource ke luar cakupan app.
• RBAC Argo CD membatasi siapa yang bisa baca Secret lewat UI dan CLI. Role default readOnly tidak melihat isi Secret.
• Variabel environment untuk repo (username, password, sshPrivateKey) disimpan sebagai Secret di namespace argocd, lindungi akses ke namespace itu.

# Abaikan perbedaan field tertentu, misalnya yang diubah webhook lain
spec:
  ignoreDifferences:
    - group: apps
      kind: Deployment
      jsonPointers:
        - /spec/replicas

#Status dan Troubleshooting

argocd app get guestbook          # ringkasan sync + health per resource
argocd app diff guestbook         # lihat perbedaan Git vs live
argocd app wait guestbook         # tunggu sampai synced dan healthy
argocd app history guestbook      # riwayat sync untuk rollback

Kasus yang sering muncul:

• OutOfSync padahal tidak ada perubahan: biasanya webhook admission menambah field (contoh last-applied-configuration) atau HPA mengubah spec.replicas. Solusinya ignoreDifferences atau sync option RespectIgnoreDifferences=true.
• Stuck di Progressing: cek kubectl describe pod, penyebab umum image pull lama, resource node kurang, PVC tidak binding, atau init container tidak selesai.
• Degraded setelah sync: lihat resource yang merah di UI, events di namespace biasanya langsung menunjukkan sebabnya.
• Sync gagal karena CRD belum ada: urutkan dengan sync wave supaya CRD diterapkan sebelum custom resource.
• Auto-sync mati sendiri: ini efek rollback manual. Nyalakan lagi dengan argocd app set guestbook --sync-policy automated.

#Alur Kerja GitOps Harian

Alur lengkap dari kode sampai deploy dengan GitOps:

# 1. Developer push kode fitur, CI build dan test
# 2. CI build image dan push ke registry
docker build -t registry.example.com/app:v1.4.2 .
docker push registry.example.com/app:v1.4.2
 
# 3. CI (atau developer) update image tag di repo config
cd gitops-config/
yq -i '.images[0].newTag = "v1.4.2"' apps/guestbook/kustomization.yaml
git commit -am "Bump guestbook ke v1.4.2"
git push
 
# 4. Merge request direview, setelah merge Argo CD menarik perubahan
argocd app get guestbook   # verifikasi Synced + Healthy

Langkah 3 adalah inti GitOps: perubahan produksi selalu lewat commit yang ter-review. Image promotion hanyalah update satu baris tag di repo config.

#Tips Praktis

• Satu repo config terpisah dari repo aplikasi, aksesnya dibatasi
• Root app atau ApplicationSet untuk bootstrap, bukan Application manual satu-satu
• prune: true dan selfHeal: true untuk environment non-kritis, manual untuk produksi
• Selalu set targetRevision ke branch atau tag eksplisit, jangan HEAD dari mirror default
• Pakai AppProject untuk batasi repo dan namespace per tim
• Secrets tidak pernah polos di Git: Sealed Secrets, SOPS, atau External Secrets
• Sync wave untuk urutan dependency (CRD dulu, database sebelum aplikasi)
• PreSync hook untuk migrasi database
• Monitor Argo CD sendiri: metrics endpoint tersedia untuk Prometheus
• Set ApplyOutOfSyncOnly=true untuk app dengan ratusan resource

#Glosarium

#Resources

• Argo CD docs
• Automated sync policy
• Sync options
• Resource health
• OpenGitOps principles
• ApplicationSet controller