Actualizar desde versiones 1.5 a 1.6

Consideraciones

Esta guía lo lleva en el proceso de actualizar una instalación pre-existente de EEI. Tenga en cuenta que:

• la versión requerida de EEI en ejecución es la v1.5.x
• se actualiza toda la solución EEI que se despliega con Docker
• se introducen nuevos módulos obligatorios para su despliegue

Personas

En esta versión se incorpora un nuevo módulo llamado Arai-Personas, el cual entre otras cosas provee servicios para definir los sellos de las personas con capacidad de firma de documentos dentro de la institución.

Configuración inicial

Para la incorporación del mismo al despliegue, hace falta definir previamente una serie de configuraciones:

• Se deben crear dos secretos que contendran información sensible

  • personas_db_pass: Password de la conexión con la base de datos.
  • personas_api_users: Json que define pares de usuario/password para la autenticación de la API de Personas

• La distribucion provee el script de bash secrets.sh.dist para ejemplificar como inicializar todos los valores requeridos.

Puede crear el secret de personas_db_pass y personas_api_users (en caso de no haberlo generado con el secret.sh.dist de la ultima versión) de la siguiente forma:

printf "postgres123" | docker secret create personas_db_pass -

printf '[["documentos","documentos123"],["huarpe","huarpe123"],["usuarios","usuarios123"]]' | docker secret create personas_api_users -

Crear la base de datos

Crear la base de datos como recurso externo, recordar que la configuración para la misma se debe incluir en el secreto previo y también en archivo prod/arai/personas.env

DB_HOST=db-personas
DB_PORT=5432
DB_DBNAME=arai_personas
DB_USERNAME=postgres
DB_PASSWORD=postgres
DB_SCHEMA=personas
DB_ENCODING=UTF8

Deberá crear la base de datos con los datos definidos previamente. Además, en el sitio de documentación de Araí-Personas hay documentación extensa de cómo crear la base de Postgres.

https://documentacion.siu.edu.ar/personas

Inicializar la base de datos

Este paso se lleva a cabo mediante el despliegue de la tarea

docker stack deploy \
    --with-registry-auth \
    -c prod/arai/util/personas_migrar_base.yml \
    personas_db

Puede verificar el estado de ejecución del mismo de la siguiente manera:

docker service logs personas_db_migrar -f

Una vez finalizado con éxito, puede borrar el stack:

docker stack rm personas_db

Desplegar el stack

Una vez realizada la configuración e inicialización de la base de datos, pasamos a desplegar el runtime del módulo de la siguiente forma:

cd prod/arai
docker stack deploy \
    --with-registry-auth \
    -c prod/arai/personas.yml \
    personas

Usuarios

La nueva versión de Arai-Usuarios incorpora varios cambios y/o mejoras, entre ellas:

• Vinculación con Araí-Personas
• Imagen LDAP que soporta claves generadas con el algoritmo BCRYPT, usando el mecanismo BIND.

Puesta en mantenimiento

Inicialmente, bajamos el stack usuarios para evitar acceso y tenerlo en mantenimiento.

docker stack rm usuarios

Atención: esto pondrá a todo el servicio de SSO fuera de servicio

Realizar el backup de las bases de datos LDAP y PostgreSQL de manera preventiva.

Incorporar nuevo secreto

Una vez realizado dichos backup, hay que agregar un nuevo secreto requerído en esta nueva version de Arai-Usuarios para el correcto despliegue del servicio:

• usuarios_conexion_personas: Parámetros de conexión con la Api de Araí-Personas

• La distribucion provee el script de bash secrets.sh.dist para ejemplificar como inicializar todos los valores requeridos.

Puede crear el secret de usuarios_conexion_personas (en caso de no haberlo generado con el secret.sh.dist de la ultima versión) de la siguiente manera:

printf '[["usuarios", "usuarios123", "http://personas-api:8080/api/v1/"]]' | docker secret create usuarios_conexion_personas -

Actualizar base PostgreSQL

Sin importar como se ejecuta la base PostgreSQL, es necesario realizar la exportación de datos de instancia local de la siguiente manera:

docker stack deploy --with-registry-auth --compose-file prod/arai/util/usuarios_exportar_instalacion.yml usuarios_export
docker service logs usuarios_export_idm -f

Esperar a que exporte y se detenga la ejecución. Si tuvo éxito la operación, eliminar el stack temporal usuarios_export:

docker stack rm usuarios_export

Usando los datos de instancia local exportados previamente, realizar la migración de la base de datos PostgreSQL:

docker stack deploy --with-registry-auth --compose-file prod/arai/util/usuarios_actualizar_base.yml usuarios_actualizar_base
docker service logs usuarios_actualizar_base_idm -f

Nota: tenga en cuenta que tanto la exportación como actualización, utilizan un directorio "files" donde se descargan datos. Este directorio tiene que estar para ambas tareas, por lo que se ejecutan en el mismo nodo (por ej, mediante la constraint node.role=manager).

Finalmente, si la migración tuvo éxito, eliminar el stack temporal usuarios_actualizar_base:

docker stack rm usuarios_actualizar_base

Actualizar base OpenLDAP

Se introducen en esta versión algunos cambios al schema de LDAP, por lo que es necesario actualizarlo previamente.

La forma de actualizar el esquema LDAP depende de si está utilizando una instalación OpenLDAP tradicional o por medio de Docker.

Si esta usando OpenLDAP Docker

• Se han publicado múltiples versiones de la imagen docker. Se requiere la imagen (NUEVA) siudocker/openldap-arai con el tag o versión v1.0.0.
• Se presupone que se utiliza volúmenes de datos/config para persistir los cambios en la base OpenLDAP

A continuación se describe en forma genérica los pasos para actualizar un ambiente con Docker.

1. En este caso, se debe realizar el despliegue de la nueva versión v1.0.0 (o la que ha personalizado), basado en v1.0.0.

2. Desde el repositorio HUB del proyecto, obtener los archivos (se encuentran dentro del directorio idm/templates/ldap/$VERSION/ldif/ del proyecto) y realizar:

docker cp idm/templates/ldap/$VERSION/ldif/3.1-to-3.2.ldif ID-CONTENEDOR-LDAP:/tmp

3. Se deben actualizar los esquemas con los cambios requeridos, ejecutando dentro del contenedor de LDAP:

docker exec -it ID-CONTENEDOR-LDAP ldapmodify -c -Y EXTERNAL -Q -H ldapi:/// -f /tmp/3.1-to-3.2.ldif

NOTA: La forma de actualizar el esquema LDAP si está utilizando una instalación OpenLDAP tradicional se puede ver en el siguiente enlace si ya realizo la actualizacion por medio docker obviar esto.

Actualizar las configuraciones

En este punto, debemos ajustar las configuraciones mediante variables de entorno. Ver mas detalles acá.

Se agregan las siguientes variables de entorno: SEGURIDAD_CHECK_PASS, IDP_SESSION_DURACION, IDP_URL_PERFIL y CREDENCIALES_API_BASIC_PERSONAS. Las cuales deberán ser configuradas.

Migrar datos y vincular con Arai-Personas

Esta versión de Arai-Usuarios requiere que se ejecute la migración de ciertos datos internos. El proceso de vinculación de usuarios y personas se realiza mediante una serie de comandos que garantizan la inicialización correcta de los datos. Para mayores detalles ver acá.

A continuación se detallan los pasos:

1. En primer lugar es necesario correr el contenedor que permite realizar tareas administrativas sobre la instalación de Araí-Usuarios. Para esto se debe realizar el deploy de usuarios_cmd.yml de la siguiente forma:

   docker stack deploy  --with-registry-auth  -c prod/arai/util/usuarios_cmd.yml usr-cmd

2. El servicio anterior requiere que el nodo que ejecuta los comandos Docker sea el mismo donde se despliega el stack usuarios, agregarle por tanto el labels.cmd=usuarios al nodo para que el servicio src-cmd se inicie:

   NODE_NAME=$(docker info --format '{{ .Name }}')
   docker node update --label-add cmd=usuarios $NODE_NAME

3. Una vez se encuentra corriendo el contenedor, nos conectamos al mismo de la siguiente forma:

   docker exec -it ID_CONTENEDOR_USR_CMD bash

4. Dentro del contenedor, primero exportar las variables de entorno:

   source /entrypoint.sh --export-secrets && set +e

5. Luego migrar formato de datos de aplicaciones que almacena el IDM:

   ./idm/bin/instalador migracion idm

6. Opcional. Migrar el formato de las claves tipo BCRYPT para soportar autenticación BIND vía LDAP:

   ./idm/bin/instalador migracion bcrypt

7. Luego migrar los datos internos para soportar la vinculación de Arai-Personas:

   ./idm/bin/instalador migracion personas

8. Finalmente, inicializar las personas por cada usuario existente en Arai-Usuarios:

   ./idm/bin/instalador arai:personas inicializar

   Para mayores detalles sobre la vinculación con Arai-Personas, ver la documentación de inicialización y gestión disponibles.

Realizar el despliegue

Finalizada la nueva configuración y la migración pertinente de los datos, hay que volver a desplegar el stack para dejar operativo Arai-Usuarios:

docker stack deploy --with-registry-auth --compose-file prod/arai/usuarios.yml usuarios

Si lo desea puede ejecutar una comprobación para verificar el correcto estado de los servicios.

Arai-Documentos

A partir de esta versión se incorporan los siguientes secretos como requerídos por Arai-Documentos para su despliegue:

• docs_conexion_personas: Parámetros de conexión con la Api de Araí-Documentos
• (opcional) docs_conexion_firmar: Parámetros de conexión para realizar una firma digital. Por defecto, este parámetro se encuentra comentado en docs.yml. Para su correcta configuración, el mismo debe ser descomentado y debe poseer el usuario y password a utilizar.

Stamper

A partir de esta versión el uso del servicio Estampador utilizado por Arai-Docs es obligatorio, por lo que se requiere su despliegue en el stack correspondiente a Arai-Documentos. Para la correcta configuracion, siga los siguientes pasos

1. Dar de baja el stack

   docker stack rm docs

2. Creacion de keystore para stamper. Referirse a las indicaciones de esta guia: Crear Firma de Sistema.

3. Crear el secret. En la guia referida en el paso anterior, se genera el archivo del keystore nombrado como keystore_stamper.p12 por defecto

   docker secret create docs_stamper_keystore /ruta/a/keystore_stamper.p12

4. Modificar docs.stamper.env con los parametros utilizados durante la creación de la firma. Particularmente validar las entradas para:

   ARAI_DOCS_STAMPER_KEYSTORE_PASS = <password utilizada para crear el keystore_stamper.p12>
   ARAI_DOCS_STAMPER_KEYSTORE_ALIAS = <valor del parametro -name del paso "Exportar PKCS#12 bundle" de la guia>

Actualizar variables

En la versión 1.4 de Arai-Docs se agregaron nuevas configuraciones. Los cambios se detallan acá.

Revise todas las variables nuevas y configurelas según su necesidad. Además, debe crear el secret de docs_conexion_personas (en caso de no haberlo generado con el secret.sh.dist de la ultima versión):

DOCS_CONEXION_PERSONAS=$(cat << EOF
"{base_uri:'personas-api:8080/api/v1/',method:'basic',user:'documentos',password:'documentos123'}"
EOF
)
printf $DOCS_CONEXION_PERSONAS | docker secret create docs_conexion_personas -

Actualizar Base de Datos

1. Realizar el backup de PostgreSQL de manera preventiva

2. Desplegar el servicio que actualiza la base de datos

   docker stack deploy --with-registry-auth --compose-file prod/arai/util/docs_actualizar_base.yml docs_actualizar_base

3. Opcional. Observar el avance del proceso de migración en el log del servicio. Finalizada la migración, se puede eliminar dicho despliegue del servicio

   docker service logs docs_actualizar_base_update -f
   docker stack rm docs_actualizar_base

Nota: esto requiere acceso a la base de datos para modificar su estructura. Alternativamente, puede seguir esta guía para actualizar la base de datos.

Actualizar API, Worker y Stamper

Desplegar las nuevas versiones de la API y del Worker

docker stack deploy --with-registry-auth -c prod/arai/docs.yml docs

Huarpe

Actualizar variables

En la versión 3.1 de Huarpe se agregaron nuevas configuraciones como variables de entorno y se renombraron otras. Todas se detallan acá.

Todas estas configuraciones, se deben ver reflejados en el archivo huarpe.env.

Actualizar el despliegue

1. Bajar stack huarpe

   docker stack rm huarpe

2. Desplegar las nuevas versiones del servicio

   docker stack deploy --with-registry-auth -c prod/arai/huarpe.yml huarpe

Monitoreo

La version 1.6 cuenta con un nuevo stack de monitoreo (Loki, Grafana, Prometheus, Promtail) que incluye automatizaciones en las configuraciones y dashboards de ejemplo para implementar junto a EEI.

Si actualmente posee desplegado en su entorno el stack de loki/grafana provisto en versiones anteriores, debe darlo de baja utilizando

docker stack rm loki

Posteriormente debe eliminar los volumenes asociados previo a actualizar el stack

docker volume rm loki_grafana-data loki_log-data

Tenga en cuenta que al eliminar los volumenes perderá los logs historicos que posea el servicio de loki junto con la configuración que haya personalizado.

Proceda a la nueva documentacion de logs para implementar los nuevos servicios.