Snowpark Container Services: considerações adicionais sobre serviços e tarefas¶

Conexão ao Snowflake¶

Snowflake fornece as seguintes variáveis de ambiente para você configurar um cliente Snowflake em seu código de serviço/trabalho:

• SNOWFLAKE_ACCOUNT: fornece o nome da conta Snowflake sob a qual o serviço está sendo executado no momento.

• SNOWFLAKE_HOST: fornece o nome do host usado para conectar-se ao Snowflake.

Snowflake também fornece um token OAuth no contêiner em um arquivo chamado /snowflake/session/token. Ao criar uma conexão, você fornece esse token ao conector.

Ao criar uma conexão com o Snowflake a partir de um contêiner, você deve usar SNOWFLAKE_HOST, SNOWFLAKE_ACCOUNT e o token OAuth. Você não pode usar o token OAuth sem usar também SNOWFLAKE_HOST e não pode usar o token OAuth fora do Snowpark Container Services. Para obter mais informações, consulte Como usar um token OAuth para executar SQL.

Exemplos

• No Tutorial 2 (consulte main.py), o código lê as variáveis de ambiente da seguinte maneira:

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

  Copy

  O código passa essas variáveis para um código de criação de conexão para o cliente Snowflake de sua escolha. O contêiner usa essas credenciais para criar uma nova sessão, com a função de serviço como função principal, para executar consultas. O código de exemplo a seguir é o mínimo necessário para criar uma conexão Snowflake em Python:

  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

• Quando você usa o host padrão (ou seja, você não inclui o argumento host ao criar uma conexão), há suporte para conexão ao Snowflake usando outras formas de autenticação (como nome de usuário e senha). Por exemplo, a conexão a seguir especifica o nome de usuário e a senha para autenticação:

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

  Copy

  O uso de um host padrão requer integração de acesso externo com uma regra de rede que permite o acesso do seu serviço ao nome de host Snowflake da sua conta. Por exemplo, se o nome da sua conta for MyAccount, o nome do host será myaccount.snowflakecomputing.com. Para obter mais informações, consulte Saída de rede.

  • Crie uma regra de rede que corresponda ao nome de host da Snowflake API da sua conta:

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

    Copy

  • Crie uma integração usando a regra de rede anterior:

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

    Copy

Configuração do banco de dados e o contexto do esquema para execução de SQL¶

Esta seção explica dois conceitos:

• A lógica que o Snowflake usa para determinar o banco de dados e o esquema no qual criar seu serviço/trabalho.

• O método pelo qual o Snowflake transmite essas informações aos seus contêineres, permitindo assim que o código do contêiner execute SQL no mesmo banco de dados e contexto de esquema.

Snowflake usa a seguinte lógica para determinar o banco de dados e o esquema no qual criar um serviço/trabalho:

• Para um serviço, o Snowflake usa o nome do serviço fornecido no comando CREATE SERVICE para determinar o banco de dados e o contexto do esquema do serviço:

  • Exemplo 1: o comando CREATE SERVICE a seguir especifica test_service como o nome do serviço:

    CREATE SERVICE test_service IN COMPUTE POOL ...
    

    Copy

    Snowflake coloca esse serviço no banco de dados e esquema atuais.

  • Exemplo 2: o comando CREATE SERVICE a seguir especifica um nome de serviço completo:

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

    Copy

    Snowflake coloca o serviço no banco de dados (test_db) e esquema (test_schema) especificados, independentemente do esquema atual.

• Para um trabalho, você não fornece um nome de trabalho ao criá-lo usando o comando EXECUTE SERVICE:

  EXECUTE SERVICE IN COMPUTE POOL ..
  

  Copy

  Nesse caso, você não tem a oportunidade de colocar o trabalho em qualquer lugar. Portanto, o Snowflake coloca o trabalho no banco de dados e no esquema atuais. Se quiser que um trabalho execute instruções SQL em esquemas diferentes, você poderá executar o trabalho usando contextos de esquema diferentes. Por exemplo:

  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

Quando o Snowflake inicia um serviço/trabalho, ele fornece informações de banco de dados e esquema para os contêineres em execução usando as seguintes variáveis de ambiente:

• SNOWFLAKE_DATABASE

• SNOWFLAKE_SCHEMA

O código do contêiner pode usar variáveis de ambiente no código de conexão para determinar qual banco de dados e esquema usar, conforme mostrado neste exemplo:

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

Exemplo

No Tutorial 2, você cria um trabalho do Snowflake que se conecta ao Snowflake e executa instruções SQL. As etapas a seguir resumem como o código do tutorial usa as variáveis de ambiente:

1. Na configuração comum (consulte a seção Configuração comum), você cria recursos, incluindo um banco de dados e um esquema. Você também define o banco de dados e o esquema atuais para a sessão:

   USE DATABASE tutorial_db;
   ...
   USE SCHEMA data_schema;
   

   Copy

2. Depois de criar um trabalho (executar EXECUTE SERVICE), o Snowflake inicia o contêiner e define as seguintes variáveis de ambiente no contêiner para o banco de dados e o esquema atuais da sessão:

   • SNOWFLAKE_DATABASE é definido como “TUTORIAL_DB”

   • SNOWFLAKE_SCHEMA é definido como “DATA_SCHEMA”

3. O código do trabalho (consulte main.py no Tutorial 2) lê estas variáveis de ambiente:

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

   Copy

4. O código do trabalho define o banco de dados e o esquema como o contexto no qual executar as instruções SQL (função run_job() em main.py):

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

   Copy

Como usar um token OAuth para executar SQL¶

Todos os clientes fornecidos pelo Snowflake oferecem suporte a OAuth como forma de autenticação. Os contêineres de serviço/trabalho também usam o mecanismo OAuth para autenticação com Snowflake. Por exemplo, quando um contêiner deseja executar SQL, o contêiner cria uma conexão com o Snowflake, semelhante a qualquer outro cliente 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'
)

Quando você cria um serviço/trabalho, o Snowflake executa os contêineres e fornece um token Oauth para os contêineres usarem no seguinte local dentro do contêiner: /snowflake/session/token.

Observe os seguintes detalhes sobre este token OAuth:

• Você deve ler o conteúdo do arquivo /snowflake/session/token imediatamente antes de usá-lo porque o conteúdo expira em 10 minutos e o Snowflake atualiza esse arquivo a cada poucos minutos. Depois que um contêiner se conecta ao Snowflake com êxito, o tempo de expiração não se aplica à conexão (como acontece com qualquer sessão criada diretamente pelos usuários).

• Este token OAuth é válido apenas no serviço/trabalho específico do Snowflake. Você não pode copiar o token OAuth e usá-lo fora do serviço/trabalho.

• Usando o token OAuth, os contêineres se conectam ao Snowflake como usuário e função de serviço/trabalho da seguinte maneira:

  • O usuário é a pessoa que criou o serviço/trabalho.

  • A função é a função de serviço para o serviço/trabalho e esta é a única função suportada. Você não pode mudar a função.

• Usar o token OAuth para se conectar criará uma nova sessão. O token OAuth não está associado a nenhuma sessão SQL existente.

  Nota

  Uma diferença significativa entre a execução de procedimentos armazenados e a execução de um serviço/trabalho é que os procedimentos armazenados são executados na mesma sessão que o SQL que os executa. Mas toda vez que um contêiner estabelece uma nova conexão, você cria uma nova sessão.

Entrada de rede¶

Para permitir que qualquer coisa interaja com seu serviço pela internet, você declara as portas de rede nas quais seu serviço está escutando como pontos de extremidade no arquivo de especificação de serviço. Esses pontos de extremidade controlam a entrada.

Por padrão, os pontos de extremidade de serviço são privados. Somente funções de serviço e comunicações serviço a serviço podem fazer solicitações aos pontos de extremidade privados. Você pode declarar um ponto de extremidade como público para permitir solicitações a um ponto de extremidade da internet. A função que cria o serviço (com um ponto de extremidade público) deve ter o privilégio BIND SERVICE ENDPOINT na conta.

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

Para obter um exemplo, consulte Tutorial 1.

Saída de rede¶

O código do seu aplicativo (trabalho ou serviço) pode exigir acesso à internet. Por padrão, os contêineres de aplicativos não têm permissão para acessar a internet. Você precisa ativar o acesso à internet usando integrações de acesso externo (EAIs).

Normalmente, você deseja que um administrador de conta crie EAIs para gerenciar o acesso externo permitido de trabalhos e serviços. Os administradores da conta podem então conceder o uso de EAI a funções específicas que os desenvolvedores usam para executar trabalhos ou serviços.

O exemplo a seguir descreve as etapas para criar uma EAI que permite o tráfego de saída para destinos específicos determinados usando regras de rede. Em seguida, consulte a EAI ao criar um trabalho ou serviço para permitir solicitações para destinos específicos da internet.

Exemplo

Suponha que você queira que o código do seu aplicativo (trabalho ou serviço) envie solicitações para os seguintes destinos:

• Solicitações de HTTPS para translation.googleapis.com

• Solicitações de HTTP e HTTPS para google.com

Siga estas etapas para permitir que seu trabalho ou serviço acesse esses domínios na Internet:

1. Criação de uma integração de acesso externo (EAI). Isso requer permissões apropriadas. Por exemplo, você pode usar a função ACCOUNTADMIN para criar uma EAI. Este é um processo de duas etapas:

   1. Use o comando CREATE NETWORK RULE para criar uma ou mais regras de rede de saída listando destinos externos aos quais você deseja permitir acesso. Você pode realizar este exemplo com uma regra de rede, mas para ilustração, criamos duas regras de rede:

      1. Crie uma regra de rede chamada translate_network_rule:

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

         Copy

         Esta regra permite conexões TCP com o destino translation.googleapis.com. O domínio na propriedade VALUE_LIST não especifica o número da porta opcional, portanto a porta padrão 443 (HTTPS) é assumida. Isso permite que seu aplicativo se conecte a qualquer URL que comece com https://translation.googleapis.com/.

      2. Crie uma regra de rede chamada 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

         Isso permite que seu aplicativo se conecte a qualquer URL que comece com http://google.com/ ou https://google.com/.

      O Snowpark Container Services oferece suporte apenas às regras de rede que permitem as portas 22,80,443 e 1024+. Se uma regra de rede referenciada permitir acesso a outras portas, a criação do serviço falhará. Entre em contato com seu representante de conta se precisar do uso de portas adicionais.

      Nota

      Para permitir que seu trabalho ou serviço envie solicitações HTTP ou HTTPS para qualquer destino na internet, especifique «0.0.0.0» como o domínio na propriedade VALUE_LIST. A regra de rede a seguir permite enviar solicitações «HTTP» e «HTTPS» para qualquer lugar na Internet. Somente as portas 80 ou 443 são suportadas com «0.0.0.0».

      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. Crie uma integração de acesso externo (EAI) que especifique que as duas regras de rede de saída anteriores são permitidas:

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

      Copy

      Agora o administrador da conta pode conceder o uso da integração aos desenvolvedores para permitir que executem um trabalho/serviço que pode acessar destinos específicos na Internet.

      GRANT USAGE ON INTEGRATION google_apis_access_integration TO ROLE test_role;
      

      Copy

2. Crie o serviço ou um trabalho fornecendo EAI conforme mostrado nos exemplos a seguir. A função que está criando o serviço ou trabalho precisa do privilégio de uso na EAI e do privilégio de leitura nos segredos referenciados. Observe que você não pode usar a função ACCOUNTADMIN para criar um serviço ou trabalho.

   • Crie um serviço:

     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

     Este exemplo de solicitação CREATE SERVICE usa uma especificação de serviço sequencial e especifica a propriedade opcional EXTERNAL_ACCESS_INTEGRATIONS para incluir a EAI. A EAI especifica as regras de rede que permitem o tráfego de saída do serviço para destinos específicos.

   • Crie um trabalho:

     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

     Este exemplo de comando EXECUTE SERVICE especifica a especificação embutida e a propriedade opcional EXTERNAL_ACCESS_INTEGRATIONS para incluir a EAI. Isso permite o tráfego de saída do trabalho para destinos especificados nas regras de rede permitidas por EAI.

Comunicações de rede entre contêineres¶

Há duas considerações:

• Comunicações entre contêineres de uma instância de serviço: se uma instância de serviço executar vários contêineres, esses contêineres poderão se comunicar entre si por meio do host local (não há necessidade de definir pontos de extremidade na especificação de serviço).

• Comunicação entre contêineres em vários serviços/trabalhos ou múltiplas instâncias de serviço: contêineres pertencentes a diferentes serviços (ou diferentes instâncias do mesmo serviço) podem se comunicar usando pontos de extremidade definidos em arquivos de especificação. Para obter mais informações, consulte Comunicações serviço a serviço.

Como passar os segredos como variáveis de ambiente¶

Para transmitir segredos do Snowflake de contêineres como variáveis de ambiente, inclua um campo containers.secrets:

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

secretKeyRef: esse valor depende do tipo de segredo do Snowflake. Possíveis valores:

• username ou password se o segredo do Snowflake for do tipo password.

• secret_string se o segredo do Snowflake for do tipo generic_string.

• access_token se o segredo do Snowflake for do tipo oauth2.

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

Como passar segredos em arquivos de contêiner locais¶

Para disponibilizar os segredos do Snowflake para o contêiner do seu aplicativo em arquivos de contêiner locais, inclua um campo containers.secrets:

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

directoryPath: Snowflake preenche um arquivo para cada chave de segredo neste diretório especificado; especificar secretKeyRef não é necessário.

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'