En proyectos grandes, que consisten en decenas y cientos de servicios interactivos, un enfoque de la documentaci贸n como c贸digo, documentos como c贸digo , se est谩 volviendo cada vez m谩s obligatorio.
Le mostrar茅 c贸mo puede aplicar esta filosof铆a en las realidades del servicio clasificado, o m谩s bien, comenzar茅 desde la primera etapa de su implementaci贸n: la automatizaci贸n de la actualizaci贸n de datos en la documentaci贸n.
Kit de herramientas
El principio de "documentaci贸n como c贸digo" implica el uso de las mismas herramientas al escribir documentaci贸n que al crear c贸digo: lenguajes de marcado de texto, sistemas de control de versiones, revisi贸n de c贸digo y pruebas autom谩ticas. El objetivo principal: crear condiciones para que todo el equipo trabaje en conjunto en el resultado final: una base de conocimiento completa e instrucciones para usar servicios de productos individuales. A continuaci贸n, hablar茅 sobre las herramientas espec铆ficas que hemos elegido para resolver este problema.
Como lenguaje de marcado de texto, decidimos utilizar el texto reStructuredText m谩s universal. Adem谩s de una gran cantidad de directivas que proporcionan todas las funciones b谩sicas para estructurar el texto, este lenguaje admite formatos finales clave, incluido el HTML necesario para nuestro proyecto.
Los archivos se convierten de .rst a .html a trav茅s del generador de documentaci贸n de Sphinx . Le permite crear sitios est谩ticos para los cuales puede hacer los suyos o usar temas ya preparados. Nuestro proyecto utiliza dos temas prefabricados : stanford-theme y bootstrap-theme . El segundo contiene subtemas que le permiten establecer diferentes esquemas de color para los elementos clave de la interfaz.
Para un acceso conveniente y r谩pido a la versi贸n actual de la documentaci贸n, utilizamos un sitio est谩tico alojado por una m谩quina virtual accesible desde la red de 谩rea local del equipo de desarrollo.
Los archivos fuente del proyecto se almacenan en el repositorio de Bitbucket, y el sitio se genera solo a partir de los archivos contenidos en la rama maestra. La actualizaci贸n de los datos es posible solo a trav茅s de la solicitud de extracci贸n, que le permite verificar todas las secciones nuevas de la documentaci贸n antes de que se publiquen en el dominio p煤blico.
Dado que entre la finalizaci贸n de una nueva secci贸n de la documentaci贸n y su env铆o al sitio es necesario verificar su contenido, el proceso clave en toda la cadena es el proceso de construir el sitio y actualizar los datos en el host. Este procedimiento debe repetirse cada vez que la solicitud de extracci贸n con la actualizaci贸n se fusione con la rama principal del proyecto.
Implementar esta l贸gica le permite a Jenkins , un sistema de integraci贸n continua de desarrollo, en nuestro caso, la documentaci贸n. Te contar茅 m谩s sobre la configuraci贸n en las secciones:
- Agregar un nuevo nodo a Jenkins
- Descripci贸n de Jenkinsfile
- Integraci贸n de Jenkins y Bitbucket
Agregar un nuevo nodo a Jenkins
Para crear y actualizar la documentaci贸n en el sitio, debe registrar una m谩quina preparada de antemano como agente de Jenkins para esto.
Preparaci贸n de la m谩quina
De acuerdo con los requisitos de Jenkins , todos los componentes incluidos en el sistema, incluida la m谩quina maestra y todos los nodos de agente registrados, deben tener JDK o JRE instalados. En nuestro caso, se utilizar谩 JDK 8 , para cuya instalaci贸n es suficiente ejecutar el comando:
sudo apt-get -y install java-1.8.0-openjdk git
La m谩quina maestra se conectar谩 al agente para realizar tareas asignadas en 茅l. Para hacer esto, debe crear un usuario en el agente bajo el cual se realizar谩n todas las operaciones y en el que todos los archivos generados por Jenkins se almacenar谩n en la carpeta de inicio. En sistemas Linux, simplemente ejecute el comando:
sudo adduser jenkins \--shell /bin/bash su jenkins
Para establecer una conexi贸n entre la m谩quina maestra y el agente, debe configurar SSH y agregar las claves de autorizaci贸n necesarias. Generaremos las claves en el agente, despu茅s de lo cual agregaremos la clave p煤blica al archivo authorized_keys para el usuario jenkins .
Construiremos el sitio con la documentaci贸n en un contenedor Docker usando una imagen de Python ya preparada : 3.7 . Siga las instrucciones en la documentaci贸n oficial para instalar Docker en el agente. Para completar el proceso de instalaci贸n, debe volver a conectarse al agente. Verifique la instalaci贸n ejecutando el comando que carga la imagen de prueba:
docker run hello-world
Para no tener que ejecutar comandos Docker en nombre del superusuario (sudo), es suficiente agregar el grupo de acopladores de usuario creado en la etapa de instalaci贸n, en cuyo nombre se ejecutar谩n los comandos.
sudo usermod -aG docker $USER
Configuraci贸n de nuevo nodo de Jenkins
Dado que conectarse al agente requiere autorizaci贸n, debe agregar las credenciales apropiadas en la configuraci贸n de Jenkins. En la documentaci贸n oficial de Jenkins se proporcionan instrucciones detalladas sobre c贸mo hacer esto en m谩quinas con Windows.
IMPORTANTE: El identificador especificado en la secci贸n Configurar Jenkins -> Administrar entornos de compilaci贸n -> Nombre de nodo -> Configurar en el par谩metro Etiquetas se usa en el archivo Jenkins para indicar el agente en el que se realizar谩n todas las operaciones.
Descripci贸n de Jenkinsfile
La ra铆z del repositorio del proyecto contiene el archivo Jenkins , que contiene instrucciones para:
- Preparaci贸n del entorno de construcci贸n e instalaci贸n de dependencias.
- Construye un sitio usando Sphinx
- Actualizaci贸n de la informaci贸n del host.
Las instrucciones se establecen utilizando directivas especiales, cuya aplicaci贸n consideraremos m谩s a fondo en el ejemplo del archivo utilizado en el proyecto.
Indicaci贸n del agente
Al comienzo del archivo Jenkins, especifique la etiqueta del agente en Jenkins , en la que se realizar谩n todas las operaciones. Para hacer esto, use la directiva del agente :
agent { label '-' }
Preparaci贸n del medio ambiente
Para ejecutar el comando de construcci贸n del sitio sphinx-build, debe establecer variables de entorno en las que se almacenar谩n las rutas de datos reales. Adem谩s, para actualizar la informaci贸n en el host, debe especificar de antemano las rutas donde se almacenan los datos del sitio con la documentaci贸n. La directiva de entorno le permite asignar estos valores a las variables:
environment { SPHINX_DIR = '.' //, Sphinx BUILD_DIR = 'project_home_built' // SOURCE_DIR = 'project_home_source' // .rst .md DEPLOY_HOST = 'username@127.1.1.0:/var/www/html/' //@IP__:__ }
Acciones principales
Las instrucciones principales que se ejecutar谩n en Jenkinsfile est谩n contenidas en la directiva de etapas , que consta de los diferentes pasos descritos por las directivas de etapa . Un ejemplo simple de una tuber铆a CI de tres etapas:
pipeline { agent any stages { stage('Build') { steps { echo 'Building..' } } stage('Test') { steps { echo 'Testing..' } } stage('Deploy') { steps { echo 'Deploying....' } } } }
Inicie el contenedor Docker e instale dependencias
Primero, ejecute el contenedor Docker con la imagen de Python terminada : 3.7 . Para hacer esto, use el comando docker run con los indicadores --rm y -i . Luego, secuencialmente haga lo siguiente:
- instalar python virtualenv ;
- crear y activar un nuevo entorno virtual;
- instalar en 茅l todas las dependencias necesarias enumeradas en el archivo
require.txt, que se almacena en la ra铆z del repositorio del proyecto.
stage('Install Dependencies') { steps { sh ''' docker run --rm -i python:3.7 python3 -m pip install --user --upgrade pip python3 -m pip install --user virtualenv python3 -m virtualenv pyenv . pyenv/bin/activate pip install -r \${SPHINX\_DIR}/requirements.txt ''' } }
Construye un sitio con documentaci贸n
Ahora construyamos un sitio. Para hacer esto, ejecute el comando sphinx-build con los siguientes indicadores:
-q : solo advertencias y errores de registro;
-w : escribe un registro en el archivo especificado despu茅s del indicador;
-b : nombre del -b del sitio;
-d : especifica el directorio para almacenar archivos en cach茅 - encurtidos doctree.
Antes de comenzar el ensamblaje, con el rm -rf elimine el ensamblaje y los registros del sitio anterior. En caso de un error en una de las etapas, el registro de ejecuci贸n de compilaci贸n sphinx aparecer谩 en la consola de Jenkins .
stage('Build') { steps { // clear out old files sh 'rm -rf ${BUILD_DIR}' sh 'rm -f ${SPHINX_DIR}/sphinx-build.log' sh ''' ${WORKSPACE}/pyenv/bin/sphinx-build -q -w ${SPHINX_DIR}/sphinx-build.log \ -b html \ -d ${BUILD_DIR}/doctrees ${SOURCE\_DIR} ${BUILD\_DIR} ''' } post { failure { sh 'cat ${SPHINX_DIR}sphinx-build.log' } } }
Actualizaci贸n del sitio de host
Y, por 煤ltimo, actualizaremos la informaci贸n sobre el host que da servicio al sitio con la documentaci贸n del producto disponible en el entorno local. En la implementaci贸n actual, el host es la misma m谩quina virtual que est谩 registrada como agente Jenkins para la tarea de ensamblar y actualizar la documentaci贸n.
Como herramienta de sincronizaci贸n, utilizamos la utilidad rsync . Para que funcione correctamente, es necesario configurar una conexi贸n SSH entre el contenedor Docker, en el que se encontraba el sitio con la documentaci贸n, y el host.
Para configurar la conexi贸n SSH con Jenkinsfile , se deben instalar los siguientes complementos en Jenkins :
- Complemento de agente SSH : le permite utilizar el paso
sshagent en los scripts para proporcionar credenciales del nombre de usuario / clave del formulario. - Complemento de credenciales SSH : le permite guardar credenciales del formulario nombre de usuario / clave en la configuraci贸n de Jenkins .
Despu茅s de instalar los complementos, debe especificar las credenciales actuales para conectarse al host completando el formulario en la secci贸n Credenciales :
- ID : identificador que se usar谩 en Jenkinsfile en el paso
sshagent para indicar credenciales espec铆ficas ( docs-deployer ); - Nombre de usuario : el nombre de usuario bajo el cual se realizar谩n las operaciones de actualizaci贸n de datos del sitio (el usuario debe tener acceso de escritura a la carpeta
/var/html del host); - Clave privada : una clave privada para acceder al host;
- Frase de contrase帽a: contrase帽a para la clave, si se configur贸 en la etapa de generaci贸n.
A continuaci贸n se muestra el c贸digo de script que se conecta a trav茅s de SSH y actualiza la informaci贸n en el host utilizando las variables del sistema especificadas en la etapa de preparaci贸n del entorno con las rutas a los datos necesarios. El resultado del comando rsync se escribe en el registro, que se mostrar谩 en la consola de Jenkins en caso de errores de sincronizaci贸n.
stage('Deploy') { steps { sshagent(credentials: ['docs-deployer']) { sh ''' #!/bin/bash rm -f ${SPHINX_DIR}/rsync.log RSYNCOPT=(-aze 'ssh -o StrictHostKeyChecking=no') rsync "${RSYNCOPT[@]}" \ --delete \ ${BUILD_DIR_CI} ${DEPLOY_HOST}/ ''' } } post { failure { sh 'cat ${SPHINX_DIR}/rsync.log' } } }
Integraci贸n de Jenkins y Bitbucket
Hay muchas formas de organizar la interacci贸n de Jenkins y Bitbucket , pero en nuestro proyecto decidimos usar el complemento Construcciones parametrizadas para Jenkins . La documentaci贸n oficial contiene instrucciones detalladas para instalar el complemento, as铆 como la configuraci贸n que debe especificarse para ambos sistemas. Para trabajar con este complemento, debe crear un usuario de Jenkins y generar un token especial para 茅l que le permita iniciar sesi贸n en el sistema.
Crear un token de usuario y API
Para crear un nuevo usuario en Jenkins , vaya a Configuraci贸n de Jenkins -> Administraci贸n de usuarios -> Crear usuario , y complete todas las credenciales necesarias en el formulario.
El mecanismo de autenticaci贸n que permite que los scripts o aplicaciones de terceros utilicen la API de Jenkins sin transmitir realmente la contrase帽a del usuario es un token de API especial que se puede generar para cada usuario de Jenkins . Para hacer esto:
- inicie sesi贸n en la consola de administraci贸n utilizando los detalles del usuario creado anteriormente;
- vaya a Configurar Jenkins -> Gesti贸n de usuarios ;
- haga clic en el 铆cono de ajustes a la derecha del nombre de usuario con el que est谩n autorizados en el sistema;
- busque la API de token en la lista de par谩metros y haga clic en el bot贸n Agregar nuevo token ;
- en el campo que aparece, especifique el identificador del token API y haga clic en el bot贸n Generar ;
- siguiendo el mensaje en la pantalla, copie y guarde el token API generado.
Ahora en la configuraci贸n del servidor Bitbucket , puede especificar el usuario predeterminado para conectarse a Jenkins .
Conclusi贸n
Si antes, el proceso consisti贸 en varios pasos:
- Descargue la actualizaci贸n al repositorio
- esperar la confirmaci贸n de la correcci贸n;
- armar un sitio web con documentaci贸n;
- actualizar informaci贸n sobre el host;
ahora solo haga clic en un bot贸n Fusionar en Bitbucket. Si despu茅s de verificar no es necesario realizar cambios en los archivos de origen, la versi贸n actual de la documentaci贸n se actualiza inmediatamente despu茅s de confirmar la exactitud de los datos.
Esto simplifica enormemente la tarea del escritor t茅cnico, lo que lo salva de una gran cantidad de acciones manuales, y los gerentes de proyecto obtienen una herramienta conveniente para rastrear adiciones de documentaci贸n y comentarios.
Automatizar este proceso es el primer paso para construir una infraestructura de gesti贸n de documentaci贸n. En el futuro, planeamos agregar pruebas autom谩ticas que verifiquen la correcci贸n de los enlaces externos utilizados en la documentaci贸n, y tambi茅n queremos crear objetos de interfaz interactivos que est茅n integrados en temas ya preparados para Sphinx .
隆Gracias a quienes leyeron esto para llamar la atenci贸n, pronto continuaremos compartiendo los detalles de la creaci贸n de documentaci贸n en nuestro proyecto!