Warum SRE-Dokumentation wichtig ist. Teil 2

Guten Abend allerseits!

Vor dem Start des DevOps Practices and Tools-Kursdatenstroms ist also nichts mehr übrig ( dh ein Tag). Dies bedeutet, dass wir Zeit haben müssen, um den Rest des Artikels „Warum SRE-Dokumentation wichtig ist“ in dieser Zeit abzuschließen.

Wir fahren fort.

Dokumente zum Einbinden eines neuen Dienstes

SREs führen eine PRR (Production Readiness Review) durch, um zu überprüfen, ob der Service den Betriebsbereitschaftsstandards entspricht, und um sicherzustellen, dass die Servicebesitzer verstehen, wie SRE-Wissen zur Verwaltung großer Systeme verwendet wird.

Der Service muss diesen Test durchlaufen, bevor er in Produktion geht. (Vor dem Start wird es nicht von SRE, sondern vom Entwicklungsteam selbst unterstützt.) Das Ziel von PRR in dieser Phase besteht darin, sicherzustellen, dass der Service zum Zeitpunkt des Starts die Mindeststandards für Zuverlässigkeit erfüllt.



Die nächste PRR erfolgt vor der Übertragung des SRE-Dienstes, dh nach dem Start kann viel Zeit vergehen. Und wenn das SRE-Team beschließt, einen neuen Service in Anspruch zu nehmen, wird eine gründliche Analyse des Produktionszustands und der verwendeten Servicepraktiken durchgeführt. Ziel ist es, den Prozess der Serviceübertragung in Bezug auf Zuverlässigkeit und Betriebsstabilität zu vereinfachen und SRE dabei zu helfen, besser damit umzugehen.

Durch die Durchführung von PRRs vor der Übergabe des Dienstes können SREs mehr Fragen stellen und höhere Standards für Zuverlässigkeit und Benutzerfreundlichkeit festlegen als bei der Durchführung von PRRs vor dem Start. PRR vor dem Start kann „leicht“ sein, um das Entwicklungsteam nicht zu verlangsamen.

In Zoes Geschichte hatte das Team keinen standardisierten Prozess oder keine PRR-Checkliste, was bedeutet, dass bei der Übertragung des Dienstes sehr wichtige Probleme übersehen werden könnten. Daher besteht die Gefahr einer Kollision mit einer Vielzahl von Problemen, die leicht vorweggenommen und gelöst werden können, bevor die Verantwortung für die Verwaltung des Dienstes übernommen wird.

Für die PRR / Service-Übertragung müssen PRR-Vorlagen und Prozessdokumentationen (Prozessdokumente) erstellt werden, in denen beschrieben wird, wie SRE-Teams mit dem neuen Service arbeiten und PRR-Vorlagen verwenden. Die im Übertragungsprozess verwendeten Muster können umfassender sein als die beim Start verwendeten.

Die PRR-Vorlage deckt mehrere Bereiche ab und muss nach Antworten auf kritische Fragen suchen. Tabelle 1 zeigt einige der Bereiche und verwandten Probleme, die in der Vorlage behandelt werden.

Bereich	Fragen
Architektur und Abhängigkeiten	Wie lautet der Anforderungspfad vom Client zum Frontend und dann zum Backend? Gibt es verschiedene Arten von Anforderungen mit unterschiedlichen Latenzanforderungen?
Kapazitätsplanung	Was sind die Erwartungen für das Verkehrsaufkommen und die Wachstumsraten während und nach dem Start? Haben Sie die Rechenleistung, die zur Unterstützung dieses Datenverkehrs erforderlich ist?
Arten von Fehlern	Gibt es einzelne Fehlerquellen in Ihrer Architektur? Wie können Sie die Nichtverfügbarkeit von Abhängigkeiten beseitigen?
Prozesse und Automatisierung	Sind manuelle Prozesse erforderlich, um den Service zu unterstützen?
Externe Abhängigkeiten	Welche Daten, Codes, Dienste oder Ereignisse von Drittanbietern hängen vom Dienst und dem Start ab? Ist einer Ihrer Partner vom Service abhängig? Wenn ja, müssen sie über den Start informiert werden?

Tabelle 1. Beispielbereiche einer PRR-Vorlage

In der Prozessdokumentation sollten auch die Dokumente angegeben sein, die der SRE vom Produktentwicklungsteam als Voraussetzungen für die Übertragung anfordern sollte. Beispielsweise können sie das Entwicklungsteam bitten, ein Playbook für häufig auftretende Probleme zu erstellen.

Darüber hinaus muss die SRE-Organisation ein Überprüfungsdokument erstellen, in dem dem Entwicklungsteam kurz die Rolle und die Verantwortungsbereiche des SRE erläutert werden. Dies ist notwendig, um realistische Erwartungen zu bilden. Das erste Dokument sollte erläutern, was SRE ist, und alle im vorherigen Teil und am Anfang dieses Artikels behandelten Themen abdecken, einschließlich der Hauptfunktionen, des Lebenszyklus, der Support- / Wartungsverantwortung. Der Hauptzweck dieses Dokuments besteht darin, sicherzustellen, dass Entwickler SRE nicht mit dem OPS-Team verwechseln und Pager-Antworten nicht als alleinige Pflicht von SRE betrachten. Wie in der zuvor beschriebenen Geschichte gezeigt, würde dies zu Kommunikationsproblemen und Missverständnissen führen, wenn die Entwickler zum Zeitpunkt der Übertragung des Dienstes nicht vollständig verstanden hätten, was SRE tat.

Darüber hinaus muss ein Engagement-Modelldokument erstellt werden, um die Erwartungen zu klären und den Prozess der Interaktion zwischen dem SRE-Team und dem Produktentwicklungsteam während und nach der Übertragung des Service zu erläutern. In der Dokumentation behandelte Themen können Folgendes umfassen:

• Service-Transfer-Kriterien und PRR-Prozess.
• Der Prozess der Erörterung von Berichten über Service-Level-Ziele (kurz SLO) und der Fehlerberechnung.
• Neue Startkriterien und Einfrierrichtlinie (falls möglich).
• Inhalt und Häufigkeit der Servicestatusberichte des SRE-Teams.
• Personalbedarf SRE.
• Der Prozess der Planung einer Roadmap für neue Funktionen und die Priorität einer Funktion, die die Zuverlässigkeit (von SRE gefordert) gegenüber neuen Produktfunktionen erhöht.

Servicebetriebsdokumentation

Zur Unterstützung des Dienstes stützen sich die SRE-Teams in erster Linie auf die wichtigsten Betriebsdokumentationen: allgemeine Beschreibung (Interview) des Dienstes, Spielbücher und -verfahren, Post-Mortem, Richtlinien und SLA. (Hinweis: Dieser Abschnitt war im Kapitel „Do Docs Better“ in Seeking SRE enthalten.)

Service-Interview

Eine allgemeine Beschreibung des Dienstes ist wichtig, um zu verstehen, welche Art von Dienst sie unterstützen. SRE muss die Architektur des Systems, seine Komponenten und Abhängigkeiten, die Kontakte des Dienstes und seiner Eigentümer kennen. Die allgemeine Beschreibung des Dienstes ist das Ergebnis der gemeinsamen Arbeit des Entwicklungsteams und des SRE-Teams. Sie wurde erstellt, um SRE-Aufgaben zu leiten und zu priorisieren und Bereiche für weitere Studien zu identifizieren. Solche Interviews werden normalerweise als Ergebnis von PRR erhalten und sollten aktualisiert werden, wenn sich der Dienst ändert (z. B. wenn neue Abhängigkeiten auftreten).

Ein einfaches Interview gibt SRE genügend Informationen, um den Service weiter zu erkunden. Ein vollständiges Interview enthält eine ausführliche Beschreibung des Dienstes und seiner Interaktion mit der Welt um ihn herum sowie Links zu Dashboards, Metriken und allen Informationen, die SRE zur Lösung unvorhergesehener Probleme benötigt.

Spielbuch

Manchmal auch Runbook genannt, ist es ein grundlegendes Dokument, mit dem Ingenieure während einer Schicht auf Benachrichtigungen eines Serviceüberwachungssystems reagieren können. Wenn das Team von Zoey beispielsweise ein Spielbuch hätte, in dem die Bedeutung der Warnung "Job Ragnarok lehnte sich zurück" und die Maßnahmen in der Situation, in der sie empfangen wurde, erläutert würden, wäre der Vorfall in wenigen Minuten behoben. Playbooks verkürzen die Wiederherstellungszeit von Vorfällen und bieten nützliche Links zu Konsolen und Verfahren.

Die Playbooks enthalten Anweisungen zum Überprüfen, Eliminieren und Eskalieren generierter Benachrichtigungen über Netzwerküberwachungsprozesse. Die Namen der Benachrichtigungen in Playbooks stimmen normalerweise mit den vom System generierten Namen überein. Sie enthalten Befehle und Schritte, die auf ihre Richtigkeit geprüft werden müssen. Sie müssen regelmäßig aktualisiert werden, wenn neue Methoden zur Problemlösung entdeckt werden sowie wenn neue Fehlertypen identifiziert und Abhängigkeiten hinzugefügt werden.

Playbooks werden nicht ausschließlich für Benachrichtigungen erstellt. Sie können auch Produktionsverfahren zum Freigeben von Releases, zur Überwachung und zur Fehlerbehebung enthalten. Weitere Beispiele für Produktionsverfahren sind das Ein- und Ausschalten eines Dienstes, die Wartung eines Dienstes und ein Unfall / eine Eskalation.

Post mortem

SREs arbeiten mit großen, komplexen, verteilten Systemen und verbessern die Dienste mithilfe neuer Funktionen und der Hinzufügung neuer Systeme. Angesichts des Ausmaßes und der Geschwindigkeit des Wandels sind Vorfälle und Störungen daher unvermeidlich. Post-mortem ist ein wichtiges SRE-Instrument, das den Lernprozess aus unseren Fehlern formalisiert. In Zoes hypothetischer Geschichte hatte das Team kein formelles Post-Mortem-Verfahren, so dass es kein formelles Verfahren gab, um die Schlussfolgerungen des Vorfalls aufzuzeichnen, die dessen Wiederholung verhindern würden. Das Team ist also dazu verdammt, dieselben Fehler immer wieder zu wiederholen.

SRE-Teams müssen eine standardisierte Post-Mortem-Vorlage mit Abschnitten erstellen, die wichtige Informationen zum Fehler erfassen. Idealerweise sollte die Vorlage so strukturiert sein, dass sie von einem Datenanalysetool problemlos analysiert werden kann. Es sendet Crash-Dynamik-Berichte mit Post-Mortem als Datenquelle. Jedes mit dieser Vorlage erstellte Post-Mortem beschreibt einen Produktionsfehler, einschließlich der folgenden Informationen (Minimum):

• Chronologie der Ereignisse (Zeitleiste).
• Beschreibung der Auswirkungen auf den Benutzer.
• Grundursache
• Aktionspunkte / Lektionen gelernt.

Postmortem wird von einem Teammitglied geschrieben, das auf einen Fehler stößt, idealerweise für diejenigen, die an dessen Entfernung teilgenommen haben und die Verantwortung für die Verbesserungen übernehmen können. Post mortem sollte unschuldig geschrieben werden. Es sollte Informationen enthalten, die zum Verständnis der Ereignisse erforderlich sind, sowie eine Liste von Entscheidungen, die getroffen werden müssen, um die Wahrscheinlichkeit eines erneuten Auftretens zu verringern, die Folgen zu verringern und / oder die Wiederherstellung zu vereinfachen.

Richtlinien

In der Richtliniendokumentation sind spezifische technische und nichttechnische Regeln und Produktionsrichtlinien angegeben. Technische Regeln können beispielsweise für die Protokollierung von Änderungen in der Produktion, die Verwaltung von Protokollen, die Benennung interner Dienste (Benennungsregeln, die Ingenieure bei der Implementierung von Diensten befolgen müssen) sowie die Verwendung und Verfügbarkeit von Notfallidentifikationsdaten gelten.

Richtlinien können auch auf Prozesse gerichtet werden. Eskalationsregeln helfen Ingenieuren, Fehler als Notfall und Nicht-Notfall zu klassifizieren und zu verstehen, welche Maßnahmen in einer bestimmten Situation zu ergreifen sind. Richtlinien zu Schichterwartungen beschreiben die Struktur des Teams und den Verantwortungsbereich jedes einzelnen Mitglieds.

Service Level Agreement

Service Level Agreement (kurz Service Level Agreement - SLA) - eine offizielle Vereinbarung mit dem Kunden über die erbrachten Servicearbeiten und die im Falle eines Ausfalls ergriffenen Maßnahmen. SRE-Teams dokumentieren die Verfügbarkeit und Latenz von Diensten und überwachen die mit SLAs verbundene Dienstleistung.

Die Dokumentation und Veröffentlichung von SLAs sowie eine gründliche Analyse der Benutzererfahrung und deren Vergleich mit SLAs ermöglichen es SRE-Teams, schneller zu innovieren, ohne die UX-Qualität zu verlieren. SREs, die Dienste mit einem eindeutigen SLA unterstützen, erkennen Fehler schneller und beheben sie daher schneller. SLA reduziert auch die Reibung zwischen den SRE- und SWE-Teams (Softwareentwicklern), sodass Teams Ziele und Ergebnisse objektiv diskutieren und subjektive Risikobewertungen vermeiden können.

Es ist anzumerken, dass das Bestehen einer externen, rechtsgültigen Vereinbarung möglicherweise nicht für die meisten SRE-Teams gilt. In solchen Fällen können SRE-Teams auf Service-Level-Ziele (kurz SLO) beschränkt sein. SLO - Bestimmen Sie das gewünschte Serviceniveau für eine bestimmte Metrik, z. B. Verfügbarkeit oder Verzögerung.

Produktdokumentation

SRE-Teams bemühen sich, 50 Prozent ihrer Zeit mit der Arbeit an einem Projekt, der Entwicklung von Software zur Automatisierung manueller Arbeit oder der Verbesserung der Servicezuverlässigkeit zu verbringen. In diesem Abschnitt werden Dokumente zu den von SRE entwickelten Produkten und Tools beschrieben.

Diese Dokumente sind wichtig, damit Benutzer verstehen können, ob dieses Produkt für sie geeignet ist, wie sie damit arbeiten und wie sie Support erhalten. Sie bieten auch die richtige Benutzererfahrung und erleichtern die Produktakzeptanz.

Produkt über Seite

Die Beschreibungsseite hilft SRE- und Produktentwicklungsingenieuren zu verstehen, was ein Produkt oder Tool ist, was es tut und wie es verwendet wird.

Konzepthandbuch

Ein Konzeptleitfaden oder Glossar definiert alle für das Produkt spezifischen Konzepte. Die Definition von Konzepten ermöglicht die Aufrechterhaltung der Konsistenz in der Dokumentation und den Elementen von Benutzeroberflächen, APIs und CLIs (Befehlszeilenschnittstellen).

Erste Schritte

Ziel des Leitfadens für die ersten Schritte ist es, die Ingenieure mit einem Minimum an Verzögerungen schnell auf den neuesten Stand zu bringen. Dies ist nützlich für neue Benutzer, die das Produkt ausprobieren möchten.

Codelab

Mit diesen Tutorials können Ingenieure theoretische Erklärungen, Codebeispiele und Übungen kombinieren, um das Produkt schnell kennenzulernen. Codelabs bieten auch detaillierte Skripte, die Ingenieure Schritt für Schritt durch eine Reihe von Aufgaben führen. Diese Tutorials sind normalerweise länger als die ersten Anleitungen. Sie können mehr als ein Produkt oder Werkzeug abdecken, wenn sie mit etwas zusammenhängen.

Praktische Anleitung

Eine solche Anleitung ist für Benutzer erforderlich, die ein bestimmtes Problem lösen möchten. Diese Anleitungen sind normalerweise eine Schritt-für-Schritt-Anleitung, die Sie befolgen müssen.
FAQ

Auf der FAQ-Seite kann der Benutzer Antworten auf die häufigsten Fragen erhalten, sich über die auftretenden Schwierigkeiten und Einschränkungen informieren und Links zu Dokumenten und anderen Seiten finden, um detailliertere Informationen zu erhalten.

Unterstützung

Auf der Support-Seite erfahren Ingenieure, wie sie das Problem lösen können, mit dem sie konfrontiert sind. Dort finden Sie auch einen Eskalationsplan, Informationen zur Fehlerbehebung, Gruppenverknüpfungen, Dashboards und SLOs sowie Schichtinformationen.

API-Beschreibung

In diesem Handbuch werden Funktionen, Klassen und Methoden beschrieben, normalerweise mit einem Minimum an Begleittext. Eine solche Dokumentation wird meistens basierend auf Kommentaren im Code erstellt und manchmal von technischen Redakteuren geschrieben.

Entwicklerhandbuch

In diesem Handbuch können Entwickler lernen, wie sie mit der Produkt-API programmieren. Solche Handbücher sind normalerweise erforderlich, wenn SREs Produkte erstellen, die Entwicklern APIs bereitstellen. Auf diese Weise können Sie gemischte Tools erstellen, die die APIs des jeweils anderen aufrufen, um komplexere Aufgaben auszuführen.

Dokumente zur Meldung des Servicestatus

In diesem Abschnitt werden die Dokumente beschrieben, die das SRE-Team erstellt, um den Status der unterstützten Dienste zu beschreiben.

Vierteljährliche Serviceüberprüfung

Informationen zum Status des Service werden in zwei Formaten präsentiert: einem vom SRE-Leiter vereinbarten vierteljährlichen Bericht, der in der gesamten SRE-Organisation verteilt wird, und Präsentationen für den Lead in der Produktentwicklung und Teamarbeit.

SRE-Führungskräfte sind an vierteljährlichen Berichten interessiert, da sie Informationen zu folgenden Themen bereitstellen:

• Support-Probleme (Schichten, Tickets, Obduktion). SRE-Führungskräfte wissen, dass es notwendig ist, zu reagieren und Prioritäten zu ändern, wenn Supportprobleme mehr als 50 Prozent der Ressourcen des SRE-Teams beanspruchen. Ziel ist es, das Problem bereits in einem frühen Stadium zu identifizieren.
• Ausführung von SLA. SRE-Verantwortliche möchten wissen, ob mit der SLA alles in Ordnung ist und ob es ungesunde Komponenten im Ökosystem gibt, die eine Bedrohung darstellen.
• Risiken SLA-Führungskräfte möchten wissen, welche Risiken SRE bekannt sind und welche Auswirkungen auf Produkt- und Geschäftsziele haben können.

Quartalsberichte geben dem SRE-Team die Möglichkeit:

• Betonen Sie die Vorteile von SRE für das Produktentwicklungsteam sowie die Arbeit des SRE-Teams.
• Fordern Sie Priorität an, um Probleme zu beheben, die den SRE-Befehl (Resilience) beeinträchtigen.
• Fordern Sie Feedback zu den Prioritäten des SRE-Teams an.
• Betonen Sie den breiteren Beitrag des Teams.

Überblick über erfolgreiche Techniken

Diese Überprüfung hilft dabei, erfolgreiche Techniken anzuwenden und einen stabilen Zustand zu erreichen, in dem Operationen ein Minimum an Zeit erfordern. Um solche Berichte zu erstellen, stellen SRE-Teams eine Standort- und Teamcharta, Schichtstatusdetails, Projekte vs. Unterbrechungen, Kapazitätsplanung usw.

Eine Überprüfung erfolgreicher Praktiken hilft dem SRE-Team, sich mit dem Rest der SRE-Organisation zu vergleichen und die Leistung in Schlüsselbereichen zu verbessern: Schichtstatus, Projekte gegen Unterbrechungen, SLOs und Kapazitätsplanung.

Das Ende des zweiten Teils.

Lesen Sie den nächsten Teil.

Wir warten wie gewohnt auf Ihre Fragen und Kommentare.