De YAML de Kubernetes a un diagrama de arquitectura

Un namespace con una docena de manifiestos es fácil de desplegar y difícil de explicar. El YAML le dice al servidor de API todo lo que necesita, pero no le dice a alguien nuevo en el equipo qué Service está delante de qué Deployment, ni por qué la API de checkout habla con payments. Esta guía es un método repetible para pasar de YAML de Kubernetes a un diagrama a mano: haz inventario de los objetos, lee las relaciones en campos concretos, decide qué dejar fuera, organiza el layout y mantenlo al día. Al final reconstruimos el resultado en Archboard con el pack de Kubernetes.

Aquí no hay magia: lees campos y dibujas conexiones. Esa es la idea. El diagrama debe capturar la intención, y la intención la aportas tú.

Paso 1: haz inventario de los objetos

Empieza por los manifiestos renderizados, no por las plantillas. Si usas Helm o Kustomize, renderiza primero para ver lo que realmente se aplica:

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

Si la carga de trabajo ya está en marcha, pregúntale al clúster y sé explícito con los tipos:

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

No te fíes de kubectl get all. La categoría all cubre Pods, Services, Deployments, ReplicaSets, StatefulSets, DaemonSets, Jobs, CronJobs y HPA, pero omite Ingress, ConfigMap, Secret, PVC, NetworkPolicy y ServiceAccount. Varios de ellos llevan justo las conexiones que quieres dibujar.

Para los objetos que contienen relaciones, saca la 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

Apunta el inventario como una lista plana: tipo, nombre, namespace. Esa lista es tu checklist para el dibujo.

Ejemplo: de YAML de Kubernetes a diagrama para un servicio

Este es un conjunto pequeño pero típico para un servicio en el 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, un Secret referenciado pero no mostrado y una dependencia escondida en un valor de configuración.

Paso 2: encuentra las relaciones en los campos

Los objetos de Kubernetes rara vez se referencian por ID. Lo hacen por nombre o, más a menudo, por label. Los labels y selectores son el pegamento; vale la pena releer la documentación de Kubernetes sobre labels y selectores antes de empezar.

Recorre la lista en el orden del tráfico:

• Ingress → Service. backend.service.name y port.number en cada ruta nombran el Service directamente. El host y la ruta se convierten en la etiqueta de la conexión.
• Service → Deployment. Un Service nunca nombra un Deployment. Su spec.selector coincide con los labels de spec.template.metadata.labels del Deployment. Aquí coincide app: checkout-api, así que dibuja la conexión. Si dudas, kubectl get endpointslices -n shop muestra las direcciones de los Pods que el Service seleccionó de verdad; sin endpoints, el selector no coincide con nada, o los Pods que coinciden aún no tienen IP.
• Deployment → ConfigMap / Secret / PVC. Mira envFrom, env[].valueFrom y volumes[] (configMap, secret, persistentVolumeClaim.claimName).
• HPA → Deployment. spec.scaleTargetRef nombra el objetivo.
• NetworkPolicy. spec.podSelector elige los Pods que protege; ingress[].from indica quién puede hablar con ellos y egress[].to, adónde pueden conectarse.
• Dependencias ocultas. PAYMENTS_URL apunta a payments.shop.svc.cluster.local. Ningún campo une checkout con payments, pero la llamada existe. Esta es la conexión que las herramientas pasan por alto y la que más necesitan las personas.

Del campo YAML al elemento del diagrama

Paso 3: decide qué dejar fuera

Un diagrama que lo muestra todo no muestra nada. Reglas que funcionan bien:

• Las réplicas son etiquetas, no cajas. Dibuja un solo nodo Deployment y escribe 3–10 replicas (HPA) en él. Tres cajas Pod idénticas añaden ruido y dejan de ser correctas en cuanto el HPA escala.
• Oculta los ReplicaSets. Son un detalle de implementación de los rollouts.
• Dibuja Pods solo cuando importan, por ejemplo Pods independientes, o cuando explicas la planificación en Nodes.
• Agrupa lo repetitivo. ServiceAccounts, RBAC por defecto y Secrets para descargar imágenes suelen ir en una nota, no en el lienzo.
• Conserva lo que explica una decisión. Si una NetworkPolicy es la razón por la que checkout no puede llegar directamente a la base de datos, se queda.

Paso 4: organiza el layout

Coloca el tráfico norte-sur de izquierda a derecha: clientes → Ingress → Service → Deployment → Services y almacenes de datos posteriores. La configuración (ConfigMap, Secret) va debajo de la carga que alimenta; el escalado (HPA), encima. Dibuja cada namespace como un marco, para que las llamadas entre namespaces destaquen como conexiones que salen de un marco. Etiqueta las conexiones con protocolo y puerto, no solo con flechas.

Visualizadores automáticos vs diagrama dibujado

Algunas herramientas del ecosistema leen el estado en vivo del clúster desde el servidor de API y lo muestran como un grafo. Son exactas sobre lo que se está ejecutando ahora mismo y útiles para depurar. La contrapartida: muestran cada ReplicaSet, Pod y endpoint, no ven una dependencia que vive en una variable de entorno y no transmiten intención, como por qué existe algo o qué está planificado. Un diagrama dibujado es menos completo y más útil para el onboarding, las revisiones de diseño y el contexto de incidentes. Muchos equipos usan ambos.

Paso 5: mantenlo al día

Un diagrama solo es fiable si cambia junto con los manifiestos:

• Guarda el archivo del diagrama junto a los manifiestos y revísalo en el mismo pull request.
• Añade una línea a la plantilla de PR: "¿Cambia un Ingress, un selector de Service, un HPA o una NetworkPolicy? Actualiza el diagrama."
• Vuelve a ejecutar los comandos de inventario del paso 1 en las revisiones periódicas y compáralos con el dibujo.

Reconstruir el ejemplo en Archboard

En Archboard dibujas a partir del inventario que acabas de hacer, decidiendo qué entra en el diagrama, con nodos que corresponden a los kinds de Kubernetes:

1. Inicia sesión con Google o GitHub y crea un diagrama.
2. Desde el pack Kubernetes, añade un Namespace. Se dibuja como un marco; llámalo shop.
3. Fuera del marco, a la izquierda, añade una Box o un Text del pack Core para los clientes.
4. Dentro del marco, coloca Ingress, Service y Deployment de izquierda a derecha. Conecta sus puertos y etiqueta las conexiones shop.example.com/api/checkout y 80 → 8080.
5. Añade ConfigMap y Secret debajo del Deployment y conéctalos. Añade encima un HPA con la etiqueta 3–10, CPU 70%.
6. Añade un segundo Service para payments y conéctalo desde el Deployment, para que la dependencia oculta sea visible.
7. Pon en el lienzo un bloque Markdown con el fragmento YAML clave en un bloque de código delimitado, o una nota breve de "por qué".
8. Exporta el diagrama como JSON y haz commit junto a los manifiestos; exporta SVG o PNG para el README.

Esto cabe en el límite del plan Free de 15 nodos de diagrama por diagrama; las notas y los textos cuentan aparte, hasta 150. Para layouts de referencia, abre /examples/kubernetes-ingress-flow y /examples/kubernetes-microservices; Usar este ejemplo copia cualquiera de los dos en tu espacio de trabajo, como hace Abrir en Archboard con el diagrama de arriba. Hay más patrones en /use-cases/kubernetes.

Preguntas frecuentes

¿Puede Archboard importar mi YAML de Kubernetes? Sí, como punto de partida. Pega los manifiestos renderizados o la salida de kubectl get -o yaml en la herramienta gratuita YAML de Kubernetes a diagrama: dibuja los namespaces como marcos y conecta Ingress, Services, cargas de trabajo, ConfigMaps, Secrets y volúmenes tal como los define el YAML. Para verlo no necesitas cuenta; con una cuenta gratuita abres el resultado en Archboard como un diagrama nuevo, o usas Importar desde YAML… en el editor para añadirlo a uno existente. No se mantiene sincronizado con tu YAML, así que los pasos de este artículo siguen sirviendo para revisar el resultado y mantenerlo al día.

¿Debo dibujar cada Pod? Normalmente no. Un solo nodo Deployment con una etiqueta de réplicas es más claro y sigue siendo correcto cuando el HPA escala.

¿Y los charts de Helm? Renderízalos primero con helm template y dibuja la salida, no las plantillas.

¿Cómo encuentro dependencias que no aparecen en ningún campo? Busca svc.cluster.local y otros nombres de host en los ConfigMaps y los valores de env, y luego confírmalo con los responsables de cada servicio.

Empieza gratis — un puesto, sin tarjeta de crédito.