SnowCD (Connectivity Diagnostic Tool)¶

O SnowCD (isto é, a ferramenta de diagnóstico de conectividade do Snowflake) ajuda os usuários a diagnosticarem e solucionarem problemas de conexão da rede com o Snowflake.

Visão geral¶

SnowCD aproveita os endereços IP e as portas do nome de host do Snowflake listados pelas funções SYSTEM$ALLOWLIST() ou SYSTEM$ALLOWLIST_PRIVATELINK() para executar uma série de verificações de conexão a fim de avaliar e ajudar a solucionar problemas na conexão de rede com o Snowflake.

Importante

Se a sua conta Snowflake utiliza conectividade privada para se conectar ao serviço Snowflake, execute a função SYSTEM$ALLOWLIST_PRIVATELINK para obter o endereço IP e as portas do nome de host do Snowflake a fim de avaliar e solucionar problemas de conexão de rede com o Snowflake.

Para obter mais informações, consulte:

O SnowCD retorna um dos seguintes resultados:

All checks passed para indicar uma conexão de rede saudável.

Uma mensagem informando que uma ou mais verificações falharam com uma sugestão de solução do problema.

Os usuários podem usar o SnowCD para avaliar a conexão de rede com o Snowflake a qualquer momento e verificar se as configurações necessárias estão corretas. Por exemplo, os usuários podem integrar o SnowCD aos seguintes casos de uso:

Scripts de implantação automatizada.

Uma verificação de pré-requisitos antes de implantar um serviço que se conecte ao Snowflake.

Verificações de ambiente ao iniciar uma nova máquina.

Verificações periódicas em máquinas em funcionamento.

O SnowCD trabalha com conexões diretas ou conexões via servidores proxy.

O SnowCD verifica o acesso ao banco de dados Snowflake e aos estágios usados para armazenar dados temporariamente (por exemplo, para carregamento).

O SnowCD verifica se uma resposta HTTP foi devolvida pelo host HTTP. Isso pode detectar problemas como os seguintes:

Nenhum servidor HTTP está rodando na porta e no endereço IP especificados.
Houve uma falha na pesquisa de DNS (Domain Name System).
Ocorreu um ataque “man-in-the middle” que usou um certificado inválido para representar o serviço desejado.
Alguns tipos de outras falhas de rede abaixo do nível HTTP.

O SnowCD não detecta todos os problemas possíveis. As limitações conhecidas incluem:

Os estágios exigem informações adicionais de autenticação que o SnowCD não possui. Embora o SnowCD verifique o acesso básico a um estágio, o SnowCD não realiza uma verificação rigorosa do código de resposta HTTP recebido do estágio. Portanto, o SnowCD não detecta problemas como:
- Negação de política de acesso aos buckets Amazon S3, armazenamento de blobs do Azure ou Google Cloud Storage para os estágios.
- Problemas de conexão com o servidor proxy do cliente, por exemplo, o servidor proxy retorna um erro HTTP 403.

Como o SnowCD não detecta todos os problemas possíveis, o Snowflake recomenda que, após verificar com sucesso o acesso a um estágio pelo SnowCD, você execute um comando PUT para carregar um arquivo em um estágio. A maneira mais simples de executar um comando PUT é geralmente no SnowSQL.

Atenção

Solucionar um ou mais problemas de conexão de rede é complicado. Dependendo do ambiente, pode ser necessário usar o SnowCD com outras abordagens de solução de problemas. Por exemplo, se o SnowCD retornar informações sobre um problema com o OCSP, consulte as seções de OCSP nesta página.

Uso de SnowCD¶

Passo 1: Executar a função SYSTEM$ALLOWLIST ou SYSTEM$ALLOWLIST_PRIVATELINK¶

Esse é um passo prévio e ele só precisa ser concluído uma vez, a menos que os nomes de hosts ou as portas mudem.

Conecte-se ao Snowflake pela interface da Web.
Execute SELECT SYSTEM$ALLOWLIST(); ou SELECT SYSTEM$ALLOWLIST_PRIVATELINK();.
salve o resultado da consulta em um arquivo (por exemplo, allowlist.json).

Para obter mais informações sobre essas funções, consulte SYSTEM$ALLOWLIST ou SYSTEM$ALLOWLIST_PRIVATELINK.

Os exemplos abaixo usam JSON como formato de saída da função SQL correspondente. O SnowCD aceita os formatos JSON, CSV ou TSV como entrada para a Passo 3: Executar o SnowCD.

Para salvar o resultado da consulta no formato CSV ou TSV, na interface da Web, clique no ícone Download or View Results, selecione CSV ou TSV, e clique em Export.

Arquivo de exemplo (sem recuo e redigido)

Execute SYSTEM$ALLOWLIST e salve a saída em um arquivo (por exemplo, allowlist.json).

Onde:

<local_de_armazenamento> é o local de armazenamento (Amazon S3, Google Cloud Storage ou Microsoft Azure) que armazena o arquivo que um cliente Snowflake pode ler ou escrever.

<id_de_região> é a região do AWS onde sua conta Snowflake e VPCs estão localizadas.
[{"type":"STAGE","host":"<storage_location>.s3.<region_id>.amazonaws.com","port":443},
{"type":"STAGE","host":"<storage_location>.s3-<region_id>.amazonaws.com","port":443},
{"type":"STAGE","host":"<storage_location>.s3.amazonaws.com","port":443},
{"type":"SNOWSQL_REPO","host":"<repository_name_1>.s3.<region_id>.amazonaws.com","port":443},
{"type":"SNOWSQL_REPO","host":"<repository_name_2>.snowflakecomputing.com","port":443},
{"type":"OUT_OF_BAND_TELEMETRY","host":"<telemetry_subdomain>.snowflakecomputing.com","port":443},
{"type":"OCSP_CACHE","host":"ocsp.snowflakecomputing.com","port":80},
{"type":"OCSP_RESPONDER","host":"ocsp.digicert.com","port":80}]

Arquivo de exemplo (com recuo e redigido)

Execute SYSTEM$ALLOWLIST e salve a saída em um arquivo (por exemplo, allowlist.json).

Onde:

<local_de_armazenamento> é o local de armazenamento (Amazon S3, Google Cloud Storage ou Microsoft Azure) que armazena o arquivo que um cliente Snowflake pode ler ou escrever.

<id_de_região> é a região do AWS onde sua conta Snowflake e VPCs estão localizadas.

[{
  "type": "STAGE",
  "host": "<storage_location>.s3.<region_id>.amazonaws.com",
  "port": 443
}, {
  "type": "STAGE",
  "host": "<storage_location>.s3-<region_id>.amazonaws.com",
  "port": 443
}, {
  "type": "STAGE",
  "host": "<storage_location>.s3.amazonaws.com",
  "port": 443
}, {
  "type": "SNOWSQL_REPO",
  "host": "<repository_name_1>.s3.<region_id>.amazonaws.com",
  "port": 443
}, {
  "type": "SNOWSQL_REPO",
  "host": "<repository_name_2>.snowflakecomputing.com",
  "port": 443
}, {
  "type": "OUT_OF_BAND_TELEMETRY",
  "host": "<telemetry_subdomain>.snowflakecomputing.com",
  "port": 443
}, {
  "type": "OCSP_CACHE",
  "host": "ocsp.snowflakecomputing.com",
  "port": 80
}, {
  "type": "OCSP_RESPONDER",
  "host": "ocsp.digicert.com",
  "port": 80
}]

Arquivo de exemplo (sem recuo e redigido)

Execute SYSTEM$ALLOWLIST_PRIVATELINK e salve a saída em um arquivo (por exemplo, allowlist.json).

Onde:

<local_de_armazenamento> é o local de armazenamento (Amazon S3, Google Cloud Storage ou Microsoft Azure) que armazena o arquivo que um cliente Snowflake pode ler ou escrever.

<id_de_região> é a região do AWS onde sua conta Snowflake e VPCs estão localizadas.

[{"type":"SNOWFLAKE_DEPLOYMENT","host":"<storage_location>.<region>.privatelink.snowflakecomputing.com","port":443},
{"type":"STAGE","host":"<storage_location>.<region>.amazonaws.com","port":443},
{"type":"STAGE","host":"<storage_location>-<region>.amazonaws.com","port":443},
{"type":"STAGE","host":"<storage_location>.amazonaws.com","port":443},
{"type":"SNOWSQL_REPO","host":"<repository_name_1>.s3.<region>.amazonaws.com","port":443},
{"type":"SNOWSQL_REPO","host":"<repository_name_2>.snowflakecomputing.com","port":443},
{"type":"OUT_OF_BAND_TELEMETRY","host":"<telemetry_subdomain>.snowflakecomputing.com","port":443},
{"type":"OCSP_CACHE","host":"ocsp.<storage_location>.<region>.privatelink.snowflakecomputing.com","port":80}]

Arquivo de exemplo (com recuo e redigido)

Execute SYSTEM$ALLOWLIST_PRIVATELINK e salve a saída em um arquivo (por exemplo, allowlist.json).

Onde:

<local_de_armazenamento> é o local de armazenamento (Amazon S3, Google Cloud Storage ou Microsoft Azure) que armazena o arquivo que um cliente Snowflake pode ler ou escrever.

<id_de_região> é a região do AWS onde sua conta Snowflake e VPCs estão localizadas.

[{
  "type": "SNOWFLAKE_DEPLOYMENT",
  "host": "<storage_location>.<region>.privatelink.snowflakecomputing.com",
  "port": 443
}, {
  "type": "STAGE",
  "host": "<storage_location>.<region>.amazonaws.com",
  "port": 443
}, {
  "type": "STAGE",
  "host": "<storage_location>-<region>.amazonaws.com",
  "port": 443
}, {
  "type": "STAGE",
  "host": "<storage_location>.amazonaws.com",
  "port": 443
}, {
  "type": "SNOWSQL_REPO",
  "host": "<repository_name_1>.s3.<region>.amazonaws.com",
  "port": 443
}, {
  "type": "SNOWSQL_REPO",
  "host": "<repository_name_2>.snowflakecomputing.com",
  "port": 443
}, {
  "type": "OUT_OF_BAND_TELEMETRY",
  "host": "<telemetry_subdomain>.snowflakecomputing.com",
  "port": 443
}, {
  "type": "OCSP_CACHE",
  "host": "ocsp.<storage_location>.<region>.privatelink.snowflakecomputing.com",
  "port": 80
}]

Atenção

Salve o arquivo allowlist.json no local onde outras portas e nomes de hosts externos permitidos foram definidos para o seu ambiente.

Dica

Se você não quiser a saída no formato JSON e preferir o formato de tabela, execute o seguinte comando:

use warehouse my_warehouse;
select value:type as type,
       value:host as host,
       value:port as port
   from table(flatten(input => parse_json(system$allowlist())));

Passo 2: Baixar e instalar o SnowCD¶

Linux¶

Para baixar e instalar o SnowCD no Linux, realize os seguintes passos:

Baixe a versão mais recente do SnowCD da página de Download do SnowCD.
Abra o aplicativo Linux Terminal e navegue até o diretório onde você baixou o arquivo.
Verifique se as somas de verificação SHA256 correspondem.
$ sha256sum <filename>
Extraia o arquivo.
$ gunzip <filename>
Torne o arquivo executável.
$ chmod +x <filename>
Renomeie o executável como snowcd.
$ mv <filename> snowcd

Nota

Usuários Linux rodando RHEL ou CentOS podem instalar o SnowCD usando o yum, e usuários Debian podem instalar usando o apt.

macOS¶

Para baixar e instalar o SnowCD no macOS, realize os seguintes passos:

Baixe a versão mais recente do arquivo SnowCD pkg autenticado a partir da página Download do SnowCD.

Os arquivos pkg utilizam a seguinte convenção de nomenclatura:

snowcd-<número_de_versão>-darwin_x86_64.pkg

Por exemplo:

snowcd-1.0.5-darwin_x86_64.pkg
Abra o aplicativo do terminal e navegue até o diretório onde você baixou o arquivo.
Verifique se as somas de verificação SHA256 correspondem.

Para obter a soma de verificação do arquivo, execute o comando:
```
$ shasum -a 256 <filename>
```
Compare a soma de verificação do arquivo com a soma de verificação mostrada no site de download.
Abra o aplicativo Finder e navegue até o diretório onde você baixou o arquivo pkg.
Extraia e instale o SnowCD clicando duas vezes no arquivo pkg.

Os arquivos, incluindo o executável snowcd, serão instalados no diretório /opt/snowflake/snowcd.

Windows¶

Para baixar e instalar o SnowCD no Windows, realize os seguintes passos:

Baixe a versão mais recente do SnowCD da página de Download do SnowCD.
Execute o arquivo MSI usando o Windows Installer.

Passo 3: Executar o SnowCD¶

Antes de executar o SnowCD em ambientes macOS e Linux, você pode adicionar o diretório dele ao $PATH. Em ambientes Windows, você pode adicionar o SnowCD a suas variáveis de ambiente.

Em ambientes macOS ou Linux, você pode rodar o executável snowcd a partir da linha de comando executando snowcd <path_to_allowlist.json> [flags].
Em ambientes Windows, execute snowcd.exe <path_to_allowlist.json> [flags].

Dica

Para obter uma descrição completa dos sinalizadores suportados pelo snowcd, execute snowcd -h.

Se todas as verificações forem válidas, o SnowCD retorna o número de verificações no número de hosts com a mensagem All checks passed, como segue.

Performing 30 checks on 12 hosts
All checks passed

Se você tentar executar o SnowCD sem transmitir as informações da lista de permissão JSON de SELECT SYSTEM$ALLOWLIST(), a seguinte mensagem de erro será exibida como um lembrete para incluir o arquivo, com a lista de sinalizadores suportados atualmente, o tipo de dados onde aplicável, e uma breve descrição do sinalizador.

Error: please provide whitelist generated by SYSTEM$ALLOWLIST()
Usage:
./snowcd <path to input json file> [flags]

Examples:
./snowcd test.json

Flags:
  -h, --help                   help for ./snowcd
  --logLevel string            log level (panic, fatal[default], error, warning, info, debug, trace) (default "fatal")
  --logPath string             Output directory for log. When not specified, no log is generated
  --proxyHost string           host for http proxy. (When not specified, does not use proxy at all)
  --proxyIsHTTPS               Is connection to proxy secure, i.e. https. (default false)
  --proxyPassword string       password for http proxy.(default empty)
  --proxyPort int              port for http proxy.(default 8080) (default 8080)
  --proxyUser string           user name for http proxy.(default empty)
  -t, --timeout int            timeout for each hostname's checks in seconds (default 5) (default 5)
  --version                    version for ./snowcd

Se o SnowCD detectar um ajuste ou configuração incorreta, as informações da(s) verificação(ões) com erro serão exibidas com uma sugestão de solução de problemas. Por exemplo, a resposta abaixo indica um nome de host inválido.

Check for 1 hosts failed, display as follow:
==============================================
Host: www.google1.com
Port: 443
Type: SNOWFLAKE_DEPLOYMENT
Failed Check: DNS Check
Error: lookup www.google1.com: no such host
Suggestion: Check your configuration on DNS server

Como usar o SnowCD com um proxy HTTP¶

O SnowCD pode ser executado em um proxy HTTP para determinar seu status de conectividade.

Importante

Atualmente, o Snowflake não oferece suporte a servidores proxy com encerramento SSL.

Durante a configuração da lista de permissões do firewall e do proxy, use a passagem SSL (ou seja, ignore a descriptografia SSL).

Usando o Linux como exemplo, execute o seguinte comando para executar o SnowCD em um proxy, substituindo valores de sinalizadores quando necessário.

snowcd allowlist.json \
  --proxyHost <hostname> \
  --proxyPort <port_number> \
  --proxyUser <username> \
  --proxyPassword <password>

O registro em log é opcional e você pode adicionar os dois sinalizadores de log ao comando proxy. É importante incluir um caminho para o arquivo de log para garantir que o registro em log ocorra ao executar o comando.

snowcd allowlist.json \
  --proxyHost <hostname> \
  --proxyPort <port_number> \
  --proxyUser <username> \
  --proxyPassword <password> \
  --logLevel trace \
  --logPath test.log

Depois de executar esse comando, você pode visualizar o rastreamento no arquivo test.log.