Configuração do contêiner do Agent Snowflake Connector for MySQL¶

Escolha de um sistema de orquestração de contêiner¶

O agente é empacotado como uma imagem de contêiner Docker padrão e pode ser executado em qualquer sistema de orquestração com suporte ao padrão. Pode ser uma instância autônoma do Docker, Kubernetes, RedHat OpenShift, uma solução gerenciada na nuvem, como AWS Fargate, dentre outras. Muitas vezes, sua organização terá um sistema preferencial existente para você usar.

Preste atenção à seção de configuração do agente deste documento, porque diferentes sistemas de orquestração apresentam diferentes restrições. Seu sistema, ou configuração específica, pode não permitir que você monte volumes graváveis (conforme é exigido com a opção de configuração primária do agente).

Exemplos posteriores se concentrarão no Kubernetes como o sistema de orquestração mais popular. A abordagem geralmente será semelhante em outros sistemas, e você precisará ajustar os exemplos para sua configuração.

Confirme os recursos do sistema necessários¶

• O agente é um aplicativo que exige muita memória e requer um mínimo de 6GB de RAM para operar corretamente.

• O número ideal de CPUs é 4. Menos CPUs pode diminuir o desempenho. Mais CPUs não melhorará o desempenho.

Configuração de conectividade¶

O agente precisa se conectar a todos os banco de dados de origem dos quais você pretende ler dados. Configure sua rede e firewalls para que conexões diretas sejam possíveis e a porta clássica do cliente MySQL esteja acessível. Normalmente é a porta 3306. Para obter mais informações, consulte Tabelas de referência de porta de MySQL.

Se seus bancos de dados de origem residirem em redes isoladas e a conexão a partir de um único agente não for possível, será necessário instalar instâncias adicionais do aplicativo nativo do conector, cada uma com seu próprio agente. Este recurso está atualmente em versão preliminar privada. Entre em contato com o suporte Snowflake para solicitar acesso.

O agente também se conecta diretamente à sua implementação do Snowflake. Para obter informações sobre quais nomes de host precisam estar disponíveis, consulte Permissão de nomes de host.

Se alguma das conexões do agente passar por um proxy, será necessário passar configuração adicional ao agente. Consulte Revisão das variáveis de ambiente de configuração opcionais.

Download do driver MariaDB JDBC¶

O agente usa esse driver para se conectar e interagir com bancos de dados MySQL. Apesar de ser nominalmente um driver para MariaDB, eles são compatíveis.

Devido às limitações de licenciamento, o driver JDBC não pode ser distribuído junto com o agente, e você terá que fornecê-lo. Baixe o MariaDB JDBC Connector 3.4.1 e salve-o em um diretório de onde você possa montá-lo no contêiner do agente.

[Opcional] Como obter e preparar certificados SSL para bancos de dados de origem¶

Quando o agente se conecta aos bancos de dados de origem via SSL, ele requer seus certificados para validar as conexões. Esses certificados devem estar disponíveis no Java Truststore dentro do contêiner do agente, no caminho /opt/java/openjdk/lib/security/cacerts.

A maneira mais simples de fornecer certificados ao agente é adicioná-los ao arquivo cacerts existente na máquina host e montar esse arquivo no contêiner em execução.

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

Como preparar a configuração do agente¶

O agente pode ser configurado por meio de arquivos JSON montados em contêiner, variáveis de ambiente ou uma mistura de ambos. As chaves de acesso necessárias para se conectar ao Snowflake podem ser montadas a partir do sistema de arquivo do host, fornecidas como segredos de contêiner ou variáveis de ambiente.

As seções a seguir descrevem diferentes opções de configuração, das mais simples às mais abrangentes. Escolha uma abordagem com base nas especificidades da infraestrutura.

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

Revisão das variáveis de ambiente de configuração opcionais¶

O agente oferece suporte às seguintes configurações opcionais, disponíveis ao configurar variáveis de ambiente adicionais no contêiner:

SNOWFLAKE_PRIVATEKEYPATH

Especifica o caminho absoluto para o arquivo com a chave privada do usuário do agente. Isso é usado ao montar sua própria chave privada no contêiner, geralmente por meio de um segredo do sistema de orquestração.

SNOWFLAKE_PRIVATEKEYPASSWORD

Especifica a senha para a chave privada do usuário do agente. Se você deixar o agente gerar as chaves, essa senha será definida na chave privada. Se você reutilizar chaves existentes, esta senha será usada para acessar a chave privada existente.

SNOWFLAKE_PRIVATEKEY

Especifica o conteúdo da chave privada do usuário do agente. Isso pode ser definido quando não for possível montar a chave privada como um arquivo no contêiner.

SNOWFLAKE_ENFORCEDURL

Especifica o URL da conexão ao Snowflake, substituindo o mecanismo de descoberta do próprio agente. Isso é usado principalmente para conectar-se a implementações do PrivateLink.

JAVA_OPTS

Especifica configurações ou propriedades Java adicionais que serão passadas para o processo do agente.

As mais comumente usadas são:

• A opção -Xmx para definir o tamanho máximo do heap Java. A Snowflake recomenda configurar esse valor como a quantidade de memória disponível para o contêiner, menos 1GB.

  Por exemplo, se o contêiner tiver 6GB de RAM disponível, defina o seguinte:

  JAVA_OPTS=-Xmx5g
  

  Copy

• Quando a conexão do agente ao Snowflake exigir um proxy, defina o seguinte:

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

  Copy

• Para ignorar o proxy para alguns hosts ou endereços IP, como bancos de dados de origem, defina a propriedade http.nonProxyHosts adicional. Use um símbolo de canal (|) para separar vários nomes de host. Use um asterisco (*) como caractere curinga.

  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

• Para passar credenciais ao proxy, defina as propriedades do sistema http.proxyUser e http.proxyPassword.

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

  Copy

Configuração da conectividade do PrivateLink¶

Se você estiver se conectando a uma implementação do PrivateLink, deverá fornecer explicitamente o URL para o agente para se conectar, configuração a variável de ambiente SNOWFLAKE_ENFORCEDURL.

Para determinar o URL do PrivateLink de sua conta, você pode:

• Abrir o arquivo snowflake.json que obteve durante o processo de configuração. Encontrar a matriz nomeada allowlistPrivatelink, e a entrada com o type de SNOWFLAKE_DEPLOYMENT.

• Use a função SYSTEM$GET_PRIVATELINK_CONFIG.

Chaves de acesso Snowflake¶

O agente é autenticado no Snowflake como uma conta de serviço, criada pelo assistente de configuração do conector no Snowsight, usando um conjunto de chaves de acesso. O assistente de configuração cria chaves de acesso temporárias e adiciona a chave privada ao arquivo snowflake.json em um campo nomeado temporaryPrivateKey.

Durante sua inicialização, o agente substitui essas chaves temporárias:

1. Gerando um novo conjunto de chaves de acesso e armazenando-as em /home/agent/.ssh como database-connector-agent-app-private-key.p8 e database-connector-agent-app-public-key.pub dentro do contêiner. Este diretório deve ser montado como um volume externo e gravável no contêiner, para que as chaves persistam quando o contêiner for desligado.

2. Alterando sua conta de serviço para usar as novas chaves.

3. Removendo o campo temporaryPrivateKey do arquivo snowflake.json.

Após a substituição inicial da chave, o agente nunca rotaciona as chaves de acesso.

É possível usar as chaves geradas pelo agente. Ou você pode criar seu próprio conjunto, alterar a conta de serviço e fornecer a chave privada ao agente.

A ordem de descoberta da chave privada do agente é:

1. Qualquer chave passada usando a variável de ambiente SNOWFLAKE_PRIVATEKEY. Se esse valor for encontrado, o conector ignorará a chave temporária de snowflake.json.

2. Chaves encontradas em volumes montados em /home/agent/.ssh/database-connector-agent-app-private-key.p8. Se este arquivo for encontrado, o conector ignorará a chave temporária de snowflake.json.

3. O valor do campo temporaryPrivateKey do arquivo snowflake.json.

Como acessar o ponto de extremidade de verificação de integridade¶

O agente expõe um ponto de extremidade HTTP com informações de integridade. É possível usar esse ponto de extremidade ao executar o agente em um sistema de orquestração para determinar quando o agente foi totalmente iniciado e se ele está íntegro. O ponto de extremidade está disponível na porta 8080 e no caminho /actuator/health.

Para usar o ponto de extremidade como uma sonda de atividade no Kubernetes, adicione o seguinte à configuração de seu Pod:

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