Du YAML Kubernetes au diagramme d'architecture

Un namespace avec une douzaine de manifestes se déploie facilement, mais s'explique mal. Le YAML dit au serveur d'API tout ce dont il a besoin, mais il ne dit pas à une nouvelle recrue quel Service se trouve devant quel Deployment, ni pourquoi l'API checkout appelle payments. Ce guide propose une méthode reproductible pour passer du YAML Kubernetes à un diagramme, à la main : inventorier les objets, lire les relations dans des champs précis, décider ce qu'on laisse de côté, organiser la mise en page et garder le schéma à jour. À la fin, nous reconstruisons le résultat dans Archboard avec le pack Kubernetes.

Pas de magie ici : vous lisez des champs et vous tracez des liens. C'est tout l'intérêt. Le diagramme doit capturer l'intention, et l'intention, c'est vous qui l'ajoutez.

Étape 1 : inventorier les objets

Partez des manifestes rendus, pas des templates. Si vous utilisez Helm ou Kustomize, faites d'abord le rendu pour voir ce qui est réellement appliqué :

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

Si la charge de travail tourne déjà, interrogez le cluster en nommant explicitement les types :

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

Ne vous fiez pas à kubectl get all. La catégorie all couvre les Pods, Services, Deployments, ReplicaSets, StatefulSets, DaemonSets, Jobs, CronJobs et HPA, mais elle ignore Ingress, ConfigMap, Secret, PVC, NetworkPolicy et ServiceAccount. Plusieurs d'entre eux portent justement les liens que vous voulez dessiner.

Pour les objets qui portent des relations, récupérez la spec complète :

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

Notez l'inventaire sous forme de liste plate : type, nom, namespace. Cette liste devient votre checklist pour le dessin.

Exemple : du YAML Kubernetes au diagramme pour un service

Voici un ensemble réduit mais typique pour un service dans le 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

Cinq objets, un Secret référencé mais non montré, et une dépendance cachée dans une valeur de configuration.

Étape 2 : trouver les relations dans les champs

Les objets Kubernetes se référencent rarement par ID. Ils se référencent par nom ou, plus souvent, par label. Les labels et les sélecteurs sont la colle ; la documentation Kubernetes sur les labels et sélecteurs mérite une relecture avant de commencer.

Parcourez la liste dans l'ordre du trafic :

• Ingress → Service. backend.service.name et port.number dans chaque chemin nomment directement le Service. L'hôte et le chemin deviennent l'étiquette du lien.
• Service → Deployment. Un Service ne nomme jamais un Deployment. Son spec.selector correspond aux labels de spec.template.metadata.labels du Deployment. Ici app: checkout-api correspond, donc tracez le lien. En cas de doute, kubectl get endpointslices -n shop affiche les adresses des Pods réellement sélectionnés par le Service ; aucun endpoint signifie que le sélecteur ne correspond à rien, ou que les Pods correspondants n'ont pas encore d'IP.
• Deployment → ConfigMap / Secret / PVC. Regardez envFrom, env[].valueFrom et volumes[] (configMap, secret, persistentVolumeClaim.claimName).
• HPA → Deployment. spec.scaleTargetRef nomme la cible.
• NetworkPolicy. spec.podSelector choisit les Pods protégés ; ingress[].from indique qui peut leur parler et egress[].to où ils peuvent se connecter.
• Dépendances cachées. PAYMENTS_URL pointe vers payments.shop.svc.cluster.local. Aucun champ ne relie checkout à payments, mais l'appel est bien réel. C'est le lien que les outils manquent et dont les humains ont le plus besoin.

Du champ YAML à l'élément du diagramme

Étape 3 : décider ce qu'on laisse de côté

Un diagramme qui montre tout ne montre rien. Quelques règles qui tiennent la route :

• Les réplicas sont des étiquettes, pas des boîtes. Dessinez un seul nœud Deployment et inscrivez 3–10 replicas (HPA) dessus. Trois boîtes Pod identiques ajoutent du bruit et deviennent fausses dès que le HPA scale.
• Masquez les ReplicaSets. Ce sont un détail d'implémentation des rollouts.
• Ne dessinez les Pods que s'ils comptent, par exemple des Pods autonomes, ou quand vous expliquez l'ordonnancement sur les Nodes.
• Regroupez le boilerplate. ServiceAccounts, RBAC par défaut et Secrets de pull d'images vont généralement dans une note, pas sur le canevas.
• Gardez ce qui explique une décision. Si une NetworkPolicy explique pourquoi checkout ne peut pas joindre directement la base de données, elle reste.

Étape 4 : organiser la mise en page

Placez le trafic nord-sud de gauche à droite : clients → Ingress → Service → Deployment → Services et stockages en aval. La configuration (ConfigMap, Secret) va sous la charge de travail qu'elle alimente ; la mise à l'échelle (HPA) au-dessus. Dessinez chaque namespace comme un cadre, pour que les appels inter-namespaces ressortent comme des liens qui sortent d'un cadre. Étiquetez les liens avec le protocole et le port, pas seulement des flèches.

Visualiseurs automatiques ou diagramme dessiné

Certains outils de l'écosystème lisent l'état live du cluster depuis le serveur d'API et l'affichent sous forme de graphe. Ils sont exacts sur ce qui tourne à l'instant et utiles pour déboguer. La contrepartie : ils montrent chaque ReplicaSet, Pod et endpoint, ils ne voient pas une dépendance logée dans une variable d'environnement, et ils ne portent aucune intention, comme la raison d'être d'un composant ou ce qui est prévu. Un diagramme dessiné est moins complet mais plus utile pour l'onboarding, les revues de conception et le contexte d'incident. Beaucoup d'équipes utilisent les deux.

Étape 5 : garder le diagramme à jour

Un diagramme n'est fiable que s'il évolue avec les manifestes :

• Stockez le fichier du diagramme à côté des manifestes et relisez-le dans la même pull request.
• Ajoutez une ligne au template de PR : « Modifie un Ingress, un sélecteur de Service, un HPA ou une NetworkPolicy ? Mettez à jour le diagramme. »
• Relancez les commandes d'inventaire de l'étape 1 lors des revues périodiques et comparez avec le dessin.

Reconstruire l'exemple dans Archboard

Dans Archboard, vous dessinez à partir de l'inventaire que vous venez de dresser, en décidant de ce qui a sa place sur le diagramme, avec des nœuds qui correspondent aux kinds Kubernetes :

1. Connectez-vous avec Google ou GitHub et créez un diagramme.
2. Depuis le pack Kubernetes, ajoutez un Namespace. Il est dessiné comme un cadre ; nommez-le shop.
3. À gauche, hors du cadre, ajoutez une Box ou un Text du pack Core pour les clients.
4. Dans le cadre, placez Ingress, Service et Deployment de gauche à droite. Connectez leurs ports et étiquetez les liens shop.example.com/api/checkout et 80 → 8080.
5. Ajoutez ConfigMap et Secret sous le Deployment et connectez-les. Ajoutez au-dessus un HPA étiqueté 3–10, CPU 70%.
6. Ajoutez un second Service pour payments et reliez-le depuis le Deployment, pour rendre visible la dépendance cachée.
7. Posez sur le canevas un bloc Markdown avec l'extrait YAML clé dans un bloc de code délimité, ou une courte note « pourquoi ».
8. Exportez le diagramme en JSON et commitez-le à côté des manifestes ; exportez en SVG ou PNG pour le README.

Cet exemple tient dans la limite du plan Free de 15 nœuds de diagramme par diagramme ; les notes et les textes sont comptés à part, jusqu'à 150. Pour des mises en page de référence, ouvrez /examples/kubernetes-ingress-flow et /examples/kubernetes-microservices ; Utiliser cet exemple copie l'un ou l'autre dans votre espace de travail, comme le fait Ouvrir dans Archboard pour le diagramme ci-dessus. D'autres modèles sont sur /use-cases/kubernetes.

FAQ

Archboard peut-il importer mon YAML Kubernetes ? Oui, comme point de départ. Collez les manifestes rendus ou la sortie de kubectl get -o yaml dans l’outil gratuit YAML Kubernetes vers diagramme : il dessine les namespaces comme des cadres et relie Ingress, Services, workloads, ConfigMaps, Secrets et volumes tels que le YAML les définit. Aucun compte n’est nécessaire pour l’afficher ; avec un compte gratuit, vous ouvrez le résultat dans Archboard comme nouveau diagramme, ou utilisez Importer depuis du YAML… dans l’éditeur pour l’ajouter à un diagramme existant. Il ne reste pas synchronisé avec votre YAML : les étapes de cet article servent toujours à vérifier le résultat et à le tenir à jour.

Dois-je dessiner chaque Pod ? En général, non. Un seul nœud Deployment avec une étiquette de réplicas est plus clair et reste juste quand le HPA scale.

Et les charts Helm ? Faites d'abord le rendu avec helm template et dessinez la sortie, pas les templates.

Comment repérer les dépendances qui n'apparaissent dans aucun champ ? Cherchez svc.cluster.local et les autres noms d'hôte dans les ConfigMaps et les valeurs env, puis confirmez avec les responsables des services.

Commencez gratuitement — un siège, sans carte bancaire.