Argo CD ile GitOps: Kubernetes Dağıtım Rehberi
Aziz Özdemiroğlu

Kubernetes'e kubectl apply ile elle dağıtım yapmak, kimin neyi ne zaman değiştirdiğini kaybetmenin en hızlı yoludur. GitOps bu sorunu tersine çevirir: kümenin istenen durumu Git'te tutulur, bir denetleyici (controller) kümeyi sürekli bu duruma getirir. Bu rehberde GitOps'un mantığını, Argo CD kurulumunu, ilk uygulamanızı, ortam yönetimini ve güvenlik ayarlarını adım adım anlatıyoruz.
Kısaca
- GitOps: İstenen durum Git'te, çekme (pull) tabanlı bir ajan kümeyi bu duruma eşitler. CI hattının kümeye yazma yetkisi olmaz.
- Argo CD: Kubernetes için en yaygın GitOps aracı. Web arayüzü, CLI ve
Applicationadlı özel kaynakla çalışır. - Temel kavramlar: Synced/OutOfSync (Git ile küme aynı mı?), Healthy/Degraded (kaynaklar çalışıyor mu?), self-heal ve prune.
- Ortamlar için uygulama kodu ile yapılandırma deposunu ayırın. Kustomize overlay veya Helm values ile ortam farklarını yönetin.
- Güvenlik: varsayılan admin parolasını değiştirin, SSO kullanın, AppProject ile kaynak ve hedefleri kısıtlayın.
GitOps nedir, neden "pull"?
Geleneksel (push) CI/CD
Geliştirici → CI → kubectl apply → Küme (CI'ın küme yönetici yetkisi var)
GitOps (pull)
Geliştirici → PR → Yapılandırma deposu (Git)
▲
Argo CD (küme içinde) ── sürekli karşılaştırır ve eşitler ──► Küme
| Avantaj | Açıklama |
|---|---|
| Denetim izi | Her değişiklik bir commit ve PR; kim, ne zaman, neden belli |
| Geri alma | git revert ile önceki duruma dönüş |
| Kayma (drift) tespiti | Biri kümede elle değişiklik yaparsa Argo CD "OutOfSync" gösterir |
| Daha az yetki | CI sistemi küme kimlik bilgisi tutmaz |
| Felaket kurtarma | Yeni küme + Argo CD = aynı durum |
Kurulum
kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
# Pod'ların hazır olmasını bekleyin
kubectl -n argocd rollout status deploy/argocd-server
# İlk admin parolası
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d; echo
# Arayüze yerel erişim
kubectl -n argocd port-forward svc/argocd-server 8080:443
Üretimde stable yerine belirli bir sürüm etiketinin manifestini kullanın ve kurulumu da Git'te tutun (Argo CD kendini de yönetebilir).
İlk girişten sonra:
argocd login localhost:8080
argocd account update-password
kubectl -n argocd delete secret argocd-initial-admin-secret
Depo yapısı
Uygulama kodu ile dağıtım yapılandırmasını ayrı depolarda tutmak yaygın ve önerilen bir yaklaşımdır:
yapilandirma-deposu/
├── apps/
│ └── blog/
│ ├── base/
│ │ ├── deployment.yaml
│ │ ├── service.yaml
│ │ └── kustomization.yaml
│ └── overlays/
│ ├── staging/
│ │ └── kustomization.yaml # replika: 1, imaj: blog:1.8.0-rc1
│ └── production/
│ └── kustomization.yaml # replika: 3, imaj: blog:1.7.2
└── argocd/
├── projects/blog.yaml
└── applications/
├── blog-staging.yaml
└── blog-production.yaml
Neden ayrı depo? Uygulama deposundaki her commit dağıtım tetiklemez, dağıtım yetkisi farklı kişilere verilebilir ve CI imaj etiketini güncellemek için yapılandırma deposuna dar kapsamlı bir PR açar.
İlk Application
# argocd/applications/blog-production.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: blog-production
namespace: argocd
spec:
project: blog
source:
repoURL: https://github.com/ornek-org/yapilandirma-deposu.git
targetRevision: main
path: apps/blog/overlays/production
destination:
server: https://kubernetes.default.svc
namespace: blog
syncPolicy:
automated:
prune: true # Git'ten silinen kaynakları kümeden de sil
selfHeal: true # Kümedeki elle değişiklikleri geri al
syncOptions:
- CreateNamespace=true
kubectl apply -f argocd/applications/blog-production.yaml
argocd app get blog-production
Durumları okumak
| Durum | Anlamı | Ne yapmalı |
|---|---|---|
| Synced + Healthy | Git ile küme aynı, kaynaklar sağlıklı | — |
| OutOfSync | Git ile küme farklı | Fark ekranını (diff) inceleyin, sync edin |
| Progressing | Dağıtım sürüyor | Rollout'u bekleyin |
| Degraded | Kaynaklar sağlıksız (CrashLoop, hazır olmayan pod) | Olayları ve günlükleri inceleyin |
| Missing | Kaynak Git'te var, kümede yok | Sync edin |
Ortamlar arası terfi (promotion)
- CI yeni imajı derler, imzalar ve kayıt defterine iter (
blog:1.8.0). - CI, yapılandırma deposunda staging overlay'indeki imaj etiketini güncelleyen bir PR açar.
- PR birleşince Argo CD staging'i günceller. Testler geçer.
- Production overlay'ini güncelleyen ikinci PR, onay gerektiren dal korumasıyla birleştirilir.
# apps/blog/overlays/production/kustomization.yaml
resources:
- ../../base
replicas:
- name: blog
count: 3
images:
- name: ghcr.io/ornek-org/blog
newTag: "1.7.2"
Bu akışta sürüm terfisi bir PR onayıdır; kimin neyi üretime aldığı Git geçmişinde kalır.
Güvenlik ayarları
AppProject ile sınırlar
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
name: blog
namespace: argocd
spec:
sourceRepos:
- https://github.com/ornek-org/yapilandirma-deposu.git
destinations:
- server: https://kubernetes.default.svc
namespace: blog
clusterResourceWhitelist: [] # küme genelinde kaynak (ClusterRole vb.) oluşturamaz
namespaceResourceBlacklist:
- group: ""
kind: ResourceQuota
Diğer öneriler
- Admin hesabını devre dışı bırakın, SSO (OIDC) ile giriş yapın
- RBAC ile ekiplere yalnızca kendi projelerinde sync yetkisi verin
- Depo erişimi için salt okunur deploy key veya GitHub App kullanın
- Sırları Git'e düz metin koymayın: Sealed Secrets, SOPS veya External Secrets Operator kullanın
- Argo CD arayüzünü internete açmayın veya kimlik doğrulayan bir proxy arkasına alın
- Argo CD sürümünü güncel tutun, güvenlik bültenlerini izleyin
Çok sayıda uygulama: App of Apps ve ApplicationSet
Uygulama sayısı arttıkça her biri için elle Application oluşturmak zorlaşır. İki yaygın desen var:
- App of Apps: Tek bir "kök" Application,
argocd/applications/dizinindeki diğer tüm Application tanımlarını yönetir. Yeni uygulama eklemek, dizine bir YAML dosyası eklemekten ibarettir. - ApplicationSet: Bir şablondan ve bir üreticiden (generator) çok sayıda Application üretir. Örneğin her ortam dizini veya her küme için otomatik uygulama:
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
name: blog-ortamlar
namespace: argocd
spec:
generators:
- git:
repoURL: https://github.com/ornek-org/yapilandirma-deposu.git
revision: main
directories:
- path: apps/blog/overlays/*
template:
metadata:
name: 'blog-{{path.basename}}'
spec:
project: blog
source:
repoURL: https://github.com/ornek-org/yapilandirma-deposu.git
targetRevision: main
path: '{{path}}'
destination:
server: https://kubernetes.default.svc
namespace: 'blog-{{path.basename}}'
Yeni bir overlay dizini eklendiğinde ilgili Application otomatik oluşur.
Sık yapılan hatalar
| Hata | Sonuç | Çözüm |
|---|---|---|
selfHeal açıkken kümede elle düzeltme |
Değişiklik birkaç dakika içinde geri alınır | Düzeltmeyi Git'e commit edin |
prune olmadan çalışmak |
Git'ten silinen kaynaklar kümede kalır | prune: true + dikkatli incele |
| HPA kullanırken replika sayısını Git'te sabitlemek | Sürekli OutOfSync | ignoreDifferences ile spec.replicas alanını hariç tutun |
latest imaj etiketi |
Ne çalıştığı belirsiz, geri alma imkânsız | Değişmez sürüm etiketi veya digest |
Sonuç
GitOps, Kubernetes dağıtımlarını "kim ne yaptı?" belirsizliğinden çıkarıp denetlenebilir, geri alınabilir bir sürece dönüştürür. Argo CD ile küçük başlayın: tek bir uygulama, tek bir ortam, otomatik sync kapalı. Fark ekranına ve sync akışına alıştıktan sonra self-heal ve prune'u açın, ardından ortam terfisini PR akışına bağlayın.




