Présentation des enregistrements de décision d'architecture

Last reviewed 2024-08-16 UTC

Les enregistrements de décision d'architecture (ADR) vous aident à expliquer pourquoi vos équipes d'application ou d'infrastructure ont fait certains choix de conception. Ce document explique quand et comment utiliser les ADR lorsque vous créez et exécutez des applications sur Google Cloud.

Un ADR capture les principales options disponibles, les principales exigences qui déterminent une décision, et les décisions de conception elles-mêmes. Les ADR sont généralement stockés dans un fichier Markdown proche du code base pertinent pour cette décision. Si un utilisateur doit comprendre le contexte d'une décision d'architecture spécifique, par exemple pourquoi vous utilisez un cluster Google Kubernetes Engine (GKE) régional, il peut examiner l'ADR et le code correspondant.

Les ADR peuvent également vous aider à exécuter des applications et des services plus fiables. L'ADR vous aide à comprendre votre état actuel et à résoudre les problèmes le cas échéant. Les ADR créent également un ensemble de décisions d'ingénierie pour aider aux déploiements futurs et à la prise de décision.

Quand utiliser des ADR

Les ADR permettent de suivre les domaines clés qui, selon vous, sont importants pour votre déploiement. Les catégories suivantes peuvent figurer dans vos ADR :

  • Des produits spécifiques, tels que le choix entre Pub/Sub et Cloud Tasks.
  • Options et configurations de produit spécifiques, telles que l'utilisation de clusters GKE régionaux avec objet Ingress multi-cluster pour les applications à disponibilité élevée.
  • Conseils d'architecture généraux, par exemple les bonnes pratiques pour les fichiers manifestes Dockerfile.

Voici quelques exemples spécifiques de choix qui peuvent justifier de créer un ADR :

  • Comment et pourquoi configurer la haute disponibilité pour vos instances Cloud SQL ?
  • Quelle est votre approche en termes de disponibilité des clusters GKE ? Utilisez-vous des clusters régionaux ? Utilisez-vous des versions Canary ? Pourquoi ?

Lorsque vous évaluez les produits à utiliser, l'ADR vous aide à expliquer chacune de vos décisions. Vous pouvez revenir à l'ADR à mesure que l'équipe évolue et gagne en connaissance de la pile logicielle utilisée, ou lorsque vous devez prendre de nouvelles décisions ou ajuster des décisions précédentes. Si vous effectuez des ajustements, incluez la décision précédente et la raison de la modification. Cet historique permet de conserver une trace de l'évolution de l'architecture à mesure que les besoins de l'entreprise évoluent, ou lorsque de nouvelles exigences techniques ou solutions sont identifiées.

Les situations suivantes vous aident à savoir quand créer des ADR :

  • Lorsque vous avez un défi ou une question technique et qu'il n'y a pas de base existante pour prendre une décision (solution recommandée, procédure d'opération standard, plan ou codebase).
  • Lorsque vous ou votre équipe proposez une solution qui n'est pas documentée de manière facilement accessible à l'équipe.
  • Lorsque deux options d'ingénierie ou plus sont disponibles et que vous souhaitez documenter vos réflexions et les raisons de vos choix.

Lorsque vous écrivez un ADR, il est utile de garder à l'esprit vos lecteurs potentiels. Les principaux lecteurs sont des membres de l'équipe qui travaillent sur la technologie couverte par l'ADR. Des groupes plus larges de lecteurs potentiels de l'ADR peuvent inclure des équipes adjacentes qui souhaitent comprendre vos décisions, telles que les équipes d'architecture et de sécurité.

Vous devez également tenir compte du fait que l'application peut changer de propriétaire ou inclure de nouveaux membres d'équipe. Ce programme aide les nouveaux contributeurs à comprendre le contexte des choix d'ingénierie qui ont été faits. L'ADR facilite également la planification des modifications futures.

Format d'un ADR

Un ADR standard comprend un ensemble de chapitres. Vos ADR doivent vous permettre de capturer ce que vous jugez important pour l'application et votre organisation. Certains ADR peuvent tenir sur une page, tandis que d'autres nécessitent une explication plus longue.

L'exemple d'ADR suivant montre comment mettre en forme un ADR pour inclure les informations importantes pour votre environnement :

  • Auteurs et équipe
  • Contexte et problème que vous souhaitez résoudre
  • Exigences fonctionnelles et non fonctionnelles que vous souhaitez traiter
  • Impact potentiel du parcours utilisateur critique (CUJ) sur la décision
  • Présentation des options clés
  • Votre décision et les raisons de ce choix

Pour vous aider à conserver une trace de vos choix, vous pouvez inclure un horodatage pour rappeler quand la décision a été prise.

Fonctionnement des ADR

Les ADR fonctionnent mieux lorsque les ingénieurs, les développeurs ou les propriétaires d'applications peuvent facilement accéder aux informations qu'ils contiennent. Lorsqu'ils ont une question sur la raison pour laquelle une opération est effectuée d'une certaine manière, ils peuvent consulter l'ADR pour trouver une réponse standardisée.

Pour rendre l'ADR accessible, certaines équipes l'hébergent dans un wiki centralisé également accessible aux propriétaires d'établissements, plutôt que dans le dépôt de gestion du code source. Lorsqu'un utilisateur a une question sur une décision d'ingénierie spécifique, l'ADR est là pour fournir des réponses.

Les ADR fonctionnent bien dans les cas suivants :

  • Intégration: les nouveaux membres de l'équipe peuvent facilement en apprendre davantage sur le projet et peuvent examiner le rapport ADR s'ils ont des questions lorsqu'ils apprennent un nouveau codebase.
  • Évolution de l'architecture: en cas de transfert de la pile technologique entre plusieurs équipes, les nouveaux propriétaires peuvent consulter les décisions précédentes pour comprendre l'état actuel du système. L'équipe peut également examiner les décisions passées lorsqu'une nouvelle technologie est disponible. L'ADR peut aider les équipes à éviter de répéter les mêmes points de discussion et à fournir un contexte historique lorsque les équipes reviennent sur des sujets.
  • Partage des bonnes pratiques: les équipes peuvent s'aligner sur les bonnes pratiques de l'ensemble de l'organisation lorsque les ADR expliquent pourquoi certaines décisions ont été prises et pourquoi les alternatives ont été écartées.

Un ADR est souvent écrit en Markdown pour être léger et basé sur du texte. Les fichiers Markdown peuvent être inclus dans le dépôt de gestion du code source avec le code de votre application.

Stockez vos ADR à proximité du code de votre application, idéalement dans le même système de contrôle de version. Lorsque vous apportez des modifications à votre ADR, vous pouvez examiner les versions précédentes de la source si nécessaire.

Vous pouvez également utiliser un autre support, comme un document Google Docs ou un wiki interne. Ces emplacements alternatifs peuvent être plus accessibles aux utilisateurs qui ne font pas partie de l'équipe qui a créé l'ADR. Une autre option consiste à créer votre ADR dans un dépôt de contrôle de source, mais en mettant en miroir les décisions clés dans un wiki plus accessible.

Étape suivante