Snowflake Connector for MySQL エージェントコンテナの設定¶

コンテナオーケストレーションシステムの選択¶

エージェントは標準的なDockerコンテナイメージとしてパッケージ化されており、標準をサポートするオーケストレーションシステムで実行できます。これには、スタンドアロンの Docker インスタンス、 Kubernetes、 RedHat OpenShift、 AWS Fargate などのクラウド管理ソリューションが含まれます。組織には、使用が推奨される既存のシステムが存在することがよくあります。

オーケストレーションシステムに応じて制約が異なるため、このドキュメントのエージェントの構成セクションをよく確認してください。使用中のシステムまたは特定の設定によっては、書き込み可能なボリュームをマウントできない場合があります（エージェントの主な構成オプションで必要な場合）。

後の例では、最も一般的なオーケストレーションシステムであるKubernetesに焦点を当てます。他のシステムでも同様のアプローチをとることが多く、各自の設定に合わせて例を調整する必要があります。

必要なシステムリソースの確認¶

• エージェントはメモリを大量に消費するアプリケーションであり、正しく動作するためには最低 6GB の RAM が必要です。

• 最適な CPUs の数は4です。CPUs が少ないとパフォーマンスが低下する可能性があります。CPUs を増やしてもパフォーマンスは向上しません。

接続の設定¶

エージェントは、データを読み取ろうとするすべてのソースデータベースに接続する必要があります。直接接続を可能にし、 MySQL の従来のクライアントポートに到達できるように、ネットワークとファイアウォールを構成します。通常はポート 3306 です。詳細については、 MySQL のポート参照表 をご参照ください。

ソースデータベースが分離されたネットワークに存在し、単一のエージェントから接続できない場合は、コネクタのネイティブアプリケーションの追加インスタンスをインストールし、それぞれに独自のエージェントをインストールする必要があります。この機能は現在プライベートプレビュー中です。アクセスをリクエストするには、 Snowflakeサポート にご連絡ください。

エージェントは、Snowflakeデプロイメントに直接接続することもできます。使用可能にする必要があるホスト名の詳細については、 ホスト名の許可 をご参照ください。

エージェントの接続のいずれかがプロキシを通過する場合は、エージェントに追加の構成を渡す必要があります。 オプションの構成環境変数を確認する をご参照ください。

MariaDB JDBC ドライバーをダウンロードする¶

このドライバーを使用し、エージェントは MySQL データベースに接続してやり取りします。名目上は MariaDB 用のドライバーですが、互換性があります。

ライセンスの制限により、 JDBC ドライバーはエージェントと一緒に配布できないため、自分で提供する必要があります。 MariaDB JDBC コネクタ3.4.1 をダウンロードし、エージェントのコンテナにマウントできるディレクトリに保存します。

［オプション］ソースデータベースの SSL 証明書を取得および準備する¶

エージェントが SSL 経由でソースデータベースに接続する場合、接続を検証するために証明書が必要になります。これらの証明書は、エージェントのコンテナ内のJava Truststoreのパス /opt/java/openjdk/lib/security/cacerts で使用できる必要があります。

エージェントに証明書を供給する最も簡単な方法は、ホストマシンの既存の cacerts ファイルに証明書を追加し、そのファイルを実行中のコンテナにマウントすることです。

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

エージェントの構成の準備¶

エージェントは、コンテナにマウントされた JSON ファイルまたは環境変数、あるいはその両方を組み合わせて構成できます。Snowflakeへの接続に必要なアクセスキーは、ホストのファイルシステムからマウントするか、コンテナシークレットとして提供するか、環境変数として提供することができます。

次のセクションでは、最も簡単なものから最も包括的なものまで、さまざまな構成オプションについて説明します。インフラストラクチャの詳細に基づいてアプローチを選択します。

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

オプションの構成環境変数を確認する¶

エージェントは、コンテナに追加の環境変数を設定することで使用できる、次のオプション設定をサポートしています。

SNOWFLAKE_PRIVATEKEYPATH

エージェントユーザーの秘密キーを含むファイルへの絶対パスを指定します。これは、通常オーケストレーションシステムのシークレットを介して、独自の秘密キーをコンテナにマウントするときに使用されます。

SNOWFLAKE_PRIVATEKEYPASSWORD

エージェントユーザーの秘密キーのパスワードを指定します。エージェントにキーを生成させると、このパスワードが秘密キーに設定されます。既存のキーを再利用する場合、このパスワードは既存の秘密キーにアクセスするために使用されます。

SNOWFLAKE_PRIVATEKEY

エージェントユーザーの秘密キーの内容を指定します。コンテナ内のファイルとして秘密キーをマウントできない場合に、これを設定できます。

SNOWFLAKE_ENFORCEDURL

エージェント独自の検出メカニズムを上書きして、Snowflakeに接続するための URL を指定します。これは主に PrivateLink デプロイメントに接続するために使用されます。

JAVA_OPTS

エージェントのプロセスに渡される追加のJava設定またはプロパティを指定します。

最もよく使用されるものは次のとおりです。

• 最大Javaヒープサイズを設定するための -Xmx オプション。Snowflakeでは、この値をコンテナで使用可能なメモリ量から 1GB を引いた値に設定することを推奨しています。

  たとえば、コンテナで 6GB の RAM が使用可能な場合は、次のように設定します。

  JAVA_OPTS=-Xmx5g
  

  Copy

• エージェントからSnowflakeへの接続にプロキシが必要な場合は、次のように設定します。

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

  Copy

• ソースデータベースなど、一部のホストまたは IP アドレスのプロキシをバイパスするには、追加の http.nonProxyHosts プロパティを設定します。パイプ記号（|）を使用して複数のホスト名を区切ります。アスタリスク（*）をワイルドカード文字として使用します。

  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

• プロキシの認証情報を渡すには、 http.proxyUser および http.proxyPassword システムプロパティを設定します。

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

  Copy

PrivateLink 接続の設定¶

PrivateLink デプロイメントに接続する場合は、 SNOWFLAKE_ENFORCEDURL 環境変数を設定して、エージェントが接続する URL を明示的に指定する必要があります。

アカウントの PrivateLink URL を確認するには、次のいずれかの方法を実行します。

• 構成プロセス中に取得した snowflake.json ファイルを開きます。 allowlistPrivatelink という名前の配列を見つけ、次に SNOWFLAKE_DEPLOYMENT の type を持つエントリーを見つけます。

• SYSTEM$GET_PRIVATELINK_CONFIG 関数を使用します。

Snowflakeのアクセスキーを理解する¶

エージェントは、Snowsightのコネクタのセットアップウィザードで作成されたサービスアカウントとして、アクセスキーのセットを使用してSnowflakeと認証します。設定ウィザードは一時的なアクセスキーを作成し、 秘密 キーを snowflake.json ファイルの temporaryPrivateKey という名前のフィールドに追加します。

エージェントは、最初の起動時にこれらの一時的なキーを次のように置き換えます。

1. 新しいアクセスキーのセットを生成し、コンテナ内の /home/agent/.ssh に database-connector-agent-app-private-key.p8 および database-connector-agent-app-public-key.pub として保存します。このディレクトリは、コンテナがシャットダウンしてもキーが保持されるように、コンテナへの外部の書き込み可能なボリュームとしてマウントする必要があります。

2. 新しいキーを使用するようにサービスアカウントを変更します。

3. snowflake.json ファイルから temporaryPrivateKey フィールドを削除します。

最初のキーの置き換え後、エージェントはアクセスキーをローテーションしません。

エージェントによって生成されたキーを使用できます。または、独自のセットを作成し、サービスアカウントを変更して、エージェントに秘密キーを提供することもできます。

エージェントの秘密キーの検出順序は次のとおりです。

1. SNOWFLAKE_PRIVATEKEY 環境変数を使用して渡される任意のキー。この値が見つかった場合、コネクタは snowflake.json からの一時的なキーを無視します。

2. /home/agent/.ssh/database-connector-agent-app-private-key.p8 にマウントされたボリュームで見つかったキー。このファイルが見つかった場合、コネクタは snowflake.json からの一時的なキーを無視します。

3. snowflake.json ファイルの temporaryPrivateKey フィールドの値。

ヘルスチェックエンドポイントへのアクセス¶

エージェントは健全性の情報を含む HTTP エンドポイントを公開します。オーケストレーションシステムでエージェントを実行するときにこのエンドポイントを使用すると、エージェントが完全に起動したかどうか、また健全であるかどうかを判断できます。エンドポイントはポート 8080 とパス /actuator/health で使用できます。

エンドポイントをKubernetesのライブネスプローブとして使用するには、Pod構成に次を追加します。

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