Argo CD 3.5: Panduan Upgrade mTLS, Source Integrity dan Helm 4

Upgrade yang paling berbahaya adalah yang diam-diam. Helm chart dari registry internal lewat plain HTTP berjalan normal di 3.4, lalu berhenti di 3.5, karena Helm 4 tidak lagi berasumsi seperti Helm 3. Headline rilisnya tidak menyebut hal ini.

Post ini membaca halaman release v3.5.0, catatan upgrade 3.4 ke 3.5, serta dokumentasi mTLS dan Source Integrity yang baru, lalu merangkum apa yang berubah, apa yang rusak, dan urutan rollout yang saya sarankan. Saya belum menjalankan 3.5 di production, jadi setiap perilaku di bawah dikaitkan dengan dokumen yang menyebutkannya.

Apa saja yang dibawa 3.5

Rilis v3.5.0 bertanggal 4 Agustus 2026 dan halamannya mencatat 855 commit sejak tag sebelumnya. Image container ditandatangani dengan cosign, dan provenance dibuat untuk image serta binary CLI pada SLSA Level 3. Daftar fitur mencakup mTLS di repo-server (#26715), migrasi ke Helm 4 (#28076), concurrency ApplicationSet saat mengelola aplikasi (#26642), impersonation untuk operasi server (#26898) dan prefix path tag Git (#27290).

Tiga perubahan tingkat kematangan lebih penting daripada fitur mana pun. Entri dokumentasi menaikkan Source Hydrator ke beta (#28229), impersonation ke beta (#27576) dan ApplicationSet di namespace mana pun ke stable (#27417). Status stable inilah yang membuat layout ApplicationSet multi-tenant tidak lagi eksperimen.

Tulisan InfoQ, terbit 26 Juni saat 3.5 masih release candidate, menambahkan UI ApplicationSet baru dengan tampilan list, filter, detail dan tab Preview Apps. Detail itu berasal dari InfoQ, bukan dari halaman release yang saya baca, jadi anggap sebagai laporan, bukan fakta terverifikasi.

Catatan upgrade: apa yang dicek sebelum 3.5

Halaman upgrade 3.4 ke 3.5 membagi isinya menjadi breaking changes, perubahan perilaku dan deprecation. Saya ubah menjadi tabel siapa yang terdampak dan apa yang harus dilakukan. Kalau barisnya tidak mengenai Anda, lewati, tetapi Anda harus tahu baris mana yang mengenai Anda.

Perhatikan yang tidak ada. Halaman upgrade tidak mencantumkan entri di bagian API changes maupun security changes, dan tidak ada item di halaman release yang berlabel breaking. Risikonya terkumpul di perilaku, jenis yang disembunyikan rollout hijau sampai sync pertama.

Helm 4 dan jebakan OCI plain-HTTP

Argo CD 3.5 membawa Helm 4. Catatan upgrade menyebut perubahan yang menggigit: Helm v4 mewajibkan flag plain-HTTP eksplisit untuk registry OCI plain HTTP, dan Helm v3 dulu mengakses dependency OCI tanpa registrasi, yang kini tidak bisa. Repository yang sudah ada perlu field insecureOCIForceHttp berisi string true di Secret repository, atau flag CLI 3.5 dengan upsert.

# Re-register a plain-HTTP OCI chart repo for Helm 4 (Argo CD CLI 3.5).
# Without --insecure-oci-force-http, Helm 4 will not fall back to HTTP.
# Do NOT also pass --insecure-skip-server-verification: the upgrade notes say
# Helm 4 then drops --plain-http and fails with
# "http: server gave HTTP response to HTTPS client". No workaround is listed.
argocd repo add registry.internal:5000/charts \
  --type helm --name internal-charts --enable-oci \
  --insecure-oci-force-http --upsert

Nilai spec.source.helm.version seperti v3 diabaikan di 3.5, dan Helm 4 tetap merender chart. Tidak wajib dihapus, tetapi sekarang ia menjadi komentar yang menyesatkan, jadi saya bersihkan di pull request yang sama dengan audit chart untuk perbedaan Helm 4.

Keterbatasan yang didokumentasikan adalah bagian paling menyebalkan. Menggabungkan flag skip-server-verification dengan flag force-HTTP pada rantai yang sama membuat Helm 4 membuang opsi plain-http, hasilnya error http: server gave HTTP response to HTTPS client. Catatan menyatakan tidak ada workaround bila keduanya dibutuhkan.

mTLS repo-server, dan yang tidak dilakukannya

mTLS repo-server bersifat opt-in dan mati secara default. Buat Secret bernama argocd-repo-server-mtls berisi client-ca.crt, client.crt dan client.key. Argo CD me-mount-nya di /app/config/reposerver/mtls pada pod terkait, dan mTLS menyala begitu file-nya ada. Repo-server membuat sertifikat klien ephemeral untuk liveness check-nya sendiri, jadi probe tidak perlu diubah.

# The shared Secret from the 3.4 to 3.5 upgrade page. mTLS turns on
# automatically once these files exist at /app/config/reposerver/mtls.
apiVersion: v1
kind: Secret
metadata:
  name: argocd-repo-server-mtls
  namespace: argocd
type: Opaque
stringData:
  client-ca.crt: |
    <PEM-encoded CA certificate that signed the client certs>
  client.crt: |
    <PEM-encoded shared client certificate>
  client.key: |
    <PEM-encoded private key for the shared client certificate>

# Deprecated 3.4 way vs the 3.5 way, per the mTLS page:
# Wrong: --repo-server-strict-tls            (works in 3.5 with warnings)
# Right: --repo-server-ca-cert-path=/app/config/server/tls/ca.crt

Baca paragraf sisi server di halaman mTLS dua kali. Repo-server memuat satu CA pool dan menerima klien mana pun yang sertifikatnya berantai ke pool itu. Ia tidak memeriksa Subject atau SAN. Jadi mTLS di sini mengautentikasi pemanggil tetapi tidak mengotorisasi: application controller dan pod nyasar yang memegang sertifikat bersama yang sama terlihat identik. Otorisasi per komponen butuh lapisan sendiri, misalnya sidecar Envoy atau gRPC interceptor.

Ada juga migrasi flag. Flag repo-server-strict-tls di-deprecate pada argocd-server, application controller, applicationset controller dan notifications controller. Arahkan repo-server-ca-cert-path ke /app/config/server/tls/ca.crt dan pertahankan volume mount. Flag lama masih jalan di 3.5 dengan warning, dan catatan menyebut bisa dihapus di v3.6 atau lebih baru.

Source Integrity menggantikan signatureKeys GnuPG

Source Integrity dikonfigurasi di tiap AppProject pada spec.sourceIntegrity. Jika kriteria tidak terpenuhi, aplikasi tidak sync dan melaporkan error ResourceComparison. Tiap policy punya daftar glob URL repo, dengan tanda seru di depan untuk menegasikan pola, dan blok gpg berisi mode serta daftar key ID tepercaya. Hanya satu policy yang berlaku untuk satu repository, dan source yang tidak cocok dengan policy mana pun tidak diverifikasi.

Mode menentukan seberapa banyak history yang Anda pertaruhkan. Tabel berikut memuat tiga nilai yang didefinisikan dokumentasi.

# AppProject: start in head mode, the closest match to legacy signatureKeys.
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: payments
  namespace: argocd
spec:
  sourceIntegrity:
    git:
      policies:
        - repos:
            - url: "https://github.com/my-group/*"
            - url: "!https://github.com/my-group/ignored.git"   # leading ! excludes
          gpg:
            mode: head                       # none | head | strict
            keys:
              - "D56C4FCA57A46444"           # key ID from the docs example
# Import the public key first; the repo-server keyring is rebuilt from
# argocd-gpg-keys-cm on restart, so manual edits inside the pod are lost.
#   argocd gpg add --from ./release-key.asc
# Do not keep .spec.signatureKeys here: the two cannot be used together.

Migrasinya mekanis. Hapus spec.signatureKeys, definisikan policy dengan url bintang, mode head dan key ID yang sama, maka Anda mendapat perilaku lama. Jika sourceIntegrity tidak ada tetapi signatureKeys terisi, Argo CD mengonversinya otomatis, tetapi dokumentasi menyarankan migrasi manual karena signatureKeys akan dihapus, dan keduanya tidak bisa hidup bersama dalam satu project.

Impersonation, concurrency ApplicationSet dan UI

Impersonation kini berlaku untuk setiap operasi API server, padahal sebelumnya hanya sync. Melihat, patch, delete, daftar event, membaca log pod dan menjalankan resource action semuanya memakai service account dari destinationServiceAccounts milik AppProject. Jika akun itu dibatasi pada verb yang dibutuhkan sync, UI akan mulai menampilkan error permission setelah upgrade.

Concurrency ApplicationSet berasal dari pull request 26642. Controller bisa meng-update Application yang dikelolanya secara paralel, padahal dulu satu per satu, yang menurut PR bisa memakan banyak menit untuk ratusan aplikasi. Flag-nya concurrent-application-updates dengan environment variable ARGOCD_APPLICATIONSET_CONTROLLER_CONCURRENT_APPLICATION_UPDATES. Default 1, yang mempertahankan perilaku sekuensial, disebut di ringkasan review PR, bukan di kode yang saya baca.

# ApplicationSet controller: the flag and env var named in PR 26642.
# The PR review summary gives the default as 1 (sequential). Step up slowly.
env:
  - name: ARGOCD_APPLICATIONSET_CONTROLLER_CONCURRENT_APPLICATION_UPDATES
    value: "4"        # example only: my own starting point, not a measured value

Menaikkannya adalah trade-off terhadap API server dan repo-server Anda. Saya akan menaikkannya bertahap sambil memantau latency reconcile, bukan memasang angka besar karena opsinya ada. Saya tidak punya pengukuran nilai yang tepat dan tidak akan mengarangnya.

Di mana bisa salah

Source Integrity punya batasan terdokumentasi yang penting untuk fleet nyata. Hanya source Git yang didukung, jadi source Helm dan OCI tidak bisa diverifikasi. Verifikasi signature tidak didukung untuk ApplicationSet yang diisi git generator bila field project di-template. Dan dengan source integrity aktif, argocd app sync dengan flag local tidak lagi berfungsi, menghilangkan kebiasaan debugging yang banyak dipakai tim.

Keyring adalah jebakan kedua. Keyring di dalam pod repo-server dibangun ulang dari ConfigMap argocd-gpg-keys-cm saat restart, jadi perubahan manual di pod hilang, dan jika keyring tidak sinkron solusi yang didokumentasikan adalah restart pod repo-server. Import key juga bisa butuh waktu untuk menyebar di cluster, yang tampak persis seperti kegagalan signature.

Ada dua konflik sumber yang perlu diketahui. InfoQ menggambarkan Source Integrity sebagai sourceIntegrity.required pada spec Application dengan flag app set, sedangkan dokumentasi Argo CD menaruhnya di AppProject pada spec.sourceIntegrity. Saya mengikuti dokumentasi. Halaman upgrade juga menyebut Helm 4.2.0 di satu bagian dan 4.2.1 di bagian lain tanpa merekonsiliasi, jadi cek versi yang dilaporkan image Anda.

Yang dikerjakan hari Senin

Lakukan audit di 3.4 dulu, karena semua item bisa dicek sebelum Anda mengubah apa pun. Ini urutan yang saya ikuti.

1. Cari di semua Application dan Secret repository untuk registry OCI plain-HTTP dan dependency OCI, lalu putuskan pindah ke HTTPS atau daftarkan dengan opsi force-HTTP.
2. Daftar AppProject yang masih memakai signatureKeys dan tulis policy mode head yang setara, agar migrasi berupa diff yang direview, bukan konversi otomatis.
3. Cari flag repo-server-strict-tls yang sudah deprecated di manifest Anda dan ganti dengan repo-server-ca-cert-path sebelum hilang.
4. Cek RBAC destinationServiceAccounts untuk verb yang kini dipakai UI dan API, dan pindahkan known_hosts yang Anda mount ke argocd-ssh-known-hosts-cm.
5. Upgrade instance non-production, aktifkan mTLS di sana, pastikan klien tanpa sertifikat ditolak, baru rencanakan production.

Perintah berikut mencakup audit yang bisa di-script. Sesuaikan namespace dengan milik Anda.

# 1. AppProjects still on the deprecated GnuPG config
kubectl -n argocd get appprojects -o json \
  | jq -r '.items[] | select(.spec.signatureKeys) | .metadata.name'

# 2. Applications that pin a Helm version (ignored on 3.5, Helm 4 renders)
kubectl get applications -A -o json \
  | jq -r '.items[] | select(.spec.source.helm.version != null)
           | [.metadata.namespace, .metadata.name, .spec.source.helm.version] | @tsv'

# 3. The deprecated strict-TLS flag in your workloads
kubectl -n argocd get deploy,sts -o yaml | grep -n -- '--repo-server-strict-tls'

# 4. Which Helm version the repo-server image reports (the notes say 4.2.0 and 4.2.1)
kubectl -n argocd exec deploy/argocd-repo-server -- helm version

Aturan saya untuk rilis ini: fiturnya opsional, perubahan perilakunya tidak. Anggap Helm 4, cakupan impersonation dan host key SSH sebagai upgrade yang sebenarnya, lalu adopsi mTLS dan Source Integrity sesudahnya, dalam mode head, satu project per satu.