Configuration du conteneur Agent Snowflake Connector for MySQL¶

Sélection d’un système d’orchestration de conteneur¶

L’agent est conditionné sous forme d’image de conteneur Docker standard et peut être exécuté sur n’importe quel système d’orchestration prenant en charge la norme. Il peut s’agir d’une instance Docker autonome, de Kubernetes, de RedHat OpenShift, d’une solution gérée dans le cloud telle que AWS Fargate ou d’autres solutions. Votre entreprise disposera souvent d’un système existant privilégié que vous pourrez utiliser.

Faites attention à la section Configuration de l’agent de ce document, car des systèmes d’orchestration différents entraînent des contraintes différentes. Il se peut que votre système ou votre configuration spécifique ne permette pas de monter des volumes accessibles en écriture (comme cela est requis avec l’option de configuration principale de l’agent).

Les exemples ultérieurs se concentreront sur Kubernetes comme système d’orchestration le plus populaire. L’approche sera souvent similaire dans d’autres systèmes et vous devrez ajuster les exemples à votre configuration.

Confirmer les ressources système requises¶

• L’agent est une application gourmande en mémoire et nécessite un minimum de 6GB de RAM pour pouvoir fonctionner correctement.

• Le nombre optimal de CPUs est de 4. Un nombre de CPUs inférieur peut diminuer les performances. Un nombre de CPUs supérieur n’améliorera pas les performances.

Configurer la connectivité¶

L’agent doit se connecter à chaque base de données source à partir de laquelle vous prévoyez de lire des données. Configurez votre réseau et vos pare-feu afin de permettre les connexions directes et afin que le port client standard de MySQL soit accessible. Il s’agit généralement du port 3306. Pour plus d’informations, voir Tableaux de références des ports de MySQL.

Si vos bases de données sources résident sur des réseaux isolés et qu’il n’est pas possible de se connecter à partir d’un seul agent, vous devrez installer des instances supplémentaires de l’application native du connecteur, chacune avec son propre agent. Cette fonctionnalité est actuellement proposée en avant-première privée. Pour demander l’accès, contactez l”Assistance Snowflake.

L’agent se connecte également directement à votre déploiement Snowflake. Pour plus d’informations sur les noms d’hôte qui doivent être disponibles, voir Autorisation des noms d’hôte.

Si l’une des connexions de l’agent passe par un proxy, vous devrez transmettre une configuration supplémentaire à l’agent. Voir Examiner les variables d’environnement de configuration facultatives.

Télécharger le pilote MariaDB JDBC¶

L’agent utilise ce pilote pour se connecter aux bases de données MySQL et interagir avec elles. Bien qu’il s’agisse d’un pilote nommé pour MariaDB, elles sont compatibles avec lui.

En raison de limitations de licence, le pilote JDBC ne peut pas être distribué avec l’agent et vous devrez le fournir. Téléchargez le connecteur MariaDB JDBC 3.4.1 et enregistrez-le dans un répertoire à partir duquel vous pouvez le monter dans le conteneur de l’agent.

[Facultatif] Obtenir et préparer des certificats SSL pour les bases de données sources¶

Lorsque l’agent se connecte aux bases de données sources via SSL, il nécessite leurs certificats pour valider les connexions. Ces certificats doivent être disponibles dans Java Truststore à l’intérieur du conteneur de l’agent, sous le chemin d’accès /opt/java/openjdk/lib/security/cacerts.

Le moyen le plus simple de fournir des certificats à l’agent est de les ajouter dans le fichier cacerts existant du poste hôte, puis de monter ce fichier dans le conteneur en cours d’exécution.

openssl x509 -outform der -in ca-root.pem -out ca-root.der
keytool -import -alias server-root \
    -keystore $JAVA_HOME/jre/lib/security/cacerrts -file ca-root.der

Préparer la configuration de l’agent¶

L’agent peut être configuré via des variables d’environnement et/ou des fichiers JSON montés dans le conteneur. Les clés d’accès requises pour se connecter à Snowflake peuvent être montées à partir du système de fichiers de l’hôte, fournies sous forme de secrets de conteneur ou de variables d’environnement.

Les sections suivantes décrivent différentes options de configuration, de la plus simple à la plus complète. Adoptez une approche adaptée aux spécificités de votre infrastructure.

{
    "<data_source_name_1>": {
        "url": "jdbc:mariadb://<host>:<port>/[?<key1>=<value1>[&<key2>=<value2>]]",
        "username": "<mysql_db_username>",
        "password": "<mysql_db_password>"
    },
    "<data_source_name_2>": {
        "url": "jdbc:mariadb://<host>:<port>/[?<key1>=<value1>[&<key2>=<value2>]]",
        "username": "<mysql_db_username>",
        "password": "<mysql_db_password>"
    }
}

docker run -d \
   --restart unless-stopped \
   --name database-connector-agent \
   --volume </path/to/ssh/keys/directory>:/home/agent/.ssh \
   --volume </path/to/mariadb/jdbc/jar>:/home/agent/libs/mariadb-jdbc-driver \
   --volume </path/to/snowflake/json/file>:/home/agent/snowflake.json \
   --volume </path/to/datasources/json/file>:/home/agent/datasources.json \
   -m 6g \
   snowflakedb/database-connector-agent:latest

docker run \
  -e SNOWFLAKE_USERNAME="MYSQL_AGENT_USER" \
  -e SNOWFLAKE_APPLICATION_NAME="SNOWFLAKE_CONNECTOR_FOR_MYSQL" \
  -e SNOWFLAKE_ALLOWLIST_0_HOST="example_account.us-west-2.aws.snowflakecomputing.com" \
  -e SNOWFLAKE_ALLOWLIST_0_PORT=443 \
  -e SNOWFLAKE_ALLOWLIST_0_TYPE="SNOWFLAKE_DEPLOYMENT" \
  ...

{
  "userName": "MYSQL_AGENT_USER",
  "applicationName": "SNOWFLAKE_CONNECTOR_FOR_MYSQL",
  "allowlist": [
  {
    "host": "example_account.us-west-2.aws.snowflakecomputing.com",
    "port": 443,
    "type": "SNOWFLAKE_DEPLOYMENT"
  }
  ]
}

docker run \
  -e SNOWFLAKE_USERNAME="CONNECTOR_MYSQL_AGENT" \
  -e SNOWFLAKE_APPLICATION_NAME="CONNECTOR_MYSQL_INSTANCE" \
  -e SNOWFLAKE_ENFORCEDURL="example_account.us-west-2.aws.snowflakecomputing.com:443" \
  ...

docker run \
  -e SNOWFLAKE_DATASOURCES_MYSQLDS1_URL="jdbc:mariadb://example.internal:3306/" \
  -e SNOWFLAKE_DATASOURCES_MYSQLDS1_USERNAME="example_user" \
  -e SNOWFLAKE_DATASOURCES_MYSQLDS1_PASSWORD="example_password" \
  ...

{
    "MYSQLDS1": {
        "url": "jdbc:mariadb://example.internal:3306/",
        "username": "example_user",
        "password": "example_password"
    }
}

Examiner les variables d’environnement de configuration facultatives¶

L’agent prend en charge les paramètres facultatifs suivants, disponibles via la définition de variables d’environnement supplémentaires dans le conteneur :

SNOWFLAKE_PRIVATEKEYPATH

Spécifie le chemin d’accès absolu au fichier contenant la clé privée de l’utilisateur d’agent. Cela est utilisé lors du montage de votre propre clé privée dans le conteneur, généralement via le secret d’un système d’orchestration.

SNOWFLAKE_PRIVATEKEYPASSWORD

Spécifie le mot de passe de la clé privée de l’utilisateur d’agent. Si vous laissez l’agent générer les clés, ce mot de passe sera défini sur la clé privée. Si vous réutilisez des clés existantes, ce mot de passe sera utilisé pour accéder à la clé privée existante.

SNOWFLAKE_PRIVATEKEY

Spécifie le contenu de la clé privée de l’utilisateur d’agent. Cela peut être défini lorsque le montage de la clé privée sous forme de fichier dans le conteneur n’est pas une option.

SNOWFLAKE_ENFORCEDURL

Spécifie l’URL permettant de se connecter à Snowflake, en remplaçant le propre mécanisme de découverte de l’agent. Cela est principalement utilisé pour se connecter à des déploiements PrivateLink.

JAVA_OPTS

Spécifie les paramètres ou propriétés Java supplémentaires qui seront transmis au processus de l’agent.

Les plus couramment utilisés sont :

• L’option -Xmx permettant de définir la taille maximale du Heap Java. Snowflake recommande de définir cette valeur sur la quantité de mémoire disponible pour le conteneur, moins 1GB.

  Par exemple, si le conteneur a 6GB de RAM disponible, définissez les éléments suivants :

  JAVA_OPTS=-Xmx5g
  

  Copy

• Lorsque la connexion de l’agent à Snowflake nécessite un proxy, définissez les éléments suivants :

  JAVA_OPTS=-Dhttp.useProxy=true -Dhttp.proxyHost=<proxy-host> -Dhttp.proxyPort=<proxy-port>
  

  Copy

• Pour contourner le proxy pour certains hôtes ou adresses IP, par exemple, des bases de données sources, définissez la propriété http.nonProxyHosts supplémentaire. Utilisez un symbole de barre verticale (|) pour séparer plusieurs noms d’hôte. Utilisez un astérisque (*) comme caractère générique.

  JAVA_OPTS=-Dhttp.useProxy=true -Dhttp.proxyHost=<proxy-host> -Dhttp.proxyPort=<proxy-port>
    -Dhttp.nonProxyHosts='*.my_company.com|localhost|myorganization-myaccount.snowflakecomputing.com|192.168.91.*'
  

  Copy

• Pour transmettre les identifiants de connexion du proxy, définissez les propriétés système http.proxyUser et http.proxyPassword.

  JAVA_OPTS=-Dhttp.useProxy=true -Dhttp.proxyHost=<proxy-host> -Dhttp.proxyPort=<proxy-port>
    -Dhttp.proxyUser=<proxy-user> -Dhttp.proxyPassword=<proxy-pass>
  

  Copy

Configurer la connectivité PrivateLink¶

Si vous vous connectez à un déploiement PrivateLink, vous devez fournir l’URL pour que l’agent puisse se connecter explicitement en définissant la variable d’environnement SNOWFLAKE_ENFORCEDURL.

Pour déterminer l’URL PrivateLink de votre compte, procédez de l’une des manières suivantes :

• Ouvrez le fichier snowflake.json que vous avez obtenu lors du processus de configuration. Recherchez le tableau nommé allowlistPrivatelink, puis l’entrée avec le type SNOWFLAKE_DEPLOYMENT.

• Utilisez la fonction SYSTEM$GET_PRIVATELINK_CONFIG.

Comprendre les clés d’accès Snowflake¶

L’agent s’authentifie auprès de Snowflake sous forme de compte de service, créé par l’assistant de configuration du connecteur dans Snowsight, à l’aide d’un jeu de clés d’accès. L’assistant de configuration crée des clés d’accès temporaires et ajoute la clé privée au fichier snowflake.json dans un champ nommé temporaryPrivateKey.

Lors de son démarrage initial, l’agent remplace ces clés temporaires comme suit :

1. En générant un nouveau jeu de clés d’accès et en les stockant sous /home/agent/.ssh comme database-connector-agent-app-private-key.p8 et database-connector-agent-app-public-key.pub à l’intérieur du conteneur. Ce répertoire doit être monté sous forme de volume externe accessible en écriture dans le conteneur, afin que les clés persistent lorsque le conteneur s’arrête.

2. En modifiant son compte de service de sorte à utiliser les nouvelles clés.

3. En supprimant le champ temporaryPrivateKey du fichier snowflake.json.

Après le remplacement de clés initial, l’agent ne fait jamais tourner les clés d’accès.

Vous pouvez utiliser les clés générées par l’agent. Ou vous pouvez créer votre propre jeu, modifier le compte de service et fournir la clé privée à l’agent.

L’ordre de découverte de la clé privée de l’agent est le suivant :

1. Toute clé transmise via la variable d’environnement SNOWFLAKE_PRIVATEKEY. Si cette valeur est trouvée, le connecteur ignorera la clé temporaire de snowflake.json.

2. Clés trouvées sur les volumes montés dans /home/agent/.ssh/database-connector-agent-app-private-key.p8. Si ce fichier est trouvé, le connecteur ignorera la clé temporaire de snowflake.json.

3. Valeur du champ temporaryPrivateKey du fichier snowflake.json.

Accès au point de terminaison de contrôle d’intégrité¶

L’agent expose un point de terminaison HTTP contenant des informations d’intégrité. Vous pouvez utiliser ce point de terminaison lors de l’exécution de l’agent dans un système d’orchestration pour déterminer à quel moment l’agent est entièrement lancé et s’il est intègre. Le point de terminaison est disponible sous le port 8080 et le chemin d’accès /actuator/health.

Pour utiliser le point de terminaison comme probe liveness (sonde de vivacité) dans Kubernetes, ajoutez les éléments suivants à la configuration de votre Pod :

apiVersion: v1
kind: Pod
spec:
  containers:
  - ...
    livenessProbe:
      httpGet:
        path: /actuator/health
        port: 8080
      initialDelaySeconds: 5
      periodSeconds: 10