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

Importante

O recurso de trabalho do Snowpark Container Services está atualmente em versão preliminar privada e sujeito aos Termos de versão preliminar em https://snowflake.com/legal. Entre em contato com seu representante Snowflake para obter mais informações.

Conexão ao Snowflake de dentro de um contêiner

Quando você inicia um serviço ou tarefa, o Snowflake fornece credenciais para os contêineres em execução, permitindo que o código do contêiner use drivers para se conectar ao Snowflake e executar SQL (semelhante a qualquer outro código no seu computador conectado ao Snowflake). As credenciais fornecidas são autenticadas como a função de serviço. Snowflake fornece algumas informações como variáveis de ambiente em seus contêineres.

Cada objeto no Snowflake tem uma função de proprietário. No caso de um serviço ou tarefa, Snowflake tem um conceito chamado função de serviço (este termo se aplica tanto a serviços quanto a tarefas). A função de serviço determina quais recursos seu serviço pode executar ao interagir com o Snowflake. Isso inclui a execução de SQL, acesso a estágios e rede serviço a serviço.

Nota

Na implementação atual, a função de serviço é igual à função de proprietário.

Por exemplo, você cria um test_role como parte da configuração comum para os tutoriais. Você concede os privilégios necessários à função e depois usa a função ao criar um serviço e um tarefa. Essa função é a função de proprietário do serviço e da tarefa e a função de serviço que determina os recursos do serviço e da tarefa.

Nota

As funções de serviço não podem ser nenhuma das funções privilegiadas, incluindo ACCOUNTADMIN, SECURITYADMIN e ORGADMIN.

Quando você cria um serviço, o Snowflake também cria um “usuário de serviço” específico para esse serviço. Quando o serviço executa uma consulta, ele executa a consulta como usuário do serviço. O que o usuário do serviço pode fazer é determinado pela função do serviço.

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.

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

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

    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 (ou trabalho) 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 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/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'
)
Copy

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.

Configuração dos recursos de rede

As seções a seguir explicam como configurar recursos de rede (entrada e saída de rede) para seu serviço e trabalho.

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
Copy

Para obter um exemplo, consulte Tutorial 1.

Nota

Atualmente, apenas os serviços, e não os trabalhos, oferecem suporte à entrada na rede.

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.

Nota

Ao testar um serviço localmente, você não está usando o proxy Snowflake e, portanto, haverá diferenças entre sua experiência ao executar um serviço localmente e quando implantado no Snowpark Container Services. Revise esta seção e atualize sua configuração local para melhores testes.

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 não têm permissão para acessar a internet. O navegador também deve restringir o acesso do aplicativo cliente à internet e o possível compartilhamento de dados. 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. 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.

Solicitações recebidas no serviço

Quando chega uma solicitação, o proxy faz o seguinte antes de encaminhar a solicitação ao serviço:

  • Solicitações recebidas com métodos HTTP banidos: se uma solicitação HTTP recebida usar qualquer um dos métodos HTTP banidos a seguir, o proxy não encaminhará a solicitação para seu serviço:

    • TRACE

    • OPTIONS

    • CONNECT

Respostas enviadas aos clientes

O proxy Snowflake aplica essas modificações à resposta enviada pelo seu serviço antes de encaminhar a resposta ao cliente.

  • Limpeza de cabeçalho: o proxy Snowflake remove esses cabeçalhos de resposta, se presentes:

    • X-XSS-Protection

    • Server

    • X-Powered-By

    • Public-Key-Pins

  • Cabeçalho de resposta Content-Type: se sua resposta de serviço incluir o cabeçalho Content-Type com qualquer um dos seguintes valores de tipo MIME (que indicam um executável), o proxy Snowflake não encaminhará essa resposta ao cliente. Em vez disso, o proxy enviará uma resposta 403 Forbidden.

    • application/x-msdownload: executável da Microsoft.

    • application/exe: executável genérico.

    • application/x-exe: outro executável genérico.

    • application/dos-exe: DOS executável.

    • application/x-winexe: executável do Windows.

    • application/msdos-windows: MS-DOS executável do Windows.

    • application/x-msdos-program: MS-DOS executável.

    • application/x-sh: script de shell Unix.

    • application/x-bsh: script de shell Bourne.

    • application/x-csh: script de shell C.

    • application/x-tcsh: script de shell Tcsh.

    • application/batch: arquivo em lote do Windows.

  • Cabeçalho de resposta X-Frame-Options: para evitar ataques de clickjacking, o proxy Snowflake define esse cabeçalho de resposta como DENY, evitando que outras páginas da Web usem um iframe para a página da Web do seu serviço.

  • Cabeçalho de resposta Cross-Origin-Opener-Policy (COOP): Snowflake define o cabeçalho de resposta COOP como same-origin para impedir que janelas de origem cruzada de referência acessem sua guia de serviço.

  • Cabeçalho de resposta Cross-Origin-Resource-Policy (CORP): Snowflake define o cabeçalho CORP como same-origin para evitar que sites externos carreguem recursos expostos pelo ponto de extremidade de entrada (por exemplo, em um iframe).

  • Cabeçalho de resposta X-Content-Type-Options: o proxy Snowflake define esse cabeçalho como nosniff para garantir que os clientes não alterem o tipo MIME indicado na resposta pelo seu serviço.

  • Cabeçalho de resposta Cross-Origin-Embedder-Policy (COEP): o proxy Snowflake define o cabeçalho de resposta COEP como credentialless, o que significa que ao carregar um objeto de origem cruzada, como uma imagem ou um script, se o objeto remoto não suportar o protocolo Cross-Origin Resource Sharing (CORS), o Snowflake não enviará as credenciais ao carregá-lo.

  • Cabeçalho de resposta Content-Security-Policy-Report-Only: o proxy Snowflake substitui esse cabeçalho de resposta por um novo valor direcionando o cliente para enviar os relatórios CSP ao Snowflake.

  • Cabeçalho de resposta Content-Security-Policy (CSP): por padrão, o proxy Snowflake adiciona a seguinte linha de base CSP para proteção contra ataques comuns da Web.

    default-src 'self' 'unsafe-inline' 'unsafe-eval' http: https: blob: data:; object-src 'none'; connect-src 'self' http: https: wss:; frame-ancestors 'self';
    
    Copy

    Há duas considerações sobre política de segurança de conteúdo:

    • Além da política de segurança de conteúdo de linha de base que o proxy adiciona, o próprio serviço pode adicionar explicitamente um CSP na resposta. Um serviço pode optar por aumentar a segurança adicionando um CSP mais rigoroso. Por exemplo, um serviço pode adicionar o seguinte CSP para permitir scripts somente de self.

      script-src 'self'
      
      Copy

      Na resposta resultante enviada ao cliente, haverá dois cabeçalhos CSP. Ao receber a resposta, os navegadores do cliente aplicam a política de segurança de conteúdo mais rigorosa que inclui as restrições adicionais especificadas por cada política.

    • Se você configurar uma integração de acesso externo (EAI) para permitir que seu serviço acesse um site externo (Saída de rede), o proxy Snowflake criará um CSP que permite que sua página da web acesse esse site. Por exemplo, suponha que uma regra de rede associada a EAI permita acesso de saída de serviço a example.com. Em seguida, o proxy Snowflake adiciona este cabeçalho de resposta CSP:

      default-src 'self' 'unsafe-inline' 'unsafe-eval' http://example.com https://example.com blob: data:; object-src 'none'; connect-src 'self' http://example.com https://example.com wss://example.com; frame-ancestors 'self';
      
      Copy

      Os navegadores respeitam a política de acesso ao conteúdo recebida na resposta. Neste exemplo, os navegadores permitem que o aplicativo acesse example.com, mas não outros sites.

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

      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 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 usar segredos do Snowflake para passar credenciais para um contêiner

Se seu serviço ou trabalho se comunicar com pontos de extremidade externos (fora do Snowflake), você precisará fornecer informações de credenciais em seu contêiner para uso do código do aplicativo. Para fazer isso, primeiro armazene suas credenciais em objetos de segredo do Snowflake. Em seguida, no arquivo de especificação de serviço ou trabalho, inclua o campo containers.secrets para transmitir esses segredos aos contêineres.

Você pode passar essas credenciais para variáveis de ambiente nos contêineres ou disponibilizá-las em arquivos locais nos contêineres. Dependendo da sua escolha, o arquivo de especificação fornece construções, conforme explicado nas seções a seguir.

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

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.

Nota

Os segredos passados como variáveis de ambiente não podem ser atualizados após a criação de um serviço (ou trabalho).

Exemplo 1: como passar segredos do tipo senha como variáveis de ambiente

Neste exemplo, você cria o seguinte objeto de segredo do Snowflake do tipo password:

CREATE SECRET testdb.testschema.my_secret_object
  TYPE = password
  USERNAME = 'snowman'
  PASSWORD = '1234abc';
Copy

Para fornecer esse objeto de segredo do Snowflake às variáveis de ambiente (por exemplo, LOGIN_USER e LOGIN_PASSWORD) em seu contêiner, adicione o seguinte campo containers.secrets no arquivo de especificação:

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
Copy

O campo containers.secrets neste exemplo é uma lista de dois objetos snowflakeSecret:

  • O primeiro objeto mapeia username no objeto do segredo do Snowflake para a variável de ambiente LOGIN_USER em seu contêiner.

  • O segundo objeto mapeia password no objeto do segredo do Snowflake para a variável de ambiente LOGIN_PASSWORD em seu contêiner.

Exemplo 2: como passar segredos do tipo cadeia_de_caracteres_genérica como variáveis de ambiente

Neste exemplo, você cria o seguinte objeto de segredo do Snowflake do tipo generic_string:

CREATE SECRET testdb.testschema.my_secret
  TYPE=generic_string
  SECRET_STRING='
       some_magic: config
  ';
Copy

Para fornecer esse objeto do segredo do Snowflake para variáveis de ambiente (por exemplo, GENERIC_SECRET) em seu contêiner, adicione o seguinte campo containers.secrets no arquivo de especificação:

containers:
- name: main
  image: <url>
  secrets:
  - snowflakeSecret: testdb.testschema.my_secret
    secretKeyRef: secret_string
    envVarName: GENERIC_SECRET
Copy

Sobre como passar segredos do tipo oauth2 para variáveis de ambiente

Este não é um cenário útil porque quando os tokens OAuth expiram, um novo token deve ser passado para o contêiner. Mas os segredos passados como variáveis de ambiente não podem ser atualizados, portanto, não passe segredos do tipo «oauth2» como variáveis de ambiente.

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

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

Nota

Após a criação de um serviço (ou trabalho), se o objeto do segredo do Snowflake for atualizado, o Snowflake atualizará os arquivos do segredo correspondentes nos contêineres em execução.

Exemplo 1: como passar segredos do tipo senha em arquivos de contêiner locais

Neste exemplo, você cria o seguinte objeto de segredo do Snowflake do tipo password:

CREATE SECRET testdb.testschema.my_secret_object
  TYPE = password
  USERNAME = 'snowman'
  PASSWORD = '1234abc';
Copy

Para disponibilizar essas credenciais em arquivos de contêiner locais, adicione o seguinte campo containers.secrets no arquivo de especificação:

containers:
- name: main
  image: <url>
  secrets:
  - snowflakeSecret: testdb.testschema.my_secret_object
    directoryPath: '/usr/local/creds'
Copy

Quando você inicia seu serviço ou trabalho, o Snowflake cria dois arquivos dentro dos contêineres: /usr/local/creds/username e /usr/local/creds/password. O código do seu aplicativo pode então ler esses arquivos.

Exemplo 2: como passar segredos do tipo oauth2 em arquivos de contêiner locais

Neste exemplo, você cria o seguinte objeto de segredo do Snowflake do tipo oauth2:

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

Para disponibilizar essas credenciais em arquivos de contêiner locais, adicione o seguinte campo containers.secrets no arquivo de especificação:

containers:
- name: main
  image: <url>
  secrets:
  - snowflakeSecret: testdb.testschema.oauth_secret
    directoryPath: '/usr/local/creds'
Copy

Snowflake busca o token de acesso do objeto do segredo do OAuth e cria /usr/local/creds/access_token nos contêineres.

Quando um trabalho ou serviço usa segredos do tipo oauth2, espera-se que o serviço ou trabalho use esse segredo para acessar um destino da internet. Um segredo oauth deve ser permitido pela integração de acesso externo (EAI); caso contrário, CREATE SERVICE ou EXECUTE SERVICE falharão. Este requisito de EAI extra se aplica apenas a segredos do tipo oauth2 e não a outros tipos de segredos.

Em resumo, as etapas típicas na criação de tal serviço são:

  1. Crie um segredo do tipo oauth2 (mostrado anteriormente).

  2. Crie uma EAI para permitir o uso do segredo por um serviço ou trabalho. Por exemplo:

    CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION example_eai
      ALLOWED_NETWORK_RULES = (<name>)
      ALLOWED_AUTHENTICATION_SECRETS = (testdb.testschema.oauth_secret)
      ENABLED = true;
    
    Copy
  3. Crie um serviço ou trabalho que inclua um campo containers.secrets na especificação. Isso também especifica a propriedade opcional EXTERNAL_ACCESS_INTEGRATIONS para incluir uma EAI para permitir o uso do segredo oauth2.

    Um exemplo de comando CREATE SERVICE (com especificação inline):

    CREATE SERVICE eai_service
      IN COMPUTE POOL MYPOOL
      FROM SPECIFICATION
      $$
      spec:
        containers:
          - name: main
            image: <url>
            secrets:
            - snowflakeSecret: testdb.testschema.oauth_secret
              directoryPath: '/usr/local/creds'
        endpoints:
          - name: api
            port: 8080
      $$
      EXTERNAL_ACCESS_INTEGRATIONS = (example_eai);
    
    Copy

Para obter mais informações sobre saída, consulte Saída de rede.

Diretrizes e limitações

  • Requisitos da plataforma de imagem: atualmente, o Snowpark Container Services exige imagens da plataforma Linux/AMD64.

  • Contêineres de serviço/trabalho não são privilegiados: os contêineres de serviço/trabalho não são executados como privilegiados e, portanto, não podem alterar a configuração do hardware no host e podem alterar apenas configurações de OS limitadas. Os contêineres de serviço/trabalho só podem executar configurações do sistema operacional que um usuário normal (ou seja, um usuário que não requer root) pode fazer.

  • Como renomear o banco de dados e o esquema:

    • Não renomeie bancos de dados e esquemas onde você já criou um serviço. Renomear é efetivamente mover um serviço para outro banco de dados e esquema, que não é compatível. Por exemplo:

      • O nome do serviço DNS continuará refletindo o banco de dados antigo e o nome do esquema.

      • As informações de banco de dados e esquema que o Snowflake forneceu aos contêineres de serviço em execução continuarão a se referir aos nomes antigos.

      • Os novos logs que os serviços ingerem na tabela de eventos continuarão a fazer referência ao banco de dados antigo e aos nomes de esquema.

      • A função de serviço continuará a fazer referência ao serviço no banco de dados e esquema antigos e, quando você invocar a função de serviço, ela falhará.

    • Uma especificação de serviço pode fazer referência a objetos como estágios Snowflake e repositórios de imagens. Se você renomear os nomes do banco de dados ou do esquema onde esses objetos residem, será necessário atualizar manualmente os nomes do banco de dados e do esquema dos objetos referenciados na especificação de serviço.

  • Descarte e cancelamento de um banco de dados e esquema:

    • Quando você descarta o banco de dados ou esquema pai, os serviços são excluídos de forma assíncrona. Isso significa que um serviço pode continuar em execução por algum tempo antes que os processos internos o removam.

    • Se você tentar cancelar um banco de dados ou esquema excluído anteriormente, não há garantia de que os serviços serão restaurados.

  • Transferência de propriedade: a transferência de propriedade de serviços e trabalhos não é suportada.

  • Replicação: ao lidar com replicação no Snowflake, observe o seguinte:

    • Os objetos do Snowpark Container Services, como serviços, trabalhos, pools de computação e repositórios, não podem ser replicados.

    • Se você criar um repositório em um banco de dados, o banco de dados inteiro não poderá ser replicado. Nos casos em que o banco de dados contém outros recursos, como serviços, trabalhos ou pools de computação, o processo de replicação do banco de dados será bem-sucedido, mas esses objetos individuais no banco de dados não serão replicados.

  • Tempo limite dos trabalhos: o trabalho do Snowpark Container Services é executado de forma síncrona. Se uma instrução expirar, o trabalho será cancelado. O tempo limite padrão da instrução é de dois dias. Os clientes podem alterar o tempo limite definindo o parâmetro STATEMENT_TIMEOUT_IN_SECONDS usando ALTER SESSION.

    ALTER SESSION SET statement_timeout_in_seconds=<time>
    
    Copy

    Configure-o antes de executar o comando EXECUTE SERVICE.