SnowCD (Connectivity Diagnostic Tool)¶

SnowCD （即 Connectivity Diagnostic Tool）可帮助用户诊断和排查与 Snowflake 的网络连接故障。

概述¶

SnowCD 利用 SYSTEM$ALLOWLIST() 或 SYSTEM$ALLOWLIST_PRIVATELINK() 函数列出的 Snowflake 主机名 IP 地址和端口运行一系列连接检查，以评估与 Snowflake 的网络连接，并帮助排查故障。

重要

如果您的 Snowflake 账户使用与 Snowflake 服务的专用连接，请执行 SYSTEM$ALLOWLIST_PRIVATELINK 函数以获取 Snowflake 主机名 IP 地址和端口，从而评估与 Snowflake 的网络连接，并为其排查故障。

有关更多信息，请参阅：

SnowCD 会返回以下值之一：

All checks passed，表示网络连接正常。

一条消息，指出一项或多项检查失败，并提供故障排除建议。

用户可随时利用 SnowCD 评估与 Snowflake 的网络连接，以验证所需的配置设置是否正确。例如，用户可以将 SnowCD 集成到这些用例中：

自动执行的部署脚本。

在部署连接到 Snowflake 的服务之前执行先决条件检查。

在启动新机器时执行环境检查。

对运行中的机器执行定期检查。

SnowCD 可直接连接，也可通过代理服务器连接。

SnowCD 会检查对 Snowflake 数据库和用于临时存储数据（例如出于加载目的）的暂存区的访问权限。

SnowCD 验证是否从 HTTP 主机返回 HTTP 响应。这可以检测诸如下列问题：

没有 HTTP 服务器在指定 IP 地址和端口上运行。
存在 DNS （域名系统）查找失败。
发生了中间人攻击，并且使用了无效证书模拟所需服务。
HTTP 级别以下的某些类型的其他网络故障。

SnowCD 并不能检测所有可能出现的问题。已知的限制包括：

暂存区需要额外的身份验证信息，而 SnowCD 不能提供这些信息。虽然 SnowCD 会验证对暂存区的基本访问，但 SnowCD 不会对来自暂存区的 HTTP 响应代码执行严格检查。因此，SnowCD 不会检测到以下问题：
- 针对暂存区的 Amazon S3 桶、Azure Blob 存储或 Google Cloud Storage 的访问策略拒绝。
- 连接到客户的代理服务器时出现问题，例如代理服务器返回 HTTP 403 错误。

由于 SnowCD 无法检测所有可能出现的问题，Snowflake 建议在通过 SnowCD 成功验证对某个暂存区的访问之后，运行 PUT 命令将文件加载到暂存区。要运行 PUT 命令，最简单的方法通常是通过 SnowSQL。

注意

对一个或多个网络连接问题进行故障排除非常困难。根据具体环境的不同，可能需要将 SnowCD 与其他故障排除方法配合使用。例如，如果 SnowCD 返回了关于 OCSP 问题的信息，请参阅本页上的 OCSP 部分。

使用 SnowCD¶

第 1 步：运行 SYSTEM$ALLOWLIST 或 SYSTEM$ALLOWLIST_PRIVATELINK 函数¶

此步骤为先决条件，除非主机名或端口发生更改，否则就需要先完成一次。

通过 Web 界面连接到 Snowflake。
执行 SELECT SYSTEM$ALLOWLIST(); 或 SELECT SYSTEM$ALLOWLIST_PRIVATELINK();。
将查询结果保存到文件（即 allowlist.json）。

有关这些函数的详细信息，请参阅 SYSTEM$ALLOWLIST 或 SYSTEM$ALLOWLIST_PRIVATELINK。

下面的示例使用 JSON 作为相应 SQL 函数的输出格式。SnowCD 允许将 JSON、CSV 或 TSV 格式用作`第 3 步：运行 SnowCD`_ 的输入。

要将查询结果保存为 CSV 或 TSV 格式，请在 Web 界面中点击 Download or View Results 图标，选择 CSV 或 TSV，然后点击 Export。

示例文件（未缩进、未编辑）

执行 SYSTEM$ALLOWLIST 并将输出保存到文件（例如 allowlist.json）。

其中：

:code:` <storage_location>` 是存储 Snowflake 客户端可读取或写入的文件的存储位置（Amazon S3、Google Cloud Storage 或 Microsoft Azure）。

:code:` <region_id>` 是您的 VPCs 和 Snowflake 账户所在的 AWS 区域。

[{"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.cn","port":443},
{"type":"OUT_OF_BAND_TELEMETRY","host":"<telemetry_subdomain>.snowflakecomputing.cn","port":443},
{"type":"OCSP_CACHE","host":"ocsp.snowflakecomputing.cn","port":80},
{"type":"OCSP_RESPONDER","host":"ocsp.digicert.com","port":80}]

示例文件（已锁紧、已编辑）

执行 SYSTEM$ALLOWLIST 并将输出保存到文件（例如 allowlist.json）。

其中：

:code:` <storage_location>` 是存储 Snowflake 客户端可读取或写入的文件的存储位置（Amazon S3、Google Cloud Storage 或 Microsoft Azure）。

:code:` <region_id>` 是您的 VPCs 和 Snowflake 账户所在的 AWS 区域。

[{
  "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.cn",
  "port": 443
}, {
  "type": "OUT_OF_BAND_TELEMETRY",
  "host": "<telemetry_subdomain>.snowflakecomputing.cn",
  "port": 443
}, {
  "type": "OCSP_CACHE",
  "host": "ocsp.snowflakecomputing.cn",
  "port": 80
}, {
  "type": "OCSP_RESPONDER",
  "host": "ocsp.digicert.com",
  "port": 80
}]

示例文件（未缩进、未编辑）

执行 SYSTEM$ALLOWLIST_PRIVATELINK 并将输出保存到文件（例如 allowlist.json）。

其中：

:code:` <storage_location>` 是存储 Snowflake 客户端可读取或写入的文件的存储位置（Amazon S3、Google Cloud Storage 或 Microsoft Azure）。

:code:` <region_id>` 是您的 VPCs 和 Snowflake 账户所在的 AWS 区域。

[{"type":"SNOWFLAKE_DEPLOYMENT","host":"<storage_location>.<region>.privatelink.snowflakecomputing.cn","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.cn","port":443},
{"type":"OUT_OF_BAND_TELEMETRY","host":"<telemetry_subdomain>.snowflakecomputing.cn","port":443},
{"type":"OCSP_CACHE","host":"ocsp.<storage_location>.<region>.privatelink.snowflakecomputing.cn","port":80}]

示例文件（已锁紧、已编辑）

执行 SYSTEM$ALLOWLIST_PRIVATELINK 并将输出保存到文件（例如 allowlist.json）。

其中：

:code:` <storage_location>` 是存储 Snowflake 客户端可读取或写入的文件的存储位置（Amazon S3、Google Cloud Storage 或 Microsoft Azure）。

:code:` <region_id>` 是您的 VPCs 和 Snowflake 账户所在的 AWS 区域。

[{
  "type": "SNOWFLAKE_DEPLOYMENT",
  "host": "<storage_location>.<region>.privatelink.snowflakecomputing.cn",
  "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.cn",
  "port": 443
}, {
  "type": "OUT_OF_BAND_TELEMETRY",
  "host": "<telemetry_subdomain>.snowflakecomputing.cn",
  "port": 443
}, {
  "type": "OCSP_CACHE",
  "host": "ocsp.<storage_location>.<region>.privatelink.snowflakecomputing.cn",
  "port": 80
}]

注意

将 allowlist.json 文件保存到为环境定义了其他允许对外部使用的主机名和端口的位置。

小技巧

如果您不希望获得 JSON 格式的输出，而是更希望使用表的格式，请执行以下操作：

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())));

第 2 步：下载并安装 SnowCD¶

Linux¶

要在 Linux 上下载和安装 SnowCD，请完成以下步骤：

从 `SnowCD 下载 `_ 页面下载最新版本的 SnowCD。
打开 Linux 终端应用程序，并导航到保存下载文件的目录。
验证 SHA256 校验和是否匹配。
$ sha256sum <filename>
提取文件。
$ gunzip <filename>
使文件可执行。
$ chmod +x <filename>
将可执行文件重命名为 snowcd。
$ mv <filename> snowcd

备注

运行 RHEL 或 CentOS 的 Linux 用户可使用 yum 安装 SnowCD，而 Debian 用户可使用 apt 安装。

macOS¶

要在 macOS 上下载和安装 SnowCD，请完成以下步骤：

从 SnowCD 下载 `_ 页面下载经过证实的最新版本 SnowCD ``pkg` 文件。

pkg 文件使用以下命名约定：

snowcd- <version_number>-darwin_x86_64.pkg

例如：

snowcd-1.0.5-darwin_x86_64.pkg
打开终端应用程序，并导航到保存下载文件的目录。
验证 SHA256 校验和是否匹配。

要获取文件校验和，请执行以下命令：
```
$ shasum -a 256 <filename>
```
将文件的校验和与下载站点上显示的校验和进行对比。
打开 Finder 应用程序，导航到保存下载的 pkg 文件的目录。
双击 pkg 文件提取并安装 SnowCD。

这些文件（包括 snowcd 可执行文件）均安装到 /opt/snowflake/snowcd 目录中。

Windows¶

要在 Windows 上下载和安装 SnowCD，请完成以下步骤：

从 `SnowCD 下载 `_ 页面下载最新版本的 SnowCD。
使用 Windows 安装程序运行 MSI 文件。

第 3 步：运行 SnowCD¶

在 macOS 和 Linux 环境中运行 SnowCD 之前，可将其目录添加到 $PATH。在 Windows 环境中，可将 SnowCD 添加到环境变量。

在 macOS 或 Linux 环境中，可通过执行 snowcd <path_to_allowlist.json> [flags] 从命令行运行 snowcd 可执行文件。
在 Windows 环境中，可执行 snowcd.exe <path_to_allowlist.json> [flags]。

小技巧

如需查看 snowcd 支持的标记的完整说明，请执行 snowcd -h。

如果所有检查都有效，SnowCD 会返回在多少个主机上执行了多少次检查，并附带 All checks passed 消息，如下所示。

Performing 30 checks on 12 hosts
All checks passed

如果您尝试运行 SnowCD，而不从 SELECT SYSTEM$ALLOWLIST() 传递 JSON 允许列表信息，则会显示以下错误消息，提醒您包含该文件，以及当前支持的标记列表、其数据类型（如适用）和标记的简要描述。

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

如果 SnowCD 检测到不正确的设置或配置，则会显示有关失败的检查的信息以及故障排除建议。例如，下面的响应指示存在无效的主机名。

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

通过 HTTP 代理使用 SnowCD¶

SnowCD 可针对 HTTP 代理运行以确定其连接状态。

重要

目前，Snowflake 不支持 SSL 终结代理服务器。

在配置防火墙和代理服务器允许列表时，使用 SSL 直通（即绕过 SSL 解密）。

使用 Linux 作为代表性示例，执行以下命令以针对代理运行 SnowCD，并在必要时替换标志值。

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

日志记录是可选的，可将两个日志记录标记添加到代理命令中。必须包含日志文件的路径，以确保在运行命令时执行日志记录。

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

执行此命令后，您可以在 test.log 文件中查看跟踪记录。