Argo CD'yi Production'da İşletmek ve 2.x'ten 3.6'ya Değişenler: SSO, RBAC, Notifications, Metrikler ve Upgrade

Sürüm notu: Bu yazıdaki örnekler kind 0.33 ile Kubernetes 1.37 ve Argo CD 3.6.1 (CLI 3.6.1) ile denenmiştir. Tek seferde giriş (SSO) yapılandırması, yüksek erişilebilir (HA) kurulum ve sürüm yükseltme komutu lab'da çalıştırılmadı; yazıda ayrıca belirtiliyor.

Önce Tahmin Et

Bir role p, role:app-editor, applications, update, bookstore/*, allow yetkisi veriyorsun. Bu rol bookstore-api-prod Application'ının kendisini değiştirebilir. Peki aynı rol Argo CD UI'ından bu uygulamanın içindeki api Rollout'unu ya da bir Pod'u düzenleyebilir mi? Argo CD 2.x'te cevap evetti. 3.6'daki cevap, argocd admin settings rbac can çıktısıyla, RBAC (Role-Based Access Control; rol tabanlı yetkilendirme) bölümünde.

Argo CD'nin Ayarları da Git'te

Serinin başından beri sitedeki serilerin ortak örnek uygulaması Bookstore'un (bir online kitapçı) bütün durumu Git'te, ama Argo CD'nin kendi ayarları kubectl patch ile yapılmış değişikliklerdi: yedinci yazıdaki secret çözme eklentisi için argocd-cm, progressive sync için argocd-cmd-params-cm. Bu yazıda kullanıcıları, RBAC'ı ve bildirimleri ekliyoruz; bunları da elle yapmak, Argo CD'nin en kritik ayarlarını Git'in dışında bırakmak olurdu. App of Apps root'unun altına bir Application daha koyduk:

# Argo CD'nin kendi ayarları (hesaplar, RBAC, bildirimler) Git'ten, Argo CD tarafından uygulanır.
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: argocd-settings
  namespace: argocd
spec:
  project: default
  source:
    repoURL: http://git-server.git-server.svc.cluster.local/bookstore-config
    targetRevision: main
    path: argocd/settings
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated:
      selfHeal: true
    syncOptions:
      # Yalnız Git'teki key'leri yönet; aynı ConfigMap'lerdeki kurulum varsayılanlarına dokunma.
      - ServerSideApply=true

İki ayrıntı önemli. argocd-cm'de kurulumun koyduğu varsayılanlar var (3.0'dan beri resource.exclusions gibi); Git'teki dosya yalnız bizim key'lerimizi taşıyor. Server-side apply ile Argo CD yalnız kendi yazdığı alanların sahibi oluyor ve diğer key'ler yerinde kalıyor; 3.6'dan beri ServerSideApply=true olan uygulamaların diff'i de server-side diff ile hesaplanıyor. İkincisi, her ConfigMap'te argocd.argoproj.io/sync-options: Prune=false annotation'ı var ve automated'da prune yok: bir dosyanın yanlışlıkla silinmesi Argo CD'nin ayarlarını silmesin. İlk sync'te üç ConfigMap serverside-applied oldu ve resource.exclusions olduğu gibi kaldı.

Bir adım ötesi Argo CD'nin kendisini, yani kurulum manifest'ini de bir Application ile yönetmek: kustomization.yaml sürümü sabitlenmiş install.yaml'ı resource olarak alır, patch'ler (yedinci yazıdaki repo-server patch'i, HA ayarları) yanında durur ve yükseltme, URL'deki sürümü değiştiren bir pull request olur. 3.3'ten beri ApplicationSet CRD'si (Custom Resource Definition; Kubernetes'e eklenen özel nesne tipi) client-side apply sınırını aştığı için böyle bir Application'da ServerSideApply=true zorunlu. Lab'da bu adımı atmadık; Argo CD'yi elle kurulmuş hâliyle bıraktık.

Kullanıcılar, SSO ve RBAC

Argo CD'nin kimlik doğrulaması iki yoldan gelir: argocd-cm'de tanımlanan local hesaplar ve SSO (şirket hesabıyla tek seferde giriş). Production'da insanlar SSO'dan gelmeli; local hesaplar CI gibi makineler ve acil durum için kalır. Lab'da SSO sağlayıcısı olmadığı için iki local hesap açtık: giriş yapabilen bir geliştirici (ada) ve yalnız API key'i olan bir CI hesabı (ci-bot):

data:
  # KSOPS (7. yazı).
  kustomize.buildOptions: --enable-alpha-plugins --enable-exec
  # Local hesaplar: giriş yapan bir kişi ve yalnız API key'i olan CI.
  accounts.ada: login
  accounts.ci-bot: apiKey

Yetkiler argocd-rbac-cm'de, Casbin formatında. p satırı bir role izin verir (rol, resource, action, nesne, karar), g satırı bir kullanıcıyı ya da SSO grubunu role bağlar:

data:
  # Varsayılan olarak kimse bir şey alamaz; her yetki aşağıdaki bir rolden gelir.
  policy.default: ""
  policy.csv: |
    # Geliştiriciler: bütün Bookstore uygulamalarını ve log'larını görür, yalnız dev'i sync eder.
    p, role:bookstore-developer, applications, get, bookstore/*, allow
    p, role:bookstore-developer, logs, get, bookstore/*, allow
    p, role:bookstore-developer, applications, sync, bookstore/bookstore-*-dev, allow
    # Release: her ortamı sync eder ve workload'ları yeniden başlatır, hiçbir şey silemez.
    p, role:bookstore-release, applications, get, bookstore/*, allow
    p, role:bookstore-release, applications, sync, bookstore/*, allow
    p, role:bookstore-release, applications, action/argoproj.io/Rollout/*, bookstore/*, allow
    # Platform ekibi: her şey (gerçek kurulumda bir SSO grubu).
    g, platform-team, role:admin
    g, ada, role:bookstore-developer
    g, ci-bot, role:bookstore-release

ada ile giriş yapıp denedik. Uygulamaları görüyor (yalnız bookstore project'indekileri; root ve argocd-settings listede yok), dev'i sync edebiliyor, prod'u sync edemiyor ve hiçbir şeyi silemiyor:

$ argocd app sync bookstore-api-prod
{"level":"fatal","msg":"rpc error: code = PermissionDenied desc = permission denied: applications, sync, bookstore/bookstore-api-prod, sub: ada, iat: 2026-11-15T05:09:27Z"}
$ argocd app sync bookstore-web-dev
Phase:              Succeeded
Message:            successfully synced (all tasks run)
$ argocd app delete bookstore-web-dev
{"level":"fatal","msg":"rpc error: code = PermissionDenied desc = permission denied: applications, delete, bookstore/bookstore-web-dev, sub: ada, iat: 2026-11-15T05:09:27Z"}

Policy'yi her seferinde bir kullanıcıyla denemek yerine argocd admin settings rbac can ile dosya üzerinde kontrol etmek mümkün; bir pull request'teki RBAC değişikliğini CI'da böyle doğrulayabilirsin:

argocd admin settings rbac can ci-bot sync applications bookstore/bookstore-api-prod --policy-file argocd-rbac-cm.yaml

ada get logs bookstore/bookstore-api-prod -> Yes
ada sync applications bookstore/bookstore-api-prod -> No
ci-bot get logs bookstore/bookstore-api-prod -> No
ci-bot sync applications bookstore/bookstore-api-prod -> Yes
ci-bot delete applications bookstore/bookstore-api-prod -> No
ci-bot action/argoproj.io/Rollout/restart applications bookstore/bookstore-api-prod -> Yes

SSO tarafında Argo CD iki yol sunuyor: kurulumla gelen Dex üzerinden (GitHub, LDAP (şirket dizin servisi protokolü), SAML (kurumsal kimlik federasyonu standardı) gibi connector'lar) ya da doğrudan bir OIDC (OpenID Connect; OAuth 2.0 üzerine kurulu kimlik protokolü) sağlayıcısı. Microsoft Entra ID için doğrudan OIDC ayarı şu şekilde olur; bu ayarı lab'da çalıştırmadık:

data:
  url: https://argocd.example.com
  oidc.config: |
    name: Entra ID
    issuer: https://login.microsoftonline.com/<tenant-id>/v2.0
    clientID: <application-id>
    clientSecret: $oidc.entra.clientSecret
    requestedScopes: ["openid", "profile", "email"]
    requestedIDTokenClaims: {"groups": {"essential": true}}

$oidc.entra.clientSecret değeri argocd-secret'tan okunur; secret ConfigMap'e yazılmaz. Gruplar token'daki groups claim'inden gelir ve argocd-rbac-cm'de scopes: '[groups]' ile RBAC'a bağlanır: g, <grup-id>, role:bookstore-developer. 3.0 Dex kullananlar için bir değişiklik getirdi: RBAC'taki kullanıcı kimliği artık Dex'in sub claim'i değil, federated_claims.user_id. Policy'lerde kullanıcıyı sub değeriyle yazdıysan yükseltmeden önce güncellemen gerekiyor.

3.0'ın RBAC Değişiklikleri: update, delete ve logs

Önce Tahmin Et'in cevabı. 3.0'dan önce bir Application üzerindeki update ya da delete yetkisi, o uygulamanın yönettiği kaynaklara da geçiyordu. Artık geçmiyor:

role:app-editor update applications bookstore/bookstore-api-prod -> Yes
role:app-editor update/argoproj.io/Rollout/bookstore-prod/api applications bookstore/bookstore-api-prod -> No
role:app-editor update/*/Pod/*/* applications bookstore/bookstore-api-prod -> No

Rol Application'ı değiştirebiliyor ama içindeki Rollout'u ya da bir Pod'u değiştiremiyor; bunun için update/<grup>/<kind>/<namespace>/<ad> biçiminde ayrı bir izin gerekiyor. Eski davranış argocd-cm'de server.rbac.disableApplicationFineGrainedRBACInheritance: "false" ile geri getirilebiliyor, ama yeni davranış daha güvenli. İkinci değişiklik log'lar: 3.0'dan beri log görmek ayrı bir izin (logs, get) ve applications, get ile birlikte gelmiyor. Yukarıdaki çıktıda ci-bot prod'u sync edebiliyor ama log'larını göremiyor. 2.x'te policy.default tanımlamamış ve log zorlamasını açmamış bir kurulum, yükseltmeden sonra kullanıcılarının log sekmesini kaybettiğini görür; çözüm her role açıkça logs, get eklemek.

CI Token'ı ve Admin Hesabını Kapatmak

CI'ın Argo CD'ye erişmesi gerekiyorsa (bir sync'i tetiklemek, durumunu beklemek) ona bir kişinin parolası değil, kendi hesabının süreli bir token'ı verilir. Token'ı bir dosyaya yazdık ve hiçbir yerde göstermedik:

argocd account generate-token --account ci-bot --expires-in 1h > ci-bot-token.txt
argocd app sync bookstore-api-staging --auth-token "$(cat ci-bot-token.txt)"
argocd app delete bookstore-api-staging --yes --auth-token "$(cat ci-bot-token.txt)"

Phase:              Succeeded
Message:            successfully synced (no more tasks)
{"level":"fatal","msg":"rpc error: code = PermissionDenied desc = permission denied: applications, delete, bookstore/bookstore-api-staging, sub: ci-bot, iat: 2026-11-15T05:10:13Z"}

Beşinci yazıdaki AppProject rolü de (proj:bookstore:deployer) aynı işi project düzeyinde görüyor; ikisi arasındaki fark yetkinin nerede tanımlandığı: project rolü project'in içinde, global rol argocd-rbac-cm'de. Son adım kurulumla gelen admin hesabı. İkinci yazıda ilk parolasını değiştirmiştik; production'da bu hesap yalnız kurulum için var ve SSO çalıştıktan sonra kapatılır. Bunu da Git'ten yaptık (admin.enabled: "false"); sync'ten sonra:

$ argocd login 127.0.0.1:52611 --username admin
{"level":"fatal","msg":"rpc error: code = Unauthenticated desc = Account admin is disabled"}

Kapatmadan önce role:admin'e bağlı bir SSO grubu ve çalıştığı doğrulanmış bir giriş olmalı; yoksa Argo CD'yi yalnız kubectl ile yönetebilen bir duruma düşersin.

Notifications ve Metrikler

Sekizinci yazıda abort edilmiş bir Rollout'un ancak biri bakınca fark edildiğini gördük. Argo CD Notifications controller'ı kurulumla geliyor; ayarları argocd-notifications-cm'de: bir service (Slack, Microsoft Teams, e-posta ya da düz webhook), mesaj template'leri ve ne zaman gönderileceğini söyleyen trigger'lar. Lab'da gelen istekleri log'a yazan küçük bir webhook alıcısı kurduk:

  service.webhook.lab: |
    url: http://webhook-receiver.lab-tools.svc.cluster.local:8080/argocd
    headers:
      - name: Content-Type
        value: application/json
  trigger.on-deployed: |
    - description: A sync succeeded and the application is Healthy
      oncePer: app.status.sync.revision
      send: [app-event]
      when: app.status.operationState != nil and app.status.operationState.phase in ['Succeeded'] and app.status.health.status == 'Healthy'
  trigger.on-health-degraded: |
    - description: The application is Degraded
      send: [app-event]
      when: app.status.health.status == 'Degraded'
  # Her generated Application'a tek tek annotation koymadan bütün Bookstore uygulamaları.
  subscriptions: |
    - recipients: [lab]
      triggers: [on-deployed, on-health-degraded]
      selector: component in (api, web)

Subscription'ı ConfigMap'te global tanımladık, çünkü Application'lar ApplicationSet'ten üretiliyor ve annotation'ları template'ten geliyor. oncePer aynı revizyon için ikinci kez bildirim gitmesini engelliyor. Ayar uygulandığı anda her uygulama için bir on-deployed bildirimi geldi (o revizyon için daha önce bildirim yoktu), sonra ada'nın sync'i:

POST /argocd HTTP/1.1
Host: webhook-receiver.lab-tools.svc.cluster.local:8080
User-Agent: Go-http-client/1.1
Content-Length: 176
Content-Type: application/json
Accept-Encoding: gzip

{"app": "bookstore-web-dev", "revision": "f10adb6a69763aaf9279107d78f79985630ed118",
 "sync": "Synced", "health": "Healthy",
 "message": "successfully synced (all tasks run)"}

Argo CD'nin hazır trigger ve template kataloğu da var (on-sync-failed, on-health-degraded, Slack ve Teams mesaj biçimleri); sıfırdan yazmak yerine onu kurup service'i bağlamak çoğu ekip için yeterli. Bildirim olaylar içindir; eğilim ve alarm için metrikler gerekir. Application controller'ın argocd-metrics Service'i (8082) her uygulama için bir argocd_app_info serisi yayınlıyor:

argocd_app_info{autosync_enabled="true",dest_namespace="bookstore-prod",dest_server="https://kubernetes.default.svc",health_status="Healthy",hydrator_status="",name="bookstore-api-prod",namespace="argocd",operation="",phase="Succeeded",project="bookstore",repo="http://git-server.git-server.svc.cluster.local/bookstore-config",sync_status="Synced"} 1

Sync ve health durumu ayrı metrikler değil, bu serinin label'ları. 3.0 eski argocd_app_sync_status, argocd_app_health_status ve argocd_app_created_time metriklerini tamamen kaldırdı; endpoint'te bu adlarla tek satır yok. 2.x'ten kalan dashboard ve alarmların bu label'lara taşınması gerekiyor. hydrator_status label'ı 3.6 ile geldi. Bir Degraded alarmı Prometheus'ta şöyle yazılabilir; lab Prometheus'u Argo CD'yi scrape etmediği için bu kuralı çalıştırmadık:

- alert: ArgoCDAppDegraded
  expr: argocd_app_info{health_status="Degraded"} == 1
  for: 5m
  labels:
    severity: warning
  annotations:
    summary: "{{ $labels.name }} has been Degraded for 5 minutes"

Bunların yanında argocd_app_sync_total, argocd_app_reconcile (reconcile süresi histogram'ı), argocd_cluster_connection_status ve repo-server'ın git isteği metrikleri, Argo CD'nin kendisinin sağlığını gösteriyor. 3.6 ApplicationSet progressive sync için de metrikler ekledi.

Ölçeklemek: HA, Sharding ve Çoklu Cluster

Lab'daki kurulum non-HA install.yaml: her component'ten bir pod, Redis tek. Production'da manifests/ha/install.yaml var: API server ve repo-server birden fazla replica, Redis HAProxy önünde üç replica'lı (Sentinel ile). HA kurulumu pod anti-affinity kuralları yüzünden en az üç node istiyor; tek node'luk kind cluster'ımızda denemedik. Repo-server en çok kaynak isteyen parça: her manifest üretimi bir kustomize build ya da helm template, ve secret çözen plugin'ler bunu ağırlaştırıyor; replica sayısını ve reposerver.parallelism.limit'i önce bu component için ayarla.

Application controller birden fazla cluster yönettiğinde sharding devreye giriyor: StatefulSet replica sayısını artırıp ARGOCD_CONTROLLER_REPLICAS'ı aynı değere getirdiğinde cluster'lar shard'lara bölünüyor; --sharding-method ile legacy, round-robin ya da consistent-hashing seçiliyor. Sharding cluster bazında: tek bir dev cluster'ı yüzlerce uygulamayla tek shard'a düşer. Çoklu cluster'da iki model var: merkezî bir Argo CD'nin bütün cluster'ları yönettiği hub-spoke modeli (tek UI, tek RBAC; ama merkez bütün cluster'ların credential'ını taşıyor) ve her cluster'da kendi Argo CD'si (izolasyon iyi, operasyon yükü fazla). Beşinci yazıdaki cluster generator'ı, hub-spoke modelinde aynı ApplicationSet'i her cluster'a yaymanın yolu.

2.x'ten 3.6'ya Değişenler ve Yükseltme

Argo CD yılda dört minor sürüm çıkarıyor ve yalnız son üç minor patch alıyor. 3.6.0 2026-11-03'te çıktığı için şu an desteklenenler 3.4, 3.5 ve 3.6; 3.3 aynı gün EOL (end of life; destek dışı) oldu. Yani bir kurulumu desteklenir tutmak yaklaşık her altı ayda bir yükseltme demek. 2.x'ten gelen biri için önemli değişiklikler:

Yükseltme yolu her minor'ın upgrade notunu okumak: 3.0'dan 3.6'ya gidiyorsan aradaki altı notun hepsi geçerli. Önce bir yedek; argocd admin export bütün Application'ları, ApplicationSet'leri, project'leri ve Argo CD'nin ConfigMap ve Secret'larını tek bir dosyaya yazıyor (dosya secret içerdiği için Git'e değil, bir kasaya):

argocd admin export -n argocd > argocd-backup.yaml
grep '^kind:' argocd-backup.yaml | sort | uniq -c

   2 kind: AppProject
   8 kind: Application
   1 kind: ApplicationSet
   4 kind: ConfigMap
   2 kind: Secret

Sonra manifest'in tamamı, sürüm sabitlenerek uygulanır. Bu komutu lab'da yeni bir sürümle çalıştırmadık, çünkü 3.6.1 en güncel sürüm; ikinci yazıdaki kurulum komutunun aynısı:

kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/argo-cd/v3.6.1/manifests/install.yaml

Yalnız image'ı değiştirmek yetmez; manifest'teki parametre değişiklikleri kaçar. Argo CD'yi Argo CD ile yönetiyorsan aynı iş URL'deki sürümü değiştiren bir pull request oluyor; önce bir test cluster'ında, sonra production'da.

Üretimde Dikkat

Serinin sonunda GitOps'u "kurduk" demekle "işletiyoruz" demek arasındaki farkı bir kontrol listesi olarak toparlayalım. Bu maddeler bu dokuz yazıda tek tek denediğimiz şeyler:

• Cluster'ın istenen durumunun tamamı Git'te; elle uygulanan tek şey App of Apps root'u (ve bu yazıdan sonra Argo CD'nin ayarları da Git'te).
• Config repo'su uygulama repo'sundan ayrı, ortam başına bir klasör; promotion bir commit ya da pull request, geri almak bir revert.
• CI'da kubeconfig yok; config repo'suna yazan kimlikler sayılı, prod overlay'i branch protection ve CODEOWNERS arkasında.
• Image'lar tag ve digest ile sabit; aynı overlay'e tek yazar (CI ya da Image Updater).
• Secret'lar ya cluster'da çözülüyor (Sealed Secrets, External Secrets Operator) ya da riskleri bilinerek repo-server'da; anahtar yedeği ve felaket provası yapılmış.
• Migration'lar hook ve wave ile sıralı, expand-contract'a uygun; prod sürümleri canary analizinden geçiyor.
• Her Application bir project'te; insanlar SSO'dan, CI süreli token ile geliyor; admin kapalı.
• Degraded ve sync hatası bildirim üretiyor; argocd_app_info üzerinde alarm var; Argo CD son üç minor'ın içinde.

Argo CD her ihtiyaca cevap değil. Flux'a ne zaman bakılır? UI ve merkezî bir kontrol paneli yerine her şeyin Kubernetes nesneleriyle ifade edildiği bir model istiyorsan, çok sayıda cluster'ın her birinin kendi reconciler'ını çalıştırmasını tercih ediyorsan, Helm release'lerini HelmRelease nesneleriyle yönetmek ve OCI (Open Container Initiative; container image standardı) artifact'larını kaynak olarak kullanmak istiyorsan Flux'un toolkit yaklaşımı daha uygun olabilir. İki proje de CNCF'te (Cloud Native Computing Foundation; Kubernetes'in de bağlı olduğu vakıf) graduated; ilk yazıdaki karşılaştırma hâlâ geçerli. Argo CD'nin farkı uygulama merkezli UI'ı, project ve RBAC modeli ve Rollouts gibi aynı ailedeki araçlarla uyumu.

Sık Düşülen Tuzaklar

Argo CD'nin ayarlarını Git'e koyup prune'u açık bırakmak. Bir dosya silindiğinde argocd-cm silinir ve Argo CD'nin kendi ayarları gider.

Admin hesabını SSO'yu doğrulamadan kapatmak.

policy.default: role:readonly bırakmak. Herkes her project'in her uygulamasını, cluster'ları ve repo'ları görür; varsayılan boş olmalı.

2.x'ten 3.x'e upgrade notlarını okumadan geçmek. Log sekmesi kaybolan geliştiriciler, boş kalan dashboard'lar ve ilk sync'te bütün kaynakların yeniden etiketlenmesi bu notlarda yazıyor.

CI'a kişisel hesabın token'ını vermek. Kişi işten ayrıldığında pipeline durur; süresiz bir token sızarsa geri alınması zor olur.

Küçük Bir Deneme

★☆☆ argocd-rbac-cm'e role:bookstore-developer için staging'i sync etme izni ekleyen bir değişikliği bir branch'te hazırla ve merge etmeden önce argocd admin settings rbac can ile dosya üzerinde doğrula.

★★☆ Argo CD'nin hazır notifications kataloğunu kur, on-sync-failed trigger'ını lab webhook'una bağla ve dev'de bilerek başarısız bir sync üret (olmayan bir image tag'i). Gelen mesajın içeriğini kendi template'inle karşılaştır.

★★★ Argo CD'nin kendisini bir Application ile yönet: sürümü sabitlenmiş install.yaml'ı resource olarak alan bir kustomization.yaml, yedinci yazıdaki repo-server patch'i ve ServerSideApply=true. Sonra 3.6.1'den bir sonraki patch sürümüne geçişi bir pull request olarak dene.

Bu yazıyla GitOps ve Argo CD serisi bitiyor. Push tabanlı bir pipeline'ın göremediği drift'ten başladık; Argo CD'yi kurduk, sync ve health'i ayırdık, migration'ı hook'larla sıraya koyduk, altı uygulamayı tek bir ApplicationSet'ten ürettik, CI'ı Git üzerinden promotion yapan bir parçaya çevirdik, secret'ları Git'e güvenle koyduk, prod sürümlerini metrikle korunan canary'lerden geçirdik ve en son Argo CD'nin kendisini bir ekibin işletebileceği hâle getirdik. Buradan sonrası Helm serisinde: Argo CD'nin source tipi olarak yalnız kenarından geçtiğimiz Helm chart'larını orada baştan yazıyoruz.