Como desenhar um diagrama de arquitetura Kubernetes (com template grátis)

A maioria dos diagramas de Kubernetes falha de uma de duas formas: ou é uma parede de ícones de Pod que ninguém consegue ler, ou um rascunho de três caixas que diz "cluster" e quase nada além disso. Um diagrama de arquitetura Kubernetes útil fica no meio do caminho. Ele mostra por onde o tráfego entra, quais objetos o roteiam, onde o estado fica e quais fronteiras importam, num nível de detalhe adequado a quem vai ler.

Neste guia você vai ver o que incluir, como escolher o nível de detalhe de acordo com o público, quais erros tornam um diagrama inútil e como construir um passo a passo no Archboard. O template gratuito abre com um clique como um novo diagrama no seu próprio workspace.

O que um bom diagrama de arquitetura Kubernetes mostra

A documentação do Kubernetes descreve os componentes do cluster: control plane, kubelet, kube-proxy e assim por diante. Essa é a visão de plataforma. A maioria dos times precisa da visão de workload: como a sua aplicação roda no cluster. Cinco coisas concentram a maior parte do valor.

1. Fronteiras do cluster e dos namespaces

Desenhe o cluster como a fronteira externa e os namespaces como frames dentro dele. É nos namespaces que se aplicam RBAC, resource quotas e a maioria das NetworkPolicies, então são as primeiras fronteiras sobre as quais as pessoas perguntam ("o payments tem namespace próprio?"). Se você roda vários clusters (prod e staging, ou um por região), dê a cada um sua própria fronteira, com nome e ambiente.

2. Tráfego norte-sul

Mostre o caminho da requisição de fora do cluster para dentro:

Client → Ingress → Service → Deployment → Pods

Deixe a direção explícita com setas. Anote as regras de host e path do Ingress e o tipo e a porta do Service. Esse único caminho responde à maioria das perguntas do tipo "para onde vai essa requisição?" durante um incidente.

O tráfego leste-oeste (de serviço para serviço dentro do cluster) também importa, mas desenhe de forma seletiva: as chamadas que atravessam namespaces ou estão no caminho crítico.

3. Configuração e armazenamento

Ligue ConfigMaps, Secrets e PersistentVolumeClaims aos workloads que os usam. Um Deployment com um Secret e um PVC diz duas coisas ao leitor: esse workload guarda credenciais e tem estado que sobrevive a um Pod. Desenhe o estado externo, como um Postgres gerenciado, fora da fronteira do cluster, para ficar claro o que pertence ao cluster e o que não pertence.

4. Escalonamento

Coloque um HorizontalPodAutoscaler ao lado do Deployment que ele controla, com réplicas mín./máx. e a métrica no nome ou numa nota ("2–10, CPU 70%"). Isso diz mais do que dez Pods desenhados.

5. NetworkPolicy

Se você usa NetworkPolicies, mostre quais se aplicam e o que elas permitem. Quem faz uma revisão de segurança quer ver "só o namespace api alcança o Postgres", e não ter que deduzir isso.

Como os manifestos viram nós no diagrama

Pegue três objetos comuns:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: orders-api
  namespace: shop
spec:
  replicas: 3
  selector:
    matchLabels: { app: orders-api }
  template:
    metadata:
      labels: { app: orders-api }
    spec:
      containers:
        - name: api
          image: registry.example.com/orders-api:1.4.2
          ports: [{ containerPort: 8080 }]
          envFrom: [{ secretRef: { name: orders-db } }]
---
apiVersion: v1
kind: Service
metadata:
  name: orders-api
  namespace: shop
spec:
  selector: { app: orders-api }
  ports: [{ port: 80, targetPort: 8080 }]
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: shop
  namespace: shop
spec:
  rules:
    - host: shop.example.com
      http:
        paths:
          - path: /orders
            pathType: Prefix
            backend:
              service: { name: orders-api, port: { number: 80 } }

No diagrama, eles viram:

Três réplicas viram um único nó Deployment com "×3", e não três caixas de Pod. As conexões seguem as referências do YAML: backend do Ingress → Service, selector do Service → Deployment, envFrom → Secret.

Escolha o nível de detalhe pelo público

Um único diagrama raramente serve a todos. Decida para quem ele é antes de desenhar.

Se dois públicos precisam de coisas diferentes, desenhe duas visões em vez de um diagrama que tenta fazer tudo.

Erros comuns

• Desenhar cada réplica de Pod. Réplicas são um número, não arquitetura. Um nó Deployment com a contagem de réplicas, mais um HPA se ele escala, é mais legível do que uma grade de caixas idênticas.
• Misturar lógico e físico. Worker nodes, zonas e alocação de Pods são uma visão física; Ingress → Service → Deployment é uma visão lógica. Coloque as duas no mesmo canvas e nenhuma fica legível. Se você precisa da visão física, faça um diagrama separado.
• Sem direção de tráfego. Linhas sem setas não dizem quem chama quem. Use conexões direcionadas e mantenha o fluxo principal em um só sentido, da esquerda para a direita ou de cima para baixo.
• Diagramas desatualizados. Um diagrama com os serviços do ano passado faz mais mal do que nenhum. Coloque um responsável e uma data de "última verificação" no canvas e atualize quando uma mudança adicionar ou remover uma caixa.
• Conexões sem explicação. "Service → Deployment" é óbvio; "orders-api → payments-api" merece protocolo e porta.

Como desenhar passo a passo no Archboard

O pack Kubernetes do Archboard tem 33 tipos de nós de primeira classe com portas, de Namespace (desenhado como frame), Node, Pod, Deployment, StatefulSet, Job e CronJob a Service, Ingress, rotas da Gateway API, ConfigMap, Secret, PersistentVolumeClaim, HPA, NetworkPolicy e RBAC. Você conecta portas em vez de traçar linhas soltas entre formas genéricas. Você pode começar pelos seus manifestos com Importar de YAML… ou posicionar cada nó à mão; de qualquer forma, a decisão "o que importa aqui?", que é o tema deste guia, continua sendo sua.

1. Estude os exemplos. Abra o exemplo de microsserviços em Kubernetes (Ingress → Service → Deployment/Pod → PVC → Postgres) e o exemplo de fluxo de Ingress. Repare no layout: o tráfego flui em um sentido e o estado fica no final.
2. Crie um diagrama no seu workspace e adicione um Frame para o cluster, com o nome do cluster e do ambiente.
3. Adicione um Namespace para cada namespace relevante, dentro do frame do cluster.
4. Posicione o caminho da requisição: Ingress, depois Service, depois Deployment, da esquerda para a direita. Conecte porta a porta e adicione rótulos Text curtos para host/path e portas.
5. Ligue configuração e estado: ConfigMap e Secret ao lado do Deployment que os lê, um PVC para armazenamento persistente e um nó de banco de dados fora do frame do cluster para um Postgres gerenciado.
6. Adicione escalonamento e políticas: um HPA ao lado do seu Deployment, com mín./máx. e métrica, e nós NetworkPolicy nas fronteiras de namespace que eles protegem.
7. Adicione contexto no canvas: um bloco Markdown com responsável, data de verificação e links para o repositório ou runbook. Blocos de código também funcionam no canvas, então o trecho principal do manifesto pode ficar ao lado dos seus nós.
8. Compartilhe: exporte SVG ou PNG para um documento de design ou compartilhe um link público. O salvamento automático e os snapshots de revisão deixam você voltar atrás se uma reorganização der errado.

Para uma visão multiconta de vários clusters, o pack Cloud tem um nó Kubernetes Cluster.

O plano Free inclui todos os packs nativos e permite 15 nós de diagrama por diagrama, mais 150 notas e textos, o que basta para o caminho de requisição de um serviço. Um mapa completo com vários serviços provavelmente vai exigir o Pro.

O template gratuito

O template gratuito é /templates/kubernetes-architecture: Usar este modelo abre o template como um novo diagrama no seu workspace. Para um layout mais completo, /examples/kubernetes-microservices tem Usar este exemplo, que faz uma cópia para você renomear os nós com os nomes dos seus serviços. Só para o caminho do tráfego, /examples/kubernetes-ingress-flow é um ponto de partida menor. Mais padrões estão na página de casos de uso de Kubernetes.

Perguntas frequentes

Devo desenhar o control plane? Só se o diagrama for sobre a própria plataforma, por exemplo para um time de plataforma ou um plano de upgrade. Em diagramas de aplicação, o control plane é ruído; os leitores já assumem que ele existe.

Pods ou Deployments? Deployments, com a contagem de réplicas. Desenhe Pods individuais só quando um Pod específico importa: um layout de sidecars, uma sessão de depuração ou uma execução de Job ou CronJob.

Como mantenho o diagrama atualizado? Defina um responsável, coloque uma data de verificação no canvas e revise junto com os pull requests que mudam os serviços que ele mostra. Uma exportação JSON do diagrama pode ficar no repositório ao lado dos manifestos.

Um diagrama pode cobrir vários clusters? Sim, num nível mais alto: uma fronteira por cluster, com apenas o tráfego entre clusters desenhado. Mantenha o detalhe de cada cluster em diagramas separados.

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