Article rédigé par Eren Altogan et Faissal Salami

A vouloir délivrer des incréments de plus en plus rapidement pour générer du feedback, on en oublie souvent les « tâches ingrates » de nos livraisons. La documentation est l’un d’entre eux (les tests en sont un autre).

Par manque de temps, on se contente souvent d’une mise à jour du fichier readme inclus avec le repo du projet avec une phrase lacunaire. Dans le meilleur des cas, on fait référence aux nombreux tickets inclus dans cette livraison. Pourtant, la documentation est tout aussi importante que l’incrément en lui-même.

Paradoxalement, quand nous cherchons des informations, nous nous précipitons vers le fichier readme en espérant qu’un autre membre de l’équipe aura été plus rigoureux que nous. Et c’est souvent peine perdue. Si mettre à jour la documentation est une tâche chronophage, c’est qu’on a besoin d’un peu d’aide. Si on a bien des générateurs de code, on devrait donc avoir des générateurs de documentation, n’est-ce pas ?

Cloudockit pour générer la documentation technique

Cloudockit est un générateur de documentation technique. Il va créer automatiquement des rapports aux formats Word, PDF & HTML (d’autres formats à venir) mais également des diagrammes Visio, Draw.io, Lucidchart et PDF de votre environnement Cloud ou On-Premises pour un grand nombre de plateformes :

• Microsoft Azure
• AWS
• Google Cloud Platform
• Vmware
• Hyper-V

Cloudockit analyse votre infrastructure, génère de la documentation ainsi que des schémas d’architecture comme on peut le voir ci-dessous, mais est capable d’aller beaucoup plus loin en proposant :

• Une analyse de la compliance selon différents critères (disponibilité, pratiques, sécurité, performance, coût) ;
• La détection des changements entre deux analyses sur ces mêmes critères.

Cette dernière fonctionnalité est très intéressante pour retracer les changements dans le temps et retrouver la cause d’une dérive dans nos déploiements.

Cloudockit est disponible en trois versions :

• SaaS
• Desktop
• Container

Quelle édition de Cloudockit choisir ?

Utiliser la solution SaaS implique qu’on accepte que les données générées soient stockées en ligne mais aussi que la solution ait accès à nos infrastructures. Selon les exigences de sécurité de vos environnements, il peut être plus opportun de choisir la version « Desktop » qui propose un stockage local de vos données sur une machine physique / virtuelle. D’un point de vue licencing, la solution est facturée au nombre d’utilisateurs. Chaque licence acquise nous donne droit à un usage SaaS et à un autre Desktop distinct.

Enfin, l’édition Container peut être intéressante à regarder pour une intégration de Cloudockit dans vos pipelines Azure DevOps. Elle est limitée à vingt-cinq utilisateurs. Dans le contexte de cet article, nous allons nous intéresser à la version « Desktop ».

Mise en œuvre de la solution Cloudockit

La solution Cloudockit est disponible sur le site de l’éditeur et vous pourrez vous aider de la documentation utilisateur mise à disposition. Une fois installée, la solution est assez simple d’usage en nous proposant de d’analyser immédiatement une souscription ou de planifier l’opération : c’est ce que nous allons faire en sélectionnant l’option « Start or Schedule a document generation ».

Dans le contexte de cet article, nous allons analyser une infrastructure Azure mais on comprend ici tout l’intérêt de la solution puisqu’elle permet d’analyser les infrastructures hébergées sur les principales plateformes Cloud mais aussi On-Premises.

Cloudockit vous propose trois méthodes d’authentification :

• La première, la plus classique, utilise un service principal avec un secret comme méthode d’authentification. Cette approche impliquera de gérer l’expiration du secret / certificat, car tout à une durée de vie.
• La deuxième repose sur une authentification utilisateur, ce qui exclut toute forme d’automatisation.
• Enfin la dernière repose sur les Managed Identities et n’est utilisable que sur une machine virtuelle Azure ou machine virtuelle managée avec Azure ARC.

Ce service principal devra avoir des permissions sur la ou les souscriptions que nous voulons analyser (Rôle Reader au niveau de la souscription ou au niveau Management group). Parce que les rapports seront stockés dans un Storage Account, l’identité devra également disposer du rôle « Contributeur » sur cette ressource Azure. Il ne nous reste plus qu’à sélectionner la souscription à analyser.

Cas d’usage de Cloudockit

Pour illustrer les capacités de Cloudockit, nous avons déployé les ressources Azure suivantes via Terraform :

• Virtual network
• Load Balancer
• Public IP
• Network Interface
• Virtual Machine
• Virtual Machine Scale Set
• Disk

Dans l’état actuel de notre déploiement, on peut constater que notre Virtual Machine Scale Set est configuré avec deux instances.

Une fois ces ressources déployées, ne reste plus qu’à analyser notre souscription.

Analyse de notre environnement

Dans Cloudockit, on dispose de l’onglet « Documents » pour générer les rapports. Nous pouvons choisir plusieurs formats pour les rapports (on peut relever qu’il manque toutefois le markdown) et pour la génération des schémas.

Point de vigilance : le format JSON sera très utile pour analyser le contenu de ces rapports. L’onglet « Organize content » est intéressant pour filtrer spécifiquement ce que nous voulons analyser (resource groups, tags…).

Avec l’onglet « Track Changes », nous avons la possibilité de générer notre rapport en le comparant à un précédent. C’est une fonctionnalité très intéressante, surtout dans un contexte CI/CD pour comprendre la nature des changements opérés sur l’infrastructure.

Le résultat de cette analyse sera restitué sous forme d’un fichier JSON, ce qui facilite son exploitation ultérieure. Le résultat peut être mis à disposition de plusieurs manières via l’onglet « Drop-off ». Nativement Cloudockit propose les moyens suivants :

• Mail ;
• Mise à disposition dans un Storage Account / Storage local ;
• Mise à disposition dans un espace SharePoint dans Office 365 et donc indirectement dans Teams ;
• One Drive ;
• GitHub ;
• Azure DevOps ;
• Callback Url : une fois l’analyse terminée, Cloudockit va rappeler l’URL renseignée et mettre à disposition un lien contenant les documents générés. L’option facilite grandement l’intégration dans une chaine CI/CD.

La gestion de la compliance est un autre point d’attention de Cloudockit. La solution propose de comparer notre infrastructure avec les exigences de certaines règlementations telles que HIPAA (Health Insurance Portability and Accountability Act) et PCI (Peripheral Component Interconnect).

A noter : il est tout à fait possible de créer ses propres règles de conformité.

Rapports mis à disposition

Une fois l’opération terminée, le rapport est mis à disposition selon le ou les moyens sélectionnés.

Les rapports mis à disposition sont très détaillés avec une approche « top to bottom » nous précisant les régions Azure dans lesquelles nous avons des ressources déployées (dans la région Azure West Europe) et la position de notre souscription dans la hiérarchie des Management groups.

Resource Group

Dans le document, nous trouverons également une section « groupe de ressources » listant les services. Nous retrouvons dans cette section les ressources que nous avons déployées.

Premier point d’attention : la section « Billing ». Dans cette section, nous allons être en mesure de suivre l’évolution de notre consommation Azure pour identifier nos postes de dépenses. Avec la fonction « Track changes », on va pouvoir déterminer si les changements que nous avons opérés sur notre infrastructure ont permis de réduire les coûts. Si ce n’est pas le cas, nous serons à même de déterminer quels changements sont la cause de notre augmentation des coûts.

Avec l’introduction de la notion de Landing zones voilà quelques années, nos environnements Azure sont de plus en plus standardisés avec des Azure Policies. Réaliser et maintenir un inventaire exhaustif des policies que nous mettrons en œuvre est aujourd’hui bien plus simple.

Revenons sur les ressources que nous avons déployées : ci-dessous notre Virtual Machine Scale Set.

Nous observons qu’il y a bien les deux instances déployées.

Compliance Rule

Dans cette section, on trouve le résultat de l’évaluation des règles de conformité de nos ressources.

Détection des changements

Pour la suite de la démonstration, nous avons ajouté une instance à notre ressource Virtual Machine Scale Set. Dans le « Plan » de notre déploiement Terraform, le changement a bien été identifié : celui-ci est bien répercuté dans Azure lors de la phase « Apply ».

Lorsqu’on relance l’analyse de notre environnement, nous disposons de l’historique des analyses et pouvons sélectionner celle que nous souhaitons utiliser pour mettre en évidence les changements opérés dans notre infrastructure. Voici les informations qui apparaissent maintenant dans le nouveau document généré.

Nous constatons que la colonne « Trend » est remplie avec des flèches :

• Une flèche vers le haut indique l’ajout d’une ressource ;
• Une flèche vers la droite signifie qu’il n’y a pas eu de changement ;
• Enfin, une flèche vers le bas nous informe de la suppression de la ressource.

Il existe aussi une colonne « Number » indiquant le nombre de ressources. Dans notre cas, nous constatons bien l’ajout d’une ressource avec le (+1) au niveau VMSS. Nous sommes passés de deux à trois instances.

On retrouve cette même information dans la rubrique « Change detected » des rapports générés. Dans notre contexte, l’ajout d’une nouvelle instance à notre Virtual Machine Scale Set a d’autres conséquences :

• Un nouveau membre associé au Backend pool du Load Balancer ;
• Une nouvelle adresse IP consommée sur le sous-réseau avec une interface réseau ;
• Un Managed disk supplémentaire.

Au niveau du schéma, nous voyons bien la nouvelle instance avec ses dépendances. Dans le schéma ci-dessous, nous observons des « + », pour indiquer les ressources ajoutées dans l’environnement :

Mise en pratique de Cloudockit

La réalisation de la documentation est souvent repoussée en dernier car il s’agit d’une tâche très chronophage. Pourtant, la perte de temps est tout aussi importante pour vérifier une information ou faire évoluer une infrastructure quand la documentation n’est pas à jour.

Avec Cloudockit, vous n’avez plus d’excuse pour ne pas avoir de documentions de vos infrastructures à jour !

De plus dans un monde où le FinOps est un sujet de plus en plus important, Cloudockit vous permet de faire d’une pierre deux coups en surveillant l’évolution financière de votre infrastructure.

Bien entendu, cette solution a un coût, mais il doit être vu comme un investissement.

Si le sujet vous intéresse, nous vous conseillons la lecture de l’article « Automate Your Cloud Documentation & Architecture Diagrams in Your Pipelines With Cloudockit Container ».

Article rédigé par Eren Altogan et Faissal Salami