Por qué es importante la documentación de SRE. Parte 2

Buenas tardes a todos!

Por lo tanto, no queda nada (es decir, un día) antes del inicio de la secuencia del curso Prácticas y herramientas de DevOps , lo que significa que necesitamos tiempo para completar el resto del artículo "Por qué es importante la documentación de SRE" durante este tiempo.

Continuamos

Documentos para el nuevo servicio de incorporación

Los SRE realizan una PRR (revisión de preparación de la producción) para verificar que el servicio cumpla con los estándares de preparación operacional y para asegurarse de que los propietarios del servicio entiendan cómo utilizar el conocimiento de SRE para administrar sistemas grandes.

El servicio debe pasar por esta prueba antes de lanzarse a producción. (Antes del lanzamiento, no cuenta con el respaldo de SRE, sino del propio equipo de desarrollo). El objetivo de PRR en esta etapa es asegurarse de que el servicio cumpla con los estándares mínimos de confiabilidad en el momento del lanzamiento.



El próximo PRR ocurre antes de la transferencia del servicio SRE, es decir, puede pasar mucho tiempo después del lanzamiento. Y cuando el equipo de SRE decide tomar un nuevo servicio, se lleva a cabo un análisis exhaustivo del estado de producción y las prácticas de servicio utilizadas. El objetivo es simplificar el proceso de transferencia de servicios en términos de confiabilidad y estabilidad operativa, así como ayudar a SRE a manejarlo mejor.

Al realizar PRR antes de entregar el servicio, los SRE pueden hacer más preguntas y establecer estándares más altos de confiabilidad y facilidad de uso que cuando se realizan PRR antes del lanzamiento. El PRR antes del lanzamiento puede ser "ligero" para no ralentizar el equipo de desarrollo.

En la historia de Zoe, el equipo no tenía un proceso estandarizado o una lista de verificación de PRR, lo que significa que podrían pasar por alto problemas muy importantes al transferir el servicio. Por lo tanto, existe el riesgo de una colisión con una gran cantidad de problemas que podrían anticiparse y resolverse fácilmente antes de asumir la responsabilidad de administrar el servicio.

La transferencia de PRR / servicio requiere la creación de plantillas de PRR y documentación del proceso (documento de proceso) que describa cómo los equipos SRE trabajarán con el nuevo servicio y usarán las plantillas de PRR. Los patrones utilizados en el proceso de transferencia pueden ser más completos que los utilizados durante el inicio.

La plantilla PRR cubre varias áreas y se requiere para buscar respuestas a preguntas críticas. La Tabla 1 muestra algunas de las áreas y problemas relacionados que cubre la plantilla.

Area	Preguntas
Arquitectura y dependencias	¿Cuál es la ruta de solicitud del cliente a la interfaz y luego al backend? ¿Existen diferentes tipos de solicitudes con diferentes requisitos de latencia?
Planificación de la capacidad	¿Cuáles son las expectativas para los volúmenes de tráfico y las tasas de crecimiento durante y después del lanzamiento? ¿Tiene la potencia informática necesaria para soportar este tráfico?
Tipos de fallas	¿Hay puntos únicos de falla en su arquitectura? ¿Cómo se elimina la falta de disponibilidad de dependencia?
Procesos y Automatización	¿Hay algún proceso manual necesario para respaldar el servicio?
Dependencias externas	¿Qué datos, códigos, servicios o eventos de terceros dependen del servicio y el lanzamiento? ¿Alguno de sus socios depende del servicio? Si es así, ¿deben ser notificados del lanzamiento?

Tabla 1. Áreas de ejemplo de una plantilla PRR

La documentación del proceso también debe indicar los documentos que el SRE debe solicitar al equipo de desarrollo del producto como requisitos previos para la transferencia. Por ejemplo, pueden pedirle al equipo de desarrollo que cree un libro de jugadas para problemas comunes.

Además, la organización SRE necesitará crear un documento de revisión que explique brevemente al equipo de desarrollo el rol y las áreas de responsabilidad de la SRE. Esto es necesario para formar expectativas realistas. El primer documento debe explicar qué es SRE, cubrir todos los temas tratados en la parte anterior y al comienzo de este artículo, incluidas las funciones principales, el ciclo de vida del servicio, las responsabilidades de soporte / mantenimiento. El objetivo principal de este documento es asegurarse de que los desarrolladores no confundan SRE con el equipo de OPS y no consideren que las respuestas de buscapersonas son el único deber de SRE. Como se muestra en la historia descrita anteriormente, si en el momento de la transferencia del servicio los desarrolladores no entendían completamente lo que estaba haciendo SRE, esto conduciría a problemas de comunicación y malentendidos.

Además, es necesario crear un documento modelo de compromiso para aclarar las expectativas y explicar el proceso de interacción entre el equipo de SRE y el equipo de desarrollo de productos durante y después de la transferencia del servicio. Los temas cubiertos en la documentación pueden incluir lo siguiente:

• Criterios de transferencia de servicios y proceso de PRR.
• El proceso de discutir informes de objetivos de nivel de servicio (brevemente SLO) y cálculo de errores.
• Nuevos criterios de lanzamiento y política de inicio de congelación (si es posible).
• El contenido y la frecuencia de los informes de estado del servicio del equipo de SRE.
• Requisitos de personal SRE.
• El proceso de planificar una hoja de ruta de nuevas funcionalidades y la prioridad de una funcional que aumente la confiabilidad (requerida por SRE) sobre la funcionalidad de nuevos productos.

Servicio de Documentación de Operación

Para respaldar el servicio, los equipos de SRE se basan principalmente en la documentación operativa principal: descripción general (entrevista) del servicio, libros de jugadas y procedimientos, autopsia, directivas y SLA. (Nota: esta sección estaba presente en el capítulo "Hacer mejor los documentos" en Seeking SRE).

Entrevista de servicio

Una descripción general del servicio es fundamental para comprender el SRE qué tipo de servicio admiten. SRE necesita conocer la arquitectura del sistema, sus componentes y dependencias, los contactos del servicio y sus propietarios. La descripción general del servicio es el resultado del trabajo conjunto del equipo de desarrollo y el equipo de SRE, está creado para guiar y priorizar las tareas de SRE e identificar áreas para su posterior estudio. Dichas entrevistas generalmente se obtienen como resultado de PRR y deben actualizarse a medida que cambia el servicio (por ejemplo, si aparecen nuevas dependencias).

Una simple entrevista le da a SRE suficiente información para explorar más el servicio. Una entrevista completa proporciona una descripción detallada del servicio y cómo interactúa con el mundo que lo rodea, así como enlaces a paneles, métricas, toda la información que SRE necesita para resolver problemas imprevistos.

Libro de jugadas

A veces también llamado runbook, es un documento fundamental que permite a los ingenieros responder a las notificaciones de un sistema de monitoreo de servicio durante un turno. Por ejemplo, si el equipo de Zoey tuviera un libro de jugadas que explicara el significado de la alerta "Job Ragnarok se echó hacia atrás" y lo que debe hacerse en la situación en que se recibió, el incidente se resolvería en cuestión de minutos. Los libros de jugadas reducen el tiempo de recuperación de incidentes y proporcionan enlaces útiles a consolas y procedimientos.

Los libros de jugadas contienen instrucciones para verificar, eliminar y escalar cualquier notificación generada de los procesos de monitoreo de la red. Los nombres de las notificaciones en los libros de jugadas generalmente coinciden con lo que genera el sistema. Contienen comandos y pasos que necesitan ser probados para la precisión. Deben actualizarse regularmente cuando se descubren nuevos métodos para resolver problemas, así como cuando se identifican nuevos tipos de fallas y se agregan dependencias.

Los libros de jugadas no se crean exclusivamente para notificaciones. También pueden contener procedimientos de producción para liberar versiones, monitoreo y resolución de problemas. Otros ejemplos de procedimientos de producción incluyen activar / desactivar un servicio, mantenimiento de un servicio y un accidente / escalada.

Post mortem

Los SRE trabajan con sistemas distribuidos complejos a gran escala, y también mejoran los servicios con la ayuda de nuevas funciones y la incorporación de nuevos sistemas. Por lo tanto, dada la escala y la velocidad del cambio, los incidentes y las interrupciones son inevitables. La autopsia es una herramienta SRE importante, que formaliza el proceso de aprendizaje de nuestros errores. En la historia hipotética de Zoe, el equipo no tenía un procedimiento post mortem formal, por lo que no hubo un proceso formal para registrar las conclusiones del incidente que evitaría su repetición. Entonces el equipo está condenado a repetir los mismos errores una y otra vez.

Los equipos de SRE necesitan crear una plantilla post mortem estandarizada con secciones que capturen información importante sobre el fallo. Idealmente, la plantilla debe estar estructurada para que pueda ser analizada fácilmente por una herramienta de análisis de datos. Envía informes de dinámica de bloqueo utilizando autopsia como fuente de datos. Cada post mortem creado con esta plantilla describe una falla de producción, incluida la siguiente información (mínimo):

• Cronología de eventos (línea de tiempo).
• Descripción del impacto en el usuario.
• Causa raíz
• Puntos de acción / Lecciones aprendidas.

Postmortem está escrito por un miembro del equipo que encuentra una falla, idealmente para aquellos que participaron en su eliminación y pueden asumir la responsabilidad de las mejoras. La autopsia debe escribirse de manera inocente. Debe contener la información necesaria para comprender lo que ha sucedido, así como una lista de decisiones que deben tomarse para reducir la probabilidad de recurrencia, reducir las consecuencias y / o simplificar la recuperación.

Directivas

En la documentación de la política, se indican normas técnicas y no técnicas específicas y directivas de producción. Las reglas técnicas pueden aplicarse, por ejemplo, al registro de cambios en la producción, el mantenimiento de registros, el nombramiento de servicios internos (reglas de denominación que los ingenieros deben seguir al implementar servicios) y el uso y disponibilidad de datos de identificación de emergencia.

Las directivas también pueden dirigirse a procesos. Las reglas de escalado ayudan a los ingenieros a clasificar las fallas como de emergencia y no de emergencia y a comprender qué acciones tomar en una situación dada; Las directivas de expectativas de cambio describen la estructura del equipo y el área de responsabilidad de cada uno de sus miembros.

Acuerdo de nivel de servicio

Acuerdo de nivel de servicio (Acuerdo de nivel de servicio, en resumen, SLA): un acuerdo formal con el cliente sobre el trabajo proporcionado del servicio y las medidas tomadas en caso de incumplimiento de las obligaciones. Los equipos de SRE documentan la disponibilidad y la latencia del servicio, y supervisan el rendimiento del servicio asociado con los SLA.

La documentación y publicación de SLA, así como un análisis exhaustivo de la experiencia del usuario y su comparación con los SLA, permiten a los equipos de SRE innovar más rápido sin perder la calidad de UX. Los SRE que admiten servicios con un claro aviso de SLA fallan más rápido y, por lo tanto, los reparan más rápido. SLA también reduce la cantidad de fricción entre los equipos SRE y SWE (desarrolladores de software), lo que permite a los equipos discutir objetivamente objetivos y resultados, evitando juicios subjetivos sobre el riesgo.

Vale la pena señalar que la existencia de un acuerdo externo legalmente válido puede no aplicarse a la mayoría de los equipos SRE. En tales casos, los equipos SRE pueden estar limitados a objetivos de nivel de servicio (SLO para abreviar). SLO: determine el nivel de servicio deseado para una métrica específica, por ejemplo, disponibilidad o retraso.

Documentación del producto

Los equipos de SRE se esfuerzan por pasar el 50 por ciento de su tiempo trabajando en un proyecto, desarrollando software para automatizar el trabajo manual o mejorando la confiabilidad del servicio. Esta sección describe documentos relacionados con el producto y las herramientas que desarrolla SRE.

Estos documentos son importantes porque permiten a los usuarios comprender si este producto es adecuado para ellos, cómo comenzar a trabajar con él y cómo obtener soporte. También proporcionan la experiencia de usuario correcta y facilitan la adopción del producto.

Página de información del producto

La página de descripción ayuda a los ingenieros de desarrollo de productos y SRE a comprender qué es un producto o herramienta, qué hace y cómo usarlo.

Manual conceptual

Una guía conceptual o glosario define todos los conceptos únicos del producto. La definición de conceptos permite mantener la coherencia en la documentación y los elementos de las interfaces de usuario, API y CLI (interfaces de línea de comandos).

Guía de inicio

El objetivo de la guía de inicio es actualizar rápidamente a los ingenieros con un mínimo de demoras. Esto es útil para los nuevos usuarios que desean probar el producto.

Codelab

Los ingenieros pueden usar estos tutoriales, combinando explicaciones teóricas, ejemplos de código y ejercicios, para conocer rápidamente el producto. Codelabs también proporciona scripts detallados que guían a los ingenieros paso a paso a través de una serie de tareas. Estos tutoriales suelen ser más largos que las guías de inicio. Pueden cubrir más de un producto o herramienta si están relacionados con algo.

Guía práctica

Dicha orientación es necesaria para los usuarios que desean resolver un problema específico. Estas guías suelen ser una guía paso a paso que debe seguir.
FAQ

En la página de preguntas frecuentes, el usuario puede obtener respuestas a las preguntas más populares, conocer las dificultades y limitaciones que se pueden encontrar, encontrar enlaces a documentos y otras páginas para obtener información más detallada.

Apoyo

En la página de soporte, los ingenieros pueden aprender cómo resolver el problema que enfrentan. También puede encontrar un plan de escalación, información de resolución de problemas, enlaces de grupo, paneles y SLO, así como información de turnos.

Descripción de la API

Esta guía describe funciones, clases y métodos, generalmente con un mínimo de texto adjunto. Dicha documentación se crea con mayor frecuencia en función de los comentarios en el código y, en ocasiones, está escrita por escritores técnicos.

Guía para desarrolladores

De esta guía, los desarrolladores pueden aprender a programar con la API del producto. Dichas guías suelen ser necesarias si los SRE crean productos que proporcionan API a los desarrolladores, lo que le permite crear herramientas mixtas que invocan las API de los demás para realizar tareas más complejas.

Documentos para informar el estado del servicio

Esta sección describe los documentos que crea el equipo de SRE para describir el estado de los servicios compatibles.

Revisión trimestral del servicio

La información sobre el estado del servicio se presenta en dos formatos: un informe trimestral acordado por el líder de SRE, que se distribuye por toda la organización de SRE, y presentaciones para el líder en el desarrollo de productos y el equipo.

Los líderes de SRE están interesados ​​en los informes trimestrales, ya que proporcionan información sobre lo siguiente:

• Problemas de soporte (turnos, tickets, autopsia). Los líderes de SRE saben que si los problemas de soporte comienzan a ocupar más del 50 por ciento de los recursos del equipo de SRE, es necesario responder y cambiar las prioridades. El objetivo es identificar el problema ya en las primeras etapas.
• Ejecución de SLA. Los líderes de SRE quieren saber si todo está bien con el SLA, si hay componentes no saludables en el ecosistema que representan una amenaza.
• Riesgos Los líderes de SLA quieren saber sobre los riesgos conocidos por SRE que pueden interferir con los objetivos del producto y del negocio.

Los informes trimestrales brindan al equipo de SRE la oportunidad de:

• Enfatice los beneficios de SRE para el equipo de desarrollo de productos, así como el trabajo del equipo de SRE.
• Solicite prioridad para resolver problemas que interfieran con el comando SRE (resiliencia).
• Solicite comentarios sobre las prioridades del equipo SRE.
• Enfatice la contribución más amplia del equipo.

Resumen de técnicas exitosas

Esta revisión ayuda a adoptar técnicas exitosas y llegar a un estado estable en el que las operaciones requieren un mínimo de tiempo. Para preparar dichos informes, los equipos de SRE proporcionan una carta del sitio y del equipo, detalles del estado del turno, proyectos vs. interrupciones, planificación de capacidad, etc.

Una revisión de las prácticas exitosas ayuda al equipo de SRE a compararse con el resto de la organización de SRE y a mejorar el desempeño en áreas clave: estado del cambio, proyectos versus interrupciones, SLO y planificación de la capacidad.

El final de la segunda parte.

Lee la siguiente parte.

Estamos a la espera de sus preguntas y comentarios como de costumbre.