Snowpark Container Services: サービスおよびジョブに関するその他の考慮事項¶

Snowflakeへの接続¶

Snowflakeは、サービス/ジョブコード内でSnowflakeクライアントを構成するために、以下の環境変数を提供します。

• SNOWFLAKE_ACCOUNT: サービスが現在実行されているSnowflakeアカウントの名前を提供します。

• SNOWFLAKE_HOST: Snowflakeへの接続に使用するホスト名を指定します。

また、Snowflakeはコンテナー内の OAuth トークンを /snowflake/session/token という名前のファイルで提供します。接続を作成する場合は、このトークンをコネクタに提供します。

コンテナーからSnowflakeへの接続を作成するときには、 SNOWFLAKE_HOST、 SNOWFLAKE_ACCOUNT、および OAuth トークンを使用する必要があります。SNOWFLAKE_HOST を使用せずに OAuth トークンを使用することはできず、 OAuth トークンをSnowpark Container Services外部で使用することはできません。詳細については、 SQL を実行するための OAuth トークンの使用 をご参照ください。

例

• チュートリアル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.com になります。詳細については、 ネットワークエグレス をご参照ください。

  • アカウントのSnowflake APIホスト名に一致するネットワークルールを作成します。

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

    Copy

  • 先行するネットワークルールを使用して統合を作成します。

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

    Copy

SQL を実行するためのデータベースとスキーマコンテキストを設定します。¶

このセクションでは、2つの概念について説明します。

• サービス/ジョブを作成するデータベースとスキーマを決定するためにSnowflakeが使用するロジック。

• Snowflakeがこの情報をコンテナーに伝え、コンテナーコードが同じデータベースとスキーマコンテキストで SQL を実行できるようにするためのメソッド。

Snowflakeは以下のロジックを使用して、サービス/ジョブを作成するデータベースとスキーマを決定します。

• サービスの場合、Snowflakeは CREATE SERVICE コマンドで提供されたサービス名を使用して、サービスのデータベースとスキーマコンテキストを決定します。

  • 例1: 次の CREATE SERVICE コマンドは、サービス名として test_service を指定します。

    CREATE SERVICE test_service IN COMPUTE POOL ...
    

    Copy

    Snowflakeは、このサービスを現在のデータベースとスキーマに配置します。

  • 例2: 次の CREATE SERVICE コマンドは完全修飾サービス名を指定します。

    CREATE SERVICE test_db.test_schema.test_service IN COMPUTE POOL ...
    

    Copy

    Snowflakeは、現在のスキーマに関係なく、指定されたデータベース（test_db）とスキーマ（test_schema）にサービスを配置します。

• ジョブの場合、ジョブを作成するときに EXECUTE SERVICE コマンドを使用してジョブ名を指定することはありません。

  EXECUTE SERVICE IN COMPUTE POOL ..
  

  Copy

  この場合は、どこにもジョブを配置する機会がありません。したがって、Snowflakeはジョブを現在のデータベースとスキーマに配置します。異なるスキーマでジョブに SQL ステートメントを実行させる場合は、異なるスキーマコンテキストを使用することができます。例:

  USE ROLE test_role;
  USE DATABASE tutorial_db;
  
  USE SCHEMA schema1;
  -- Execute using tutorial_db and schema1
  EXECUTE SERVICE IN COMPUTE POOL ...
  
  USE SCHEMA schema2;
  -- execute service again, using schema2
  EXECUTE SERVICE IN COMPUTE POOL ...
  

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

SQL を実行するための OAuth トークンの使用¶

Snowflakeが提供するすべてのクライアントは、認証方法として OAuth をサポートしています。Snowflakeと合わせてサービス/ジョブコンテナーも OAuth メカニズムを使用して認証します。たとえば、コンテナーが 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はコンテナーを実行し、コンテナー内の /snowflake/session/token にコンテナーが使用するOauthトークンを提供します。

この 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 をご参照ください。

ネットワークエグレス¶

アプリケーション（ジョブまたはサービス）コードは、インターネットへのアクセスを必要とする場合があります。デフォルトでは、アプリケーションコンテナーはインターネットにアクセスする権限を持っていません。 外部アクセス統合（EAIs） を使用してインターネットアクセスを有効にする必要があります。

通常、ジョブやサービスから許可される外部アクセスを管理するために、アカウント管理者は EAIs を作成します。アカウント管理者は、開発者がジョブやサービスを実行するために使用する特定のロールに EAI の使用権限を付与できます。

次の例は、ネットワークルールを使用して指定された特定の宛先へのエグレストラフィックを許可する EAI を作成するステップの概要を示しています。その後、特定のインターネット宛先へのリクエストを許可するジョブやサービスを作成するときに、 EAI を参照します。

例

アプリケーション（ジョブまたはサービス）のコードが、以下の宛先にリクエストを送信するとします。

• HTTPS が、translation.googleapis.comにリクエストする

• HTTP と HTTPS が、google.comにリクエストする

以下のステップに従って、ジョブやサービスがインターネット上のこれらのドメインにアクセスできるようにします。

1. 外部アクセス統合（EAI）を作成するこれには適切な権限が必要です。たとえば、 ACCOUNTADMIN ロールを使用して EAI を作成することができます。これは2段階のプロセスです。

   1. CREATE NETWORK RULE コマンドを使用して、アクセスを許可する外部宛先をリストした1つ以上のエグレスネットワークルールを作成します。この例は1つのネットワークルールで実現できますが、説明のために2つのネットワークルールを作成します。

      1. translate_network_rule という名前のネットワークルールを作成します。

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

         Copy

         このルールは、 translation.googleapis.com の宛先への TCP 接続を許可します。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 に接続できます。

      Snowpark Container Servicesは、ポート22、80、443、1024+を許可するネットワークルールのみをサポートします。参照されているネットワークルールが他のポートへのアクセスを許可している場合、サービスの作成は失敗します。追加のポートが必要な場合は、担当者にお問い合わせください。

      注釈

      ジョブまたはサービスが HTTP または HTTPS リクエストをインターネット上の任意の宛先に送信できるようにするには、 VALUE_LIST プロパティでドメインとして「0.0.0.0」を指定します。以下のネットワークルールは、インターネット上の任意の宛先に「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） を作成し、先行する2つのエグレスネットワークルールが許可されることを指定します。

      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 の使用権限と参照されるシークレットの読み取り権限が必要です。ACCOUNTADMIN ロールを使用してサービスやジョブを作成することはできません。

   • サービスを作成します。

     USE ROLE test_role;
     
     CREATE SERVICE eai_service
       IN COMPUTE POOL MYPOOL
       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
       $$
       EXTERNAL_ACCESS_INTEGRATIONS = (google_apis_access_integration);
     

     Copy

     この例の CREATE SERVICE リクエストは、インラインサービス仕様を使用し、 EAI を含むようにオプションの EXTERNAL_ACCESS_INTEGRATIONS プロパティを指定します。EAI は、サービスから特定の宛先へのエグレストラフィックを許可するネットワークルールを指定します。

   • ジョブを作成します。

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

     Copy

     この例の EXECUTE SERVICE コマンドは、インライン仕様と、 EAI を含めるためのオプション EXTERNAL_ACCESS_INTEGRATIONS プロパティを指定します。これは、ジョブから EAI が許可するネットワークルールで指定された宛先への、エグレストラフィックを許可します。

コンテナー間のネットワーク通信¶

次の2つを考慮します。

• サービスインスタンスのコンテナー間の通信: サービスインスタンスが複数のコンテナーを実行する場合、これらのコンテナーはlocalhostを介して相互に通信できます（サービス仕様でエンドポイントを定義する必要はありません）。

• 複数のサービス/ジョブまたは複数のサービスインスタンスにまたがるコンテナー間の通信: 異なるサービス（または同じサービスの異なるインスタンス）に属するコンテナーは、仕様ファイルで定義されたエンドポイントを使用して通信できます。詳細については、 サービス間通信 をご参照ください。

シークレットを環境変数として引き渡し¶

コンテナーにSnowflakeシークレットを環境変数として渡すには、 containers.secrets フィールドを含めます。

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

secretKeyRef: この値はSnowflakeシークレットの型によって異なります。可能な値:

• username、またはSnowflakeシークレットが password 型の場合は 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: 指定されたこのディレクトリにあるシークレットキーごとに1つのファイルが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'