Cómo dibujar un diagrama de arquitectura de Kubernetes (con plantilla gratis)

La mayoría de los diagramas de Kubernetes fallan de una de dos maneras: o son un muro de iconos de Pods que nadie puede leer, o un boceto de tres cajas que dice "cluster" y poco más. Un diagrama de arquitectura de Kubernetes útil está en medio. Muestra por dónde entra el tráfico, qué objetos lo enrutan, dónde vive el estado y qué límites importan, con un nivel de detalle adecuado para quien lo lee.

En esta guía verás qué incluir, cómo elegir el nivel de detalle según la audiencia, qué errores vuelven inútil un diagrama y cómo construir uno paso a paso en Archboard. La plantilla gratuita se abre con un clic como un diagrama nuevo en tu propio workspace.

Qué muestra un buen diagrama de arquitectura de Kubernetes

La documentación de Kubernetes describe los componentes del cluster: control plane, kubelet, kube-proxy, etc. Esa es la vista de plataforma. La mayoría de los equipos necesita la vista de workloads: cómo corre tu aplicación en el cluster. Cinco cosas aportan casi todo el valor.

1. Límites del cluster y de los namespaces

Dibuja el cluster como el límite exterior y los namespaces como marcos dentro de él. En los namespaces se aplican RBAC, las resource quotas y la mayoría de las NetworkPolicies, así que son los límites por los que la gente pregunta primero ("¿payments tiene su propio namespace?"). Si ejecutas varios clusters (prod y staging, o uno por región), dale a cada uno su propio límite con su nombre y entorno.

2. Tráfico norte-sur

Muestra el camino de la petición desde fuera del cluster hacia dentro:

Client → Ingress → Service → Deployment → Pods

Haz explícita la dirección con flechas. Anota las reglas de host y ruta del Ingress y el tipo y puerto del Service. Este único camino responde a la mayoría de las preguntas de "¿a dónde va esta petición?" durante un incidente.

El tráfico este-oeste (de servicio a servicio dentro del cluster) también importa, pero dibújalo de forma selectiva: las llamadas que cruzan namespaces o que están en la ruta crítica.

3. Configuración y almacenamiento

Conecta los ConfigMaps, Secrets y PersistentVolumeClaims a los workloads que los usan. Un Deployment con un Secret y un PVC le dice dos cosas al lector: este workload maneja credenciales y tiene un estado que sobrevive a un Pod. Dibuja el estado externo, como un Postgres gestionado, fuera del límite del cluster, para que quede claro qué es del cluster y qué no.

4. Escalado

Pon un HorizontalPodAutoscaler junto al Deployment al que apunta, con las réplicas mín./máx. y la métrica en su nombre o en una nota ("2–10, CPU 70 %"). Eso dice más que diez Pods dibujados.

5. NetworkPolicy

Si usas NetworkPolicies, muestra cuáles se aplican y qué permiten. Quien hace una revisión de seguridad quiere ver "solo el namespace api puede llegar a Postgres", no deducirlo.

Cómo se traducen los manifiestos a nodos del diagrama

Toma tres objetos corrientes:

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 } }

En el diagrama se convierten en:

Tres réplicas se convierten en un solo nodo Deployment con "×3", no en tres cajas de Pod. Las conexiones siguen las referencias del YAML: backend del Ingress → Service, selector del Service → Deployment, envFrom → Secret.

Elige el nivel de detalle según la audiencia

Un solo diagrama rara vez sirve para todos. Decide para quién es antes de dibujar.

Si dos audiencias necesitan cosas distintas, dibuja dos vistas en lugar de un diagrama que intente hacerlo todo.

Errores comunes

• Dibujar cada réplica de Pod. Las réplicas son un número, no arquitectura. Un nodo Deployment con el número de réplicas, más un HPA si escala, se lee mejor que una cuadrícula de cajas idénticas.
• Mezclar lo lógico y lo físico. Los worker nodes, las zonas y la ubicación de los Pods son una vista física; Ingress → Service → Deployment es una vista lógica. Si las pones juntas en un canvas, ninguna se entiende. Si necesitas la vista física, haz un diagrama aparte.
• Sin dirección del tráfico. Las líneas sin flechas no dicen quién llama a quién. Usa conexiones dirigidas y mantén el flujo principal en un solo sentido, de izquierda a derecha o de arriba abajo.
• Diagramas desactualizados. Un diagrama con los servicios del año pasado hace más daño que no tener ninguno. Pon un responsable y una fecha de "última revisión" en el canvas, y actualízalo cuando un cambio agregue o quite una caja.
• Conexiones sin explicar. "Service → Deployment" es obvio; "orders-api → payments-api" merece un protocolo y un puerto.

Cómo dibujarlo paso a paso en Archboard

El pack Kubernetes de Archboard tiene 33 tipos de nodos de primera clase con puertos, desde Namespace (dibujado como frame), Node, Pod, Deployment, StatefulSet, Job y CronJob hasta Service, Ingress, rutas de Gateway API, ConfigMap, Secret, PersistentVolumeClaim, HPA, NetworkPolicy y RBAC. Conectas puertos en lugar de trazar líneas sueltas entre formas genéricas. Puedes partir de tus manifiestos con Importar desde YAML… o colocar cada nodo a mano; en cualquier caso, la decisión de «qué importa aquí», que es el tema de esta guía, sigue siendo tuya.

1. Estudia los ejemplos. Abre el ejemplo de microservicios en Kubernetes (Ingress → Service → Deployment/Pod → PVC → Postgres) y el ejemplo de flujo de Ingress. Fíjate en la disposición: el tráfico fluye en un sentido y el estado queda al final.
2. Crea un diagrama en tu workspace y agrega un Frame para el cluster, con el nombre del cluster y del entorno.
3. Agrega un Namespace por cada namespace que importe, dentro del marco del cluster.
4. Coloca el camino de la petición: Ingress, luego Service, luego Deployment, de izquierda a derecha. Conecta puerto con puerto y agrega etiquetas Text cortas para host/ruta y puertos.
5. Conecta configuración y estado: ConfigMap y Secret junto al Deployment que los lee, un PVC para el almacenamiento persistente y un nodo de base de datos fuera del marco del cluster para un Postgres gestionado.
6. Agrega escalado y políticas: un HPA junto a su Deployment con mín./máx. y métrica, y nodos NetworkPolicy en los límites de namespace que protegen.
7. Agrega contexto en el canvas: un bloque Markdown con el responsable, la fecha de revisión y enlaces al repositorio o al runbook. Los bloques de código también funcionan en el canvas, así que el fragmento clave del manifiesto puede quedar junto a sus nodos.
8. Compártelo: exporta SVG o PNG para un documento de diseño, o comparte un enlace público. El autoguardado y los snapshots de revisión te permiten volver atrás si una reorganización sale mal.

Para una vista multicuenta de varios clusters, el pack Cloud tiene un nodo Kubernetes Cluster.

El plan Free incluye todos los packs integrados y permite 15 nodos de diagrama por diagrama, más 150 notas y textos, suficiente para el camino de petición de un servicio. Un mapa completo con varios servicios probablemente necesitará Pro.

La plantilla gratuita

La plantilla gratuita es /templates/kubernetes-architecture: Usar esta plantilla la abre como un diagrama nuevo en tu workspace. Para una disposición más completa, /examples/kubernetes-microservices tiene Usar este ejemplo, que lo copia para que puedas renombrar los nodos con los nombres de tus servicios. Si solo te interesa el camino del tráfico, /examples/kubernetes-ingress-flow es un punto de partida más pequeño. Encontrarás más patrones en la página de casos de uso de Kubernetes.

Preguntas frecuentes

¿Debo dibujar el control plane? Solo si el diagrama trata de la plataforma en sí, por ejemplo para un equipo de plataforma o un plan de actualización. En los diagramas de aplicación, el control plane es ruido; los lectores asumen que existe.

¿Pods o Deployments? Deployments, con el número de réplicas. Dibuja Pods individuales solo cuando un Pod concreto importa: una disposición de sidecars, una sesión de depuración o la ejecución de un Job o CronJob.

¿Cómo lo mantengo actualizado? Asígnale un responsable, pon una fecha de revisión en el canvas y revísalo junto con los pull requests que cambian los servicios que muestra. Una exportación JSON del diagrama puede vivir en el repositorio junto a los manifiestos.

¿Un diagrama puede cubrir varios clusters? Sí, a un nivel más alto: un límite por cluster y solo el tráfico entre clusters. Deja el detalle de cada cluster en diagramas separados.

Empieza gratis — un asiento, sin tarjeta de crédito