Versionado de elementos sobre Git
- 1 Introducción
- 2 Requisitos para habilitar el versionado
- 3 Configuración del repositorio Git
- 4 Formato de serialización de los elementos
- 5 Mensaje de commit en edición y creación
- 6 Histórico de cambios, restauración y edición de un elemento
- 7 Creación de Snapshot y Tag de Git
- 8 Restaurar la plataforma
- 9 Modificación de elementos desde repositorio Git
Disponible desde versión 3.3.1 (moonwalker)
Para versionar FlowEngine, Dataflow y Notebooks, será necesario mapear los volúmenes al controlpanel
Notebooks → /usr/local/notebooks/
FlowEngine → /usr/local/flows/
Datflows → /usr/local/dataflows/
Introducción
En esta release se ha añadido una funcionalidad que nos permite tener versionados los elementos de plataforma, tales como ontologías, dashboards, gadgets, apis…, en un repositorio Git, de tal forma que podemos tener un control de cambios sobre dichos elementos y restaurar una versión anterior en cualquier momento.
Además, podremos generar versiones etiquetadas de los elementos (tags en Git), para que en caso de migración o de querer restaurar una versión en concreto de los elementos, podamos hacerlo sin problemas.
Requisitos para habilitar el versionado
Para poder habilitar el versionado de elementos en una instalación de plataforma necesitaremos:
Repositorio Git (GitHub o GitLab) con un token de API con permisos de escritura.
Role administrator: solo los administradores pueden configurar esta funcionalidad.
Configuración del repositorio Git
En primer lugar, tendremos que configurar el repositorio Git que va a utilizar la plataforma para ir versionando los elementos. La plataforma trabajará siempre en la misma rama de Git establecida en la configuración.
Para configurarlo, iremos al menú > Version Control > Configuration
Aquí rellenaremos todos los campos necesarios y marcaremos la opción de crear repositorio si así lo deseamos:
En caso de tener ya un repositorio creado, desmarcar la opción.
Una vez configurado, podremos modificar la configuración en cualquier momento, incluso deshabilitar el versionado de recursos temporalmente (botón arriba a la izquierda). También podremos borrar directamente la configuración.
Además, en el momento de configurarlo, se nos generará un SNAPSHOT de los recursos actuales en el repositorio:
Formato de serialización de los elementos
Para serializar las entidades o elementos del sistema de versionado, hemos elegido el formato Yaml, ya que para elementos como los Dashboards o Gadgets, nos permite mostrar el contenido HTML de manera legible.
Además, si queremos editar el fichero para luego restaurarlo, será mucho más sencillo.
Hay algunos elementos como los Web Projects, Dataflows, flows y notebooks, que además de tener un fichero serializado con la información de la entidad de base de datos, tendrán asociado un/unos fichero(s) zip que contendrán los recursos físicos de dicho elemento.
Mensaje de commit en edición y creación
Cuando se habilita el sistema de versionado, nos empezaran a aparecer pop-ups con un cuadro de texto para introducir un mensaje de commit a la hora de crear o actualizar elementos versionables.
Por ejemplo, al editar una ontología:
Si dejamos el commit vacío, se pondrá un mensaje de commit genérico, indicando el usuario que ha editado o creado el elemento.
Mensajes de commit para Dataflows, Flows y Notebooks
Como estos elementos tiene recursos físicos en disco asociados, es necesario realizar el commit de manera “manual e intencionada” desde el listado de los mismos, a través de un botón especial.
Histórico de cambios, restauración y edición de un elemento
En la opción de menú Restore Resource, disponible para todos los usuarios que tengan role igual o superior a developer, se nos abrirá una pantalla en la que podremos ver el histórico de cambios para cualquier elemento al que tengamos acceso, restaurarlo e incluso modificar la versión actual.
Restauración de un elemento existente
Si el elemento existe actualmente en la plataforma, elegiremos la primera opción “Restore existing resource”.
Aquí nos saldrá un desplegable con todos los elementos que son versionables de plataforma.
Una vez seleccionado el tipo de elemento, nos aparecerá un desplegable con el elemento concreto que queremos restaurar.
Por último, al seleccionar el elemento a restaurar, nos aparecerá un desplegable de commits que al seleccionarlo nos mostrará el contenido del elemento en ese commit.
Nos aparecerá un visor de código con las diferencias existentes entre el elemento actual (editable, a la derecha) y el elemento en el commit seleccionado (no editable, a la izquierda).
Una vez aquí, podremos restaurar la versión del commit (botón Restore), o editar la versión actual para mergear cambios, por ejemplo. Para editar la versión actual, modificaremos el contenido del elemento en el editor, y pulsaremos en Save Changes (cmd + s / ctrl + s).
Restauración de un elemento no existente
En caso de que queramos recuperar un elemento que fue borrado en algun commit, podemos hacerlo desde la opción “Restored deleted entity”
Aquí elegiremos el tipo de entidad, la ruta relativa al elemento en el repositorio Git, y el commit de dónde lo queremos restaurar. Finalmente le daremos a “Load content” para verificar que el contenido es correcto y después a “Restore”.
Creación de Snapshot y Tag de Git
Podemos generar un Snapshot de los elementos versionables de plataforma en cualquier momento.
Snapshot con todos los elementos
Si queremos generar una versión incluyendo todos los elementos, nos aseguraremos de que están marcados todos los elementos (por defecto es así).
En este caso el nombre del Tag será opcional.
Snapshot con elementos seleccionados
En caso de queramos generar una versión solo con ciertos elementos del sistema, tendremos que dejar marcados únicamente los recursos que queremos incluir.
Hay que tener en cuenta que si desmarcamos usuarios, los recursos asociados a esos usuarios se excluirán automáticamente, aunque estén marcados.
En este caso sí será necesario indicar el nombre del Tag de Git.
Restaurar la plataforma
Con esta funcionalidad también podemos restaurar todos los elementos de plataforma desde un repositorio git indicando un tag o branch.
También se puede realizar este proceso para migrar/promocionar entornos, por ejemplo, para llevarse los elementos de un entorno de desarrollo a uno de pre-producción.
Este proceso borrará todos los elementos versionables que no se encuentren en el repositorio Git.
Modificación de elementos desde repositorio Git
Es posible también modificar los elementos manualmente desde el repositorio, y después restaurarlos en plataforma.
Para ello iremos a cualquier pantalla del versionado (para usuarios no administradores, pantalla restaurar recurso), y buscaremos el botón “Sync repository”.
De esta forma se sincronizarán los cambios con la base de datos.