Docker - Des diagrammes en tant que code

Quel plaisir de pouvoir dessiner des diagrammes en écrivant simplement du texte. Certains outils sont plus connus que d'autres, par exemple Mermaid — que j'ai depuis automatisé dans Documentation as Code - Transformez votre infrastructure en diagrammes soignés avec Python et Mermaid, et dont le cousin Graphviz est traité dans Python - Générer des flux avec pydot.

Connaissiez-vous https://diagrams.mingrammer.com/ ? Explorons-le avec, bien entendu, une image Docker prête à l'emploi.

Le résultat​

Voici un diagramme produit par cet article, et il n'y avait que du texte en entrée :

La commande qui l'a produit tient sur une ligne ; le fichier .py est envoyé dans un container et le .png atterrit dans votre dossier courant :

$ cat team.py | docker run -i --rm -v $(pwd):/out -u 1000:1000 gtramontina/diagrams:0.23.3▋

Pourquoi ça fonctionne​

• Le fichier .py n'est pas exécuté sur votre machine : il est envoyé dans le container, qui contient Python, la librairie diagrams, Graphviz et l'ensemble des jeux d'icônes AWS/Azure/GCP/K8S.
• -v $(pwd):/out est ce qui permet à l'image générée de revenir dans votre dossier au lieu de mourir avec le container.
• -u 1000:1000 exécute le container avec votre identité, de sorte que le fichier produit appartienne à votre utilisateur et pas à root.

Le code source​

Comme toujours pour la démo, ouvrez un shell Linux et lancez mkdir -p /tmp/docker-diagrams && cd $_ pour créer un dossier docker-diagrams dans votre dossier temporaire Linux et vous y rendre.

Créez ensuite un nouveau fichier team.py avec le contenu qui a produit le diagramme ci-dessus :

from diagrams import Diagram
from diagrams.aws.compute import EC2
from diagrams.aws.database import RDS
from diagrams.aws.network import ELB

with Diagram("My Team", show=False, direction="TB"):?
    (
        ELB("Olivier")?
        >> [EC2("Christophe"), EC2("Jason"), EC2("Niki"), EC2("Rudy"), EC2("Stijn")]?
        >> RDS("Work together")?
    )

Puis lancez la commande de conversion montrée plus haut.

0.23.3 est la dernière version disponible au moment d'écrire ce document. Voir https://hub.docker.com/r/gtramontina/diagrams/tags pour récupérer la plus récente.

Facile, non ?

Une vraie architecture​

Vingt lignes de Python pour un organigramme d'équipe, c'est sympa ; voici le même exercice sur une infrastructure réelle :

from diagrams import Cluster, Diagram
from diagrams.k8s.compute import Pod, StatefulSet
from diagrams.k8s.network import Service
from diagrams.k8s.storage import PV, PVC, StorageClass

with Diagram("Stateful Architecture", show=False):?
    with Cluster("Apps"):?
        svc = Service("svc")
        sts = StatefulSet("sts")

        apps = []?
        for _ in range(3):?
            pod = Pod("pod")
            pvc = PVC("pvc")
            pod - sts - pvc?
            apps.append(svc >> pod >> pvc)?

    apps << PV("pv") << StorageClass("sc")?

Et l'image obtenue :

Dingue, non ? Et tout ça sans rien installer !

Le code de l'image Docker est ici : https://github.com/gtramontina/docker-diagrams, et vous trouverez plein d'autres exemples sur https://github.com/mingrammer/diagrams.

Icônes et autres outils (référence, à garder sous le coude)​

Une énorme liste d'icônes/nœuds est disponible sur plusieurs pages à partir de https://diagrams.mingrammer.com/docs/nodes/onprem. Voir OnPrem, AWS, Azure, GCP, IBM, K8S et aussi comment créer les vôtres (à partir d'images .png locales) : Custom.

Et comme diagrams est loin d'être le seul outil texte-vers-image, voici la liste sur laquelle je reviens sans cesse :

• DB Diagram (voir aussi Drawdb-app - Rendez votre modèle de base de données en png, Markdown, mermaid, ...)
• DBML-renderer, dbml-renderer convertit des fichiers DBML en images SVG
• Graphviz, un logiciel open source de visualisation de graphes
• JSON Crack, visualisez instantanément vos données JSON sous forme de graphes (je lui ai consacré un article : Afficher un fichier JSON sous forme de mind map)
• Kroki, crée des diagrammes à partir de descriptions textuelles
• Mermaid, son éditeur en ligne, l'extension de prévisualisation pour vscode et l'outil de conversion en ligne de commande
• Nomnoml, un outil pour dessiner des diagrammes UML avec une syntaxe simple
• Pikchr, Pikchr (prononcez « picture ») est un langage de balisage à la PIC pour les diagrammes dans la documentation technique
• Plantuml, génère des diagrammes à partir d'une description textuelle
• Sequence diagram (semble basé sur Mermaid)
• Structurizr, une façon de créer des modèles d'architecture logicielle Structurizr basés sur le modèle C4, via un langage dédié textuel
• svgbob, transforme vos gribouillis de diagrammes ASCII en jolis petits SVG
• Vega, une grammaire de visualisation
• yEd Graph Editor, une interface graphique : il faut glisser-déposer des objets et les redimensionner. Il ne gère pas les fichiers texte comme les autres outils cités ici.

Conclusion​

Des diagrammes d'architecture qui vivent dans votre repository, que vous pouvez differ et relire comme n'importe quel autre fichier, et qui n'exigent jamais Python ni Graphviz sur votre machine. La prochaine fois que l'infrastructure change, vous modifiez une ligne de texte au lieu de déplacer une boîte à la souris.

Si vous préférez rester sur une syntaxe que vous connaissez déjà, Documentation as Code - Transformez votre infrastructure en diagrammes soignés avec Python et Mermaid fait la même chose avec Mermaid.