Exécuter le connecteur à l'aide d'une image Docker

Modifié le : Mer, 8 Janv., 2025 à 5:59 H

Note : pour suivre cette documentation, des connaissances sur le fonctionnement de Docker et la construction d'images de conteneurs sont nécessaires.

Le connecteur Desktop peut être exécuté en ligne de commande via l'utilisation d'une image Docker.

La configuration nécessaire pour l'exécution de l'image sera la même que celle du connecteur desktop, elle est détaillée dans la page suivante : Configuration requise. Il sera bien sûr nécessaire d'y ajouter un client ou un orchestrateur Docker de votre choix.

Le connecteur Desktop est un programme Java. Aussi, nous partirons d'une image de base offrant un environnement d'exécution Java correspondant aux prérequis du connecteur Desktop.

Sur cette image de base, 4 types de ressources devront être ajoutées :

Le dossier du connecteur Desktop, issu de l'archive zip décompressée
Les plugins du connecteur selon vos technologies
Le(s) fichier(s) de configuration de vos connexions (fichiers .properties qui sont créés lors de la sauvegarde de paramètres de connexion dans le connecteur Desktop en mode GUI, dans le dossier connection/)
Le(s) fichier(s) contenant vos jetons d'accès à l'API DataGalaxy (sauf si vous souhaitez les passer en arguments à l'exécution, ce que nous ferons dans cet exemple).

Pour le connecteur Desktop et les plugins, vous pouvez les télécharger depuis votre plateforme DataGalaxy, ou bien de manière programmatique en suivant cette documentation (notamment si vous souhaitez automatiser la construction de vos images de manière régulière afin de les tenir à jour).

Construction de l'image Docker connector-cli

Comme pour toute image Docker, vous pouvez inclure les fichiers nécessaires lors de la construction de l'image afin qu'elle soit autonome, ou bien utiliser des points de montage ou volumes. Libre à vous, selon votre contexte et vos contraintes, de choisir ce que vous souhaitez embarquer dans l'image. Dans cette documentation, nous choisissons d'embarquer le connecteur et ses plugins (dans l'exemple : Databricks) dans l'image et d'utiliser les points de montage pour les fichiers de configuration.

Comme nous embarquons le JRE open source Temurin dans le zip de notre connecteur, nous nous baserons également sur l'image Temurin image pour construire notre image connector-cli.

Dans cet exemple, nous construisons notre image Docker sous un environnement Linux. Nous nous plaçons dans un répertoire de travail créé pour l'occasion.

Note : ce document décrit une manière fonctionnelle d'obtenir une image Docker pour l'exécution du connecteur. Libre à vous d'adapter les scripts en fonction de votre besoin et de vos contraintes.

Variables d'environnement

Nous commençons par définir quelques variables d'environnement qui nous seront utiles pour la suite :

Notre token d'accès à l'API DataGalaxy
Notre mot de passe d'accès à notre système (ici un token Databricks)
L'URL de l'API de notre environnement DataGalaxy (voir le guide de l'API)
Le nom du Workspace DataGalaxy dans lequel nous souhaitons envoyer les métadonnées.

$ export DG_TOKEN=ey...
$ export DATABRICKS_PWD=xy...
$ export DG_API_URL=https://myinstance.api.datagalaxy.com/v2
$ export WS="MyWorkspace"

Préparation des fichiers nécessaires

Nous préparons les fichiers suivants :

Fichiers .properties de paramétrage des connexions à nos systèmes (ici Databricks) :
- Pour l'exemple, ceci est représenté par la commande vi. Cependant, de votre côté, vous copierez plutôt ces fichiers depuis le dossier connection/ d'un connecteur Desktop, suite à la sauvegarde de profils de connexions en mode GUI
Fichiers .jar d'exécution du connecteur Desktop en mode CLI, que nous récupérerons dans l'archive zip téléchargée grâce à l'API DataGalaxy des connecteurs
Fichiers .jar de plugins récupérés par la même API.

Les fichiers que nous souhaitons embarquer dans l'image Docker sont mis dans un sous-dossier connector-cli/ prévu à cet effet, alors que les fichiers de paramétrage des connexions seront rangés dans un autre sous-dossier connection/.

$ mkdir connection
$ vi connection/databricks-sql.properties
$
$ mkdir desktop-connector
$ curl -H "Authorization: Bearer $DG_TOKEN" -O "$DG_API_URL/connectivity/packages/desktop/latest/64bits.zip"
$ unzip -d dg-connector 64bits.zip
$
$ mkdir -p connector-cli/dg-connector
$ cp dg-connector/datagalaxy-cli-connector.jar connector-cli/dg-connector
$ cp -r dg-connector/lib connector-cli/dg-connector
$ cp -r dg-connector/conf connector-cli/dg-connector
$
$ mkdir connector-cli/plugins
$ curl -H "Authorization: Bearer $DG_TOKEN" -o connector-cli/plugins/databricks.jar "$DG_API_URL/connectivity/packages/databricks/latest/contents.jar"

Tests du mode cli

Afin de s'assurer du bon fonctionnement du connecteur en mode CLI avant de construire notre image, nous pouvons effectuer quelques tests depuis le dossier connector-cli/.

Nous vérifions :

Que notre version de Java est compatible avec les prérequis du connecteur (nous n'aurons pas besoin de cela pour l'image Docker car nous choisirons notre image de base en fonction des prérequis)
Que l'appel de l'option --version du connecteur CLI nous retourne bien la version du connecteur que nous avons téléchargée
Que l'appel de l'option plugins du connecteur CLI liste l'ensemble des plugins que nous avons téléchargés
Que le connecteur en mode CLI fonctionne correctement pour importer des métadonnées depuis notre système (ici Databricks) et les pousser dans notre plateforme DataGalaxy.

$ cd connector-cli
$ CWD=$(dirname $0)
$ java -version
$ java -classpath "$CWD/datagalaxy-cli-connector.jar:$CWD/lib/*:$CWD/plugins/*" \
   --add-opens=java.base/java.nio=ALL-UNNAMED  \
   com.datagalaxy.connector.desktop.cli.Main --version
$ java -classpath "$CWD/datagalaxy-cli-connector.jar:$CWD/lib/*:$CWD/plugins/*"  \
   --add-opens=java.base/java.nio=ALL-UNNAMED  \
   com.datagalaxy.connector.desktop.cli.Main plugins
$ java -classpath "$DIR/datagalaxy-cli-connector.jar:$DIR/lib/*:$DIR/plugins/*" \
   -Ddatagalaxy.configurationPath="$DIR/conf" \
   --add-opens=java.base/java.nio=ALL-UNNAMED  \
   com.datagalaxy.connector.desktop.cli.Main \
   import-api \
      --config ../connection/databricks-sql.properties \
      --server-url "$DG_API_URL" \
      --project-name "$WS" \
      --source-name "Databricks" \
      --create-source \
      --password "$DATABRICKS_PWD" \
      --token-value "$DG_TOKEN"

Note : l'ensemble des arguments que vous pouvez passer au connecteur en mode CLI est disponible dans cette documentation.

Construction de l'image

Maintenant que nous sommes assurés du bon fonctionnement du connecteur en mode CLI, nous pouvons intégrer tout cela dans une image Docker.

Pour plus de praticité dans l'usage de cette image, nous créons dans le dossier connector-cli/ un fichier entrypoint.sh qui contiendra la ligne de commande de lancement du connecteur CLI. Voici le contenu de ce fichier :

#!/bin/sh

java $JAVA_OPTS $JAVA_EXTRA_OPTS \
  -classpath "datagalaxy-cli-connector.jar:lib/*:plugins/*" \
  com.datagalaxy.connector.desktop.cli.Main "$@"

Nous créons ensuite le fichier Dockerfile qui permettra de construire notre image, basée sur l'image Open JDK Temurin Alpine et proposant la version de Java compatible avec le connecteur. Voici le contenu de ce fichier :

FROM eclipse-temurin:17-jre-alpine

RUN addgroup -g 1001 datagalaxy && adduser -D -G datagalaxy -u 1001 datagalaxy

COPY conf/* /etc/datagalaxy-connector/
COPY lib/* /opt/datagalaxy-connector/lib/
COPY plugins/* /opt/datagalaxy-connector/plugins/
COPY datagalaxy-cli-connector.jar /opt/datagalaxy-connector/
COPY entrypoint.sh /opt/datagalaxy-connector/
RUN chmod a+x /opt/datagalaxy-connector/entrypoint.sh

USER datagalaxy
WORKDIR /opt/datagalaxy-connector

ENV DIR=/opt/datagalaxy-connector
ENV JAVA_OPTS="--add-opens=java.base/java.nio=ALL-UNNAMED --add-opens=java.base/jdk.internal.misc=ALL-UNNAMED -Dio.netty.tryReflectionSetAccessible=true --illegal-access=warn -Dlogback.configurationFile=/etc/datagalaxy-connector/logback.xml -Ddatagalaxy.configurationPath=/etc/datagalaxy-connector -Dlog4j2.formatMsgNoLookups=true"
ENTRYPOINT ["./entrypoint.sh"]
CMD ["--version"]

Nous avons donc maintenant tous les éléments nécessaires à la construction de l'image :

$ ls
conf  datagalaxy-cli-connector.jar  Dockerfile  entrypoint.sh  lib  plugins

Nous pouvons lancer la construction de l'image :

$ docker build -t connector-cli:latest .

Tests de l'image

Comme nous l'avons fait pour le connecteur CLI, validons maintenant que l'image fonctionne comme souhaité.

Nous effectuons les tests suivants :

Vérification que l'exécution de l'image renvoie bien la version embarquée du connecteur
Vérification que la commande plugins liste bien les plugins embarqués
Vérification complète de l'exécution d'un import de métadonnées depuis notre système (Databricks) vers DataGalaxy.

$ cd ..
$ docker run --rm connector-cli:latest
$ docker run --rm connector-cli:latest plugins
$ docker run --rm \
   -v "./connection:/etc/datagalaxy-connector/connection" \
   connector-cli:latest \
   import-api \
      --config /etc/datagalaxy-connector/connection/databricks-sql.properties \
      --server-url "$DG_API_URL" \
      --project-name "$WS" \
      --source-name "Databricks" \
      --create-source \
      --password "$DATABRICKS_PWD" \
      --token-value "$DG_TOKEN"

Note : pour passer les fichiers .properties des connexions au conteneur, nous utilisons un point de montage puis faisons pointer la configuration (--config) vers le chemin du fichier concerné dans le conteneur. Vous pourriez avoir besoin d'autres points de montage, par exemple pour les fichiers de sortie si vous utilisez la commande import-csv ou pour passer votre fichier de token d'API DataGalaxy au conteneur. A vous d'ajuster ce modèle selon si vous préférez n'utiliser qu'un point de montage ou plusieurs, ou d'autres modifications que vous souhaiteriez apporter pour adapter cela à votre contexte.

Note : grâce à la commande que nous avons configurée dans notre entrypoint.sh, les arguments que vous passez à l'exécution de votre conteneur sont directement passés au connecteur CLI, donc la liste des arguments est identique (à la différence près du chemin du fichier .properties comme expliqué ci-desus).

Note : vous avez pu remarqué que nous avons ajouté une variable JAVA_EXTRA_OPTS dans notre entrypoint.sh, que nous n'avons pas utilisée. C'est grâce à cette variable que vous pourrez passer des options supplémentaires au conteneur, par exemple lui allouer une quantité de mémoire spécifique, comme expliqué dans les questions fréquentes de la documentation du connecteur CLI. Vous utiliseriez par exemple l'option -e du client Docker pour passer une valeur à cette variable.

Script complet

$ export DG_TOKEN=ey...
$ export DATABRICKS_PWD=xy...
$ export DG_API_URL=https://myinstance.api.datagalaxy.com/v2
$ export WS="MyWorkspace"
$
$ mkdir connection
$ vi connection/databricks-sql.properties
$
$ mkdir desktop-connector
$ curl -H "Authorization: Bearer $DG_TOKEN" -O "$DG_API_URL/connectivity/packages/desktop/latest/64bits.zip"
$ unzip -d dg-connector 64bits.zip
$
$ mkdir -p connector-cli/dg-connector
$ cp dg-connector/datagalaxy-cli-connector.jar connector-cli/dg-connector
$ cp -r dg-connector/lib connector-cli/dg-connector
$ cp -r dg-connector/conf connector-cli/dg-connector
$
$ mkdir connector-cli/plugins
$ curl -H "Authorization: Bearer $DG_TOKEN" -o connector-cli/plugins/databricks.jar "$DG_API_URL/connectivity/packages/databricks/latest/contents.jar"
$
$ cd connector-cli
$ CWD=$(dirname $0)
$ java -version
$ java -classpath "$CWD/datagalaxy-cli-connector.jar:$CWD/lib/*:$CWD/plugins/*" \
   --add-opens=java.base/java.nio=ALL-UNNAMED  \
   com.datagalaxy.connector.desktop.cli.Main --version
$ java -classpath "$CWD/datagalaxy-cli-connector.jar:$CWD/lib/*:$CWD/plugins/*"  \
   --add-opens=java.base/java.nio=ALL-UNNAMED  \
   com.datagalaxy.connector.desktop.cli.Main plugins
$ java -classpath "$DIR/datagalaxy-cli-connector.jar:$DIR/lib/*:$DIR/plugins/*" \
   -Ddatagalaxy.configurationPath="$DIR/conf" \
   --add-opens=java.base/java.nio=ALL-UNNAMED  \
   com.datagalaxy.connector.desktop.cli.Main \
   import-api \
      --config ../connection/databricks-sql.properties \
      --server-url "$DG_API_URL" \
      --project-name "$WS" \
      --source-name "Databricks" \
      --create-source \
      --password "$DATABRICKS_PWD" \
      --token-value "$DG_TOKEN"
$ 
$ vi entrypoint.sh
$ vi Dockerfile
$ docker build -t connector-cli:latest .
$
$ cd ..
$ docker run --rm connector-cli:latest
$ docker run --rm connector-cli:latest plugins
$ docker run --rm \
   -v "./connection:/etc/datagalaxy-connector/connection" \
   connector-cli:latest \
   import-api \
      --config /etc/datagalaxy-connector/connection/databricks-sql.properties \
      --server-url "$DG_API_URL" \
      --project-name "$WS" \
      --source-name "Databricks" \
      --create-source \
      --password "$DATABRICKS_PWD" \
      --token-value "$DG_TOKEN"

Fichier entrypoint.sh

#!/bin/sh

java $JAVA_OPTS $JAVA_EXTRA_OPTS \
  -classpath "datagalaxy-cli-connector.jar:lib/*:plugins/*" \
  com.datagalaxy.connector.desktop.cli.Main "$@"

Fichier Dockerfile

FROM eclipse-temurin:17-jre-alpine

RUN addgroup -g 1001 datagalaxy && adduser -D -G datagalaxy -u 1001 datagalaxy

COPY conf/* /etc/datagalaxy-connector/
COPY lib/* /opt/datagalaxy-connector/lib/
COPY plugins/* /opt/datagalaxy-connector/plugins/
COPY datagalaxy-cli-connector.jar /opt/datagalaxy-connector/
COPY entrypoint.sh /opt/datagalaxy-connector/
RUN chmod a+x /opt/datagalaxy-connector/entrypoint.sh

USER datagalaxy
WORKDIR /opt/datagalaxy-connector

ENV DIR=/opt/datagalaxy-connector
ENV JAVA_OPTS="--add-opens java.base/jdk.internal.misc=ALL-UNNAMED -Dio.netty.tryReflectionSetAccessible=true --illegal-access=warn -Ddatagalaxy.configurationPath=/etc/datagalaxy-connector -Dlog4j2.formatMsgNoLookups=true"
ENV JAVA_EXTRA_OPTS=""
ENTRYPOINT ["./entrypoint.sh"]
CMD ["--version"]

Questions fréquentes

Configuration d'un proxy

Il est possible de configurer un proxy directement via le client Docker en utilisant un fichier `~/.docker/config.json`.

Afin d'en savoir plus, nous vous invitons à consulter la documentation officielle : https://docs.docker.com/network/proxy/#configure-the-docker-client

French