Membangun GitOps Workflow dengan ArgoCD: Sinkronisasi Otomatis Manifest Kubernetes dari Git

Tantangan Menjaga Manifest Kubernetes Tetap Sesuai Kondisi Cluster

Praktik umum saat pertama kali belajar Kubernetes adalah menjalankan kubectl apply -f langsung dari laptop ke cluster. Perintah ini bekerja, tetapi kondisi cluster akhirnya bergantung pada siapa yang terakhir kali menjalankannya. Tidak ada catatan terpusat tentang siapa mengubah apa dan kapan perubahan itu terjadi.

Situasi menjadi lebih rumit saat sebuah insiden memaksa kita melakukan hotfix langsung di cluster. Perubahan tersebut tidak tercatat di Git, sehingga muncul kondisi yang disebut drift. Drift adalah selisih antara manifest yang tersimpan di repository dan objek yang benar-benar berjalan di cluster.

Masalah utama drift muncul ketika kita perlu rollback. Tanpa satu sumber kebenaran, kita tidak bisa memastikan konfigurasi mana yang pernah berjalan dengan baik. Setiap upaya reproduksi berubah menjadi tebak-tebakan, terutama di lingkungan production dengan banyak perubahan paralel.

GitOps menempatkan repository Git sebagai single source of truth. Seluruh manifest disimpan, di-review, dan di-version di sana. Cluster tidak lagi diubah lewat perintah manual, melainkan melalui commit yang bisa dilacak. Perubahan konfigurasi mengikuti alur pull request yang sama dengan perubahan kode aplikasi.

Contoh berikut memperlihatkan perintah manual dan selisih yang timbul setelahnya:

kubectl apply -f manifests/deployment.yaml
kubectl scale deployment web-app --replicas=5
kubectl get deployment web-app

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: web-app
  template:
    metadata:
      labels:
        app: web-app
    spec:
      containers:
        - name: web
          image: nginx:1.27

Output dari kubectl get deployment web-app menampilkan replicas: 5, sementara manifest di Git masih tertulis 2. Perbedaan inilah yang akan terus muncul selama tidak ada controller yang menyamakan keduanya.

Cara Kerja Argo CD sebagai Controller GitOps di Kubernetes

Argo CD berjalan sebagai controller di dalam cluster dan memantau dua hal sekaligus: repository Git dan kondisi live cluster. Dua kondisi ini dikenal sebagai desired state (manifest di Git) dan live state (objek yang benar-benar ada di cluster). Selisih antara keduanya menjadi dasar proses reconciliation.

Argo CD bertindak seperti kontroler yang terus memutar ulang perbandingan antara kondisi yang diminta Git dan kondisi nyata cluster.

Arsitektur Argo CD terdiri dari tiga komponen inti. argocd-server menyediakan API dan UI yang kita akses. argocd-application-controller menjalankan proses reconciliation dan mendeteksi perbedaan. argocd-repo-server merender manifest dari repository Git sebelum dikirim ke cluster.

Gambar: Arsitektur internal Argo CD yang terdiri dari empat lapisan — UI (Webapp, CLI), Application (API Server), Core (Application Controller, ApplicationSet Controller, Repo Server), dan Infra (Redis, Kube API, Git, Dex) — Sumber: Argo CD Developer Guide: Component Architecture

Alur sinkronisasi dimulai saat controller mendeteksi selisih antara desired state dan live state. Ketika ada perbedaan, Argo CD menandai aplikasi dengan status OutOfSync. Controller kemudian menerapkan manifest Git ke cluster sampai keduanya kembali senilai, dan status berubah menjadi Synced.

Dasar dari semua ini adalah custom resource bernama Application. Resource ini mendefinisikan dari mana manifest diambil dan ke cluster mana manifest diterapkan. Dengan mendeklarasikan Application, kita memberi Argo CD kontrak eksplisit tentang apa yang harus dijaga konsisten.

Pendekatan pull-based ini membedakan Argo CD dari pipeline push biasa. Controller membaca repository sendiri, sehingga credential cluster tidak perlu dibagikan ke sistem CI di luar. Kita cukup memberi Argo CD akses baca ke Git, dan controller yang mengurus sisanya di dalam cluster.

Instalasi Argo CD dan Pendaftaran Aplikasi Pertama

Instalasi dimulai dengan menerapkan manifest resmi dari repository Argo CD ke namespace argocd. Perintah ini membuat seluruh komponen controller beserta custom resource definition yang dibutuhkan.

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
kubectl port-forward svc/argocd-server -n argocd 8080:443

Setelah pod berjalan, kita bisa mengakses UI lewat port-forward dan login menggunakan akun admin. Password awal diambil dari secret argocd-initial-admin-secret. Untuk operasi dari terminal, kita menginstal CLI argocd dan mengarahkannya ke server melalui perintah argocd login.

Sisi Git memerlukan struktur yang jelas. Kita menaruh folder manifests/ berisi Deployment, Service, dan kustomization.yaml. Struktur ini memisahkan konfigurasi dari kode aplikasi dan memudahkan proses review.

Deklarasi Application menghubungkan repository Git ke namespace target:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: web-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/example/gitops-manifests.git
    targetRevision: main
    path: manifests
  destination:
    server: https://kubernetes.default.svc
    namespace: production

Field repoURL, path, dan targetRevision menentukan sumber manifest. Field destination menentukan ke mana manifest diterapkan. Setelah kubectl apply -f application.yaml, perintah argocd app list menampilkan aplikasi dengan status OutOfSync karena manifest belum disinkronkan.

Mengaktifkan Auto-Sync dan Self-Heal untuk Sinkronisasi Otomatis

Sinkronisasi otomatis diatur lewat blok syncPolicy. Dengan menambahkan opsi automated, Argo CD langsung menerapkan perubahan setiap kali ada commit baru di Git. Tidak ada lagi langkah manual untuk menjalankan sync.

Dua opsi penting di dalam automated adalah prune dan selfHeal. Opsi prune menghapus resource di cluster yang sudah tidak ada lagi di Git, sehingga tidak meninggalkan objek yatim. Opsi selfHeal mengembalikan perubahan manual di cluster agar sesuai dengan Git. Keduanya berisiko jika salah konfigurasi: prune bisa menghapus resource yang masih dibutuhkan jika manifest tidak lengkap, sedangkan selfHeal bisa menimpa intervensi darurat yang sebenarnya disengaja.

Kita juga dapat menambahkan retry untuk menangani kegagalan sementara dan syncOptions seperti CreateNamespace=true ketika namespace target belum ada.

spec:
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
    retry:
      limit: 5
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 3m

Alur kerjanya sederhana: kita commit manifest ke Git, Argo CD mendeteksi revisi baru, lalu cluster diperbarui tanpa intervensi manual. Perintah argocd app get web-app menampilkan status Synced dan Healthy ketika semuanya berjalan sesuai harapan.

Gambar: Alur deploy GitOps dengan Argo CD — perubahan di Git repository memicu webhook/PR, Argo CD mendeteksi perubahan, lalu melakukan sinkronisasi otomatis ke berbagai Kubernetes cluster (dev, staging, production) — Sumber: Argo CD Official Documentation

Memantau Status Sinkronisasi dan Menangani Kegagalan Deployment

Pemantauan dilakukan melalui CLI dan UI. Perintah argocd app get menampilkan ringkasan status, sementara argocd app history memperlihatkan daftar revisi yang pernah disinkronkan. UI Argo CD menyajikan visualisasi graph dari resource yang dikelola.

Ada dua indikator utama yang perlu dibaca. Sync Status menunjukkan apakah cluster senilai dengan Git, dengan nilai Synced atau OutOfSync. Health Status menunjukkan kondisi resource, dengan nilai seperti Healthy, Progressing, atau Degraded. Kombinasi keduanya membantu kita membedakan antara konfigurasi yang belum diterapkan dan aplikasi yang gagal berjalan.

Health check bawaan Argo CD memahami semantic resource Kubernetes. Untuk Deployment, Argo CD menunggu sampai replica tersedia. Untuk Service, Argo CD memeriksa apakah endpoint sudah terbentuk. Pemeriksaan ini membuat status Healthy merefleksikan kesiapan aplikasi, bukan sekadar keberhasilan apply.

Ketika deployment gagal, kita bisa kembali ke revisi sebelumnya:

argocd app get web-app
argocd app history web-app
argocd app rollback web-app 3
argocd app sync web-app --resource apps:Deployment:web-app

Perintah rollback mengembalikan aplikasi ke revisi Git tertentu. Untuk perubahan sensitif, kita bisa menonaktifkan auto-sync sementara dan menjalankan sync manual atau selective sync pada resource tertentu saja.

Best Practice Struktur Repository dan Keamanan Argo CD

Praktik pertama adalah memisahkan repository aplikasi dan repository manifest. Pemisahan ini membatasi akses dan menjaga audit trail tetap bersih, sebab developer tidak perlu hak tulis ke manifest production hanya untuk mengubah kode.

Kedua, gunakan kustomize atau Helm untuk mengelola variasi environment. Overlay per environment menghindari duplikasi YAML dan mengurangi risiko konfigurasi yang tidak konsisten antara staging dan production.

Ketiga, terapkan RBAC lewat AppProject. Setiap tim hanya diberi akses ke namespace dan repository tertentu. Pembatasan ini mencegah satu tim tanpa sengaja mengubah resource tim lain atau environment yang bukan tanggung jawabnya.

Keempat, kelola credential repository dengan SSH key atau token berbatas hak akses, bukan password akun. Terakhir, hindari menyimpan secret mentah di Git. Integrasikan Sealed Secrets atau External Secrets Operator agar nilai sensitif tetap terenkripsi dan sumber aslinya tetap berada di secret manager.

Kombinasi struktur repository yang rapi dan kontrol akses yang ketat membuat GitOps tetap aman saat jumlah aplikasi bertambah. Tanpa keduanya, otomatisasi justru mempercepat penyebaran kesalahan ke seluruh environment.

Sinkronisasi cluster langsung dari Git menghapus deployment manual yang rawan drift. Pelajari alur GitOps dan Kubernetes production-grade lebih dalam di kelas DevOps Rumah Coding.