Einstellung des Snowflake Connector for MySQL Agent Container¶

Wählen Sie ein Container-Orchestrierungssystem¶

Der Agent ist als standardmäßiges Docker Container-Image gepackt und kann auf jedem Orchestrierungssystem ausgeführt werden, das diesen Standard unterstützt. Dabei kann es sich um eine eigenständige Docker Instanz, Kubernetes, RedHat OpenShift, eine in der Cloud verwaltete Lösung, wie AWS Fargate, und andere handeln. Ihr Unternehmen hat oft ein bevorzugtes, bereits vorhandenes System, das Sie verwenden können.

Achten Sie auf den Abschnitt zur Konfiguration der Agenten in diesem Dokument, denn verschiedene Orchestrierungssysteme bringen unterschiedliche Einschränkungen mit sich. Ihr System oder Ihre spezielle Konfiguration erlaubt es Ihnen möglicherweise nicht, beschreibbare Volumes einzubinden (wie es die primäre Konfigurationsoption des Agenten verlangt).

Spätere Beispiele werden sich auf Kubernetes als das beliebteste Orchestrierungssystem konzentrieren. Die Vorgehensweise wird in anderen Systemen oft ähnlich sein, und Sie müssen die Beispiele für Ihr System anpassen.

Bestätigen Sie die erforderlichen Ressourcen des Systems¶

• Der Agent ist eine speicherintensive Anwendung und benötigt ein Minimum an 6GB von RAM, um korrekt zu funktionieren.

• Die optimale Anzahl von CPUs ist 4. Weniger CPUs kann die Leistung verringern. Mehr CPUs wird die Leistung nicht verbessern.

Einrichten der Konnektivität¶

Der Agent muss eine Verbindung zu jeder Quelldatenbank herstellen, aus der Sie Daten lesen möchten. Konfigurieren Sie Ihr Netzwerk und Ihre Firewalls so, dass direkte Verbindungen möglich sind und der klassische Client-Port von MySQL erreichbar ist. Normalerweise ist das der Port 3306. Weitere Informationen finden Sie unter MySQL-Port-Referenztabellen.

Wenn sich Ihre Quelldatenbanken in isolierten Netzwerken befinden und eine Verbindung von einem einzigen Agenten aus nicht möglich ist, müssen Sie zusätzliche Instanzen der nativen Anwendung des Konnektors installieren, jede mit ihrem eigenen Agenten. Dieses Feature befindet sich derzeit in der privaten Vorschau. Bitte wenden Sie sich an den Snowflake-Support, um den Zugang anzufordern.

Der Agent stellt auch eine direkte Verbindung zu Ihrer Snowflake-Bereitstellung her. Informationen darüber, welche Hostnamen verfügbar sein müssen, finden Sie unter Zulassen von Hostnamen.

Wenn eine der Verbindungen des Agenten über einen Proxy läuft, müssen Sie zusätzliche Konfigurationen an den Agenten weitergeben. Siehe Überprüfung der optionalen Variablen für die Konfiguration der Umgebung.

Laden Sie den MariaDB JDBC-Treiber herunter¶

Der Agent verwendet diesen Treiber, um eine Verbindung zu MySQL-Datenbanken herzustellen und mit diesen zu interagieren. Obwohl es nominell ein Treiber für MariaDB ist, sind sie kompatibel.

Aufgrund lizenzrechtlicher Beschränkungen kann der JDBC-Treiber nicht zusammen mit dem Agenten vertrieben werden, sondern muss von Ihnen bereitgestellt werden. Laden Sie den MariaDB JDBC Connector 3.4.1 herunter, und speichern Sie ihn in einem Verzeichnis, von dem aus Sie ihn in den Container des Agenten einbinden können.

[Optional] Beziehen Sie SSL-Zertifikate für Quelldatenbanken, und bereiten Sie diese vor¶

Wenn der Agent über SSL eine Verbindung zu Quelldatenbanken herstellt, benötigt er deren Zertifikate, um die Verbindungen zu validieren. Diese Zertifikate müssen im Java Truststore innerhalb des Containers des Agenten verfügbar sein, und zwar unter dem Pfad /opt/java/openjdk/lib/security/cacerts.

Der einfachste Weg, den Agenten mit Zertifikaten zu versorgen, besteht darin, sie der bestehenden Datei cacerts des Hostrechners hinzuzufügen und diese Datei dann in den laufenden Container einzubinden.

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

Konfiguration des Agenten vorbereiten¶

Der Agent kann über in den Container eingebundene JSON-Dateien oder über Umgebungsvariablen oder eine Mischung aus beidem konfiguriert werden. Die für die Verbindung mit Snowflake erforderlichen Schlüssel können vom Dateisystem des Hosts eingebunden, als Container-Geheimnisse oder als Umgebungsvariablen bereitgestellt werden.

In den folgenden Abschnitten werden verschiedene Konfigurationsmöglichkeiten beschrieben, von den einfachsten bis hin zu den umfassendsten. Wählen Sie einen Ansatz, der auf die Besonderheiten Ihrer Infrastruktur abgestimmt ist.

{
    "<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"
    }
}

Überprüfung der optionalen Variablen für die Konfiguration der Umgebung¶

Der Agent unterstützt die folgenden, optionalen Einstellungen, die durch die Einstellung zusätzlicher Umgebungsvariablen auf dem Container verfügbar sind:

SNOWFLAKE_PRIVATEKEYPATH

Gibt den absoluten Pfad zu der Datei mit dem privaten Schlüssel des Benutzers des Agenten an. Dies wird verwendet, wenn Sie Ihren eigenen privaten Schlüssel in den Container einbinden, normalerweise über das Geheimnis eines Orchestrierungssystems.

SNOWFLAKE_PRIVATEKEYPASSWORD

Gibt das Kennwort für den privaten Schlüssel des Benutzers des Agenten an. Wenn Sie den Agenten die Schlüssel generieren lassen, wird dieses Kennwort auf den privaten Schlüssel gesetzt. Wenn Sie vorhandene Schlüssel wiederverwenden, wird dieses Kennwort für den Zugriff auf den vorhandenen privaten Schlüssel verwendet.

SNOWFLAKE_PRIVATEKEY

Gibt den Inhalt des privaten Schlüssels des Benutzers des Agenten an. Dies kann eingestellt werden, wenn das Einbinden des privaten Schlüssels als Datei im Container keine Option ist.

SNOWFLAKE_ENFORCEDURL

Gibt die URL an, um eine Verbindung zu Snowflake herzustellen, wobei der eigene Erkennungsmechanismus des Agenten außer Kraft gesetzt wird. Dies wird hauptsächlich zur Verbindung mit PrivateLink verwendet.

JAVA_OPTS

Gibt zusätzliche Java-Einstellungen oder Eigenschaften an, die an den Prozess des Agenten weitergegeben werden.

Die am häufigsten verwendeten sind:

• Die Option -Xmx, um die maximale Java-Heap-Größe einzustellen. Snowflake empfiehlt, diesen Wert auf den dem Container zur Verfügung stehenden Speicher einzustellen, abzüglich 1GB.

  Wenn der Container beispielsweise über 6GB von RAM verfügt, stellen Sie Folgendes ein:

  JAVA_OPTS=-Xmx5g
  

  Copy

• Wenn die Verbindung vom Agenten zu Snowflake einen Proxy erfordert, stellen Sie Folgendes ein:

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

  Copy

• Um den Proxy für einige Hosts oder IP-Adressen zu umgehen, zum Beispiel für Quelldatenbanken, stellen Sie die zusätzliche Eigenschaft http.nonProxyHosts ein. Verwenden Sie ein Pipe-Symbol (|), um mehrere Hostnamen zu trennen. Verwenden Sie ein Sternchen (*) als Platzhalterzeichen.

  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

• Um Anmeldeinformationen für den Proxy zu übergeben, stellen Sie die Systemeigenschaften http.proxyUser und http.proxyPassword ein.

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

  Copy

Einstellen der PrivateLink-Konnektivität¶

Wenn Sie eine Verbindung zu einer PrivateLink-Bereitstellung herstellen, müssen Sie dem Agenten explizit die URL zur Verfügung stellen, mit der er sich verbinden soll, indem Sie die Umgebungsvariable SNOWFLAKE_ENFORCEDURL einstellen.

Um die PrivateLink URL Ihres Kontos zu ermitteln, können Sie entweder:

• die snowflake.json-Datei öffnen, die Sie während der Konfiguration erhalten haben. das Array mit dem Namen allowlistPrivatelink suchen und dann den Eintrag mit der Bezeichnung type von SNOWFLAKE_DEPLOYMENT.

• die Funktion SYSTEM$GET_PRIVATELINK_CONFIG verwenden.

Snowflake-Zugriffsschlüssel verstehen¶

Der Agent authentifiziert sich bei Snowflake als ein Dienstkonto, das durch den Einrichtungsassistenten des Konnektors in Snowsight erstellt wurde, unter Verwendung einer Reihe von Zugangsschlüsseln. Der Assistent erstellt temporäre Zugangsschlüssel und fügt den privaten Schlüssel in die Datei snowflake.json in einem Feld namens temporaryPrivateKey ein.

Während des ersten Starts ersetzt der Agent diese temporären Schlüssel durch:

1. Erzeugen eines neuen Satzes von Zugriffsschlüsseln und Speichern dieser Schlüssel unter /home/agent/.ssh als database-connector-agent-app-private-key.p8 und database-connector-agent-app-public-key.pub innerhalb des Containers. Dieses Verzeichnis sollte als externes, beschreibbares Volume in den Container eingebunden werden, damit die Schlüssel erhalten bleiben, wenn der Container heruntergefahren wird.

2. Änderung des Dienstkontos zur Verwendung der neuen Schlüssel.

3. Entfernen Sie das Feld temporaryPrivateKey aus der Datei snowflake.json.

Nach dem ersten Austausch der Schlüssel rotiert der Agent die Schlüssel nicht mehr.

Sie können die vom Agenten erzeugten Schlüssel verwenden. Sie können aber auch ein eigenes Set erstellen, das Dienstkonto ändern und den privaten Schlüssel an den Agenten weitergeben.

Die Reihenfolge bei der Ermittlung des privaten Schlüssels des Agenten ist:

1. Jeder Schlüssel, der mit der Umgebungsvariablen SNOWFLAKE_PRIVATEKEY übergeben wird. Wenn dieser Wert gefunden wird, ignoriert der Konnektor den temporären Schlüssel von snowflake.json.

2. Schlüssel, die auf eingebundenen Volumes gefunden wurden, in /home/agent/.ssh/database-connector-agent-app-private-key.p8. Wenn diese Datei gefunden wird, ignoriert der Konnektor den temporären Schlüssel von snowflake.json.

3. Der Wert des Feldes temporaryPrivateKey aus der Datei snowflake.json.

Zugriff auf den Endpunkt für den Healthcheck¶

Der Agent stellt einen HTTP-Endpunkt mit Informationen zur Data Health zur Verfügung. Sie können diesen Endpunkt verwenden, wenn Sie den Agenten in einem Orchestrierungssystem ausführen, um festzustellen, wann der Agent vollständig gestartet wurde und ob er funktionsfähig ist. Der Endpunkt ist unter Port 8080 und Pfad /actuator/health verfügbar.

Um den Endpunkt als Liveness-Probe in Kubernetes zu verwenden, fügen Sie Ihrer Pod-Konfiguration Folgendes hinzu:

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