Comment dessiner un schéma d'architecture Kubernetes (modèle gratuit)

La plupart des diagrammes Kubernetes échouent de l'une de deux façons : soit c'est un mur d'icônes de Pods que personne ne sait lire, soit un croquis de trois boîtes marqué « cluster » et pas grand-chose d'autre. Un schéma d'architecture Kubernetes utile se situe entre les deux. Il montre où le trafic entre, quels objets l'acheminent, où vit l'état et quelles frontières comptent, avec un niveau de détail adapté à la personne qui le lit.

Ce guide vous explique quoi inclure, comment choisir le niveau de détail selon le public, quelles erreurs rendent un diagramme inutile, et comment en construire un pas à pas dans Archboard. Le modèle gratuit s'ouvre en un clic comme nouveau diagramme dans votre propre workspace.

Ce que montre un bon schéma d'architecture Kubernetes

La documentation Kubernetes décrit les composants d'un cluster : control plane, kubelet, kube-proxy, etc. C'est la vue plateforme. La plupart des équipes ont besoin de la vue workload : comment votre application tourne sur le cluster. Cinq éléments apportent l'essentiel de la valeur.

1. Frontières du cluster et des namespaces

Dessinez le cluster comme frontière extérieure et les namespaces comme cadres à l'intérieur. C'est au niveau des namespaces que s'appliquent le RBAC, les resource quotas et la plupart des NetworkPolicies : ce sont donc les frontières sur lesquelles on vous interroge en premier (« payments a-t-il son propre namespace ? »). Si vous exploitez plusieurs clusters (prod et staging, ou un par région), donnez à chacun sa propre frontière, avec son nom et son environnement.

2. Trafic nord-sud

Montrez le chemin d'une requête, de l'extérieur du cluster vers l'intérieur :

Client → Ingress → Service → Deployment → Pods

Rendez le sens explicite avec des flèches. Notez les règles d'hôte et de chemin de l'Ingress, ainsi que le type et le port du Service. Ce seul chemin répond à la plupart des questions « où va cette requête ? » pendant un incident.

Le trafic est-ouest (de service à service à l'intérieur du cluster) compte aussi, mais dessinez-le avec parcimonie : les appels qui traversent des namespaces ou se trouvent sur le chemin critique.

3. Configuration et stockage

Rattachez les ConfigMaps, Secrets et PersistentVolumeClaims aux workloads qui les utilisent. Un Deployment avec un Secret et un PVC indique deux choses au lecteur : ce workload détient des identifiants, et il possède un état qui survit à un Pod. Placez l'état externe, comme un Postgres managé, hors de la frontière du cluster pour qu'on voie clairement ce que le cluster possède et ce qu'il ne possède pas.

4. Mise à l'échelle

Placez un HorizontalPodAutoscaler à côté du Deployment qu'il cible, avec le nombre min/max de réplicas et la métrique dans son nom ou dans une note (« 2–10, CPU 70 % »). Cela en dit plus que dix Pods dessinés.

5. NetworkPolicy

Si vous utilisez des NetworkPolicies, montrez lesquelles s'appliquent et ce qu'elles autorisent. Une personne chargée de la revue de sécurité veut voir « seul le namespace api peut joindre Postgres », pas le déduire.

Des manifestes aux nœuds du diagramme

Prenons trois objets ordinaires :

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

Sur le diagramme, ils deviennent :

Trois réplicas deviennent un seul nœud Deployment marqué « ×3 », pas trois boîtes Pod. Les liens suivent les références du YAML : backend de l'Ingress → Service, selector du Service → Deployment, envFrom → Secret.

Choisir le niveau de détail selon le public

Un seul diagramme sert rarement tout le monde. Décidez à qui il s'adresse avant de dessiner.

Si deux publics ont des besoins différents, dessinez deux vues plutôt qu'un diagramme qui essaie de tout faire.

Erreurs fréquentes

• Dessiner chaque réplica de Pod. Les réplicas sont un nombre, pas une architecture. Un nœud Deployment avec un nombre de réplicas, plus un HPA s'il scale, se lit mieux qu'une grille de boîtes identiques.
• Mélanger logique et physique. Les worker nodes, les zones et le placement des Pods relèvent de la vue physique ; Ingress → Service → Deployment relève de la vue logique. Réunies sur un même canvas, aucune des deux n'est lisible. Si vous avez besoin de la vue physique, faites-en un diagramme séparé.
• Aucun sens de trafic. Des lignes sans flèches ne disent pas qui appelle qui. Utilisez des liens orientés et faites circuler le flux principal dans un seul sens, de gauche à droite ou de haut en bas.
• Diagrammes obsolètes. Un diagramme qui montre les services de l'an dernier fait plus de mal que pas de diagramme du tout. Indiquez un responsable et une date de « dernière vérification » sur le canvas, et mettez-le à jour quand un changement ajoute ou retire une boîte.
• Liens non expliqués. « Service → Deployment » va de soi ; « orders-api → payments-api » mérite un protocole et un port.

Le dessiner pas à pas dans Archboard

Le pack Kubernetes d'Archboard compte 33 types de nœuds à part entière avec ports, de Namespace (dessiné comme un frame), Node, Pod, Deployment, StatefulSet, Job et CronJob à Service, Ingress, routes Gateway API, ConfigMap, Secret, PersistentVolumeClaim, HPA, NetworkPolicy et RBAC. Vous reliez des ports au lieu de tracer des lignes libres entre des formes génériques. Vous pouvez partir de vos manifestes avec Importer depuis du YAML… ou placer chaque nœud à la main ; dans les deux cas, la décision « qu'est-ce qui compte ici ? » au cœur de ce guide vous revient.

1. Étudiez les exemples. Ouvrez l'exemple de microservices Kubernetes (Ingress → Service → Deployment/Pod → PVC → Postgres) et l'exemple de flux Ingress. Observez la mise en page : le trafic circule dans un sens et l'état se trouve au bout.
2. Créez un diagramme dans votre workspace et ajoutez un Frame pour le cluster, nommé d'après le cluster et l'environnement.
3. Ajoutez un Namespace pour chaque namespace qui compte, à l'intérieur du cadre du cluster.
4. Placez le chemin de la requête : Ingress, puis Service, puis Deployment, de gauche à droite. Reliez les ports entre eux et ajoutez de courts libellés Text pour l'hôte/le chemin et les ports.
5. Rattachez configuration et état : ConfigMap et Secret à côté du Deployment qui les lit, un PVC pour le stockage persistant, et un nœud base de données hors du cadre du cluster pour un Postgres managé.
6. Ajoutez mise à l'échelle et politiques : un HPA à côté de son Deployment, avec min/max et métrique, et des nœuds NetworkPolicy sur les frontières de namespace qu'ils protègent.
7. Ajoutez du contexte sur le canvas : un bloc Markdown avec le responsable, la date de vérification et des liens vers le dépôt ou le runbook. Les blocs de code fonctionnent aussi sur le canvas, ce qui permet de placer l'extrait de manifeste clé à côté de ses nœuds.
8. Partagez-le : exportez en SVG ou PNG pour un document de conception, ou partagez un lien public. L'enregistrement automatique et les snapshots de révision vous permettent de revenir en arrière si une refonte tourne mal.

Pour une vue multi-comptes de plusieurs clusters, le pack Cloud propose un nœud Kubernetes Cluster.

Le plan Free inclut tous les packs intégrés et autorise 15 nœuds de diagramme par diagramme, plus 150 notes et textes, ce qui suffit pour le chemin de requête d'un service. Une carte complète de plusieurs services nécessitera probablement Pro.

Le modèle gratuit

Le modèle gratuit est /templates/kubernetes-architecture : Utiliser ce modèle l'ouvre comme nouveau diagramme dans votre workspace. Pour une mise en page plus complète, /examples/kubernetes-microservices propose Utiliser cet exemple, qui le copie pour que vous puissiez renommer les nœuds d'après vos services. Pour le seul chemin du trafic, /examples/kubernetes-ingress-flow est un point de départ plus petit. D'autres modèles sont réunis sur la page de cas d'usage Kubernetes.

FAQ

Faut-il dessiner le control plane ? Seulement si le diagramme porte sur la plateforme elle-même, par exemple pour une équipe plateforme ou un plan de mise à niveau. Dans un diagramme applicatif, le control plane est du bruit ; les lecteurs supposent qu'il existe.

Des Pods ou des Deployments ? Des Deployments, avec un nombre de réplicas. Ne dessinez des Pods individuels que lorsqu'un Pod précis compte : une disposition de sidecars, une session de débogage, ou l'exécution d'un Job ou d'un CronJob.

Comment le garder à jour ? Attribuez-lui un responsable, inscrivez une date de vérification sur le canvas, et relisez-le en même temps que les pull requests qui modifient les services qu'il montre. Un export JSON du diagramme peut vivre dans le dépôt, à côté des manifestes.

Un seul diagramme peut-il couvrir plusieurs clusters ? Oui, à un niveau plus élevé : une frontière par cluster, et seulement le trafic entre clusters. Gardez le détail de chaque cluster dans des diagrammes séparés.

Commencez gratuitement — un siège, sans carte bancaire