Warum SRE-Dokumentation wichtig ist. Teil 3

Guten Abend allerseits! Wir haben es eilig, die Nachricht zu teilen, dass wir bereits im Februar einen neuen Stream zum Kurs „Devops - Practices and Tools“ starten. Dies bedeutet, dass es Zeit ist, das zu beenden, was wir begonnen haben, und den dritten Teil des Artikels zu veröffentlichen: „Warum SRE-Dokumentation wichtig ist“ . Lass uns gehen!

Dokumente zum Verwalten von SRE-Befehlen

SRE-Teams benötigen zuverlässige und kostengünstige Dokumentation, um effizient arbeiten zu können.

Team Seite

Hinweis: Anstelle der Site können Sie im Confluence / Wiki einen separaten Bereich oder Abschnitt verwenden.

Die Website des Teams ist wichtig, da sie die Koordination von Informationen und Dokumentationen zum SRE-Team und seinen Projekten ermöglicht. Bei Google verwenden beispielsweise viele SRE-Teams g3doc (eine interne Google-Dokumentationsplattform, auf der Docks zusammen mit dem zugehörigen Code im Quellcode gespeichert sind), und einige Teams verwenden g3doc und Google Sites. In diesem Fall sind die g3doc-Seiten eng mit dem Implementierungscode / den Implementierungsdetails verbunden.

Team Charter



SRE-Teams sollten eine veröffentlichte Charta unterstützen, in der die Arbeitsmotivation dargelegt und das laufende Engagement dokumentiert wird. Die Charta ist notwendig, um die Identität, die Hauptziele und den Wert des Teams im gesamten Unternehmen zu ermitteln.

Die Charta enthält normalerweise die folgenden Elemente:

• Eine allgemeine Beschreibung des Verantwortungsbereichs des Teams. Einschließlich der Art der vom Team unterstützten Dienste (und wie), verwandter Systeme, Beispiele.
• Eine kurze Beschreibung einiger der wichtigsten vom Team unterstützten Dienste. In diesem Abschnitt werden auch die Schlüsseltechnologien und die Herausforderungen ihrer Verwendung, die Vorteile der Einbeziehung von SRE und ihre Verantwortlichkeiten hervorgehoben.
• Schlüsselprinzipien und Werte des Teams.
• Links zur Team-Website und Dokumentation.

Es wird auch das Vorhandensein einer Vision (das Konzept der Vision für die Zukunft - eine inspirierende Beschreibung der langfristigen Ziele des Teams) und einer Roadmap für mehrere Quartale vorausgesetzt.

Dokumentation zur Integration neuer SREs

Die Investition in Schulungsinstrumente und -materialien für neue Mitarbeiter wirkt sich positiv auf die Geschwindigkeit der Integration von Mitarbeitern in Arbeitsprozesse aus. Für SRE-Teams ist es von Vorteil, Neuankömmlinge so schnell wie möglich mit allen erforderlichen Schichtarbeitsfähigkeiten auszubilden. Die Geschichte von Zoe zeigt deutlich, wie der Mangel an Vollzeitschulung für einen neuen Mitarbeiter einen kleinen Vorfall zu einer schwerwiegenden Fehlfunktion macht.

Viele SRE-Teams bereiten neue Mitarbeiter mithilfe von Checklisten auf Schichten vor. Eine Schichtcheckliste deckt normalerweise Bereiche auf hoher Ebene ab (unterteilt in Unterabschnitte), die die Teammitglieder verstehen sollten. Beispiele für solche Bereiche sind Produktionskonzepte, Front-End und Back-End, Automatisierung und Instrumentierung, Überwachung und Protokollierung. Anweisungen zur Vorbereitung auf die Schicht und Aufgaben, die während der Schicht ausgeführt werden, können ebenfalls in die Checkliste aufgenommen werden.

Um neue Mitglieder des SRE-Teams vorzubereiten, verwenden sie auch Rollenspielübungen (in Google werden sie Wheel of Misfortune - das Wheel of Failure genannt). Diese Übung ist ein Fehlerszenario mit einem bestimmten Datensatz und Signalen, die SRE möglicherweise benötigt, um ein Problem während einer Schicht zu lösen. Die Teammitglieder spielen abwechselnd die Rolle eines diensthabenden Ingenieurs, um ihre Beherrschung der Notfallwiederherstellung und die Fähigkeit zum Debuggen des Systems zu verbessern. Wheel of Misfortune prüft, ob jedes Mitglied des Teams weiß, wo sich die Dokumentation zur Behebung des Problems befindet und wie mit dem Fehler umgegangen werden kann.

Speicherverwaltung

Alle Informationen des SRE-Teams können auf mehrere Websites, das lokale Repository und die Ordner von Google Drive verteilt werden, was die Suche nach der richtigen Website erheblich erschwert. Wie im zuvor beschriebenen Beispiel waren das kritische Betriebstool und die Anweisungen für seine Verwendung für Zoe (SRE im Dienst) nicht verfügbar, da sie im persönlichen Verzeichnis ihres technischen Leiters versteckt waren und die Unfähigkeit, sie zu finden, die Dauer des Servicefehlers erheblich verlängerte. Um solche Probleme zu beseitigen, müssen Sie alle Informationen strukturieren und sicherstellen, dass die Teammitglieder wissen, wo sie zu finden und zu speichern sind und wie sie zu pflegen sind. Die gut entwickelte Struktur hilft dem Team, Informationen schneller zu finden. Neue Teammitglieder werden schneller auf dem Laufenden bleiben, während diensthabende Ingenieure Probleme schneller lösen.

Im Folgenden finden Sie einige Richtlinien zum Erstellen und Verwalten eines Dokumentationsrepositorys:

• Identifizieren Sie wichtige Stakeholder und führen Sie kurze Interviews durch, um alle Bedürfnisse zu identifizieren.
• Finden Sie so viel Dokumentation wie möglich und analysieren Sie die Lücken im Inhalt.
• Richten Sie Ihre Site-Struktur so ein, dass an den richtigen Stellen neue Dokumentationen erstellt werden.
• Verschieben Sie vorhandene Dokumentation an einen neuen Speicherort.
• Archivieren und reißen Sie die alte Dokumentation ab.
• Führen Sie regelmäßige Überprüfungen durch, um die Qualität / Konsistenz der unterstützten Dokumentation sicherzustellen.
• Stellen Sie sicher, dass Standard-Suchanfragen die erforderlichen Dokumente ganz oben in der Liste der Suchergebnisse zurückgeben.
• Verwenden Sie Signale wie Google Analytics, um Standardpraktiken zu messen.

Hinweis zur Repository-Unterstützung: Es ist wichtig, die Dokumentation regelmäßig zu überprüfen und zu aktualisieren. Der Name des Eigentümers und das Datum der letzten Überprüfung sollten sichtbar sein. Mithilfe dieser Informationen können Sie die Richtigkeit des ausgewählten Dokuments überprüfen. Zoe in der Geschichte konnte nur eine veraltete Dokumentation eines kritischen Tools finden und verlor dadurch die Fähigkeit, das Problem schnell zu lösen. Unzuverlässige und veraltete Dokumentation macht SRE weniger effizient, was sich negativ auf die Zuverlässigkeit verwalteter Dienste auswirkt.

Repository-Verfügbarkeit

SRE-Teams sollten sicherstellen, dass die Dokumentation auch dann verfügbar bleibt, wenn das Standard-Repository abstürzt und nicht verfügbar ist. Jeder Google SRE besitzt eine Kopie seiner kritischen Dokumentation. Diese Kopie ist auf einem verschlüsselten kompakten Speichergerät oder einem ähnlichen entfernbaren, aber sicheren physischen Medium verfügbar, über das jede SRE verfügt.

Dokumentation zur Außerbetriebnahme eines Dienstes

Wenn der Lebenszyklus eines Dienstes endet, wird er vom SRE auf vorhersehbare Weise außer Betrieb genommen. Dieser Abschnitt enthält Empfehlungen zur Dokumentation zur Außerbetriebnahme eines Dienstes.

Es ist wichtig, die Benutzer vor der Außerbetriebnahme des Dienstes zu benachrichtigen und einen Zeitplan und Schritte anzugeben. In Ihrer Anzeige sollte erläutert werden, wann die Registrierung neuer Nutzer endet, wie vorhandene und in Zukunft erkannte Fehler verarbeitet werden und wann der Dienst endgültig nicht mehr funktioniert. Identifizieren Sie alle wichtigen Daten und den Prozess der Reduzierung der Unterstützung für SRE eindeutig und senden Sie im weiteren Verlauf Zwischenmitteilungen.

Eine einfache E-Mail-Verteilung reicht nicht aus - Sie müssen die Hauptseite mit Dokumentation, Playbooks und Codelabs aktualisieren. Kommentieren Sie nach Möglichkeit auch die Header-Dateien. Beschreiben Sie die Details der Ankündigung in einem Dokument (zusätzlich zum Brief), auf das Benutzer verweisen können. Der Brief sollte so kurz wie möglich sein, aber gleichzeitig informativ und alle wichtigen Punkte widerspiegeln. Beschreiben zusätzlicher Details: Geschäftsmotivation zum Deaktivieren des Dienstes, welche Tools Benutzer zur Migration auf einen anderen Dienst verwenden können, welche Unterstützung während der Migration verfügbar ist. Es lohnt sich auch, eine FAQ-Seite zu erstellen, die im Laufe der Zeit mit neuen Informationen zu Fragen der Benutzer gefüllt wird.

Die Rolle der Redakteure der technischen Dokumentation

Technische Redakteure (oder technische Redakteure) bieten Dienste an, die SRE effizienter und produktiver machen. Der Aufgabenbereich beschränkt sich nicht nur auf das Schreiben separater Dokumente gemäß den vom SRE-Team festgelegten Anforderungen.

Hier finden Sie einige praktische Empfehlungen für technische Redakteure zur Arbeit mit SRE-Teams.

• Technische Redakteure arbeiten mit SRE zusammen, um eine Betriebsdokumentation für die Ausführung von Diensten und eine Produktionsdokumentation für SRE-Produkte und -Tools zu erstellen.
• Sie erstellen und aktualisieren Dokumentations-Repositorys, strukturieren und reorganisieren sie entsprechend den Anforderungen der Benutzer und verbessern einzelne Dokumente im Rahmen der gesamten Repository-Verwaltung.
• Die Redakteure helfen dabei, die Verbesserungen zu identifizieren, die für die Dokumentation und das Informationsmanagement erforderlich sind. Dies umfasst die Bewertung der Dokumentation zur Erfassung von Anforderungen, die Verbesserung der von Ingenieuren erstellten Dokumente und Websites sowie die Beratung der Teams zu den Regeln für die Erstellung, Organisation, Neugestaltung, Suche und Pflege der Dokumentation.
• Die Redakteure sollten Dokumentationstools bewerten und verbessern, um bessere SRE-Lösungen bereitzustellen.

Muster

Technische Redakteure stellen auch Vorlagen zur Verfügung, die die Erstellung und Verwendung der SRE-Dokumentation vereinfachen. Vorlagen haben folgende Aufgaben:

• Vereinfachen Sie die Erstellung von Dokumentationen, indem Sie den Ingenieuren eine klare Struktur für die Erstellung neuer Dokumente zur Verfügung stellen.
• Fügen Sie Abschnitte aller erforderlichen Dokumente hinzu, um die Dokumentation vollständig zu vervollständigen.
• Sie helfen dem Leser, das Thema des Dokuments, die Art der Informationen und deren Organisation schnell zu verstehen.

Site Reliability Engineering enthält mehrere Beispieldokumentationsvorlagen. In diesem Abschnitt werden einige weitere Beispiele aufgeführt, um zu zeigen, wie die Vorlagen eine Struktur und eine Anleitung für Ingenieure zum Auffüllen mit Inhalten bereitstellen.

Service-Interview

Rückblick

Was ist das? Was macht er? Auf hoher Ebene werden die Funktionen beschrieben, die Kunden (Endbenutzer, Komponenten usw.) zur Verfügung gestellt werden.

Architektur

Erklären Sie, wie Architektur funktioniert. Beschreiben der Bewegung von Daten zwischen Komponenten. Erwägen Sie das Hinzufügen eines Diagramms für kritische Abhängigkeitssysteme sowie von Flussabfragen und Daten.

Clients und Abhängigkeiten

Listen Sie alle Kunden (die zu anderen Teams gehören) auf, die davon abhängen, und alle Dienste (die zu anderen Teams gehören), von denen es abhängt. (Dies kann auch in Form eines Systemdiagramms demonstriert werden.)

Code und Konfiguration

Erläutern Sie die Struktur der Produktion. Wo läuft es? Listen Sie Binärdateien, Jobs, Rechenzentren und Konfigurationsdateieinstellungen auf oder geben Sie an, wo sich alle befinden. Geben Sie auch den Speicherort des Codes und gegebenenfalls Informationen zum Build an.

Listen und beschreiben Sie die Konfigurationsdateien, Änderungen und Ports, die für den Betrieb dieses Produkts oder Dienstes erforderlich sind.

Beschreiben Sie Folgendes: Welche Konfigurationsdateien wurden für dieses Produkt oder diesen Service geändert? Wie erfolgt die Einrichtung?

Die Prozesse

Beschreiben Sie Folgendes: Welche Daemons und anderen Prozesse müssen ausgeführt werden, damit der Dienst funktioniert? Welche Steuerungsskripte wurden erstellt, um den Dienst zu verwalten?

Impressum

Listen und beschreiben Sie die von der Komponente erstellten Protokolldateien und welche Beobachtungen gemacht werden. Beschreiben Sie Folgendes: Welche Protokolle werden von dieser Komponente generiert? Was ist in jeder Datei? Was sind die Empfehlungen für das Studium dieser Dateien? Welche Aspekte der Komponente sollten für einen zuverlässigen Servicebetrieb überwacht werden?

Dashboards und Tools

Fügen Sie Links zu verwandten Dashboards und Tools ein.

Macht

Geben Sie die Leistung einer einzelnen Instanz an. Datencenter global: QPS-, Bandbreiten- und Latenzwerte.

SLA

Geben Sie Barrierefreiheitsziele an.

Standardverfahren

Fügen Sie Links zu Prozeduren hinzu, einschließlich Lasttests, Updates / Push / Flag-Status usw. Fügen Sie im Alarm-Playbook Links zur Alarmdokumentation hinzu.

Referenzen

Fügen Sie Links zur Konstruktionsdokumentation für die Komponente oder verwandte Komponenten hinzu, die normalerweise vom Entwicklungsteam geschrieben werden, sowie andere verwandte Informationen.

Spielbuch

Titel

Geben Sie im Namen den Namen der Warnung an (z. B. NormalAlert_AlertVery Very Normal).

Rückblick

Beschreiben Sie Folgendes: Was bedeutet diese Warnung? Kommt es zu einem Pager oder nur zum Mailen? Welche Faktoren lösen eine Warnung aus? Welche Teile des Dienstes sind betroffen? Welche Warnungen sind damit verbunden? Wer muss benachrichtigt werden?

Warnmeldungen zur Gefahrenstufe

Begründen Sie den Grad der Gefahr der Meldung und die Auswirkungen der betroffenen Teile auf den allgemeinen Zustand der Dienstleistung.

Bestätigung

Geben Sie klare Anweisungen zum Überprüfen und Validieren des Status.

Fehlerbehebung

Auflisten und Beschreiben von Debugging-Methoden und verwandten Informationsquellen. Vergessen Sie nicht die Links zu den entsprechenden Dashboards. Aktivieren Sie Warnungen. Beschreiben Sie Folgendes: Was wird in den Protokollen angezeigt, wenn eine Warnung ausgelöst wird? Welche Debugging-Handler gibt es? Gibt es nützliche Skripte und Befehle? Welchen Output erzeugen sie? Gibt es zusätzliche Aufgaben, die nach dem Entfernen der Warnung gelöst werden müssen?

Lösung

Beschreiben und listen Sie alle möglichen Lösungen für das Problem auf, das die Warnung verursacht. Beschreiben Sie Folgendes: Wie behebe ich das Problem und behebe die Warnung? Welche Befehle müssen zum Neustart ausgeführt werden? Wer sollte benachrichtigt werden, wenn aufgrund von Benutzeraktionen eine Warnung ausgelöst wird? Wer hat Erfahrung mit dem Debuggen eines ähnlichen Problems?

Eskalation

Auflisten und Beschreiben von Eskalationspfaden. Geben Sie an, welche Person oder welches Team benachrichtigt werden soll und wann dies zu tun ist. Wenn eine Eskalation nicht erforderlich ist, schreiben Sie darüber.

Verwandte Links

Stellen Sie Links zu verwandten Warnungen, Verfahren und Überprüfungsdokumentationen bereit.
Vierteljährlicher Servicebericht
Einführung
Beschreiben Sie den Service, für den das Team verantwortlich ist.

Kapazitätsplanung

Einschließlich:

• Die tatsächliche Nachfrage nach dem Dienst, beginnend mit den letzten 6 bis 8 Quartalen, ausgedrückt in den relevantesten Metriken für den Dienst (z. B. QPS oder DAU).
• Prognose für die nächsten 8 Quartale.
• Kapazitätsplan, der den prognostizierten Bedarf auf dem erforderlichen Redundanzniveau erfüllt - geben Sie die Defizit- und / oder Kapazitätsplanungsrisiken an.

Wir empfehlen außerdem, Prognosen für die letzten 2 bis 4 Quartale hinzuzufügen, damit der Leser die Stabilität und Genauigkeit der Prognosen bewerten kann.

SLA-Implementierung / Verfügbarkeit

Alle von SRE unterstützten Dienste müssen über ein schriftliches SLA verfügen, das die Leistung jedes Quartals bewertet.

Abschnitt SLA sollte die Parameter der Hauptkomponenten des Dienstes zur Messung der vierteljährlichen Durchführbarkeit von SLA-Bedingungen sowie einen Link zu einem schriftlichen SLA-Team enthalten.

Begleitende Vorfälle (optional)

Nennen Sie 3-5 wichtige Vorfälle oder Ausfälle pro Quartal.

Erfolge (optional)

Listen Sie die wichtigsten Erfolge des Quartals auf.

SLA-Änderungen (gewünscht)

Letzte Änderungen an SLA.

Servicedetails (wünschenswert)

Der Abschnitt kann Wachstum, Statistiken über Verzögerungen usw. enthalten.

Teaminformationen (optional)

Kann Informationen zur Teamzusammensetzung, zu Status, Projekten und Schichtstatistiken enthalten.

Datenquellen (erforderlich)

Beschreiben Sie die Quellen, die zum Abrufen von Eingabehilfenwerten und Berechnungsmethoden verwendet werden, und stellen Sie Links zu den entsprechenden Dashboards bereit.

Team Charter

Wer sind wir

Beschreiben Sie in einem Satz (~ 1 Zeile) das technologische Umfeld, Kunden- und Teamvorschläge sowie den Grad der SRE-Beteiligung und das spezielle Fachwissen.

Unterstützte Dienste

Beschreiben Sie die vom Team unterstützten Dienste (oder deren Gruppe), um den Arbeitsumfang weiter zu verdeutlichen.

Wie wir Zeit verbringen

Scoping hilft bei der Erstellung einer Roadmap und der Erreichung und Unterstützung langfristiger Ziele.

Teamwerte

Beschreiben Sie die Werte klar. Dies wirkt sich auf die Art und Weise aus, wie die Teammitglieder miteinander interagieren und wie Ihr Team von anderen wahrgenommen wird.

Fazit

Unabhängig davon, ob Sie ein SRE, ein SRE-Manager oder ein technischer Redakteur sind, verstehen Sie jetzt die entscheidende Bedeutung der Dokumentation im Leben eines effektiven SRE-Teams. Durch eine gute Dokumentation kann das SRE-Team wachsen und sich an eine klare Methodik für die Verwaltung neuer und bestehender Services halten.

Daher haben wir den letzten Teil dieses Artikels veröffentlicht. Der erste und der zweite Teil können durch Klicken auf die Hyperlinks gelesen werden. Weitere nützliche Informationen erhalten Sie in unserer offenen Lektion , die am 19. Februar stattfindet. Wir warten auf alle!