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/session/token 文件的内容然后再立即使用，因为内容将在 10 分钟后过期，而 Snowflake 每隔几分钟就会刷新一次此文件。容器成功连接到 Snowflake 后，过期时间将不适用于该连接（与用户直接创建的任何会话一样）。

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

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

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

  备注

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

网络入口¶

要允许任何内容通过互联网与服务交互，请在服务规范文件中将服务侦听的网络端口声明为端点。这些端点控制入口。

默认情况下，服务端点是专用的。只有 服务函数 和 服务到服务通信 可以向专用端点发出请求。您可以将端点声明为公共端点，以允许通过互联网向端点发出请求。服务的所有者角色必须具有账户的 BIND SERVICE ENDPOINT 权限。

endpoints:
- name: <endpoint name>
  port: <port number>
  protocol : < TCP / HTTP / HTTPS >
  public: true

有关示例，请参阅 教程 1。

入口和 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 代理如何处理对服务的传入请求，并修改服务对客户端的传出响应。

网络出口¶

应用程序代码可能需要访问互联网。默认情况下，应用程序容器没有访问互联网的权限。您需要使用 外部访问集成 (EAIs) 启用互联网访问。

通常，您希望账户管理员创建 EAIs 来管理允许通过服务（包括作业服务）进行的外部访问。然后，账户管理员可以向开发者用于运行服务的特定角色授予 EAI 使用量。

以下示例概述了创建 EAI 的步骤，这允许出口流量流向使用网络规则制定的特定目的地。然后，您可以在创建服务时引用 EAI 以允许对特定互联网目的地的请求。

示例

假设您希望应用程序代码将请求发送到以下目的地：

• 向 translation.googleapis.com 发出 HTTPS 请求

• 向 google.com 发出 HTTP 和 HTTPS 请求

按照以下步骤操作，使服务能够访问互联网上的这些域：

1. 创建外部访问集成 (EAI)。这需要适当的权限。例如，您可以使用 ACCOUNTADMIN 角色来创建 EAI。这个过程分为两步：

   1. 使用 CREATE NETWORK RULE 命令创建一个或多个出口网络规则，列出您希望允许访问的外部目的地。您可以使用一个网络规则来完成此示例，但为便于说明，我们创建了两个网络规则：

      1. 创建名为 translate_network_rule 的网络规则：

         CREATE OR REPLACE NETWORK RULE translate_network_rule
           MODE = EGRESS
           TYPE = HOST_PORT
           VALUE_LIST = ('translation.googleapis.com');
         

         Copy

         此规则允许 TCP 连接到 translation.googleapis.com 目的地。VALUE_LIST 属性中的域未指定可选端口号，因此将使用默认端口 443 (HTTPS)。这使应用程序可以连接到以 https://translation.googleapis.com/ 开头的任何 URL。

      2. 创建名为 google_network_rule 的网络规则：

         CREATE OR REPLACE NETWORK RULE google_network_rule
           MODE = EGRESS
           TYPE = HOST_PORT
           VALUE_LIST = ('google.com:80', 'google.com:443');
         

         Copy

         这使应用程序可以连接到任何以 http://google.com/ 或 https://google.com/ 开头的 URL。

      备注

      对于 VALUE_LIST 参数，您必须提供完整的主机名。不支持通配符（例如，*.googleapis.com）。

      Snowpark Container Services 仅支持允许端口 22、80、443 和 1024+ 的网络规则。如果引用的网络规则允许访问其他端口，则服务创建将失败。如果您需要使用其他端口，请联系客户代表。

      备注

      要允许服务向互联网上的任何目的地发送 HTTP 或 HTTPS 请求，请指定“0.0.0.0”作为 VALUE_LIST 属性。以下网络规则允许在互联网上的任何位置发送“HTTP”和“HTTPS”请求。“0.0.0.0”仅支持端口 80 或 443。

      CREATE NETWORK RULE allow_all_rule
        TYPE = 'HOST_PORT'
        MODE= 'EGRESS'
        VALUE_LIST = ('0.0.0.0:443','0.0.0.0:80');
      

      Copy

   2. 创建外部访问集成 (EAI)，指定允许使用上述两个出口网络规则：

      CREATE EXTERNAL ACCESS INTEGRATION google_apis_access_integration
        ALLOWED_NETWORK_RULES = (translate_network_rule, google_network_rule)
        ENABLED = true;
      

      Copy

      现在，账户管理员可以向开发者授予集成使用量，以允许他们运行可以访问互联网上特定目的地的服务。

      GRANT USAGE ON INTEGRATION google_apis_access_integration TO ROLE test_role;
      

      Copy

2. 按照以下示例，通过提供 EAI 创建服务。创建服务的所有者角色需要 EAI 的 USAGE 权限和引用密钥的 READ 权限。请注意，您不能使用 ACCOUNTADMIN 角色来创建服务。

   • 创建服务：

     USE ROLE test_role;
     
     CREATE SERVICE eai_service
       IN COMPUTE POOL MYPOOL
       EXTERNAL_ACCESS_INTEGRATIONS = (GOOGLE_APIS_ACCESS_INTEGRATION)
       FROM SPECIFICATION
       $$
       spec:
         containers:
           - name: main
             image: /db/data_schema/tutorial_repository/my_echo_service_image:tutorial
             env:
               TEST_FILE_STAGE: source_stage/test_file
             args:
               - read_secret.py
         endpoints:
           - name: read
             port: 8080
       $$;
     

     Copy

     此示例 CREATE SERVICE 请求使用内联服务规范，并指定可选的 EXTERNAL_ACCESS_INTEGRATIONS 属性以纳入 EAI。EAI 指定允许从服务到特定目的地的出口流量的网络规则。

   • 执行作业服务：

     EXECUTE JOB SERVICE
       IN COMPUTE POOL tt_cp
       NAME = example_job_service
       EXTERNAL_ACCESS_INTEGRATIONS = (GOOGLE_APIS_ACCESS_INTEGRATION)
       FROM SPECIFICATION $$
       spec:
         container:
         - name: curl
           image: /tutorial_db/data_schema/tutorial_repo/alpine-curl:latest
           command:
           - "curl"
           - "http://google.com/"
       $$;
     

     Copy

     此示例 EXECUTE JOB SERVICE 命令指定内联规范和可选的 EXTERNAL_ACCESS_INTEGRATIONS 属性以纳入 EAI。这允许从作业到 EAI 允许的网络规则中指定的目的地的出口流量。

容器间的网络通信¶

有两个注意事项：

• 服务实例的容器之间的通信： 如果一个服务实例运行多个容器，这些容器可以通过 localhost 相互通信（无需在服务规范中定义端点）。

• 跨多个服务或多个服务实例的容器之间的通信： 属于不同服务（或同一服务的不同实例）的容器可以使用规范文件中定义的端点进行通信。有关更多信息，请参阅 服务到服务通信。

将密钥作为环境变量传递¶

要将容器 Snowflake 密钥作为环境变量传递，请纳入 containers.secrets 字段：

containers:
- name: main
  image: <url>
  secrets:
  - snowflakeSecret: <snowflake-secret-name>
    secretKeyRef: <secret-key-reference>
    envVarName: <env-variable-name>

secretKeyRef：此值取决于 Snowflake 密钥的类型。可能的值如下：

• 如果 Snowflake 密钥是 password 类型，则为 username 或 password。

• 如果 Snowflake 密钥是 generic_string 类型，则为 secret_string。

• 如果 Snowflake 密钥是 oauth2 类型，则为 access_token。

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

在本地容器文件中传递密钥¶

要使 Snowflake 密钥可用于本地容器文件中的应用程序容器，请纳入 containers.secrets 字段：

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

directoryPath：Snowflake 为此指定目录中的每个密钥填充一个文件；指定 secretKeyRef 不是必需的。

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.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'