Pourquoi la documentation SRE est importante. 3e partie

Bonsoir à tous! Nous sommes pressés de partager la nouvelle qu'en février nous lançons un nouveau flux sur le cours Devops - Practices and Tools , ce qui signifie qu'il est temps de terminer ce que nous avons commencé et de publier la troisième partie de l'article: «Pourquoi la documentation SRE est importante» . C'est parti!

Documents pour la gestion des commandes SRE

Les équipes SRE ont besoin d'une documentation fiable et abordable pour travailler efficacement.

Site d'équipe

Remarque: Au lieu du site, vous pouvez utiliser un espace ou une section distincte dans Confluence / Wiki.

Le site de l'équipe est important car il assure la coordination des informations et de la documentation relatives à l'équipe SRE et à ses projets. Par exemple, sur Google, de nombreuses équipes SRE utilisent g3doc (une plate-forme de documentation interne de Google où les quais vivent dans le code source avec le code associé), et certaines équipes utilisent g3doc et Google Sites: dans ce cas, les pages g3doc sont étroitement liées au code / détails d'implémentation.

Charte d'équipe



Les équipes SRE doivent soutenir une charte publiée qui décrit la motivation au travail et documente l'engagement continu. La charte est nécessaire pour établir l'identité, les principaux objectifs et la valeur de l'équipe dans toute l'entreprise.

La charte comprend généralement les éléments suivants:

• Description de haut niveau du domaine de responsabilité de l'équipe. Y compris le type de services pris en charge par l'équipe (et comment), les systèmes associés, des exemples.
• Une brève description de quelques-uns des services les plus importants pris en charge par l'équipe. Cette section met également en évidence les technologies clés et les défis de leur utilisation, les avantages de l'implication des SRE et leurs responsabilités.
• Principes et valeurs clés de l'équipe.
• Liens vers le site Web et la documentation de l'équipe.

Il suppose également la présence d'un énoncé de vision (le concept de vision pour l'avenir - une description inspirante des objectifs à long terme de l'équipe) et une feuille de route pour plusieurs blocs.

Documentation pour l'intégration de nouveaux SRE

Investir dans des outils et du matériel de formation pour les nouveaux employés a un effet positif sur la vitesse d'intégration des employés dans les processus de travail. Il est avantageux pour les équipes de SRE de former les nouveaux arrivants avec toutes les compétences nécessaires au travail posté dès que possible. L'histoire de Zoe montre clairement comment le manque de formation à temps plein pour un nouvel employé fait d'un incident mineur un grave dysfonctionnement.

De nombreuses équipes SRE préparent les nouveaux employés aux quarts à l'aide de listes de contrôle. Une liste de contrôle des équipes couvre généralement les domaines de haut niveau (divisés en sous-sections) que les membres de l'équipe doivent comprendre. Des exemples de tels domaines sont les concepts de production, le front-end et le back-end, l'automatisation et l'instrumentation, la surveillance et la journalisation. De plus, des instructions pour se préparer au quart de travail et les tâches exécutées pendant le quart de travail peuvent être incluses dans la liste de contrôle.

Pour préparer les nouveaux membres de l'équipe SRE, ils utilisent également des exercices de jeu de rôle (ils sont appelés Wheel of Misfortune - la Wheel of Failure dans Google). Cet exercice est un scénario de défaillance avec un ensemble spécifique de données et de signaux dont SRE pourrait avoir besoin pour résoudre un problème pendant un quart de travail. Les membres de l'équipe jouent à tour de rôle le rôle d'un ingénieur de service pour affiner leur maîtrise de la reprise après sinistre et la capacité de déboguer le système. Wheel of Malfortune vérifie si chaque membre de l'équipe sait où trouver la documentation pour résoudre le problème et comment faire face à l'échec.

Gestion du stockage

Toutes les informations de l'équipe SRE peuvent être dispersées sur plusieurs sites, le référentiel local et les dossiers Google Drive, ce qui complique grandement la recherche du bon. Comme cela s'est produit dans l'exemple décrit précédemment, l'outil opérationnel critique et les instructions pour son utilisation n'étaient pas disponibles pour Zoé (SRE en service), car ils étaient cachés dans le répertoire personnel de son responsable technique, et l'incapacité à les trouver a considérablement augmenté la durée de la panne de service. Pour vous débarrasser de ces problèmes, vous devez structurer toutes les informations et vous assurer que les membres de l'équipe savent où les trouver et les stocker, et comment les conserver. La structure bien développée aidera l'équipe à trouver des informations plus rapidement. Les nouveaux membres de l'équipe seront plus rapides à se tenir à jour, tandis que les ingénieurs en service résoudront les problèmes plus rapidement.

Voici quelques directives sur la façon de créer et de gérer un référentiel de documentation:

• Identifiez les principales parties prenantes et menez de brèves interviews pour identifier tous les besoins.
• Trouvez autant de documentation que possible et analysez les lacunes dans le contenu.
• Basez la structure de votre site pour créer une nouvelle documentation aux bons endroits.
• Déplacer la documentation existante vers un nouvel emplacement.
• Archivez et démontez l'ancienne documentation.
• Effectuez des contrôles réguliers pour garantir la qualité / cohérence de la documentation prise en charge.
• Assurez-vous que les requêtes de recherche standard renvoient les documents nécessaires tout en haut de la liste des résultats de la recherche.
• Utilisez des signaux, tels que Google Analytics, pour mesurer les pratiques standard.

Remarque sur la prise en charge du référentiel: il est important de vérifier et de mettre à jour régulièrement la documentation. Le nom du propriétaire et la date du dernier contrôle doivent être visibles - ces informations permettent de vérifier l'exactitude du document sélectionné. Zoe dans l'histoire n'a pu trouver que la documentation obsolète d'un outil critique, perdant ainsi la capacité de résoudre rapidement le problème. La documentation non fiable et obsolète rend SRE moins efficace, ce qui affecte négativement la fiabilité des services gérés.

Disponibilité du référentiel

Les équipes SRE doivent s'assurer que la documentation reste disponible même si le référentiel standard plante et n'est pas disponible. Chaque Google SRE possède une copie de sa documentation critique. Cette copie est disponible sur un périphérique de stockage compact chiffré ou sur un support physique similaire amovible mais sécurisé que chaque SRE a en service.

Documentation pour la mise hors service d'un service

Lorsque le cycle de vie d'un service prend fin, le SRE le désaffecte de manière prévisible. Cette section fournit des recommandations pour la documentation sur la mise hors service d'un service.

Il est important d'informer les utilisateurs à l'avance de la mise hors service du service et de fournir un calendrier et des étapes. Votre annonce doit expliquer quand l'enregistrement des nouveaux utilisateurs se termine, comment les bogues existants et détectés dans le futur seront traités et quand le service cessera finalement de fonctionner. Identifiez clairement toutes les dates importantes et le processus de réduction du support pour SRE, envoyez des annonces intermédiaires au fur et à mesure de votre progression.

Une simple distribution par e-mail ne suffit pas - vous devez mettre à jour la page principale de la documentation, des playbooks et des codelabs. Aussi, si possible, commentez les fichiers d'en-tête. Décrivez les détails de l'annonce dans un document (en plus de la lettre) auquel les utilisateurs peuvent se référer. La lettre doit être aussi courte que possible, mais en même temps informative, reflétant tous les points principaux. Décrivez des détails supplémentaires: motivation de l'entreprise à désactiver le service, quels outils les utilisateurs peuvent-ils utiliser pour migrer vers un autre service, quel support est disponible pendant la migration. Il est également utile de créer une page FAQ, en la remplissant au fil du temps avec de nouvelles informations sur les questions posées par les utilisateurs.

Le rôle des éditeurs de documentation technique

Les éditeurs techniques (ou rédacteurs techniques) fournissent des services qui rendent le SRE plus efficace et productif. L'éventail des tâches ne se limite pas à la rédaction de documents séparés selon les exigences spécifiées par l'équipe SRE.

Voici quelques recommandations pratiques pour les éditeurs techniques sur le travail avec les équipes SRE.

• Les éditeurs techniques collaborent avec SRE pour créer une documentation d'exploitation pour l'exécution des services et une documentation de production pour les produits et outils SRE.
• Ils créent et mettent à jour des référentiels de documentation, les structurent et les réorganisent en fonction des besoins des utilisateurs, et améliorent les documents individuels dans le cadre de la gestion globale du référentiel.
• Les éditeurs aident à identifier les améliorations requises par la gestion de la documentation et des informations. Cela comprend l'évaluation de la documentation pour la collecte des exigences, l'amélioration des documents et des sites créés par les ingénieurs, le conseil aux équipes sur les règles de création, d'organisation, de refonte, de recherche et de maintenance de la documentation.
• Les éditeurs doivent évaluer et améliorer les outils de documentation pour fournir de meilleures solutions SRE.

Patterns

Les éditeurs techniques fournissent également des modèles qui simplifient la création et l'utilisation de la documentation SRE. Les modèles procèdent comme suit:

• Simplifiez la création de documentation en fournissant aux ingénieurs une structure claire pour la création de nouveaux documents.
• Ajoutez des sections de tous les documents nécessaires pour l'achèvement complet de la documentation.
• Ils aident le lecteur à comprendre rapidement le sujet du document, le type d'information et son organisation.

Site Reliability Engineering contient plusieurs exemples de modèles de documentation. Dans cette section, nous donnerons quelques exemples supplémentaires pour montrer comment les modèles fournissent une structure et un guide pour les ingénieurs à remplir avec du contenu.

Entretien de service

Revue

Qu'est ce que c'est Que fait-il? De haut niveau décrivent les fonctionnalités fournies aux clients (utilisateur final, composants, etc.).

L'architecture

Expliquez comment fonctionne l'architecture. Décrire le mouvement des données entre les composants. Envisagez d'ajouter un diagramme de système de dépendance critique et des requêtes et des données de flux.

Clients et dépendances

Répertoriez tous les clients (appartenant à d'autres équipes) qui en dépendent et tous les services (appartenant à d'autres équipes) dont ils dépendent. (Cela peut également être démontré sous la forme d'un schéma de système.)

Code et configuration

Expliquez la structure de la production. Où est-il en cours d'exécution? Répertoriez les fichiers binaires, les travaux, les centres de données et les paramètres du fichier de configuration, ou indiquez où ils se trouvent tous. Indiquez également l'emplacement du code et, si nécessaire, des informations sur la génération.

Répertoriez et décrivez les fichiers de configuration, les modifications et les ports requis pour faire fonctionner ce produit ou service.

Décrivez les éléments suivants: quels fichiers de configuration ont été modifiés pour ce produit ou service? Comment se déroule la configuration?

Les processus

Décrivez les éléments suivants: quels démons et autres processus doivent être exécutés pour que le service fonctionne? Quels scripts de contrôle ont été créés pour gérer le service?

Mentions légales

Énumérez et décrivez les fichiers journaux créés par le composant et les observations effectuées. Décrivez les éléments suivants: Quels journaux sont générés par ce composant? Que contient chaque fichier? Quelles sont les recommandations pour étudier ces fichiers? Quels aspects du composant doivent être contrôlés pour un fonctionnement fiable du service?

Tableaux de bord et outils

Collez des liens vers des tableaux de bord et des outils associés.

Puissance

Indiquez la puissance d'une seule instance; Datacenter à l'échelle mondiale: valeurs QPS, bande passante et latence.

SLA

Fournissez des cibles d'accessibilité.

Procédures standard

Ajoutez des liens vers les procédures, y compris les tests de charge, les mises à jour / états push / drapeau, etc. Ajoutez des liens vers la documentation des alertes dans le playbook des alertes.

Les références

Ajoutez des liens vers la documentation de conception du composant ou des composants associés, généralement rédigés par l'équipe de développement, ainsi que d'autres informations connexes.

Playbook

Le titre

Dans le nom, spécifiez le nom de l'alerte (par exemple, NormalAlert_AlertVery Very Normal).

Revue

Décrivez ce qui suit: Que signifie cette alerte? Vient-il sur un téléavertisseur ou uniquement par courrier? Quels facteurs déclenchent une alerte? Quelles parties du service sont affectées? Quelles alertes lui sont associées? Qui doit être averti?

Alertes de niveau de danger

Justifiez le degré de danger de la notification et l'impact des pièces concernées sur l'état général du service.

Confirmation

Fournissez des instructions claires pour vérifier et valider l'état.

Dépannage

Énumérez et décrivez les méthodes de débogage et les sources d'informations associées. N'oubliez pas les liens vers les tableaux de bord correspondants. Activez les alertes. Décrivez ce qui suit: Qu'est-ce qui apparaîtra dans les journaux lorsqu'une alerte est déclenchée? Quels sont les gestionnaires de débogage? Existe-t-il des scripts et des commandes utiles? Quelle sortie génèrent-ils? Y a-t-il des tâches supplémentaires qui doivent être résolues après la suppression de l'alerte?

Solution

Décrivez et répertoriez toutes les solutions possibles au problème à l'origine de l'alerte. Décrivez les éléments suivants: Comment puis-je résoudre le problème et résoudre l'alerte? Quelles commandes exécuter pour redémarrer? Qui doit être averti si une alerte est déclenchée en raison des actions de l'utilisateur? Qui a l'expérience du débogage d'un problème similaire?

Escalade

Énumérez et décrivez les chemins d'escalade. Indiquez la personne ou l'équipe à notifier et quand le faire. Si l'escalade n'est pas nécessaire - écrivez à ce sujet.

Liens connexes

Fournissez des liens vers les alertes, les procédures et la documentation de révision associées.
Rapport de service trimestriel
Présentation
Décrivez le service dont l'équipe est responsable.

Planification des capacités

Y compris:

• La demande réelle pour le service, à partir des 6 à 8 derniers trimestres, exprimée dans les mesures les plus pertinentes pour le service (par exemple, QPS ou DAU).
• Prévision pour les 8 prochains trimestres.
• Plan de capacité qui répond à la demande projetée au niveau de redondance requis - spécifiez les risques de déficit et / ou de planification de capacité.

Nous recommandons également d'ajouter des prévisions pour les 2-4 derniers trimestres afin que le lecteur puisse évaluer la stabilité et l'exactitude des prévisions.

Mise en œuvre / disponibilité du SLA

Tous les services pris en charge par SRE doivent avoir un SLA écrit, qui évalue les performances de chaque trimestre.

La section SLA doit contenir les paramètres des principales composantes du service pour mesurer la faisabilité trimestrielle des conditions SLA, ainsi qu'un lien vers une équipe SLA écrite.

Incidents concomitants (facultatif)

Énumérez 3 à 5 incidents ou défaillances majeurs par trimestre.

Réalisations (facultatif)

Énumérez les principales réalisations du trimestre.

Modifications SLA (souhaitées)

Modifications récentes du SLA.

Détails du service (souhaitable)

La section peut inclure la croissance, les statistiques des retards, etc.

Informations sur l'équipe (facultatif)

Peut inclure des informations sur la composition de l'équipe, les statuts, les projets, les statistiques des équipes.

Sources de données (obligatoire)

Décrire les sources utilisées pour obtenir les valeurs d'accessibilité, les méthodes de calcul, fournir des liens vers les tableaux de bord correspondants.

Charte d'équipe

Qui nous sommes

En une phrase (~ 1 ligne), décrivez l'environnement technologique, les propositions des clients et des équipes, ainsi que le degré d'implication SRE et l'expertise particulière.

Services supportés

Pour clarifier davantage la portée du travail, décrivez les services (ou leur groupe) que l'équipe soutient.

Comment nous passons du temps

Le cadrage aide à créer une feuille de route et à atteindre et soutenir des objectifs à long terme.

Valeurs d'équipe

Décrivez clairement les valeurs. Cela affecte la façon dont les membres de l'équipe interagissent entre eux et la façon dont votre équipe est perçue par les autres.

Conclusion

Que vous soyez un SRE, un responsable SRE ou un éditeur technique, vous comprenez maintenant l'importance cruciale de la documentation dans la vie d'une équipe SRE efficace. Une bonne documentation permet à l'équipe SRE de se développer et d'adhérer à une méthodologie claire de gestion des services nouveaux et existants.

Ainsi, nous avons publié la dernière partie de cet article, les première et deuxième parties peuvent être lues en cliquant sur les hyperliens, et vous pouvez obtenir des informations encore plus utiles dans notre leçon ouverte , qui se tiendra le 19 février. Nous attendons tout le monde!