En la industria DevOps actual nos esforzamos para cumplir ciertas prácticas ejemplares que no solamente hacen nuestro trabajo más fácil, sino que también hacen nuestros sistemas y aplicaciones más fiables. Dos de esas prácticas son automatizar tanto como sea posible y documentar lo que hacemos. Y a veces, podemos mezclar esas dos prácticas y automatizar la generación de documentación. Aquí os presentamos un ejemplo que mejoró nuestras vidas ayudándonos a simplificar la generación de documentación de manera automatizada.

Documentación

La documentación es uno de los recursos clave en un equipo de ingeniería de sistemas o de desarrollo. Hay dos aspectos en los que básicamente todo el mundo está de acuerdo: es muy importante tener buena documentación que sea útil; y es muy difícil mantenerla actualizada y con cierta lógica. Las variables que influyen en estos son muchas y generan muchas alternativas:

CAPSiDE es uno de esos equipos que ha probado varios métodos. Hemos usado y usamos más de un procedimiento, pues no toda la documentación es igual y la tecnología sigue evolucionando. Aquí está la historia de cómo automatizamos la generación de documentación HTML desde texto en reStructured con Git, Gitlab, integración continua/distribución continua y Docker.

Automating Documentation - CAPSiDE, architects of the Digital Society

La situación

Clouddeploy es una herramienta de código abierto desarrollada en CAPSiDE que nos ayuda a crear y mantener la infraestructura en AWS a través de código. Para la documentación de esta herramienta empezamos a usar una wiki, pero a medida que esta fue creciendo también creció la idea de usar otro sistema. Mientras mirábamos diferentes alternativas, nos encontramos con Sphinx que transforma texto en reStructured Text (RST) en varios formatos, como HTML o epub.

Automating Documentation - CAPSiDE, architects of the Digital Society

Todo en CAPSiDE está bajo un control de versiones, así que los archivos RST se tuvieron que gestionar con Git. También tenemos una cuenta de Gitlab donde viven nuestros repositorios. Así que, en la primera versión de esta documentación, cada miembro del equipo hizo lo siguiente para contribuir:

Este proceso inicial fue engorroso en comparación con solo editar una wiki, por lo que necesitaba perfeccionarse un poco. Y dado que la automatización es el núcleo de la ingeniería de sistemas, buscamos formas de hacerlo.

Automating Documentation - CAPSiDE, architects of the Digital Society

La integración continua al rescate

Gitlab es un repositorio muy completo que proporciona herramientas de integración continua/distribución continua. TEs una herramienta muy poderosa y fácil de configurar, y su documentación es clara y completa. Es tan simple como esto:

Si agregas un archivo .gitlab-ci.yml al directorio raíz de tu repositorio y configuras tu proyecto GitLab para usar un runner, cada acción commit o push activa tu pipeline de integración continua.

En el flujo de trabajo anterior hubo varias oportunidades para reducir la carga de trabajo del equipo:

Esto se podría hacer en Gitlab en dos tareas:

Gitlab ofrece diferentes maneras de ejecutar las tareas de integración continua/distribución continua. Para un trabajo como este en el que era necesario configurar el entorno, decidimos usar Docker.

Gitlab Runners y Docker

La imagen de Docker en este runner solamente necesitaba configurar el entorno para que pudiéramos compilar el código. Un simple Dockerfile como este fue suficiente para ello:

FROM python:2.7

RUN pip install sphinx sphinx_rtd_theme

Con este, obtuvimos la imagen oficial en Python 2.7 y usamos pip para instalar Sphinx y el tema en RTD. El siguiente paso es crear la imagen que el runner utilizará en el servidor de Gitlab:

# docker build -t capside/python-sphinx .
# docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
capside/python-sphinx latest 13bff878fafc 1 hour ago 744MB

Ahora podemos crear el runner de Gitlab. Para ello, necesitas tener privilegios sudo en el servidor de Gitlab y ser administrador en Gitlab para obtener el token:

sudo gitlab-runner register

Responde a las preguntas que te solicita (más información aquí). Parte de la configuración que se establezca respondiendo estas preguntas se puede cambiar más adelante. La última pregunta es sobre cómo elegir el tipo de ejecución:

Please enter the executor: ssh, docker+machine, docker-ssh+machine, kubernetes, docker, parallels, virtualbox, docker-ssh, shell:
docker

En este caso escogemos docker, que nos lleva a la última pregunta en la que usaremos la imagen de Docker que creamos anteriormente:

Please enter the Docker image (eg. ruby:2.1):
capside/python-sphinx

Ahora tenemos el runner configurado. El siguiente paso es configurar la pipeline para que este runner se use cuando hagamos la acción de push en el repositorio.

Creando la pipeline

Ahora necesitamos crear el archivo .gitlab-ci.yml en nuestro repositorio, para que todo se ponga en marcha. La pipeline tendrá dos tareas:

Aquí está el gitlab-ci.yml que hemos generado:

image: capside/python-sphinx

stages:
- build
- deploy

build:
stage: build
script:
- make html
artifacts:
paths:
- _build/html

publish:
stage: deploy
only:
- master
before_script:
# Create the SSH directory and give it the right permissions
- mkdir -p ~/.ssh
# Add the SSH key stored in SSH_PRIVATE_KEY variable to the agent store
- echo "$SSH_PRIVATE_KEY" | tr -d '\r' > ~/.ssh/id_rsa
# Set right permissions
- chmod -R 700 ~/.ssh
script:
# Copy generated HTML files to documentation web server
- scp -r -o StrictHostKeyChecking=no _build/html [email protected]:/home/publish/doc
- ssh -o StrictHostKeyChecking=no [email protected] sudo /opt/docs/deploy_doc.sh

Esta es la visión general de lo que todo esto significa:

Automating Documentation - CAPSiDE, architects of the Digital Society

La situación final

Al principio de este documento hablamos sobre los distintos pasos que alguien del equipo necesitaba seguir para actualizar documentación. Ahora la situación ha cambiado y tiene este aspecto:

Automating Documentation - CAPSiDE, architects of the Digital Society

Así hemos eliminado la necesidad de configurar el entorno para cada miembro del equipo, compilar el código y copiarlo manualmente al servidor una vez se apruebe. Esto hace que la actualización de la documentación sea más fácil que antes, lo cual es clave para mantenerla al día.

TAGS: automation, ci pipeline, docker, documentation, documentation generation, gitlab

speech-bubble-13-icon Created with Sketch.
Comentarios

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

*
*