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 Configuração da saída da 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.

Conexão ao Snowflake de dentro de um contêiner usando os direitos do chamador¶

Os contêineres executam consultas conectando-se ao Snowflake como o usuário do serviço e usando a função de proprietário do serviço que concede privilégios ao serviço. Em determinados cenários de aplicativos, talvez seja necessário executar consultas usando o contexto do usuário final em vez do usuário do serviço. O recurso de direito do chamador é usado nesse contexto.

Por exemplo, suponha que você crie um serviço que exponha um ponto de extremidade público para fornecer um aplicativo da Web que exiba um painel usando dados armazenados no Snowflake. Você concede a outros usuários da sua conta Snowflake acesso ao painel (concedendo a função de serviço a esses usuários). Quando qualquer um desses usuários finais fizer login no painel, você deseja que o painel exiba apenas os dados aos quais o usuário tem acesso.

No entanto, como os contêineres, por padrão, executam consultas usando o usuário do serviço e a função de proprietário do serviço, o painel mostra os dados aos quais a função de proprietário do serviço tem acesso, independentemente do usuário final conectado ao ponto de extremidade. Como resultado, os dados no painel do usuário não estão limitados ao que o usuário final tem acesso, o que permite que o usuário acesse dados que não deveriam ter permissão para acessar.

Para limitar o painel para mostrar apenas os dados acessíveis ao usuário conectado, os contêineres de aplicativos precisam executar SQL usando privilégios concedidos ao usuário final. Você pode ativar isso usando os direitos do chamador no aplicativo.

ALTER USER my_user SET DEFAULT_SECONDARY_ROLES = ( 'ALL' );

-- Permissions to resolve the table's name.
GRANT CALLER USAGE ON DATABASE <db_name> TO ROLE <service_owner_role>;
GRANT CALLER USAGE ON SCHEMA <schema_name> TO ROLE <service_owner_role>;
-- Permissions to use a warehouse
GRANT CALLER USAGE ON WAREHOUSE <warehouse_name> TO ROLE <service_owner_role>;
-- Permissions to query the table.
GRANT CALLER SELECT ON TABLE T1 TO ROLE <service_owner_role>;

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 Configuração da saída da 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.

Considerações sobre ingresso e SSO¶

Ao acessar o ponto de extremidade público pela Internet, você pode descobrir que a autenticação por nome de usuário/senha funciona, mas SSO resulta em uma página em branco ou no erro: «A integração do clienteOAuth com o ID do cliente fornecido não foi encontrada.»

Isso acontece quando você está usando o estilo antigo de autenticação federada (SSO) com o Snowflake em vez da versão mais recente de integração de segurança, conforme explicado em Configuração do Snowflake para usar a autenticação federada. Faça o seguinte para verificar:

1. Execute a seguinte consulta:

   SHOW PARAMETERS LIKE 'SAML_IDENTITY_PROVIDER' IN ACCOUNT;
   

   Copy

   Se esse parâmetro estiver definido, então, em algum momento, você estava usando a autenticação federada antiga.

2. Se o parâmetro anterior foi definido, execute as seguintes consultas para verificar se você tem uma integração de segurança SAML:

   SHOW INTEGRATIONS;
   SELECT * FROM TABLE(RESULT_SCAN(LAST_QUERY_ID())) WHERE "type" = 'SAML2';
   

   Copy

   Se você não tiver nenhuma integração do tipo SAML2, então está usando a versão antiga de autenticação federada.

Nesse caso, a solução é migrar da autenticação federada antiga para a nova autenticação federada da integração. Para obter mais informações, consulte Migração para uma integração de segurança SAML2.

Saída da rede usando conectividade privada¶

Em vez de rotear a saída da rede pela Internet pública, você pode optar por direcionar o tráfego de saída do seu serviço por meio de um ponto de extremidade de conectividade privada.

Primeiro, você precisa criar o ponto de extremidade de conectividade privada em sua conta do Snowflake. Em seguida, configure uma regra de rede para permitir que o tráfego de saída use a conectividade privada. O processo de configuração de uma integração de acesso externo (EAI) permanece o mesmo descrito na seção anterior.

Por exemplo, se você quiser habilitar o acesso de saída da Internet do seu serviço a um bucket S3 Amazon por meio de conectividade privada, faça o seguinte:

1. Habilite a conectividade do link privado para o serviço de ponto de extremidade autônomo (Amazon S3). Para obter instruções passo a passo, consulte AWS Private Link para Amazon S3.

2. Chame a função do sistema SYSTEM$PROVISION_PRIVATELINK_ENDPOINT para provisionar um ponto de extremidade de conectividade privada em seu Snowflake VNet. Isso permite que o Snowflake se conecte ao serviço externo (neste exemplo, o Amazon S3) usando conectividade privada.

   USE ROLE ACCOUNTADMIN;
   
   SELECT SYSTEM$PROVISION_PRIVATELINK_ENDPOINT(
     'com.amazonaws.us-west-2.s3',
     '*.s3.us-west-2.amazonaws.com'
   );
   

   Copy

3. Na conta do provedor de nuvem, aprove o ponto de extremidade. Neste exemplo, para a Amazon AWS, consulte Como aceitar ou rejeitar solicitações de conexão na documentação do AWS. Além disso, para aprovar o ponto de extremidade no Azure, consulte a documentação do Azure.

4. Use o comando CREATE NETWORK RULE para criar uma regra de rede de saída que especifique os destinos externos aos quais você deseja permitir o acesso.

   CREATE OR REPLACE NETWORK RULE private_link_network_rule
     MODE = EGRESS
     TYPE = PRIVATE_HOST_PORT
     VALUE_LIST = ('<bucket-name>.s3.us-west-2.amazonaws.com');
   

   Copy

   O valor do parâmetro TYPE é definido como PRIVATE_HOST_PORT. Isso indica que a regra de rede permite que o tráfego de rede de saída use a conectividade privada.

5. As demais etapas para criar uma EAI e usá-la para criar um serviço são as mesmas explicadas na seção anterior (consulte Configuração da saída da rede).

Para obter mais informações sobre como trabalhar com pontos de extremidade de conectividade privada, consulte o seguinte:

• Gerenciamento de pontos de extremidade de conectividade privada: AWS

• Gerenciar pontos de extremidade de conectividade privada: Azure

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'