Plantilla de Documento de Ownership de Servicio

Descripcion General

Los microservicios se multiplican rapidamente. En una organizacion de ingenieria en crecimiento, es facil perder track de quien es dueno de que, como desplegar un servicio, o a quien llamar cuando falla a las 3 AM. Un documento de ownership de servicio es una pagina unica de verdad para cada servicio en produccion: que hace, quien es dueno, como operarlo, y donde encontrar todo lo demas. Convierte conocimiento tribal en documentacion referenciable y previene la crisis de “nadie sabe como esto funciona”.

Cuando Usar

• For alternatives, see Monolith to Microservices — Migration Strategies.

Usa esta plantilla cuando:

• Tengas mas de cinco servicios en produccion y el ownership se este volviendo confuso
• Nuevos ingenieros necesiten dias para descubrir como desplegar o depurar un servicio
• Los incidentes se prolonguen porque nadie sabe quien es dueno del componente que falla
• Te prepares para una auditoria que requiera ownership de servicios documentado
• Estes separando un monolito y necesites asignar ownership a los servicios extraidos

Prerrequisitos

Antes de escribir documentos de ownership:

• Identificar al dueno primario (equipo o individuo) de cada servicio
• Confirmar que el servicio sigue activo; documentar servicios deprecados por separado
• Reunir links a repositorios, dashboards, runbooks, y pipelines de CI
• Verificar informacion de contacto para rotaciones de on-call
• Decidir donde viven los documentos (wiki, docs site, o READMEs de repositorio)

Solucion

# Ownership de Servicio: `<Nombre del Servicio>`

> Dueno: ______ | Equipo: ______ | Actualizado: ______ | Tier: [1/2/3]

## 1. Que Hace Este Servicio

**Proposito:** [Una oracion describiendo el rol del servicio en el sistema]

**Capacidades clave:**
- ______
- ______
- ______

**Consumidores:** [Quien llama este servicio: otros servicios, UIs, socios externos]

**Tier de servicio:**
- Tier 1 = Critico para revenue; 99.99% uptime, on-call 24/7, postmortems obligatorios
- Tier 2 = Importante; 99.9% uptime, on-call en horario laboral
- Tier 3 = Interno o no critico; 99% uptime, respuesta best-effort

---

## 2. Arquitectura

### Stack Tecnologico
| Capa | Tecnologia | Version |
|------|------------|---------|
| Lenguaje | ______ | ______ |
| Framework | ______ | ______ |
| Base de datos | ______ | ______ |
| Cache | ______ | ______ |
| Cola | ______ | ______ |
| Infraestructura | ______ | ______ |

### Diagrama

[Consumidor] -> [Load Balancer] -> [Servicio] -> [Base de datos] v [Cache]

*Link al diagrama de arquitectura completo: ______*

---

## 3. Ownership y Contactos

| Rol | Equipo / Persona | Contacto | Escalamiento |
|-----|------------------|----------|-------------|
| Dueno primario | ______ | ______ | ______ |
| Rotacion on-call | ______ | Link PagerDuty/Opsgenie | ______ |
| Engineering manager | ______ | ______ | ______ |
| Product owner | ______ | ______ | ______ |
| Contacto de seguridad | ______ | ______ | ______ |

---

## 4. Recursos Operacionales

| Recurso | Link | Notas |
|---------|------|-------|
| Codigo fuente | ______ | Branch main, tags de release |
| Pipeline CI/CD | ______ | Build, test, deploy |
| Dashboard de monitoreo | ______ | Grafana / Datadog / CloudWatch |
| Politica de alertas | ______ | PagerDuty / Opsgenie |
| Tracking de errores | ______ | Sentry / Bugsnag |
| Logs | ______ | Kibana / CloudWatch Logs |
| Runbooks | ______ | Incidentes comunes y procedimientos |
| Postmortems | ______ | Analisis historico de incidentes |
| Documentacion de API | ______ | OpenAPI / Swagger |

---

## 5. Despliegue

**Despliegue estandar:**
1. Mergear PR a main
2. CI pasa (link al pipeline)
3. Deploy via [herramienta] a [ambiente]
4. Verificar via [health check / smoke test]

**Despliegue de emergencia:**
- Branch hotfix desde ultimo tag
- Build y deploy omitiendo pasos no criticos de CI
- Rollback: ______

**Calendario de deploys:**
- Regular: ______
- Periodos de congelamiento: ______

---

## 6. Dependencias

| Servicio | Direccion | Proposito | Contacto | Critico? |
|----------|-----------|-----------|----------|----------|
| ______ | Upstream | ______ | ______ | Si/No |
| ______ | Downstream | ______ | ______ | Si/No |

**Dependencias de terceros:**
| Vendor | Servicio | Proposito | Pagina de estado |
|--------|----------|-----------|-----------------|
| ______ | ______ | ______ | ______ |

---

## 7. Seguridad y Compliance

- Autenticacion: ______
- Autorizacion: ______
- Clasificacion de datos: [Publico / Interno / Confidencial / Restringido]
- Encripcion en transito: ______
- Encripcion en reposo: ______
- Requerimientos de compliance: ______
- Ultima revision de seguridad: ______

---

## 8. Limitaciones y Riesgos Conocidos

- ______
- ______
- ______

## 9. Registro de Cambios

| Fecha | Cambio | Autor |
|-------|--------|-------|
| ______ | Documento de ownership inicial | ______ |

Explicacion

La plantilla sigue el principio de revelacion progresiva: la primera seccion responde “que es esto y a quien llamo?” en segundos. La arquitectura y los links operacionales siguen para ingenieros que necesiten depurar o modificar el servicio. Las secciones de dependencias y seguridad existen para respuesta a incidentes y auditorias. Manteniendo todo en una pagina, el documento sigue siendo usable bajo presion.

Ejemplo de Tarjeta de Ownership de Servicio

=== Servicio: notification-service ===

Dueno:     Team Comms (comm-team@company.com)
On-call:   PagerDuty schedule "comms-oncall"
Tier:      1 (Critico)
Slack:     #comms-team

Tech Stack:
  Lenguaje:   Go 1.22
  Framework:  Chi router
  Base datos: PostgreSQL 15 (managed)
  Cache:      Redis 7
  Cola:       AWS SQS

Links Clave:
  Repo:        github.com/company/notification-service
  Dashboard:   grafana.company.com/d/notif-overview
  Runbook:     wiki.company.com/runbooks/notification-service
  API Docs:    api.company.com/docs/notifications
  Postmortems: wiki.company.com/postmortems?service=notification

Dependencias:
  Upstream:    user-service (critico), auth-service (critico)
  Downstream:  email-provider (SendGrid), sms-provider (Twilio)
  Terceros:    SendGrid, Twilio (ambos tienen pagina de estado)

Deploy:
  CI:          GitHub Actions (build, test, deploy)
  Metodo:      Argo CD (GitOps)
  Frecuencia:  2-3x por semana
  Rollback:    Argo CD rollback a revision anterior

Riesgos Conocidos:
  - Rate limits de SendGrid pueden causar demoras en bursts de email
  - Conexiones WebSocket necesitan graceful shutdown durante deploys
  - Pool de conexiones DB maxea en 100; monitorear durante horas pico

Ultima actualizacion: 2026-07-11 por alice

Variantes

Contexto	Ajustes	Notas
Serverless / funcion	Reemplazar seccion de deploy con version de funcion y configuracion de triggers	Las funciones pueden no tener pipelines CI tradicionales
SaaS de terceros	Agregar detalles de contrato, fechas de renovacion, y rutas de escalamiento con vendor	No controlas la infraestructura
Data pipeline	Agregar schemas de entrada/salida, SLAs, y checks de calidad de datos	La frescura de datos importa tanto como el uptime
Libreria compartida	Agregar lista de consumidores, politica de versionado, y proceso de breaking changes	Las librerias tienen impacto transitivo
App mobile	Agregar proceso de release, links a app stores, y estrategia de rollout	Los deploys mobile no son completamente automatizables

Lo que funciona

1. Una pagina por servicio — si no cabe en una pantalla, no se leera durante un incidente
2. Link, no dupliques — el doc de ownership es un indice, no un repositorio de todo el conocimiento
3. Revisa trimestralmente — ownership, dependencias, y stacks tecnologicos cambian mas rapido de lo que crees
4. Hazlo buscable — nuevos ingenieros encuentran servicios por nombre, no navegando carpetas
5. Incluye un changelog — saber cuando se actualizo el doc te dice si confiar en el

Errores Comunes

1. Escribirlo una vez y olvidarlo — los docs de ownership obsoletos causan mas dano que ningun doc; te enganan
2. Hacerlo demasiado largo — si un ingeniero no encuentra la rotacion on-call en 10 segundos, el doc ha fallado
3. Omitir dependencias — la mitad de los incidentes son causados por fallas upstream; saber de que dependes
4. No asignar un dueno unico — “el equipo backend lo posee” no es ownership; nombra un equipo y una persona
5. Esconderlo en un wiki que nadie usa — el doc deberia estar linkeado desde el README del repo, dashboard de monitoreo, y pipeline de CI

Lectura Adicional

• Documentación oficial: consulta la referencia actualizada del framework o herramienta utilizada.
• Guías relacionadas: explora las guías de microservices y runbook para profundizar.
• Patrones complementarios: revisa los patrones de diseño aplicables a tu stack tecnológico.
• Postmortems públicos: estudia incidentes reales de equipos que enfrentaron problemas similares en producción.

Notas de Producción

• Despliega gradualmente usando canary o blue-green para detectar regresiones temprano.
• Configura alertas para errores, latencia p99 y tasa de fallos antes de habilitar en producción.
• Documenta el rollback en el runbook; prueba el procedimiento en staging al menos una vez por trimestre.
• Revisa logs estructurados con correlation IDs para trazar requests end-to-end en incidentes.

Puntos Clave

• Aplica plantilla de documento de ownership de servicio cuando necesites una solución práctica para tu caso de uso.
• Monitorea el rendimiento después de implementar; mide latencia, errores y uso de recursos antes y después.
• Revisa la sección de Troubleshooting ante errores comunes; la mayoría tienen causa raíz documentada con solución.
• Mantén dependencias actualizadas y ejecuta tests en CI para prevenir regresiones en producción.

Troubleshooting

• Pipeline fails silently: enable verbose logging and store pipeline artifacts between stages so you can inspect the exact state that failed.
• Container crashes on startup: check that environment variables, secrets, and config files are mounted correctly. Read the first 50 lines of logs before scaling replicas.
• Deployment rolls back repeatedly: verify health checks, resource limits, and startup probes. A failing readiness probe is a common cause of rolling restarts.
• Slow CI builds: cache dependencies and docker layers. Split large test suites into parallel jobs to reduce wall-clock time.
• Drift between environments: use infrastructure-as-code and immutable artifacts.

Errores Comunes en Producción

• Dejar campos requeridos vacíos o usar respuestas vagas de una palabra.
• Llenar el documento una vez y nunca actualizarlo cuando cambia el alcance o las decisiones.
• Guardar el documento donde el equipo no lo busque durante incidentes o revisiones.
• No asignar un responsable, fecha límite o cadencia de revisión.
• Copiar texto base sin eliminar secciones que no aplican.
• Saltar el control de versiones, lo que impide rollback y responsabilidad.
• No vincular el documento con decisiones relacionadas o acciones de seguimiento.
• Evitar revisiones trimestrales que retirarían secciones obsoletas o sin uso.