1. Giriş

Kubernetes dünyasında container'ları, pod'ları, servisleri ve kaynakları yönetmek için en temel araç kubectl'dir. Hem geliştiriciler hem de platform mühendisleri günlük operasyon, hata ayıklama ve dağıtım süreçlerinde kubectl'e güvenir. Bu rehber, sık kullanılan kubectl komutlarını, örneklerini ve "ne zaman" kullanılmaları gerektiğini mühendis bakış açısıyla açıklar. Amacımız; gerçek dünya senaryolarında hızlıca uygulanabilecek, referans niteliğinde bir kaynak sunmaktır.

Neden önemli? Kubernetes kümesi karmaşıktır: node'lar, ağ, depolama, gizli anahtarlar ve uygulama yaşam döngüsü bir arada yürütülür. Kubectl size bu karmaşıklığı sorgulama, analiz etme ve kontrol etme gücü verir. Ancak yanlış kullanılırsa veya yetersiz bilgiyle çalışılırsa, tüm servisleri etkileyen hatalara yol açabilir. Bu yüzden her komutun ne yaptığı ve hangi bağlamda güvenle kullanılacağı bilinmelidir.

2. Kavramsal Temeller

kubectl Nedir?

kubectl, Kubernetes API server ile konuşan komut satırı aracıdır. Kaynak oluşturma (create/apply), okuma (get/describe), güncelleme (apply/patch), silme (delete) ve debug (logs/exec/port-forward) gibi temel işlevleri sağlar. Arka planda API çağrıları gerçekleştirir ve çıktıları insan okunur veya makine okunur (JSON/YAML) formatta döndürebilir.

Temel Terminoloji

• Context: Kubectl'in hangi küme (cluster), hangi kullanıcı ve namespace ile konuştuğunu belirten yapı.
• Namespace: Kaynakları izole etmek için kullanılan mantıksal bölüm.
• Resource: Pod, Deployment, Service, ConfigMap, Secret, PersistentVolumeClaim gibi Kubernetes nesneleri.
• Label & Selector: Kaynakları etiketleme ve seçme mekanizması; sorgulama ve operasyonlarda kullanılır.

Ne Zaman Kubectl Kullanılır?

kubectl aşağıdaki durumlarda kullanılmalıdır:

• Hızlı durum kontrolleri (örn. pod sağlığı, node durumu).
• Debugging: log toplama, pod içine bağlanma (exec), port forward.
• Geçici müdahaleler: ölçeklendirme, rollout kontrolü, rollback.
• Resource yönetimi: manifest apply/delete, patching küçük değişiklikler.
• CI/CD dışında acil operasyona ihtiyaç duyulduğunda (sorumluluk ile).

3. Nasıl Çalışır? — Komut Kategorileri ve Örnekler

3.1. Kubectl Konfigürasyon ve Context İşlemleri

Context ve config yönetimi, birden fazla cluster ile çalışırken kritik öneme sahiptir. Yanlış context ile yapılan operasyonlar prod ortamda kesintiye yol açabilir; dolayısıyla aşağıdaki komutlar her operasyondan önce kontrol edilmelidir.

1) Kubeconfig dosyasını kontrol etme

kubectl config view --minify

Ne zaman kullanılır: Mevcut kubeconfig içeriğini hızlıca görmek ve active context detaylarını doğrulamak için.

2) Aktif context'i görüntüleme

kubectl config current-context

Ne zaman kullanılır: Hangi cluster ve kullanıcı ile çalıştığınızı teyit etmek istediğinizde.

3) Context değiştirme

kubectl config use-context my-cluster-context

Ne zaman kullanılır: Farklı bir cluster üzerinde çalışmaya geçerken.

4) Kubeconfig içinde context tanımlama

kubectl config set-context dev --cluster=dev-cluster --user=dev-user --namespace=development

Ne zaman kullanılır: Özel bir namespace ile birlikte yeni bir context hazırlarken.

3.2. Temel Okuma Komutları (get / describe / explain)

1) Kaynakları listeleme

kubectl get pods
kubectl get deployments
kubectl get svc --all-namespaces

Ne zaman kullanılır: Kümenin genel sağlık durumu ve uygulama bileşenlerinin çalışıp çalışmadığını görmek için. -o wide daha fazla bilgi, -n belirli namespace için kullanılır. --show-labels etiketleri gösterir.

2) Kaynağı detaylı inceleme

kubectl describe pod my-pod -n my-namespace

Ne zaman kullanılır: Pod neden CrashLoopBackOff yapıyor, hangi event'ler oluştu gibi detaylar gerektiğinde. describe; event'ler, container statuses, mount ve env detaylarını gösterir.

3) JSON/YAML çıktı alma

kubectl get deployment my-deploy -o yaml
kubectl get pod my-pod -o json

Ne zaman kullanılır: Manifesti almak, incelemek veya başka cluster'a reapply etmek için; otomasyon ve scripting senaryolarında kullanılır.

4) Resource açıklamasını öğrenme

kubectl explain deployment.spec.replicas

Ne zaman kullanılır: API alanlarını ve schema'yı hızlıca öğrenmek, manifest yazarken hata yapmamak için.

3.3. Oluşturma ve Güncelleme (apply / create / patch / replace)

1) Manifest ile uygulama

kubectl apply -f deployment.yaml

Ne zaman kullanılır: Declaration‑based (GitOps) yaklaşımla kaynakları oluşturmak veya güncellemek istediğinizde. apply idempotent davranır ve mevcut nesnelerle farkları uygular.

2) Tek satırlık hızlı oluşturma

kubectl create deployment nginx --image=nginx
kubectl create namespace staging

Ne zaman kullanılır: Hızlı testler veya ad hoc kaynak oluşturma için; production için manifest tercih edilir.

3) Küçük güncelleme (patch)

kubectl patch deployment my-deploy -p '{"spec":{"replicas":5}}'
# JSON patch ile örnek
kubectl patch deployment my-deploy --type='json' -p='[{"op":"replace","path":"/spec/replicas","value":5}]'

Ne zaman kullanılır: Hızlı, küçük değişiklikler (ör. ölçeklendirme, image tag değiştirme) için; büyük değişiklikler manifest üzerinden yapılmalıdır.

4) Bütün nesneyi değiştirme

kubectl replace -f new-deployment.yaml

Ne zaman kullanılır: Kaynağı tamamen yeni bir manifest ile değiştirmek istediğinizde. replace mevcut nesneyi silip yeniden oluşturur, dikkatli kullanılmalı.

3.4. Ölçeklendirme ve Rollout Yönetimi

1) Ölçeklendirme

kubectl scale deployment my-deploy --replicas=10

Ne zaman kullanılır: Ani trafik artışlarında veya testlerde hızlı kaynak artırımı gerektiğinde. Otomatik ölçekleyici (HPA) yoksa manuel kullanılır.

2) Rollout durumu kontrol etme

kubectl rollout status deployment/my-deploy

Ne zaman kullanılır: Yeni image deploy ederken rollout'un tamamlanıp tamamlanmadığını görmek için.

3) Rollout geri alma

kubectl rollout undo deployment/my-deploy

Ne zaman kullanılır: Yeni sürüm kritik sorunlara yol açarsa bir önceki sağlıklı sürüme geri dönmek için.

3.5. Loglar, Exec ve Debug

1) Pod loglarını alma

kubectl logs my-pod
kubectl logs -f my-pod # stream

Ne zaman kullanılır: Container içinde neler olduğunu görmek, hataları tespit etmek için. Multi-container pod'larda -c <container-name> ile container seçilir.

2) Önceki logu alma (crash sonrası)

kubectl logs --previous my-pod

Ne zaman kullanılır: Pod crash attıktan sonra önceki container ayağına ait logları görmek için.

3) Pod içinde komut çalıştırma

kubectl exec -it my-pod -- /bin/sh
kubectl exec -it my-pod -c worker -- bash

Ne zaman kullanılır: Container içine girip dosya sistemi, ağ veya prosesleri incelemek gerektiğinde. Prod ortamda dikkatli kullanılmalıdır.

4) Port forwarding

kubectl port-forward svc/my-service 8080:80

Ne zaman kullanılır: Lokal makineden cluster içindeki servise erişmek, debug veya ad-hoc testler için kullanılır. Uzun süreli üretim kullanımı önerilmez.

3.6. Dosya ve Manifest İşlemleri

1) Kaynakları dosyaya kaydetme

kubectl get deploy my-deploy -o yaml > my-deploy.yaml

Ne zaman kullanılır: Mevcut konfigürasyonu almak, versiyonlama veya inceleme yapmak için.

2) Kaynakları klonlama / export

kubectl get all -n my-namespace -o yaml > namespace-export.yaml

Ne zaman kullanılır: Taşıma veya yedekleme amacıyla namespace içeriğini dışa aktarmak istendiğinde. Dikkat: secret'lar açık metin olarak çıkarılacaktır.

3.7. Kaynak Seçimi ve Etiketleme

1) Label ile seçme

kubectl get pods -l app=myapp -n production

Ne zaman kullanılır: Belirli uygulama grubu veya sürüme ait kaynakları hedeflemek için. Etiketleme iyi bir operasyon pratiğidir.

2) Etiket ekleme/çıkarma

kubectl label pod my-pod env=staging
kubectl label pod my-pod env-

Ne zaman kullanılır: Dinamik routing, monitor veya policy hedeflemesi yapmak istendiğinde.

3.8. Güvenlik ve RBAC

1) Yetki kontrolü (can‑i sorgusu)

kubectl auth can-i create deployment --namespace=prod

Ne zaman kullanılır: Bir işlemi yapmadan önce yetkiniz olup olmadığını doğrulamak için—CI/CD pipeline'larında faydalıdır.

2) ServiceAccount token'ı ile test

kubectl run -it --rm --serviceaccount=sa-name debug --image=alpine -- sh

Ne zaman kullanılır: Bir service account'un izinlerini doğrudan test etmek istediğinizde.

3.9. Node Yönetimi ve Health

1) Node listesini alma

kubectl get nodes -o wide

Ne zaman kullanılır: Node'ların IP, rol ve hazır (Ready) durumunu görmek istediğinizde.

2) Node bakım modu (cordon & drain)

kubectl cordon node-1
kubectl drain node-1 --ignore-daemonsets --delete-emptydir-data

Ne zaman kullanılır: Node üzerinde bakım veya güncelleme yapılacaksa, yeni podların schedule edilmesini engellemek (cordon) ve mevcut podları güvenli şekilde başka node'lara taşımak (drain) için.

3) Node'u tekrar açma

kubectl uncordon node-1

Ne zaman kullanılır: Bakım sonrası node'u tekrar workload kabul edecek şekilde açarken kullanılır.

3.10. İzleme ve Performans

1) Kaynak kullanımı (top)

kubectl top nodes
kubectl top pods -n my-namespace

Ne zaman kullanılır: CPU ve bellek kullanımını görmek, hangi pod'ların kaynakları tükettiğini tespit etmek için. metrics-server kurulu olması gerekir.

2) Event'leri izleme

kubectl get events -n my-namespace --sort-by='.metadata.creationTimestamp'

Ne zaman kullanılır: Kısa süre önce oluşmuş hata ve uyarıları takip etmek için.

3.11. İleri Seviye: Kustomize, Krew ve Plugin'ler

1) Kustomize ile apply

kubectl apply -k overlays/prod

Ne zaman kullanılır: Ortak base manifest'ları overlay'lerle özelleştirip environment bazlı deploy yapmak için.

2) Kubectl plugin ve completion

kubectl krew install ctx
kubectl plugin list

Ne zaman kullanılır: Bazı görevleri kolaylaştıran eklentileri (krew) kullanmak ve komut tamamlama ile hız kazanmak için.

3) Dry‑run ve validation

kubectl apply -f manifest.yaml --dry-run=client
kubectl apply -f manifest.yaml --server-side --dry-run=server

Ne zaman kullanılır: Değişiklikleri uygulamadan önce doğrulamak, CI süreçlerinde manifest validasyonu yapmak için.

4. Gerçek Dünya Senaryoları

Hızlı Müdahale: CrashLoopBackOff

Senaryo: Production pod CrashLoopBackOff'a girdi. İzlenecek adımlar:

1. Pod listesini alın: kubectl get pods -n prod
2. Describe ile event'leri kontrol edin: kubectl describe pod my-pod -n prod
3. Logları inceleyin: kubectl logs my-pod -n prod -c container-name --previous
4. Gerekirse pod içine girip debug yapın: kubectl exec -it my-pod -n prod -- /bin/sh

Ne zaman kullanılır: Acil durumlarda sorunun kök nedenini hızlıca bulup geçici çözüm uygulamak için. Sonrasında kalıcı çözüm manifest üzerinden uygulanmalıdır.

Rolling Update Tüketim Testi

Senaryo: Yeni image deploy ediliyor, p99 latency artmadan rollout tamamlanmalı. İzlenecek adımlar:

1. Rollout başlatın: kubectl set image deployment/my-deploy my-container=myimage:v2
2. Rollout durumunu izleyin: kubectl rollout status deployment/my-deploy
3. Shadow trafikte test edin; sonuçları gözlemleyin.

Maintenance: Node Drain & Upgrade

Senaryo: Node üzerinde kernel güncellemesi gerekiyor. İzlenecek adımlar:

1. Node'u cordon ile izole edin: kubectl cordon node-1
2. Pod'ları güvenli şekilde tahliye edin: kubectl drain node-1 --ignore-daemonsets --delete-emptydir-data
3. Upgrade ve test sonrası uncordon: kubectl uncordon node-1

5. Avantajlar ve Sınırlamalar

Avantajlar

• Hızlı etkileşim: CLI ile anında durum keşfi ve müdahale.
• Scriptlenebilirlik: Otomasyon ve CI/CD süreçlerine kolay entegrasyon.
• Geniş fonksiyonellik: Diagnose, apply, scale, debug ve daha fazlası tek bir araçta.

Sınırlamalar

• Yanlış context/namespace ile tehlikeli operasyon riski.
• Yetersiz logging veya yanlış filtreleme ile eksik bilgi alınması.
• Production'da uzun süreli veya otomatik görevler için doğrudan CLI kullanımı yerine CI/CD tercih edilmelidir.

6. Alternatifler ve Karşılaştırma

7. En İyi Pratikler

Production Kullanımı

• Her zaman aktif context ve namespace'i doğrulayın: kubectl config current-context ve kubectl config view --minify.
• Manifest tabanlı deploy (GitOps) tercih edin; kubectl apply ile sürümleme yapın.
• CLI ile yapılan değişiklikleri audit loglarına alın; RBAC politikalarını sıkılaştırın.

Performans Optimizasyonu

• kubectl top ile kaynak tüketimini düzenli izleyin ve HPA/VPA ile otomasyon kurun.
• Batch job'lar için CronJob ve ResourceQuota kullanın.

Güvenlik

• CI pipeline'larından önce --dry-run=server validasyonları yapın.
• Yetkilendirme testleri için kubectl auth can-i kullanın.

8. Sık Yapılan Hatalar

• Context kontrolü atlanması: Yanlış cluster'da destructive komutlar çalıştırma riski.
• Secrets'ı düz metin export etmek: kubectl get secret -o yaml komutu hassas bilgileri açığa çıkarır; base64 decode dikkatli kullanılmalı.
• Long‑lived exec oturumları: Prod üzerinde interaktif shell açık bırakmak güvenlik riski oluşturur.

9. Gelecek Trendler

1. Akıllı CLI ve otomasyon: AI destekli komut önerileri ve otomatik onay/rollback mekanizmaları gelişecek.
2. Declarative ops artışı: İnsan müdahalesini azaltan GitOps/Policy driven yaklaşımlar yaygınlaşacak.
3. Gelişmiş debugging araçları: Dağıtık trace ve pod‑level debugging daha entegre hale gelecek.

Ek Bölümler

Sık Sorulan Sorular (FAQ)

1. kubectl ile tüm cluster'ı siler miyim?

   Teorik olarak bazı delete komutlarıyla büyük etkiler yaratabilirsiniz; bu yüzden destructive komutlarda --dry-run ve hedef context/namespace kontrolü zorunludur.

2. kubectl apply mi create mi?

   Production için apply tercih edilir; idempotent davranış ve deklaratif kullanım sağlar. create ad-hoc testlerde kullanışlıdır.

3. Pod logları neden eksik?

   Log rotasyonu, sidecar log driver veya logging agent konfigürasyonu nedeniyle eksik olabilir. kubectl logs sadece container runtime'dan gelen logları gösterir.

4. Namespace değişimini nasıl sabitleyebilirim?

   kubectl config set-context --current --namespace=dev ile current context için default namespace ayarlanabilir.

5. kubectl ile gizli bilgileri nasıl güvenli kullanırım?

   Secrets'ı manifestte düz metin tutmayın; KMS/SealedSecrets veya External Secrets kullanın.

6. Hatalı rollout'u nasıl geri alırım?

   kubectl rollout undo deployment/my-deploy komutu ile son sağlıklı sürüme dönülebilir.

7. kubectl exec güvenli mi?

   Kısa süreli debug amaçlı güvenlidir; prod ortamlarında erişim ve audit gerektirir.

8. kubectl yerine GUI mi kullanmalıyım?

   GUI öğrenme ve hızlı gözlem için faydalıdır; ancak scriptlenebilirlik ve kesin kontrol için kubectl vazgeçilmezdir.

Anahtar Kavramlar

Context

Kubectl'in hangi cluster/user/namespace ile konuştuğunu tanımlar.

Namespace

Kaynak izolasyonu için kullanılan mantıksal bölüm.

Label

Kaynakları işaretlemek ve seçmek için kullanılan anahtar-değer çiftleri.

Drain

Node üzerindeki pod'ları güvenli şekilde taşımak için kullanılan işlem.

Öğrenme Yol Haritası

1. Temel: Kubernetes kavramları, pod/deployment/service anlayışı.
2. Kubectl: Temel komutlar, context yönetimi ve manifest uygulamaları.
3. Debugging: logs, exec, port-forward ve describe ile sorun çözümü.
4. İleri Seviye: Kustomize, krew pluginleri, RBAC, güvenlik en iyi uygulamaları.
5. Pratik: Gerçek cluster üzerinde küçük change'ler yaparak öğrenin; GitOps ile entegrasyon kurun.