Do YAML do Kubernetes a um diagrama de arquitetura

Um namespace com uma dúzia de manifests é fácil de implantar e difícil de explicar. O YAML diz ao servidor de API tudo o que ele precisa, mas não diz a uma pessoa nova no time qual Service fica na frente de qual Deployment, nem por que a API de checkout conversa com payments. Este guia é um método repetível para ir do YAML do Kubernetes a um diagrama, à mão: faça o inventário dos objetos, leia os relacionamentos em campos específicos, decida o que deixar de fora, monte o layout e mantenha tudo atualizado. No final, reconstruímos o resultado no Archboard com o pack de Kubernetes.

Não tem mágica aqui: você lê campos e desenha conexões. Essa é a ideia. O diagrama deve capturar a intenção, e a intenção é algo que você acrescenta.

Passo 1: faça o inventário dos objetos

Comece pelos manifests renderizados, não pelos templates. Se você usa Helm ou Kustomize, renderize primeiro para ver o que de fato é aplicado:

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

Se a carga de trabalho já está rodando, pergunte ao cluster e seja explícito quanto aos tipos:

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

Não confie em kubectl get all. A categoria all cobre Pods, Services, Deployments, ReplicaSets, StatefulSets, DaemonSets, Jobs, CronJobs e HPAs, mas deixa de fora Ingress, ConfigMap, Secret, PVC, NetworkPolicy e ServiceAccount. Vários deles carregam justamente as conexões que você quer desenhar.

Para os objetos que guardam relacionamentos, puxe a spec completa:

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

Anote o inventário como uma lista simples: tipo, nome, namespace. Essa lista é o seu checklist para o desenho.

Exemplo: do YAML do Kubernetes ao diagrama de um serviço

Aqui está um conjunto pequeno, mas típico, para um serviço no namespace shop:

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

Cinco objetos, um Secret referenciado mas não mostrado e uma dependência escondida em um valor de configuração.

Passo 2: encontre os relacionamentos nos campos

Objetos do Kubernetes raramente apontam uns para os outros por ID. Eles apontam por nome ou, com mais frequência, por label. Labels e seletores são a cola; vale reler a documentação do Kubernetes sobre labels e seletores antes de começar.

Percorra a lista na ordem do tráfego:

• Ingress → Service. backend.service.name e port.number em cada path nomeiam o Service diretamente. Host e path viram o rótulo da conexão.
• Service → Deployment. Um Service nunca nomeia um Deployment. O spec.selector dele casa com os labels em spec.template.metadata.labels do Deployment. Aqui app: checkout-api casa, então desenhe a conexão. Na dúvida, kubectl get endpointslices -n shop mostra os endereços dos Pods que o Service realmente selecionou; sem endpoints, o seletor não casa com nada, ou os Pods que casam ainda não têm IP.
• Deployment → ConfigMap / Secret / PVC. Olhe envFrom, env[].valueFrom e volumes[] (configMap, secret, persistentVolumeClaim.claimName).
• HPA → Deployment. spec.scaleTargetRef nomeia o alvo.
• NetworkPolicy. spec.podSelector escolhe os Pods que ela protege; ingress[].from diz quem pode falar com eles e egress[].to, para onde eles podem se conectar.
• Dependências ocultas. PAYMENTS_URL aponta para payments.shop.svc.cluster.local. Nenhum campo liga checkout a payments, mas a chamada existe. Essa é a conexão que as ferramentas deixam passar e de que as pessoas mais precisam.

Do campo YAML ao elemento do diagrama

Passo 3: decida o que deixar de fora

Um diagrama que mostra tudo não mostra nada. Regras que funcionam bem:

• Réplicas são rótulos, não caixas. Desenhe um único nó Deployment e escreva 3–10 replicas (HPA) nele. Três caixas de Pod idênticas só adicionam ruído e ficam erradas assim que o HPA escala.
• Esconda os ReplicaSets. Eles são um detalhe de implementação dos rollouts.
• Desenhe Pods só quando importam, por exemplo Pods avulsos, ou quando você explica o agendamento em Nodes.
• Agrupe o boilerplate. ServiceAccounts, RBAC padrão e Secrets de pull de imagem geralmente vão em uma nota, não no canvas.
• Mantenha o que explica uma decisão. Se uma NetworkPolicy é o motivo de checkout não alcançar o banco de dados diretamente, ela fica.

Passo 4: monte o layout

Coloque o tráfego norte-sul da esquerda para a direita: clientes → Ingress → Service → Deployment → Services e armazenamentos a jusante. Configuração (ConfigMap, Secret) fica abaixo da carga que ela alimenta; escalonamento (HPA), acima. Desenhe cada namespace como um frame, para que chamadas entre namespaces se destaquem como conexões que saem de um frame. Rotule as conexões com protocolo e porta, não só com setas.

Visualizadores automáticos vs. diagrama desenhado

Algumas ferramentas do ecossistema leem o estado ao vivo do cluster pelo servidor de API e o exibem como um grafo. Elas são precisas sobre o que está rodando agora e úteis para depurar. A contrapartida: mostram cada ReplicaSet, Pod e endpoint, não enxergam uma dependência que mora em uma variável de ambiente e não carregam intenção, como por que algo existe ou o que está planejado. Um diagrama desenhado é menos completo e mais útil para onboarding, revisões de design e contexto de incidentes. Muitos times usam os dois.

Passo 5: mantenha atualizado

Um diagrama só é confiável se mudar junto com os manifests:

• Guarde o arquivo do diagrama ao lado dos manifests e revise-o no mesmo pull request.
• Adicione uma linha ao template de PR: "Muda um Ingress, seletor de Service, HPA ou NetworkPolicy? Atualize o diagrama."
• Rode de novo os comandos de inventário do passo 1 nas revisões periódicas e compare com o desenho.

Reconstruindo o exemplo no Archboard

No Archboard você desenha a partir do inventário que acabou de montar, decidindo o que entra no diagrama, com nós que correspondem aos kinds do Kubernetes:

1. Entre com Google ou GitHub e crie um diagrama.
2. No pack Kubernetes, adicione um Namespace. Ele é desenhado como um frame; chame-o de shop.
3. Fora do frame, à esquerda, adicione uma Box ou um Text do pack Core para os clientes.
4. Dentro do frame, posicione Ingress, Service e Deployment da esquerda para a direita. Conecte as portas e rotule as conexões shop.example.com/api/checkout e 80 → 8080.
5. Adicione ConfigMap e Secret abaixo do Deployment e conecte-os. Adicione acima um HPA com o rótulo 3–10, CPU 70%.
6. Adicione um segundo Service para payments e conecte-o a partir do Deployment, para que a dependência oculta fique visível.
7. Coloque no canvas um bloco Markdown com o trecho de YAML principal em um bloco de código delimitado, ou uma nota curta de "por quê".
8. Exporte o diagrama como JSON e faça commit ao lado dos manifests; exporte SVG ou PNG para o README.

Isso cabe no limite do plano Free de 15 nós de diagrama por diagrama; notas e textos contam à parte, até 150. Para layouts de referência, abra /examples/kubernetes-ingress-flow e /examples/kubernetes-microservices; Usar este exemplo copia qualquer um dos dois para o seu espaço de trabalho, como Abrir no Archboard faz com o diagrama acima. Há mais padrões em /use-cases/kubernetes.

Perguntas frequentes

O Archboard consegue importar meu YAML do Kubernetes? Sim, como ponto de partida. Cole os manifestos renderizados ou a saída de kubectl get -o yaml na ferramenta gratuita YAML do Kubernetes para diagrama: ela desenha os namespaces como molduras e conecta Ingress, Services, workloads, ConfigMaps, Secrets e volumes como o YAML os define. Para visualizar não é preciso conta; com uma conta gratuita, você abre o resultado no Archboard como um novo diagrama ou usa Importar de YAML… no editor para adicioná-lo a um diagrama existente. Ele não fica sincronizado com o seu YAML, então os passos deste post continuam valendo para revisar o resultado e mantê-lo atualizado.

Devo desenhar cada Pod? Normalmente não. Um único nó Deployment com rótulo de réplicas é mais claro e continua correto quando o HPA escala.

E os charts do Helm? Renderize primeiro com helm template e desenhe a saída, não os templates.

Como encontro dependências que não aparecem em nenhum campo? Procure svc.cluster.local e outros hostnames nos ConfigMaps e nos valores de env, e depois confirme com os donos dos serviços.

Comece grátis — um assento, sem cartão de crédito.