Administration de la solution de Datachain

L’objectif de ce chapitre est de présenter les outils (basiques) qui permettent d’effectuer les opérations courantes d’administration de la plateforme et notamment démarrage/arrêt de la solution, ainsi que sauvegarde et restauration.

Description de l’arborescence et des scripts mis à disposition

Lors d’un déploiement de Datachain Core selon les méthodes de déploiement proposé par Adobis, nous mettons à disposition un ensemble de scripts shell, qui vont permettre de gérer les services déployés, quelle que soit la granularité des stacks déployées.

A NOTER

Les scripts proposés sont des scripts permettant de faciliter le déploiement de la solution. Ils peuvent être librement adaptés par vos soins, ne sont pas soumis à licence.

A l’opposé, ces scripts ne sont pas soumis à garantie.

Dans la suite de ce chapitre, nous utiliserons les chemins standards proposés par Adobis pour le produit.

L’arborescence suivante est déployée sur tous les noeuds du cluster :

.
└── opt
    ├── adobis
    ├── products  // contient les scripts, fichier de configuration des différentes stacks
    │   ├── stack1
    │   └── stack2  // identique en terme d'arborescence globale
    ├── data  // contient les données des différents modules
    │   └── stack1  // répertoire de données de l'application
    │       └── xxx  // répertoire de données d'un service pour l'application
    └── logs  // contient les fichiers de log

Les scripts suivants sont déployés sur le noeud master du cluster :

.
└── opt
    ├── adobis
    └── products  // contient les scripts, fichier de configuration des différentes stacks
        └── stack1
            ├── shared  // scripts et éléments utilisés pas les scripts start, stop,...
            ├── previous_stacks_version  // historisation des certains éléments.
            ├── start.sh  // script de démarrage de la stack
            ├── stop.sh  // script d'arret de la stack
            ├── restart.sh  // script d'arrêt puis redémarrage de la stack
            ├── runStack.sh  // script utilisé par les scripts start, stop, restart
            ├── *.env  // configuration d'un service particulier (exemple : backend.env pour la configuration du backend de Datachain)
            ├── .env.harbor  // clés de la registry Harbor Adobis
            ├── .env.platform  // paramétrage globale (URL racine), utilisées dans les autres fichiers env ou le fichier docker-compose.
            ├── .env.global  // permet de spécifier le nom de la stack, ainsi que les réseaux dont cette stack est 'propriétaire'. Pour ce dernier point, le réseau est créée par le script de démarrage ou de redémarrage lors du lancement de la stack, si celui-ci n'existe pas encore.
            ├── .env.local  // contient potentiellement l'URL de Traefik, utilisées dans le fichier docker-compose.
            └── docker-compose-${stack-name} // Descripteur de déploiement de la stack ${stack-name}

Les fichiers .env.* présentés ci-dessus ne sont pas obligatoires. Ils peuvent être regroupées en un seul, en conservant le nom d’un des fichiers (i.e. tous les paramètres peuvent être regroupés dans un unique fichier '.env.local')

Ci-dessous un tableau avec les variables utilisées habituellement :

Paramètre	description
HARBOR_REGISTRY	Nom du registre ou récupérer les images docker
HARBOR_USER	Nom de l’utilisateur du registre si authentification
HARBOR_KEY	Clé de l’utilisateur du registre si authentification
DOCKER_NETWORKS	Réseau dont est propriétaire la(es) stack(s). Le réseau sera créé automatique si non existant. (D’un point de vue docker swarm, nous créant un réseau overlay encrypté, non attachable.)
STACKS_NAMES	Nom de la / des stack(s) séparé par des espaces. Si STACKS_NAMES=dc, alors le répertoire de déploiement doit contenir un fichier docker-compose-dc.yml. Il doit y avoir autant de fichiers docker-compose-xxx.yml que de stacks.
DOCKER_NETWORKS	Réseau dont est propriétaire la(es) stack(s). Le réseau sera créé automatique si non existant. (D’un point de vue docker swarm, nous créant un réseau overlay encrypté, non attachable.)
ADDITIONALS_COMPOSE_FILE_NAMES	Dans le cas où il y a une seule stack, mais plusieurs fichiers dockers compose, fin de nom de fichier à utiliser pour ajouter les fichiers docker-compose additionnel. Par exemple, la description du service Redis a été externalisée dans un fichier docker-compose-redis.yml, alors il est possible déclarer : ADDITIONALS_COMPOSE_FILE_NAMES=redis Les fichiers dockers-compose-STACK_NAME et docker-compose-redis.yml seront utilisés lors du démarrage de la stack.
*_URL	Externalisation des URLs pour le reverse-proxy traefik, utilisée par le(s) fichier(s) docker-compose-xxx.yml

Paramètre

description

HARBOR_REGISTRY

Nom du registre ou récupérer les images docker

HARBOR_USER

Nom de l’utilisateur du registre si authentification

HARBOR_KEY

Clé de l’utilisateur du registre si authentification

DOCKER_NETWORKS

Réseau dont est propriétaire la(es) stack(s). Le réseau sera créé automatique si non existant. (D’un point de vue docker swarm, nous créant un réseau overlay encrypté, non attachable.)

STACKS_NAMES

Nom de la / des stack(s) séparé par des espaces. Si STACKS_NAMES=dc, alors le répertoire de déploiement doit contenir un fichier docker-compose-dc.yml. Il doit y avoir autant de fichiers docker-compose-xxx.yml que de stacks.

DOCKER_NETWORKS

Réseau dont est propriétaire la(es) stack(s). Le réseau sera créé automatique si non existant. (D’un point de vue docker swarm, nous créant un réseau overlay encrypté, non attachable.)

ADDITIONALS_COMPOSE_FILE_NAMES

Dans le cas où il y a une seule stack, mais plusieurs fichiers dockers compose, fin de nom de fichier à utiliser pour ajouter les fichiers docker-compose additionnel. Par exemple, la description du service Redis a été externalisée dans un fichier docker-compose-redis.yml, alors il est possible déclarer :

ADDITIONALS_COMPOSE_FILE_NAMES=redis

Les fichiers dockers-compose-STACK_NAME et docker-compose-redis.yml seront utilisés lors du démarrage de la stack.

*_URL

Externalisation des URLs pour le reverse-proxy traefik, utilisée par le(s) fichier(s) docker-compose-xxx.yml

Démarrage et arrêt d’une stack

Le démarrage s’effectue en effectuant la commande shell suivante :

bash start.sh

L’arrêt s’effectue en effectuant la commande shell suivante :

bash stop.sh

Le redémarrage s’effectue en effectuant la commande suivante :

bash restart.sh

Cas du changement de version

En cas de changement de version de la stack, ou de premier lancement, il est possible de spécifier la version dans la ligne de commande en utilisant le sélecteur '-v' suivi du numéro de version à déployer.

bash start.sh -v 8.6.0

bash restart.sh -v 8.6.0

Ordre de démarrage des éléments de la solution déployée

Certains services nécessitent que d’autres soient déjà présents pour être opérationnels. Ci-dessous un ordre de démarrage proposé pour les différentes stacks. Selon votre propre architecture et votre propre déploiement, certaines stacks sont peut-être regroupées. De fait, celles présentées ci-dessous le sont avec un découpage standard.

Traefik : en tant que reverse proxy, aucune application ne sera accessible sans de déploiement de cette stack. L’absence de la stack traefik n’entraine pas de dysfonctionnement applicatif. Les autres applications ne sont juste pas accessibles depuis un navigateur.
Keycloak : lorsque la stack keycloak est déployée et non démarré, certains modules de la stack datachain ne peuvent pas démarrer, car utilisant des informations de sécurité issues de cette stack.
Cluster Spark : Dans le cadre du déploiement d’un cluster spark, celui-ci doit être opérationnel avant lancement de la stack Datachain et la stack Datachain devra être redémarrée si le cluster est redémarré. Dans le cas contraire, les contextes Spark de Datachain ne seront pas opérationnels.
Datachain : Dernier module à démarrer.

L’ordre d’arrêt des composants est l’ordre inverse de celui de démarrage.

Description des stacks

L’objectif est de décrire les informations/fichiers spécifiques à la stack

Traefik

De manière générale, pas de fichier complémentaire dédié d’environnement.

Keycloak

Un fichier complémentaire : keycloak.env. Configuration complète ici.

Datachain

Fichiers complémentaires :

Fichier	Service concerné
web_ui.env	Configuration du module web_ui présentée ici.
backend.env	Configuration du module web_ui présentée ici.
spark.env	Configuration du module web_ui présentée ici.

Fichier

Service concerné

web_ui.env

Configuration du module web_ui présentée ici.

backend.env

Configuration du module web_ui présentée ici.

spark.env

Configuration du module web_ui présentée ici.

Sauvegarde et Restauration

Le tableau suivant présente les éléments à sauvegarder pour les modules Datachain Core. Nous conseillons d’effectuer des sauvegardes à froid, avec au préalable arrêt des services utilisant les éléments à sauvegarder.

Module	Eléments à sauvegarde
pg	Sauvegarde de la base de donnée 'adobis'
pg_expose	Sauvegarde de la base de donnée 'expose'
pg_keycloak	Sauvegarde de la base de donnée 'keycloak'
pg_all	Sauvegarde des bases de données : adobis, keycloak, dc_console, data_view, expose (suivant les modules utilisés)
spark	Sauvegarde du système de fichier HDFS

Module

Eléments à sauvegarde

Sauvegarde de la base de donnée 'adobis'

pg_expose

Sauvegarde de la base de donnée 'expose'

pg_keycloak

Sauvegarde de la base de donnée 'keycloak'

pg_all

Sauvegarde des bases de données : adobis, keycloak, dc_console, data_view, expose (suivant les modules utilisés)

spark

Sauvegarde du système de fichier HDFS

Procédure de sauvegarde/restauration d’une base de donnée

Les serveurs de bases de données Datachain Core sont des serveurs postgreSQL. Pour plus d’information sur les procédures de sauvegarde/restauration, merci de consulter la documentation en ligne : https://www.postgresql.org/docs/current/app-pgdump.html & https://www.postgresql.org/docs/current/app-pgrestore.html.

Dans le cas d’une base de données conteneurisées, nous proposons ci-dessous deux méthodes permettant d’effectuer les sauvegardes/ restaurations.

Pour les sauvegardes/restaurations, les commandes sont à effectuer sur les machines(worker docker) ou se trouvent effectivement les conteneurs.

Avec utilisation d’un volume de sauvegarde

Un volume de sauvegarde est monté sur le service postgresSQL (pg, pg_all, etc.) sous-jacent. Par exemple

  dc_pg:
    image: ${HARBOR_REGISTRY}/dc/pg:${PRODUCT_VERSION}
    # ...
    volumes:
        - /opt/adobis/data/datachain/pg:/var/lib/postgresql/data # Volume Standard
        - /opt/adobis/data/backup/datachain/pg:/pg_dump # Volume de sauvegarde
    # ...

Pour les commandes ci-dessous, le nom de la stack Datachain est dc, et la base de donnée à sauvegarder est adobis.

Sauvegarde

docker exec -t $(docker ps -qf "name=dc_dc_pg\\.") pg_dump -U postgres --format=c --blobs --clean --create adobis -f /pg_dump/$(date +"%Y-%m-%d")_pg_dc_dump.dump

Cette commande génère dans le répertoire /pg_dump (et donc dans /opt/adobis/data/backup/datachain/pg sur le serveur) un fichier contenant la <DateDump au format AAAA-MM-JJ>_pg_dc_dump.dump.

Restauration

Le fichier de sauvegarde est le fichier 20240924_pg_dc_dump.dump. La commande de restauration sera la suivante :

echo "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = 'adobis';" | docker exec -i $(docker ps -qf "name=dc_pg\\.") /usr/bin/psql -U postgres && docker exec -t $(docker ps -qf "name=dc_dc_pg\\.") pg_restore -U postgres -c -C -d postgres /pg_dump/20240924_pg_dc_dump.dump

Absence de volume de sauvegarde

Sauvegarde

Dans ce cas, le script va d’abord effectuer le dump postgres, puis procéder à sa copie vers le répertoire de stockage final.

docker exec -t $(docker ps -qf "name=dc_dc_pg\\.") pg_dump -U postgres --format=c --blobs --clean --create adobis -f /tmp/pg_dc_dump.dump && docker cp $(docker ps -qf "name=dc_dc_pg\\."):/tmp/pg_dc_dump.dump /tmp/$(date +"%Y-%m-%d")_pg_dc_dump.dump && docker exec -t $(docker ps -qf "name=dc_dc_pg\\.") rm /tmp/pg_dc_dump.dump

Cette commande génère dans le répertoire /tmp du serveur un fichier contenant la <DateDump au format AAAA-MM-JJ>_pg_dc_dump.dump.

Restauration

Le fichier de sauvegarde est le fichier 20240924_pg_dc_dump.dump. La commande de restauration sera la suivante :

docker cp 20240924_pg_dc_dump.dump $(docker ps -qf "name=dc_dc_pg\\."):/tmp/adobis.dump && echo "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = 'adobis';" | docker exec -i $(docker ps -qf "name=dc_pg\\.") /usr/bin/psql -U postgres && docker exec -t $(docker ps -qf "name=dc_dc_pg\\.") pg_restore -U postgres -c -C -d postgres /tmp/adobis.dump && docker exec -t $(docker ps -qf "name=dc_dc_pg\\.") rm /tmp/adobis.dump

Procédure de sauvegarde/restauration HDFS

Dans la version actuelle de Datachain, le système de fichier HDFS est divisé en deux répertoires input et output. Le répertoire output contient essentiellement les éléments produits par les pipelines de traitement, les publications, ainsi que le cache (persistances notamment). De fait, le répertoire output peut devenir très vite volumineux.

Hors backup logiciel, d’autres technologies (hors scope de cette documentation) permettent de faire des backups de système de fichiers (snapshot de vm, réplication de disques, …). Il peut être plus approprié d’adapter ce type de sauvegarde, plutôt que les sauvegardes proposées ci-dessous.

Sans cluster HDFS

Dans le cas de contexte spark sans cluster Spark/Hadoop, les fichiers sont directement accessibles dans le volume docker. Il suffit donc juste de procéder à la sauvegarde du répertoire.

  dc_spark1:
    image: ${HARBOR_REGISTRY}/dc/spark:${PRODUCT_VERSION}
    # ...
    volumes:
        - /opt/adobis/data/datachain/hdfs:/data # Volume Standard
    # ...

Dans le cas ci-dessus, il faudra donc procéder à une sauvegarde du répertoire /opt/adobis/data/datachain/hdfs, sur chaque machine sur lequel se trouve un contexte Spark.

Avec cluster HDFS

Dans le cas de contexte spark avec cluster Spark/Hadoop, Hadoop met nativement en œuvre un système de réplication de données sur tous les nœuds du cluster. Il parait peu opportun d’utiliser des techniques standard de sauvegarde.

En cas de besoin d’une mise en œuvre d’une procédure de sauvegarde logicielle, merci de suivre les préconisations Hadoop sur le sujet.