Manual de despliegue

Limitaciones del kit

⚠️IMPORTANTE: revisar este apartado para tener en cuenta las limitaciones cuando se hace uso del kit de despliegue.

• El kit permite múltiples inventarios de máquinas pero no es capaz de manejar múltiples instalaciones de Anjana con configuraciones distintas. Serán necesarios múltiples kits para distintos entornos.

• La máquina donde se despliegue el kit deberá pertenecer a un solo entorno de Anjana, ya que será plataformada y sufrirá cambios de acuerdo al entorno de Anjana que se esté manejando. No será posible controlar múltiples instalaciones de Anjana desde una máquina que contenga el kit.

• En caso de que falle la instalación y el relanzamiento del kit falle, será recomendable reaprovisionar la máquina en limpio y comenzar de nuevo.

• El usuario anjana es un usuario reservado y no puede existir en la máquina.

Requisitos

Conectividad requerida

El kit descargará todos los recursos necesarios desde el repositorio central de Anjana Data por protocolo HTTPS y puerto 443 contra el servidor releases.anjanadata.com, por lo que será necesario tener conectividad desde los servidores a provisionar con dicho servicio.

Necesario solicitar acceso y credenciales en cs@anjanadata.com.

Plataformado de entorno

A partir de 25.a1, se incluye un script de plataformado que acondicionará la máquina de despliegues destinada a la ejecución del kit ansible de Anjana con los siguientes recursos:

• Descarga del kit de la versión indicada en el propio script.

• Instalación de paquetes y dependencias necesarios para la ejecución.

El script puede obtenerse aquí: anjana.sh

Una vez descargado, es necesario que se situe dentro de la máquina a plataformar. Puede accionarse usando el siguiente comando:

chmod +x anjana.sh

./anjana.sh

El script de plataformado requerirá la siguiente información:

• Modo de instalación, nuevo entorno o entorno de Anjana existente.

• Credenciales, solicitadas previamente a cs@anjanadata.com.

• Dominio, necesario para el frontal y la comunicación entre microservicios.

• Certificado, correspondiente al dominio elegido.

• Versión, por defecto la más reciente correspondiente al script de plataformado.

• Inventario, por defecto localhost, pero se indicará el inventario a utilizar aunque no se haya creado todavía. NO será posible ajustarlo posteriormente relanzando este script.

🛈NOTA: Para RedHat es necesario que el SELinux esté en Permissive o Disabled.

⚠️IMPORTANTE: Desde 25.1 un certificado es requerido y necesita ser depositado en el directorio /opt/common/anjana-certs/de todas las instancias que conformen el entorno de Anjana.
El directorio anjana-certs deberá ser creado en caso de no existir.

El certificado deberá quedar de esta forma:

Ajustes requeridos

El kit ya viene preconfigurado para desplegar Anjana según los ajustes recomendados, será necesario realizar ajustes dependiendo del entorno de acuerdo a las siguientes pautas:

🛈NOTA: Los inventarios de ejemplo sample y localhost serán reemplazados durante actualizaciones del kit, por tanto han de usarse como base para generar inventarios propios antes de continuar (inventario localhost como base para entornos Singlenode, sample para distribuidos o balanceados).

• Singlenode: Para entornos Singlenode, no se requiere modificación o ajustes adicionales, podrá ser utilizado el inventario localhost provisto en el kit.

• Distribuido / Balanceado: Para entornos Distribuidos o Balanceados, o cuando se quiera usar como nodo de ansible un nodo distinto al del entorno Anjana, será necesario usar el inventario sample provisto o generar uno nuevo clonando éste para realizar los siguientes ajustes:

  • Credenciales de conexión a infraestructura:

    

  • Nodos anjana-platform: será necesario duplicar la entrada por cada instancia presente en el entorno ajustando la numeración e IP, teniendo en cuenta que localhost hace referencia a la instancia en la que se está ejecutando el kit de ansible y no necesita ser duplicada.
    

    

  • Resto de nodos: serán ajustados de acuerdo a la distribución del entorno y las descripciones en el propio fichero, indicando en cada nodo la IP que corresponda a la instancia real. Ejemplo de uso: Si hay más de un nodo de Zookeeper, deberá duplicarse la entrada.

    

    
    

    

• Todos los entornos: De forma común a todos los tipos de entornos, la licencia deberá ser indicada y ajustada en el siguiente apartado del fichero all.yml, ubicado en la ruta (por defecto) /opt/ansible/ansible-inventories/<inventario>/group_vars/all.yml.

  

Para conocer todas las opciones ajustables disponibles, se puede consultar el Anexo - Funcionalidad avanzada.

⚠️IMPORTANTE: En caso de tratarse de un entorno de Anjana Distribuido o Balanceado, o haber ubicado el kit de ansible fuera del nodo de Anjana, es necesario lanzar el tag platform después de realizar los ajustes necesarios, para plataformar y ajustar todos los nodos del despliegue.

anjana -t platform

Instalación de Anjana

Después de haber tenido en cuenta lo mencionado en el apartado de Requisitos, habrá que revisar si es necesario realizar ajustes adicionales teniendo en cuenta los Anexos Funcionalidad avanzada o Casos de Uso.

Una vez completado, para la instalación de Anjana, tanto Singlenode como Distribuido o Balanceado, se lanzará uno de los siguientes comandos:

Para instalar Anjana con datos de ejemplo:

anjana -t anjana-sample

Para instalar Anjana sin datos de ejemplo:

anjana

Una vez finalizada la instalación se podrá acceder a los frontales de Anjana Data mediante el dominio configurado:

example.anjanadata.org/

example.anjanadata.org/configpanel

Actualización y mantenimiento del kit

Requisitos

Conectividad requerida

Se da por hecho que se cuenta con la misma conectividad mencionada anteriormente en el apartado de Conectividad requerida de la sección Despliegue de Anjana.

Actualización de kit Ansible

⚠️IMPORTANTE: Hay numerosos cambios bloqueantes para esta versión, se recomienda reconstruir la infraestructura y realizar una instalación limpia del producto en esta versión migrando los datos.

En caso contrario, para actualizaciones desde 23.1 o actualizaciones de kits dentro de la versión 25.a1 se seguirán los siguientes pasos:

Ejecución del script de plataformado

(25.a1x y anteriores)

El script de plataformado incorpora una opción para desplegar sobre un entorno existente, lo que permite realizar las siguientes acciones:

• Borrado de todos los paquetes de ansible existentes y posterior instalación de los actualizados.

• Instalación de paquetes y dependencias necesarios para la ejecución.

• Respaldo del kit existente, para su borrado y descarga del actualizado.

• Replataformado del nodo donde se está ejecutando ansible (manager).

El script de plataformado requerirá la siguiente información:

• Modo de instalación, nuevo entorno o entorno de Anjana existente.

• Inventario, por defecto localhost, pero se indicará el inventario existente. NO será posible ajustarlo posteriormente relanzando este script.

• Mensaje informativo de los cambios, para confirmar que se continúa con el proceso.

• Credenciales, solicitadas previamente a cs@anjanadata.com.

• Dominio, necesario para el frontal y la comunicación entre microservicios.

• Certificado, correspondiente al dominio elegido.

• Versión, por defecto la más reciente correspondiente al script de plataformado.

⚠️IMPORTANTE: Desde 25.1 un certificado es requerido y necesita ser depositado en el directorio /opt/common/anjana-certs/de todas las instancias que conformen el entorno de Anjana.

El certificado deberá quedar de esta forma:

Tras la finalización del script, unos comandos de ayuda serán mostrados para continuar con la operación de actualización a 25.1.

Ajustes de inventario requeridos

Será necesario revisar el apartado Ajustes requeridos de la sección Despliegue de Anjana para encontrar los pasos faltantes que se ajusten lo mejor posible al entorno existente, ya sea Singlenode o Distribuido/Balanceado.

Migración de configuración

(25.a1x y anteriores)

Debido al gran cambio estructural tanto del kit como del producto, este upgrade no puede ser incremental o parcial.

Por este motivo será necesario migrar las personalizaciones de la configuración anterior del kit a la nueva instalación teniendo en cuenta los siguientes puntos a revisar.

En all.yml:

• Credenciales de acceso a Nexus

• Credenciales de persistencias (Solr, PostgreSQL/RDS, MinIO/S3)

• Hosts y puertos de persistencias (Solr, PostgreSQL/RDS, MinIO/S3)

En hosts.yml:

• Credenciales de conexión para instancias.

• IPs y/o dominios pertenecientes a las instancias del entorno.

En anjanauihosts.yml (antes portalhosts.yml):

• Ajustes de seguridad de apache2

• Ajustes y entradas de whitelist

• Ajustes de actualizaciones de seguridad (ahora migrado al all.yml)

En templates:

• Credenciales en plugins.

• Personalizaciones en config de core y plugins.

• Personalizaciones en descriptores de core y plugins.

• Personalizaciones en config de apache2.

🛈NOTA: Se desaconsejan las personalizaciones fuera de las opciones administradas por el kit que no sean estrictamente necesarias para la configuración y descriptores de servicio del core de Anjana así como sus frontales (apache2).

Acciones manuales requeridas

(solo 4.a6 o RedHat)

La variable etc.hosts del archivo all.yml situada en el inventario que permitía personalizar los alias de Anjana en el /etc/hosts desapareció en la versión de kit 4.a7. Desde 4.a7:

• Los alias se rellenan automáticamente con la información del inventario.

• El formato será de un alias por línea.

• La nomenclatura ha cambiado y se han igualado todos los hosts, a partir de ahora se usará la estructura <host><número de host><server>.dominio.
  Ejemplo:kerno1server.anjanadata.local, kerno2server.anjanadata.local, minio1server.anjanadata.local, grafana1server.anjanadata.local, etc…

⚠️IMPORTANTE: Es necesario borrar los alias anteriores existentes y dejar que el kit los rellene automáticamente para evitar errores de redireccionamiento o duplicidad.

Mantenimiento de kit Ansible

Logs

Para el registro de la actividad del kit existe un fichero ubicado en /opt/version_report por defecto.

En el archivo se registran las acciones y modificaciones que se ejecutan en el entorno, ejemplo a continuación:

Actualización y mantenimiento de Anjana

Actualización de Anjana

La actualización de Anjana puede llevarse a cabo lanzando el siguiente comando:

anjana -t update

Por defecto buscará nuevas versiones disponibles para la versión de producto elegida en el all.yml como se muestra a continuación:

Se pueden establecer versiones concretas en caso de querer fijar un microservicio a una en específico, indicando la versión del microservicio de la siguiente manera:

Mantenimiento de Anjana

Importación/despliegue de roles y configuración

Es posible personalizar qué roles quieren importarse, editando en el all.yml la sección import_role y poniendo a true todo lo que se quiera importar/desplegar:

De esta manera se pueden añadir plugins o microservicios así como sus respectivas configuraciones a posteriori. Después de ajustar el fichero, se lanzarían las configuraciones con:

anjana -t update-config

Y la instalación de los microservicios/plugins con:

anjana -t <microservicio>

anjana -t <plugin>

Configuración y servicios

Es posible actualizar y/o desplegar la configuración de los microservicios así como los descriptores de los mismos cuando se realicen cambios y sea necesario.

🛈NOTA: La utilidad desplegará solo las configuraciones y/o descriptores de los roles que estén marcados para su importación en el all.yml, sección import_role como lo indicado en el apartado anterior Importación/despliegue de roles y configuración.

Para el despliegue de configuraciones de microservicios y plugins se lanza el siguiente tag:

anjana -t update-config

Para el despliegue de configuraciones de los frontales y apache2:

anjana -t update-vhosts

Para el despliegue de descriptores de servicio:

anjana -t update-services

Arranque, parada y reinicio del entorno

Es posible el arranque y parada de los microservicios de forma selectiva y ordenada, de forma que se evitan los errores derivados de la detención de un microservicio sin haber tenido en cuenta sus dependencias.

Ejemplo de uso: parada del backend para hacer un upgrade de Anjana.

🛈NOTA: La utilidad es compatible con múltiples instancias de un mismo microservicio (EJ: edusa1, edusa2, kerno1, kerno2, etc) pero no puede detener las instancias duplicadas de forma individual. Seleccionar la parada de kerno detendrá kerno1 y kerno2 respectivamente.

La funcionalidad provista por esta utilidad es la siguiente:

La detención y arranque ordenado de todo anjana. Se produce en el orden adecuado para evitar excepciones no intencionadas.

anjana -t stop

anjana -t start

anjana -t restart



Detención y arranque selectivo de un microservicio concreto. Se arrancarán todos los microservicios necesarios para que el seleccionado funcione. En caso de la parada se detendrán todos los microservicios que dependen del seleccionado de forma previa a la detención.

anjana -t stop-kerno

anjana -t start-kerno



Backups y restauración

Permite hacer backups en la ruta indicada en la variable backup de cada role, por defecto /opt/backups, de todas las persistencias y la configuración.

Por defecto, durante las tareas que conllevan operaciones con los datos, o durante updates, los backups son realizados de forma automática.

Para realizar backups manuales se pueden lanzar los siguientes comandos:

anjana -t backup

anjana -t backup-persistences

anjana -t backup-config

Es posible restaurar los datos de las persistencias y la configuración mediante el tag restore o sus respectivos tags individuales:

anjana -t restore

anjana -t restore-s3

anjana -t restore-bbdd

anjana -t restore-config

Migración de datos

Es posible exportar e importar los datos de las persistencias para una transferencia entre máquinas/entornos.

Por defecto, las rutas de exportación e importación, son /opt/export-import.

🛈NOTA: Es necesario establecer en el fichero all.yml, el installation.mode: manager para esta utilidad.

Las cadenas de conexión como puertos, host, contraseñas, tipo de cliente S3, entre otros, para bases de datos y MinIO y Solr pueden ser localizados y editados en el archivo all.yml del inventario:

🛈NOTA: Hay que tener en cuenta que los archivos generados serán depositados en el nodo manager, donde se estará ejecutando ansible.

Para exportar todos los datos, se usa el comando:

anjana -t export

En caso de querer incluir la configuración como parte de la exportación y generar un comprimido:

anjana -t clone

De igual manera para su importación se usa el tag import o sus correspondientes individuales:

anjana -t import

anjana -t import-s3

anjana -t import-bbdd

En caso de datos comprimidos generados mediante el tag clone, para importar se usaría el tag deploy y sus correspondientes individuales:

anjana -t deploy

anjana -t deploy-s3

anjana -t deploy-bbdd

anjana -t deploy-config

Comprobación del estado

Se ha incluido la posibilidad de comprobar el estado de salud de todos los microservicios, persistencias y plugins incluidos en el entorno.

Para ello es necesario lanzar el tag:

anjana -t check-health



✅RECOMENDADO: para encontrar rápidamente el punto de error de la aplicación. Para buscar de forma más concisa, será necesario consultar los logs del microservicio, plugin o persistencia afectados.

Exportación de logs de microservicios

Es posible exportar los logs de los microservicios de Anjana a la carpeta de cada nodo del backend, por defecto /opt/anjana-logs/<microservicio>.log.

✅RECOMENDADO: para proveer logs al equipo de soporte.

Para la exportación habría que ejecutar:

anjana -t export-log

Por defecto se exportan los últimos 5 días pero es configurable en tiempo de ejecución:

anjana -t export-log -e '{"log": {"since": "2 day ago"}}'

Los logs pueden ser subidos al servicio o servidor S3 configurado en el all.yml, por defecto son subidos al bucket anjanalogs utilizando el comando:

anjana -t export-log-s3

🛈NOTA: Es necesario establecer en el fichero all.yml, el installation.mode: manager o local para esta utilidad.

Desinstalación

Se incluye una utilidad para proceder a la desinstalación completa del producto para el inventario seleccionado.
La desinstalación respeta los directorios de backups, export-import, ansible y los archivos de registro de instalación version_report, ambos situados en la carpeta principal de Anjana (por defecto /opt).
Para realizar la desinstalación de Anjana se lanza el siguiente comando:

anjana -t uninstall



⚠️IMPORTANTE: Para que se proceda a una desinstalación correcta, el inventario y su fichero hosts.yml tienen que estar actualizados de acuerdo al entorno actual, incluyendo: máquinas activas, IPs, nombres de host, usuario de conexión ssh, etc…

Errores conocidos

Timeout

Sucede cuando durante la ejecución y a la vez el despliegue la máquina está ocupada levantando

Fallo uninstall

A veces quitar los service alguno se queda congelado y falla.

Se recomienda para resolver ejecutar:

sudo systemctl stop xxxx

sudo systemctl disable --now xxxx

sudo reboot

Fallo uninstall - cluster MinIO

El tag uninstall intenta borrar las carpetas montadas desde volumen y falla.

Para evitarlo hay que comentar la líneas de los nodos de MinIO en hosts.yml