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

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:

• SNOWFLAKE_ACCOUNT: Fornece o localizador de conta para a conta Snowflake na 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.

Para obter exemplos de código usando vários drivers Snowflake, consulte Exemplos de conexão do Snowflake.

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 proprietário 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.

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

O Snowflake usa o nome do serviço para determinar o banco de dados e o esquema no qual criar um serviço:

• Exemplo 1: nos seguintes comandos CREATE SERVICE e EXECUTE JOB SERVICE, o nome do serviço não especifica explicitamente um nome de banco de dados e esquema. O Snowflake cria o serviço e o serviço de trabalho no banco de dados e esquema atuais.

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

• Exemplo 2: nos seguintes comandos CREATE SERVICE e EXECUTE JOB SERVICE, o nome do serviço inclui um nome de banco de dados e esquema. Snowflake cria o serviço e serviço do trabalho no banco de dados (test_db) e esquema (test_schema) especificados, independentemente do esquema atual.

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

Quando o Snowflake inicia um serviço, 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 serviço de 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 serviço de trabalho (executando EXECUTE JOB 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

   Nota

   SNOWFLAKE_ACCOUNT, SNOWFLAKE_HOST, SNOWFLAKE_DATABASE, SNOWFLAKE_SCHEMA são variáveis de ambiente que o Snowflake gera para o contêiner do aplicativo, mas SNOWFLAKE_WAREHOUSE não é (o código do aplicativo do Tutorial 2 criou essa variável porque o Snowflake não passa um nome de warehouse para um contêiner).

Como especificar o warehouse para seu contêiner¶

Se seu serviço se conectar ao Snowflake para executar uma consulta em um warehouse do Snowflake, você terá as seguintes opções para especificar um warehouse:

• Especifique um warehouse no código do seu aplicativo. Especifique um warehouse como parte da configuração da conexão ao iniciar uma sessão do Snowflake para executar consultas no seu código. Para obter um exemplo, consulte Tutorial 2.

• Especifique um warehouse padrão ao criar um serviço. Especifique o parâmetro opcional QUERY_WAREHOUSE no comando CREATE SERVICE (ou EXECUTE JOB SERVICE) para fornecer um warehouse padrão. Se o código do seu aplicativo não fornecer um warehouse como parte da configuração da conexão, o Snowflake usará o warehouse padrão. Use o comando ALTER SERVICE para mudar o warehouse padrão.

Se você especificar um warehouse usando ambos os métodos, o warehouse especificado no código do aplicativo será usado.

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 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, 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 específico do Snowflake. Você não pode copiar o token OAuth e usá-lo fora do serviço.

• Usando o token OAuth, os contêineres se conectam ao Snowflake como o usuário do serviço e usam a função de proprietário do serviç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 é 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 de proprietário do serviço 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.

Entrada e segurança de aplicativos da web¶

Você pode criar um serviço Snowpark Container Services para hospedagem na web usando o suporte do ponto de extremidade público (entrada de rede). Para maior segurança, Snowflake emprega um serviço de proxy para monitorar solicitações recebidas de clientes para o seu serviço e respostas de saída do seu serviço para os clientes. Esta seção explica o que o proxy faz e como ele afeta um serviço implantado no Snowpark Container Services.

Por exemplo:

• O proxy não encaminha uma solicitação HTTP recebida se a solicitação usar um método HTTP banido.

• O proxy envia uma resposta 403 ao cliente se o cabeçalho Content-Type na resposta indicar que a resposta contém um executável.

Além disso, o proxy também pode injetar novos cabeçalhos e alterar os cabeçalhos existentes na solicitação e na resposta, tendo em mente o seu contêiner e a segurança de dados.

Por exemplo, ao receber uma solicitação, seu serviço pode enviar HTML, JavaScript, CSS e outros conteúdos de uma página da Web para o navegador do cliente na resposta. A página da web no navegador faz parte do seu serviço, atuando como interface do usuário. Por motivos de segurança, se o seu serviço tiver restrições (como uma restrição ao estabelecimento de conexões de rede com outros sites), você também poderá querer que a página da Web do seu serviço tenha as mesmas restrições.

Por padrão, os serviços têm permissões limitadas para acessar a Internet. O navegador também deve restringir o acesso do aplicativo cliente à Internet e o possível compartilhamento de dados na maioria dos casos. Se você configurar uma integração de acesso externo (EAI) para permitir que seu serviço acesse example.com (consulte Saída de rede), a página da Web do seu serviço também deverá poder acessar example.com por meio de seu navegador.

O proxy Snowflake aplica as mesmas restrições de rede ao serviço e à página da web adicionando um cabeçalho Content-Security-Policy (CSP) na resposta. Por padrão, o proxy adiciona uma linha de base CSP na resposta para proteção contra ameaças de segurança comuns. A segurança do navegador é um esforço máximo para equilibrar funcionalidade e segurança. É uma responsabilidade compartilhada para garantir que essa linha de base seja apropriada para seu caso de uso. Além disso, se o seu serviço estiver configurado para usar um EAI, o proxy aplicará as mesmas regras de rede de EAI a CSP para a página da web. Este CSP permite que a página da web no navegador acesse os mesmos sites que o serviço pode acessar.

As seções a seguir explicam como o proxy Snowflake lida com solicitações de entrada para o seu serviço e modifica as respostas de saída do seu serviço para os clientes.

Saída de rede¶

O código do seu aplicativo 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 serviços (incluindo serviços de trabalho). Os administradores da conta podem então conceder o uso de EAI a funções específicas que os desenvolvedores usam para executar 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 serviço para permitir solicitações para destinos específicos da internet.

Exemplo

Suponha que você queira que o código do seu aplicativo 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 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/.

      Nota

      Para o parâmetro VALUE_LIST, você deve fornecer um nome de host completo. Curingas (por exemplo, *.googleapis.com) não são suportados.

      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 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 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 fornecendo EAI conforme mostrado nos exemplos a seguir. A função do proprietário que está criando o serviço precisa do privilégio USAGE no privilégio EAI e READ bre os segredos referenciados. Observe que você não pode usar a função ACCOUNTADMIN para criar um serviço.

   • Crie um serviço:

     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

     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.

   • Execute um serviço de trabalho:

     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

     Este exemplo de comando EXECUTE JOB 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 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.

Especificando segredos Snowflake¶

Especifique um segredo Snowflake por nome ou referência (a referência é aplicável somente no cenário com Native Applications):

• Passe o segredo Snowflake por nome: É possível passar um nome secreto como valor do campo snowflakeSecret.

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

  Copy

  Observe que você pode opcionalmente especificar <secret-name> diretamente como o valor snowflakeSecret.

• Passe o segredo Snowflake por referência: Ao usar o Snowpark Container Services para criar um Native App (um aplicativo com contêineres), o produtor e os consumidores do aplicativo usam contas Snowflake diferentes. Em alguns contextos, um Snowflake Native App instalado precisa acessar objetos secretos existentes na conta do consumidor que existem fora do objeto APPLICATION. Nesse caso, os desenvolvedores podem usar a sintaxe da especificação “segredos por referência” para manipular credenciais, conforme mostrado:

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

  Copy

  Observe que a especificação usa objectReference em vez de objectName para fornecer um nome de referência de segredo.

Especificação do posicionamento dos segredos dentro do contêiner¶

É possível dizer ao Snowflake para colocar os segredos nos contêineres como variáveis de ambiente ou gravá-los em arquivos de contêiner locais.

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'