Snowpark Container Services: 서비스 및 작업의 추가 고려 사항¶

Snowflake에 연결하기¶

Snowflake는 서비스/작업 코드에서 Snowflake 클라이언트를 구성할 수 있도록 다음 환경 변수를 제공합니다.

• SNOWFLAKE_ACCOUNT: 현재 서비스가 실행 중인 Snowflake 계정의 이름을 제공합니다.

• SNOWFLAKE_HOST: Snowflake에 연결하는 데 사용되는 호스트 이름을 제공합니다.

Snowflake는 또한 /snowflake/session/token 이라는 파일의 컨테이너에 OAuth 토큰을 제공합니다. 연결을 생성할 때 이 토큰을 커넥터에 제공합니다.

컨테이너에서 Snowflake에 대한 연결을 생성할 때 SNOWFLAKE_HOST, SNOWFLAKE_ACCOUNT 및 OAuth 토큰을 사용해야 합니다. SNOWFLAKE_HOST도 사용해야 OAuth 토큰을 사용할 수 있으며, Snowpark Container Services 외부에서는 OAuth 토큰을 사용할 수 없습니다. 자세한 내용은 OAuth 토큰을 사용하여 SQL 실행하기 섹션을 참조하십시오.

예

• 자습서 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 실행을 위한 데이터베이스 및 스키마 컨텍스트 구성하기¶

이 섹션에서는 다음 두 가지 개념을 설명합니다.

• 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

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는 컨테이너를 실행하고 컨테이너가 컨테이너 내의 /snowflake/session/token 위치에서 사용할 Oauth 토큰을 제공합니다.

이 OAuth 토큰에 대한 다음 세부 정보를 참고하십시오.

• 콘텐츠는 10분 후에 만료되고 Snowflake는 몇 분마다 이 파일을 새로 고치므로 사용하기 직전에 /snowflake/session/token 파일의 내용을 읽어야 합니다. 컨테이너가 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 을 참조하십시오.

네트워크 송신¶

애플리케이션(작업 또는 서비스) 코드에 인터넷 액세스 권한이 필요할 수 있습니다. 기본적으로 애플리케이션 컨테이너에는 인터넷에 액세스할 권한이 없습니다. EAI(External Access Integration) 를 사용하여 인터넷 액세스를 활성화해야 합니다.

일반적으로, 작업과 서비스에서 허용되는 외부 액세스를 관리하려면 계정 관리자가 EAI를 생성해야 합니다. 그러면 계정 관리자는 개발자가 작업이나 서비스를 실행하는 데 사용하는 특정 역할에 EAI 사용 권한을 부여할 수 있습니다.

다음 예에서는 네트워크 규칙을 사용하여 지정된 특정 대상으로의 송신 트래픽을 허용하는 EAI를 생성하는 단계를 간략하게 설명합니다. 그런 다음 작업이나 서비스를 생성할 때 EAI를 참조하여 특정 인터넷 대상에 대한 요청을 허용합니다.

예

애플리케이션(작업 또는 서비스) 코드가 다음 대상으로 요청을 보내도록 하는 경우를 가정해 보겠습니다.

• translation.googleapis.com에 대한 HTTPS 요청

• google.com에 대한 HTTP 및 HTTPS 요청

작업이나 서비스가 인터넷에서 이러한 도메인에 액세스할 수 있도록 하려면 다음 단계를 따르십시오.

1. EAI(External Access Integration) 만들기 이를 위해서는 적절한 권한이 필요합니다. 예를 들어, ACCOUNTADMIN 역할을 사용하여 EAI를 생성할 수 있습니다. 이는 다음과 같은 2단계 프로세스입니다.

   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

         이 규칙을 사용해 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(외부 액세스 통합)를 생성합니다.

      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가 허용하는 네트워크 규칙에 지정된 대상으로의 송신 트래픽이 허용됩니다.

컨테이너 간 네트워크 통신¶

다음 두 가지 고려 사항이 있습니다.

• 서비스 인스턴스의 컨테이너 간 통신: 서비스 인스턴스가 여러 컨테이너를 실행하는 경우 이러한 컨테이너는 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'