Es

Migración de MariaDB al contenedor orchestrator-db:v5.9.2+#

⚠️ Importante: Para migrar a orchestrator-db:v5.9.1+ es más seguro usar un volcado lógico y un volumen nuevo. Esto evita el riesgo de dañar el directorio de datos anterior y permite volver atrás sin pérdida de información.

1. Qué conviene saber de antemano#

En las imágenes de Sherpa Orchestrator para MariaDB basadas en Chainguard se usa:

  • solo MYSQL_ROOT_PASSWORD para la inicialización;
  • el montaje existente ./backend/config/my.cnf:/etc/mysql/conf.d/my.cnf.

Los parámetros antiguos MYSQL_ALLOW_EMPTY_PASSWORD, MYSQL_USER y MYSQL_PASSWORD para el contenedor integrado ya no son necesarios.

2. Verificar la configuración actual#

cd /opt/SherpaOrchestrator

grep -E "^(DB_ENGINE|MYSQL_HOST|MYSQL_PORT|MYSQL_USER|MYSQL_PASSWORD|MYSQL_DB)=" .env

Para la MariaDB integrada, como mínimo deben ser correctos:

  • DB_ENGINE=mysql
  • MYSQL_HOST=orchestrator-db
  • MYSQL_DB=orchestrator

Verifique el contenedor y el volumen actuales:

docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}" | grep orchestrator-db

docker volume ls | grep orchestrator-mysql-data

3. Poner la aplicación en modo de mantenimiento#

Detenga los servicios de la aplicación para que no haya nuevas escrituras durante el dump:

docker compose stop orchestrator orchestrator-nginx orchestrator-websocket orchestrator-vnc-proxy orchestrator-autopilot

Asegúrese de que el contenedor orchestrator-db siga ejecutándose:

docker ps --format "table {{.Names}}\t{{.Status}}" | grep orchestrator-db

4. Crear una copia de seguridad lógica de MariaDB#

Cree un directorio:

sudo mkdir -p ./backups/mariadb
sudo chown -R "$USER:$USER" ./backups
export DB_MIGRATION_TS="$(date +%Y%m%d_%H%M%S)"
export DB_BACKUP_FILE="./backups/mariadb/orchestrator_${DB_MIGRATION_TS}.sql"

Genere un dump de las bases de datos en uso:

docker exec orchestrator-db sh -lc 'mariadb-dump \
  -uroot \
  -p"$MYSQL_ROOT_PASSWORD" \
  --databases orchestrator orchestrator_archive \
  --single-transaction \
  --routines \
  --events \
  --triggers' > "$DB_BACKUP_FILE"

Verifique el resultado:

ls -lh "${DB_BACKUP_FILE}"
tail -n 20 "${DB_BACKUP_FILE}"
💡 Por qué se usa mariadb-dump

Un volcado lógico transfiere los datos a nivel SQL y no depende del formato interno del datadir. El volumen antiguo permanece intacto y el nuevo contenedor se inicia sobre un directorio limpio.

5. Detener el contenedor antiguo de MariaDB#

docker compose stop orchestrator-db
docker ps -a --format "table {{.Names}}\t{{.Status}}" | grep orchestrator-db

Todavía no elimine el volumen antiguo.

6. Crear un volumen nuevo para MariaDB Chainguard#

Revise el volumen antiguo:

docker volume ls | grep orchestrator-mysql-data

Cree uno nuevo:

docker volume create orchestrator-mysql-data-chainguard

Verifíquelo:

docker volume inspect orchestrator-mysql-data-chainguard

7. Cambiar el compose del cliente al volumen nuevo#

Abra docker-compose.client.yml y en el servicio orchestrator-db deje el volumen antiguo comentado y active el nuevo:

volumes:
  # El volumen anterior se conserva como referencia durante la migración:
  # - orchestrator-mysql-data:/var/lib/mysql
  - orchestrator-mysql-data-chainguard:/var/lib/mysql

En la sección volumes: al final del archivo, el volumen nuevo también debe estar activo y el antiguo debe seguir comentado:

volumes:
  # orchestrator-mysql-data:
  #   driver: local

  orchestrator-mysql-data-chainguard:
    driver: local

Compruebe que en environment solo quede lo siguiente:

environment:
  MYSQL_ROOT_PASSWORD: '${MYSQL_PASSWORD}'
💡 Por qué esto es importante

Para el nuevo contenedor de MariaDB en Chainguard, es más seguro usar una sola contraseña de root sin la combinación heredada MYSQL_ALLOW_EMPTY_PASSWORD ni usuarios bootstrap adicionales. Esto elimina puntos extra de fallo en un volumen vacío.

8. Levantar el nuevo contenedor de MariaDB#

docker compose --profile mariadb up -d orchestrator-db

Revise los logs:

docker logs -f --tail=100 orchestrator-db

Compruebe que esté listo para consultas:

docker exec orchestrator-db sh -lc 'mariadb -uroot -p"$MYSQL_ROOT_PASSWORD" -Nse "SELECT 1;"'

Resultado esperado:

1

9. Restaurar la copia de seguridad en el nuevo contenedor#

docker exec -i orchestrator-db sh -lc 'mariadb \
  -uroot \
  -p"$MYSQL_ROOT_PASSWORD"' < "$DB_BACKUP_FILE"

10. Verificar las bases de datos y la configuración#

Confirme que ambas bases de datos estén presentes:

docker exec orchestrator-db sh -lc 'mariadb -uroot -p"$MYSQL_ROOT_PASSWORD" -Nse "SHOW DATABASES LIKE '\''orchestrator'\'';"'

docker exec orchestrator-db sh -lc 'mariadb -uroot -p"$MYSQL_ROOT_PASSWORD" -Nse "SHOW DATABASES LIKE '\''orchestrator_archive'\'';"'

Revise consultas de prueba:

docker exec orchestrator-db sh -lc 'MYSQL_PWD="$MYSQL_ROOT_PASSWORD" mariadb \
  -uroot \
  orchestrator \
  -Nse "SELECT COUNT(*) FROM accounts;"'

docker exec orchestrator-db sh -lc 'MYSQL_PWD="$MYSQL_ROOT_PASSWORD" mariadb \
  -uroot \
  orchestrator \
  -Nse "SELECT COUNT(*) FROM processes;"'

Compruebe que se aplicó el my.cnf personalizado:

docker exec orchestrator-db sh -lc 'MYSQL_PWD="$MYSQL_ROOT_PASSWORD" mariadb \
  -uroot \
  -Nse "SHOW VARIABLES LIKE '\''max_allowed_packet'\'';"'

Si el montaje de configuración está bien conectado, verá el valor actual de backend/config/my.cnf.

11. Volver a levantar la aplicación#

docker compose up -d orchestrator orchestrator-websocket orchestrator-nginx

Si es necesario, inicie servicios adicionales:

docker compose up -d orchestrator-vnc-proxy
docker compose up -d orchestrator-autopilot
docker compose up -d orchestrator-vault

Revise los logs del backend:

docker logs --tail=100 orchestrator

Revise la UI y algunas pantallas de trabajo.

12. Rollback si surge un problema#

Si la nueva MariaDB no funciona correctamente:

  1. Detenga los servicios:
docker compose stop orchestrator orchestrator-nginx orchestrator-websocket orchestrator-db
  1. Restaure el volumen antiguo en docker-compose.yml:
volumes:
  - orchestrator-mysql-data:/var/lib/mysql
  1. Levante la versión antigua y comprobada de la imagen de MariaDB que originalmente funcionaba con el volumen.
  2. Vuelva a iniciar los contenedores:
docker compose --profile mariadb up -d orchestrator-db
docker compose up -d orchestrator orchestrator-websocket orchestrator-nginx

13. Qué se puede eliminar después de una migración exitosa#

No elimine de inmediato lo siguiente después del cambio:

  • la copia de seguridad SQL;
  • el volumen antiguo;
  • los archivos de imagen antiguos.

Después de un período de observación, el volumen antiguo puede eliminarse:

docker volume rm orchestrator-mysql-data

Hágalo solo después de una verificación completa.