Snowpark Container Services：服务的其他注意事项¶

连接到 Snowflake¶

Snowflake 提供以下环境变量，供您在服务代码中配置 Snowflake 客户端：

• SNOWFLAKE_ACCOUNT： 提供服务当前运行使用的 Snowflake 账户的 账户定位器。

• SNOWFLAKE_HOST： 提供用于连接到 Snowflake 的主机名。

Snowflake 还在名为 /snowflake/session/token 的文件内的容器中提供 OAuth 令牌。创建连接时，向连接器提供此令牌。

从容器创建到 Snowflake 的连接时，必须使用 SNOWFLAKE_HOST、SNOWFLAKE_ACCOUNT 和 OAuth 令牌。您不能使用 OAuth 令牌而不使用 SNOWFLAKE_HOST，也不能在 Snowpark Container Services 外使用 OAuth 令牌。有关更多信息，请参阅 使用 OAuth 令牌执行 SQL。

有关使用各种 Snowflake 驱动程序的示例代码，请参阅 ` Snowflake 连接示例 <https://github.com/Snowflake-Labs/sf-samples/tree/main/samples/spcs/sf-connection (https://github.com/Snowflake-Labs/sf-samples/tree/main/samples/spcs/sf-connection)>`_。

示例

• 在 :doc:` 教程 2 <tutorials/tutorial-2>` （请参阅 main.py）中，代码按如下方式读取环境变量：

  SNOWFLAKE_ACCOUNT = os.getenv('SNOWFLAKE_ACCOUNT')
  SNOWFLAKE_HOST = os.getenv('SNOWFLAKE_HOST')
  

  Copy

  代码将这些变量传递给所选 Snowflake 客户端的连接创建代码。容器使用这些凭据创建一个新会话，并将所有者角色作为主要角色，来执行查询。以下示例代码是使用 Python 创建 Snowflake 连接所需的最简代码：

  def get_login_token():
    with open('/snowflake/session/token', 'r') as f:
      return f.read()
  
  conn = snowflake.connector.connect(
    host = os.getenv('SNOWFLAKE_HOST'),
    account = os.getenv('SNOWFLAKE_ACCOUNT'),
    token = get_login_token(),
    authenticator = 'oauth'
  )
  

  Copy

• 当使用默认主机（即，在创建连接时不纳入 host 实参）时，将支持使用其他形式的身份验证（如用户名和密码）连接到 Snowflake。例如，以下连接指定要进行身份验证的用户名和密码：

  conn = snowflake.connector.connect(
    account = os.getenv('SNOWFLAKE_ACCOUNT'),
    user = '<user-name>',
    password = <password>
  )
  

  Copy

  使用默认主机需要与网络规则进行外部访问集成，该规则允许从服务访问您账户的 Snowflake 主机名。例如，如果您的账户名称是 MyAccount，则主机名将为 myaccount.snowflakecomputing.cn。有关更多信息，请参阅 配置网络出口。

  • 创建与您账户的 Snowflake API 主机名匹配的网络规则：

    CREATE OR REPLACE NETWORK RULE snowflake_egress_access
      MODE = EGRESS
      TYPE = HOST_PORT
      VALUE_LIST = ('myaccount.snowflakecomputing.cn');
    

    Copy

  • 使用上述网络规则创建集成：

    CREATE EXTERNAL ACCESS INTEGRATION snowflake_egress_access_integration
      ALLOWED_NETWORK_RULES = (snowflake_egress_access)
      ENABLED = true;
    

    Copy

配置用于执行 SQL 的数据库和架构上下文¶

本节介绍两个概念：

• Snowflake 用于确定要在其中创建服务的数据库和架构的逻辑。

• Snowflake 将此信息传达给容器，从而使容器代码能够在同一数据库和架构上下文中执行 SQL 的方法。

Snowflake 使用服务名称来确定要在其中创建服务的数据库和架构：

• 示例 1：在以下 CREATE SERVICE 和 EXECUTE JOB SERVICE 命令中，服务名称不会显式指定数据库和架构名称。Snowflake 在当前数据库和架构中创建服务和作业服务。

  -- Create a service.
  CREATE SERVICE test_service IN COMPUTE POOL ...
  
  -- Execute a job service.
  EXECUTE JOB SERVICE
    IN COMPUTE POOL tutorial_compute_pool
    NAME = example_job_service ...
  

  Copy

• 示例 2：在以下 CREATE SERVICE 和 EXECUTE JOB SERVICE 命令中，服务名称包括数据库和架构名称。Snowflake 在指定的数据库 (test_db) 和架构 (test_schema) 中创建服务和作业服务，无论当前架构如何。

  -- Create a service.
  CREATE SERVICE test_db.test_schema.test_service IN COMPUTE POOL ...
  
  -- Execute a job service.
  EXECUTE JOB SERVICE
    IN COMPUTE POOL tutorial_compute_pool
    NAME = test_db.test_schema.example_job_service ...
  

  Copy

当 Snowflake 启动服务时，它会使用以下环境变量向正在运行的容器提供数据库和架构信息：

• SNOWFLAKE_DATABASE

• SNOWFLAKE_SCHEMA

容器代码可以使用连接代码中的环境变量来确定要使用的数据库和架构，如以下示例所示：

conn = snowflake.connector.connect(
  host = os.getenv('SNOWFLAKE_HOST'),
  account = os.getenv('SNOWFLAKE_ACCOUNT'),
  token = get_login_token(),
  authenticator = 'oauth',
  database = os.getenv('SNOWFLAKE_DATABASE'),
  schema = os.getenv('SNOWFLAKE_SCHEMA')
)

示例

在 教程 2 中，您可以创建与 Snowflake 连接并执行 SQL 语句的 Snowflake 作业服务。以下步骤总结了教程代码如何使用环境变量：

1. 在通用设置中（请参阅 通用设置 部分），您可以创建资源，包括数据库和架构。您还可以为会话设置当前数据库和架构：

   USE DATABASE tutorial_db;
   ...
   USE SCHEMA data_schema;
   

   Copy

2. 创建作业服务（通过运行 EXECUTE JOB SERVICE）后，Snowflake 启动容器，并将容器中的以下环境变量设置为会话的当前数据库和架构：

   • 将 SNOWFLAKE_DATABASE 设置为“TUTORIAL_DB”

   • 将 SNOWFLAKE_SCHEMA 设置为“DATA_SCHEMA”

3. 作业代码（请参阅教程 2 中的 main.py）读取以下环境变量：

   SNOWFLAKE_DATABASE = os.getenv('SNOWFLAKE_DATABASE')
   SNOWFLAKE_SCHEMA = os.getenv('SNOWFLAKE_SCHEMA')
   

   Copy

4. 作业代码将数据库和架构设置为执行 SQL 语句（main.py 中的 run_job() 函数）的上下文:

   {
      "account": SNOWFLAKE_ACCOUNT,
      "host": SNOWFLAKE_HOST,
      "authenticator": "oauth",
      "token": get_login_token(),
      "warehouse": SNOWFLAKE_WAREHOUSE,
      "database": SNOWFLAKE_DATABASE,
      "schema": SNOWFLAKE_SCHEMA
   }
   ...
   

   Copy

   备注

   SNOWFLAKE_ACCOUNT、SNOWFLAKE_HOST、SNOWFLAKE_DATABASE、SNOWFLAKE_SCHEMA 是 Snowflake 为应用程序容器生成的环境变量，但 SNOWFLAKE_WAREHOUSE 不是（教程 2 应用程序代码创建了此变量，因为 Snowflake 不会将仓库名称传递给容器）。

为容器指定仓库¶

如果服务连接到 Snowflake，以在 Snowflake 仓库中执行查询，则您可以使用以下选项来指定仓库：

• 在应用程序代码中指定仓库。 在启动 Snowflake 会话以在代码中运行查询时，在连接配置中指定仓库。有关示例，请参阅 教程 2。

• 在创建服务时指定默认仓库。 在 CREATE SERVICE （或 EXECUTE JOB SERVICE ）命令中指定可选的 QUERY_WAREHOUSE 参数，以提供默认仓库。如果应用程序代码未在连接配置中提供仓库，则 Snowflake 将使用默认仓库。使用 ALTER SERVICE 命令更改默认仓库。

如果同时使用这两种方法指定仓库，则将使用应用程序代码中指定的仓库。

使用 OAuth 令牌执行 SQL¶

所有 Snowflake 提供的客户端都支持使用 OAuth 作为身份验证方式。服务容器还使用 OAuth 机制来向 Snowflake 进行身份验证。例如，当容器要执行时 SQL 时，容器将创建与 Snowflake 的连接，类似于任何其他 Snowflake 客户端：

def get_login_token():
  with open('/snowflake/session/token', 'r') as f:
    return f.read()

conn = snowflake.connector.connect(
  host = os.getenv('SNOWFLAKE_HOST'),
  account = os.getenv('SNOWFLAKE_ACCOUNT'),
  token = get_login_token(),
  authenticator = 'oauth'
)

当您创建服务时，Snowflake 会运行容器，并为容器提供 Oauth 令牌，以便在容器中的以下位置使用：/snowflake/session/token。

请注意以下有关此 OAuth 令牌的详细信息：

• Snowflake 每隔几分钟就会刷新 /snowflake/session/token 文件的内容。每个令牌的有效期最长为一小时。容器成功连接到 Snowflake 后，过期时间将不适用于该连接（与用户直接创建的任何会话一样）。

• 此 OAuth 令牌仅在特定的 Snowflake 服务中有效。您无法复制 OAuth 令牌并在服务外使用它。

• 使用 OAuth 令牌，容器作为服务用户与 Snowflake 连接，并使用服务的所有者角色。

• 使用 OAuth 令牌进行连接将创建一个新会话。OAuth 令牌不与任何现有 SQL 会话关联。

  备注

  执行存储过程和执行服务间的一个显著差异是，存储过程与运行存储过程的 SQL 在同一会话中运行。但是，每次容器建立新连接时，您都会创建一个新会话。

使用调用方限从容器内部连接到 Snowflake¶

容器通过以服务用户身份连接到 Snowflake 并使用授予服务特权的服务所有者角色来执行查询。在某些应用场景中，您可能需要使用最终用户而不是服务用户的上下文来执行查询。在此上下文中会用到调用方的权限功能。

例如，假设您要创建一个公开公共端点的服务，以提供使用存储在 Snowflake 中的数据来显示仪表板的 Web 应用程序。您授予 Snowflake 账户中的其他用户对仪表板的访问权限（通过授予这些用户 服务角色）。当这些最终用户中的任何一个登录到仪表板时，您希望仪表板仅显示用户有权访问的数据。

但是，无论哪个最终用户连接到端点，由于容器默认情况下使用服务用户和服务所有者角色执行查询，仪表板都只会显示服务所有者角色有权访问的数据。因此，用户仪表板中的数据不限于最终用户有权访问的内容，这导致用户可以访问不应有权访问的数据。

要限制仪表板仅显示登录用户可访问的数据，应用程序容器需要使用授予最终用户的权限执行 SQL。您可以通过在应用程序中使用调用方权限来启用此功能。

ALTER USER my_user SET DEFAULT_SECONDARY_ROLES = ( 'ALL' );

-- Permissions to resolve the table's name.
GRANT CALLER USAGE ON DATABASE <db_name> TO ROLE <service_owner_role>;
GRANT CALLER USAGE ON SCHEMA <schema_name> TO ROLE <service_owner_role>;
-- Permissions to use a warehouse
GRANT CALLER USAGE ON WAREHOUSE <warehouse_name> TO ROLE <service_owner_role>;
-- Permissions to query the table.
GRANT CALLER SELECT ON TABLE T1 TO ROLE <service_owner_role>;

入口网页浏览器身份验证注销¶

如果您正在构建一个作为服务运行的 Web 应用程序，可以选择允许用户通过重定向到 /sfc-endpoint/logout 来从您的应用注销。

注销后，用户需要重新对 Snowflake 进行身份验证，才能访问服务的公共端点。

入口和 Web 应用程序安全性¶

您可以使用公共端点支持（网络入口）创建用于 Web 托管的 Snowpark Container Services。为了提高安全性，Snowflake 采用代理服务来监控从客户端到服务的传入请求以及从服务到客户端的传出响应。本节介绍代理的作用以及它如何影响部署到 Snowpark Container Services 的服务。

例如：

• 如果请求使用了被禁止的 HTTP 方法，代理不会转发传入的 HTTP 请求。

• 如果响应中的 Content-Type 标头指出响应包含可执行文件，则代理会向客户端发送 403 响应。

此外，代理还可以在请求和响应中注入新的标头并更改现有标头，同时兼顾容器和数据安全性。

例如，在收到请求后，服务可能会在响应中，将 HTML、JavaScript、CSS 以及其他网页内容发送到客户端浏览器。浏览器中的网页是服务的一部分，充当用户界面。出于安全原因，如果服务有限制（例如，限制与其他站点建立网络连接），您可能还希望服务网页具有同样的限制。

默认情况下，服务访问互联网的权限存在限制。在大多数情况下，浏览器还应限制客户端应用程序访问互联网和潜在的数据共享行为。如果设置外部访问集成 (EAI) 以允许服务访问 example.com （请参阅 配置网络出口 ），服务网页也应该能够通过浏览器访问 example.com。

Snowflake 代理通过在响应中添加 Content-Security-Policy (CSP) 标头，对服务和网页应用同样的网络限制。默认情况下，代理会在响应中添加基线 CSP，以防范常见的安全威胁。浏览器安全性旨在尽最大努力在功能和安全性之间取得平衡，确保这个基准适用于您的用例是大家共同的责任。此外，如果服务配置为使用 EAI，代理将对网页从 EAI 到 CSP 应用同样的网络规则。此 CSP 使浏览器中的网页能够访问与服务相同的站点。

Snowflake 提供 CORS 支持，您可在服务规范中对其进行配置。

Snowflake 代理会返回服务规范中定义的 CORS 设置。请注意，代理会删除服务返回的任何 CORS 标头。

以下 CORS 标头为默认设置：

• Access-Control-Expose-Headers 标头始终会报告以下标头名称，此外还包括端点服务规范中配置的标头信息。

  • X-Frame-Options

  • Cross-Origin-Opener-Policy

  • Cross-Origin-Resource-Policy

  • X-Content-Type-Options

  • Cross-Origin-Embedder-Policy

  • Content-Security-Policy-Report-Only

  • Content-Security-Policy

• Access-Control-Max-Age 设置为两小时。

• Access-Control-Allow-Credentials 设置为“true”。

此外，Snowflake 会将 Vary 标头的值设为 Origin，以告知浏览器：根据 Origin 的值不同，Access-Control-Allow-Origin 的返回值可能会变化。

发起 CORS 请求需要身份验证标头。您可以按照教程 1 获取 JWT 令牌（见 第 5 步）。这不能通过浏览器完成，因为令牌交换服务器不支持 CORS。不过，只要配置了允许从服务容器访问客户 Snowflake 账户的适当网络策略，任何 Snowpark Container Services 服务都可以实现此操作。

以下各节介绍了 Snowflake 代理如何处理对服务的传入请求，并修改服务对客户端的传出响应。

入口和 CORS 注意事项¶

默认情况下，浏览器会阻止一个服务器上的 Web 应用程序向另一个不同主机名的服务器发送请求。例如，如果您在 Snowpark Container Services 之外托管一个 Web 应用程序，而该应用程序需要与部署在 Snowpark Container Services 内的后端服务进行交互，则适用此限制。

CORS（跨源资源共享）使 Snowpark Container Services 能够告诉浏览器允许来自其环境外托管的 Web 应用程序的请求。您可以配置每个公共端点，指定它如何响应 CORS 预检请求和标准请求。

Snowflake 代理始终覆盖以下响应标头：

• Access-Control-Allow-Origin

• Access-Control-Allow-Methods

• Access-Control-Allow-Headers

• Access-Control-Expose-Headers

• Access-Control-Max-Age

• Access-Control-Allow-Credentials

当以下任一情况为 true 时，Snowflake 代理不会在响应中包含任何此类 CORS 标头：

• 服务端点未配置 CORS。也就是说，服务规范中没有 corsSettings

• 已为服务端点配置 CORS，但请求中的 Origin 标头与服务规范中指定的 Access-Control-Allow-Origin 字段不匹配

在服务规范中，您可以为每个公共端点配置 CORS 设置。当请求中的 origin 标头与规范中为端点指定的 Access-Control-Allow-Origin 字段相匹配时，代理就会在响应中包含规范中定义的 CORS 标头，并作如下调整：

• Access-Control-Allow-Origin：返回请求中的 Origin 标头。

• Access-Control-Expose-Headers：将您配置的允许标头列表与这些始终公开的标头合并：X-Frame-Options、Cross-Origin-Opener-Policy、Cross-Origin-Resource-Policy、X-Content-Type-Options、Cross-Origin-Embedder-Policy、Content-Security-Policy-Report-Only、Content-Security-Policy。

• Access-Control-Max-Age：设置为两小时。

• Access-Control-Allow-Credentials：设置为“true”。

入口和 SSO 注意事项¶

当从互联网访问公共端点时，您可能会发现用户名/密码身份验证正常，但 SSO 导致空白页或错误：“OAuth client integration with the given client ID is not found.”

如果将旧版本的联合身份验证 (SSO) 用于 Snowflake，而不是使用 配置 Snowflake 以使用联合身份验证 中说明的较新安全集成版本，就会出现这种情况。执行以下操作以验证：

1. 运行以下查询：

   SHOW PARAMETERS LIKE 'SAML_IDENTITY_PROVIDER' IN ACCOUNT;
   

   Copy

   如果您设置了此参数，那么在某些时候您使用的是旧版本的联合身份验证。

2. 如果设置了前面的参数，请运行以下查询以查看是否进行了 SAML 安全集成：

   SHOW INTEGRATIONS;
   SELECT * FROM TABLE(RESULT_SCAN(LAST_QUERY_ID())) WHERE "type" = 'SAML2';
   

   Copy

   如果您没有任何 SAML2 类型的集成，那么您使用的是旧版本的联合身份验证。

在这种情况下，解决方案是从旧版本联合身份验证迁移到新的集成式联合身份验证。有关更多信息，请参阅 迁移到 SAML2 安全集成。

使用专用连接的网络出口¶

您可能会选择通过 专用连接端点 来引导服务的出口流量，而不是通过公共互联网路由网络出口。

首先需要在 Snowflake 账户中创建专用连接端点。然后配置网络规则以允许传出流量使用 专用连接。设置外部访问集成 (EAI) 的过程与上一节中所述的过程相同。

例如，如果您想通过专用连接启用服务对 Amazon S3 桶的出站互联网访问，请执行以下操作：

1. 启用自维护端点服务 (Amazon S3) 的专用链接连接。有关分步说明，请参阅 Amazon S3 的 AWS 专用链接 (https://docs.aws.amazon.com/AmazonS3/latest/userguide/privatelink-interface-endpoints.html)。

2. 调用 SYSTEM$PROVISION_PRIVATELINK_ENDPOINT 系统函数，以在 Snowflake VNet 中预置专用连接端点。这使 Snowflake 能够使用专用连接连接到外部服务（在本示例中为 Amazon S3）。

   USE ROLE ACCOUNTADMIN;
   
   SELECT SYSTEM$PROVISION_PRIVATELINK_ENDPOINT(
     'com.amazonaws.us-west-2.s3',
     '*.s3.us-west-2.amazonaws.com'
   );
   

   Copy

3. 在云提供商账户中，批准该端点。在本示例中，对于 Amazon AWS，请参阅 AWS 文档中的 接受或拒绝连接请求 (https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#accept-reject-connection-requests)。 另外，要批准 Azure 中的端点，请参阅 Azure 文档 (https://learn.microsoft.com/en-us/azure/private-link/manage-private-endpoint?tabs=manage-private-link-powershell#private-endpoint-connections)。

4. 使用 CREATE NETWORK RULE 命令创建出口网络规则，指定您希望允许访问的外部目的地。

   CREATE OR REPLACE NETWORK RULE private_link_network_rule
     MODE = EGRESS
     TYPE = PRIVATE_HOST_PORT
     VALUE_LIST = ('<bucket-name>.s3.us-west-2.amazonaws.com');
   

   Copy

   TYPE 参数值已设置为 PRIVATE_HOST_PORT。这表示网络规则允许传出网络流量使用 专用连接。

5. 创建 EAI 并使用它创建服务的其余步骤与上一节中说明的步骤相同（请参阅 配置网络出口）。

有关使用专用连接端点的更多信息，请参阅以下内容：

• 管理专用连接端点：AWS

• 管理专用连接端点：Azure

指定 Snowflake 密钥¶

通过名称或引用指定 Snowflake 密钥（引用仅适用于原生应用程序场景）：

• 通过名称传递 Snowflake 密钥： 您可以将密钥名称作为 snowflakeSecret 字段值传递。

  ...
  secrets:
  - snowflakeSecret:
      objectName: '<secret-name>'
    <other info about where in the container to copy the secret>
    ...
  

  Copy

  请注意，您可以选择指定 <secret-name> directly as the `` snowflakeSecret`` 值。

• 通过引用传递 Snowflake 密钥： 使用 Snowpark Container Services 创建原生应用程序（带有容器的应用程序）时，应用程序生产者和使用者使用不同的 Snowflake 账户。在某些情况下，已安装的 Snowflake 原生应用程序需要访问使用者账户中存在于 APPLICATION 对象外部的现有密钥对象。在这种情况下，开发者可以使用“secrets by reference”规范语法来处理凭据，如下所示：

  containers:
  - name: main
    image: <url>
    secrets:
    - snowflakeSecret:
        objectReference: '<reference-name>'
      <other info about where in the container to copy the secret>
  

  Copy

  请注意，该规范使用 objectReference``（而不是 ``objectName）来提供密钥引用名称。

指定容器内的密钥位置¶

您可以告诉 Snowflake 将密钥作为环境变量放在容器中，或者将它们写入本地容器文件中。

containers:
- name: main
  image: <url>
  secrets:
  - snowflakeSecret: <secret-name>
    secretKeyRef: username | password | secret_string |  'access_token'
    envVarName: '<env-variable-name>'

CREATE SECRET testdb.testschema.my_secret_object
  TYPE = password
  USERNAME = 'snowman'
  PASSWORD = '1234abc';

containers:
- name: main
  image: <url>
  secrets:
  - snowflakeSecret: testdb.testschema.my_secret_object
    secretKeyRef: username
    envVarName: LOGIN_USER
  - snowflakeSecret: testdb.testschema.my_secret_object
    secretKeyRef: password
    envVarName: LOGIN_PASSWORD

CREATE SECRET testdb.testschema.my_secret
  TYPE=generic_string
  SECRET_STRING='
       some_magic: config
  ';

containers:
- name: main
  image: <url>
  secrets:
  - snowflakeSecret: testdb.testschema.my_secret
    secretKeyRef: secret_string
    envVarName: GENERIC_SECRET

containers:
- name: <name>
  image: <url>
  ...
  secrets:
  - snowflakeSecret: <snowflake-secret-name>
    directoryPath: '<local directory path in the container>'

CREATE SECRET testdb.testschema.my_secret_object
  TYPE = password
  USERNAME = 'snowman'
  PASSWORD = '1234abc';

containers:
- name: main
  image: <url>
  secrets:
  - snowflakeSecret: testdb.testschema.my_secret_object
    directoryPath: '/usr/local/creds'

CREATE SECRET testdb.testschema.my_secret
  TYPE=generic_string
  SECRET_STRING='
       some_magic: config
  ';

containers:
- name: main
  image: <url>
  secrets:
  - snowflakeSecret: testdb.testschema.my_secret
    directoryPath: '/usr/local/creds'

CREATE SECRET testdb.testschema.oauth_secret
  TYPE = OAUTH2
  OAUTH_REFRESH_TOKEN = '34n;vods4nQsdg09wee4qnfvadH'
  OAUTH_REFRESH_TOKEN_EXPIRY_TIME = '2023-12-31 20:00:00'
  API_AUTHENTICATION = my_integration;

containers:
- name: main
  image: <url>
  secrets:
  - snowflakeSecret: testdb.testschema.oauth_secret
    directoryPath: '/usr/local/creds'