Kubernetes YAML'dan Mimari Diyagrama

Bir düzine manifest içeren bir namespace'i deploy etmek kolaydır, anlatmak ise zor. YAML, API sunucusunun ihtiyaç duyduğu her şeyi söyler; ama yeni bir ekip arkadaşına hangi Service'in hangi Deployment'ın önünde durduğunu ya da checkout API'sinin neden payments ile konuştuğunu söylemez. Bu rehber, Kubernetes YAML'dan diyagrama elle geçmek için tekrarlanabilir bir yöntem sunuyor: nesnelerin envanterini çıkarın, ilişkileri belirli alanlardan okuyun, neyi dışarıda bırakacağınıza karar verin, yerleşimi kurun ve diyagramı güncel tutun. Sonunda aynı sonucu Archboard'da Kubernetes paketiyle yeniden çiziyoruz.

Burada sihir yok: alanları okuyup kenarları çiziyorsunuz. Mesele de bu. Diyagram niyeti yakalamalı ve niyet, sizin eklediğiniz bir şeydir.

Adım 1: Nesnelerin envanterini çıkarın

Şablonlarla değil, render edilmiş manifestlerle başlayın. Helm ya da Kustomize kullanıyorsanız, gerçekte neyin uygulandığını görmek için önce render edin:

helm template shop ./charts/shop -f values-prod.yaml > rendered.yaml
kubectl kustomize overlays/prod > rendered.yaml

İş yükü zaten çalışıyorsa cluster'a sorun ve nesne türlerini açıkça belirtin:

kubectl get deploy,svc,ing,cm,secret,pvc,hpa,networkpolicy -n shop

kubectl get all komutuna güvenmeyin. all kategorisi Pod, Service, Deployment, ReplicaSet, StatefulSet, DaemonSet, Job, CronJob ve HPA'ları kapsar; ancak Ingress, ConfigMap, Secret, PVC, NetworkPolicy ve ServiceAccount'ı atlar. Bunların birçoğu tam da çizmek istediğiniz kenarları taşır.

İlişki barındıran nesneler için tam spec'i alın:

kubectl get ingress -n shop -o yaml
kubectl get svc -n shop -o custom-columns=NAME:.metadata.name,SELECTOR:.spec.selector
kubectl get pods -n shop --show-labels

Envanteri düz bir liste olarak yazın: tür, ad, namespace. Bu liste, çizim için kontrol listenizdir.

Örnek: tek bir servis için Kubernetes YAML'dan diyagrama

shop namespace'indeki tek bir servis için küçük ama tipik bir set:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: checkout-api
  namespace: shop
spec:
  selector:
    matchLabels:
      app: checkout-api
  template:
    metadata:
      labels:
        app: checkout-api
        tier: backend
    spec:
      containers:
        - name: api
          image: registry.example.com/shop/checkout-api:1.14.2
          ports:
            - containerPort: 8080
          resources:
            requests:
              cpu: 250m
          envFrom:
            - configMapRef:
                name: checkout-config
            - secretRef:
                name: checkout-db-credentials
---
apiVersion: v1
kind: Service
metadata:
  name: checkout-api
  namespace: shop
spec:
  selector:
    app: checkout-api
  ports:
    - port: 80
      targetPort: 8080
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: shop
  namespace: shop
spec:
  ingressClassName: nginx
  rules:
    - host: shop.example.com
      http:
        paths:
          - path: /api/checkout
            pathType: Prefix
            backend:
              service:
                name: checkout-api
                port:
                  number: 80
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: checkout-config
  namespace: shop
data:
  PAYMENTS_URL: http://payments.shop.svc.cluster.local
  LOG_LEVEL: info
---
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: checkout-api
  namespace: shop
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: checkout-api
  minReplicas: 3
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70

Beş nesne, referans verilen ama gösterilmeyen bir Secret ve bir yapılandırma değerinin içine saklanmış bir bağımlılık.

Adım 2: İlişkileri alanlarda bulun

Kubernetes nesneleri birbirine nadiren ID ile işaret eder. Adla ya da daha sık olarak label ile işaret ederler. Label'lar ve selector'lar yapıştırıcıdır; başlamadan önce Kubernetes labels ve selectors belgelerini yeniden okumaya değer.

Listeyi trafik sırasıyla dolaşın:

• Ingress → Service. Her path'teki backend.service.name ve port.number Service'i doğrudan adlandırır. Host ve path, kenar etiketi olur.
• Service → Deployment. Bir Service hiçbir zaman Deployment'ı adıyla anmaz. spec.selector alanı, Deployment'ın spec.template.metadata.labels içindeki label'larla eşleşir. Burada app: checkout-api eşleşiyor, o halde kenarı çizin. Emin değilseniz kubectl get endpointslices -n shop, Service'in gerçekte seçtiği Pod adreslerini gösterir; hiç endpoint yoksa selector hiçbir şeyle eşleşmiyor ya da eşleşen Pod'ların henüz IP'si yok demektir.
• Deployment → ConfigMap / Secret / PVC. envFrom, env[].valueFrom ve volumes[] (configMap, secret, persistentVolumeClaim.claimName) alanlarına bakın.
• HPA → Deployment. spec.scaleTargetRef hedefi adlandırır.
• NetworkPolicy. spec.podSelector koruduğu Pod'ları seçer; ingress[].from onlarla kimin konuşabileceğini, egress[].to ise nereye bağlanabileceklerini belirtir.
• Gizli bağımlılıklar. PAYMENTS_URL, payments.shop.svc.cluster.local adresini gösterir. Checkout'u payments'a bağlayan bir alan yok, ama çağrı gerçek. Araçların kaçırdığı ve insanların en çok ihtiyaç duyduğu kenar budur.

YAML alanından diyagram öğesine

Adım 3: Neyi dışarıda bırakacağınıza karar verin

Her şeyi gösteren bir diyagram hiçbir şey göstermez. İşe yarayan kurallar:

• Replica sayıları kutu değil, etikettir. Tek bir Deployment düğümü çizin ve üzerine 3–10 replicas (HPA) yazın. Üç özdeş Pod kutusu gürültü ekler ve HPA ölçeklendiği anda yanlış olur.
• ReplicaSet'leri gizleyin. Bunlar rollout'ların bir uygulama ayrıntısıdır.
• Pod'ları yalnızca önemli olduklarında çizin, örneğin bağımsız Pod'lar için ya da Node'lara zamanlamayı anlatırken.
• Standart kalıpları daraltın. ServiceAccount'lar, varsayılan RBAC ve image pull Secret'ları genellikle tuvale değil, bir nota aittir.
• Bir kararı açıklayanı tutun. Checkout'un veritabanına doğrudan erişememesinin nedeni bir NetworkPolicy ise, o diyagramda kalır.

Adım 4: Yerleşimi kurun

Kuzey-güney trafiğini soldan sağa yerleştirin: istemciler → Ingress → Service → Deployment → alt akıştaki Service'ler ve veri depoları. Yapılandırma (ConfigMap, Secret) beslediği iş yükünün altına, ölçekleme (HPA) üstüne gelir. Her namespace'i bir çerçeve olarak çizin; böylece namespace'ler arası çağrılar çerçeveden çıkan kenarlar olarak öne çıkar. Kenarları yalnızca okla değil, protokol ve portla etiketleyin.

Otomatik görselleştiriciler ve çizilmiş diyagram

Ekosistemdeki bazı araçlar canlı cluster durumunu API sunucusundan okuyup bir grafik olarak gösterir. Şu anda neyin çalıştığı konusunda doğrudurlar ve hata ayıklarken faydalıdırlar. Bedeli şu: her ReplicaSet'i, Pod'u ve endpoint'i gösterirler, bir ortam değişkeninde yaşayan bağımlılığı göremezler ve bir şeyin neden var olduğu ya da neyin planlandığı gibi bir niyet taşımazlar. Çizilmiş bir diyagram daha az eksiksizdir ama onboarding, tasarım incelemeleri ve olay bağlamı için daha kullanışlıdır. Birçok ekip ikisini birlikte kullanır.

Adım 5: Güncel tutun

Bir diyagram, ancak manifestlerle birlikte değişiyorsa güvenilirdir:

• Diyagram dosyasını manifestlerin yanında saklayın ve aynı pull request'te inceleyin.
• PR şablonuna bir satır ekleyin: "Bir Ingress, Service selector, HPA ya da NetworkPolicy değişiyor mu? Diyagramı güncelleyin."
• Periyodik incelemelerde 1. adımdaki envanter komutlarını yeniden çalıştırın ve çizimle karşılaştırın.

Örneği Archboard'da yeniden oluşturmak

Archboard'da az önce çıkardığınız envanterden yola çıkarak, diyagrama neyin gireceğine karar vererek ve Kubernetes türleriyle eşleşen node'lar kullanarak çizersiniz:

1. Google ya da GitHub ile giriş yapın ve bir diyagram oluşturun.
2. Kubernetes paketinden bir Namespace ekleyin. Çerçeve olarak çizilir; adını shop koyun.
3. Çerçevenin dışında, solda istemciler için bir Core Box ya da Text ekleyin.
4. Çerçevenin içine Ingress, Service ve Deployment'ı soldan sağa yerleştirin. Port'larını bağlayın ve kenarları shop.example.com/api/checkout ve 80 → 8080 olarak etiketleyin.
5. Deployment'ın altına ConfigMap ve Secret ekleyip bağlayın. Üstüne 3–10, CPU 70% etiketli bir HPA ekleyin.
6. payments için ikinci bir Service ekleyin ve Deployment'tan bağlayın; böylece gizli bağımlılık görünür olur.
7. Tuvale, çitli bir kod bloğundaki önemli YAML parçasını ya da kısa bir "neden" notunu içeren bir Markdown bloğu koyun.
8. Diyagramı JSON olarak dışa aktarın ve manifestlerin yanına commit edin; README için SVG ya da PNG dışa aktarın.

Bu örnek, Free planın diyagram başına izin verdiği 15 diyagram node'una sığar; not ve metinler ayrı sayılır ve 150'ye kadar çıkabilir. Referans yerleşimler için /examples/kubernetes-ingress-flow ve /examples/kubernetes-microservices sayfalarını açın; iki sayfada da Bu örneği kullan diyagramı çalışma alanınıza kopyalar, tıpkı yukarıdaki diyagram için Archboard'da aç ile olduğu gibi. Daha fazla kalıp /use-cases/kubernetes sayfasında.

SSS

Archboard Kubernetes YAML'ımı içe aktarabilir mi? Evet, başlangıç noktası olarak. Render edilmiş manifestleri ya da kubectl get -o yaml çıktısını ücretsiz Kubernetes YAML'dan diyagram aracına yapıştırın: namespace'leri çerçeve olarak çizer; Ingress, Service, iş yükü, ConfigMap, Secret ve volume'ları YAML'daki tanımlara göre bağlar. Görüntülemek için hesap gerekmez; ücretsiz bir hesapla sonucu Archboard'da yeni bir diyagram olarak açarsınız ya da editörde YAML’dan içe aktar… ile mevcut bir diyagrama eklersiniz. Diyagram YAML'ınızla senkron kalmaz; sonucu kontrol etmek ve güncel tutmak için bu yazıdaki adımlar geçerliliğini korur.

Her Pod'u çizmeli miyim? Genellikle hayır. Replica etiketi olan tek bir Deployment düğümü daha nettir ve HPA ölçeklendikçe doğru kalır.

Helm chart'ları ne olacak? Önce helm template ile render edin ve şablonları değil, çıktıyı diyagrama dökün.

Hiçbir alanda geçmeyen bağımlılıkları nasıl bulurum? ConfigMap'lerde ve env değerlerinde svc.cluster.local ve diğer host adlarını arayın, ardından servis sahipleriyle doğrulayın.

Ücretsiz başlayın — tek kullanıcı, kredi kartı gerekmez.