Snowpark Container Services: como trabalhar com serviços¶

Crie um serviço de longa duração¶

Use CREATE SERVICE para criar um serviço de longa duração.

• Crie um serviço usando uma especificação embutida. Na maioria dos casos, durante o desenvolvimento, você pode escolher a especificação embutida, conforme mostrado:

  CREATE SERVICE echo_service
     IN COMPUTE POOL tutorial_compute_pool
     FROM SPECIFICATION $$
     spec:
       containers:
       - name: echo
         image: /tutorial_db/data_schema/tutorial_repository/my_echo_service_image:tutorial
         readinessProbe:
           port: 8000
           path: /healthcheck
       endpoints:
       - name: echoendpoint
         port: 8000
         public: true
     $$;
  

  Copy

• Crie um serviço usando informações de estágio. Quando você implementar o serviço em um ambiente de produção, é aconselhável aplicar o princípio de design da separação de interesses e carregar a especificação para um estágio, fornecer o comando CREATE SERVICE de informações de estágio, como mostrado:

  CREATE SERVICE echo_service
    IN COMPUTE POOL tutorial_compute_pool
    FROM @tutorial_stage
    SPECIFICATION_FILE='echo_spec.yaml';
  

  Copy

Execução de um serviço de trabalho¶

Use EXECUTE JOB SERVICE para criar um serviço de trabalho. Este comando é executado de forma síncrona e retorna uma resposta depois que todos os contêineres do serviço de trabalho saem.

• Execute um serviço de trabalho usando uma especificação inline:

  EXECUTE JOB SERVICE
     IN COMPUTE POOL tutorial_compute_pool
     NAME = example_job_service
     FROM SPECIFICATION $$
     spec:
       container:
       - name: main
         image: /tutorial_db/data_schema/tutorial_repository/my_job_image:latest
         env:
           SNOWFLAKE_WAREHOUSE: tutorial_warehouse
         args:
         - "--query=select current_time() as time,'hello'"
         - "--result_table=results"
     $$;
  

  Copy

• Execute um serviço de trabalho usando informações de estágio:

  EXECUTE JOB SERVICE
    IN COMPUTE POOL tutorial_compute_pool
    NAME = example_job_service
    FROM @tutorial_stage
    SPECIFICATION_FILE='my_job_spec.yaml';
  

  Copy

Criação de várias instâncias de serviço e habilitação do dimensionamento automático¶

Por padrão, o Snowflake executa uma instância do serviço no pool de computação especificado. Para gerenciar cargas de trabalho pesadas, você pode executar várias instâncias de serviço definindo as propriedades MIN_INSTANCES e MAX_INSTANCES, que especificam o número mínimo de instâncias do serviço para começar e o número máximo de instâncias para as quais o Snowflake pode escalar quando necessário.

Exemplo

CREATE SERVICE echo_service
   IN COMPUTE POOL tutorial_compute_pool
   FROM @tutorial_stage
   SPECIFICATION_FILE='echo_spec.yaml'
   MIN_INSTANCES=2
   MAX_INSTANCES=4;

Quando várias instâncias de serviço estão em execução, o Snowflake fornece automaticamente um balanceador de carga para distribuir as solicitações recebidas.

Para configurar o Snowflake para dimensionar automaticamente o número de instâncias de serviço em execução, siga estas etapas:

1. Especifique os requisitos de CPU e memória para sua instância de serviço no arquivo de especificação de serviço. Para obter mais informações, consulte a campo container.resources.

   Exemplo

   resources:
     requests:
      memory: <memory-reserved>
      cpu: <cpu-units>
   

   Copy

2. Ao executar o comando CREATE SERVICE, defina os parâmetros MIN_INSTANCES e MAX_INSTANCES. Você também pode usar ALTER SERVICE para alterar esses valores. O dimensionamento automático ocorre quando o MAX_INSTANCES especificado é maior que o MIN_INSTANCES.

O Snowflake começa criando o número mínimo de instâncias de serviço no pool de computação especificado. O Snowflake então aumenta ou diminui o número de instâncias de serviço usando um limite de 80% (para CPU e memória). O Snowflake monitora continuamente a utilização de recursos (memória ou CPU) no pool de computação, agregando os dados de uso de todas as instâncias de serviço em execução no momento.

Quando o uso de recursos agregados (em todas as instâncias de serviço) ultrapassa 80%, o Snowflake implanta uma instância de serviço adicional no pool de computação. Se o uso de recursos agregados cair abaixo de 80%, o Snowflake reduz a escala removendo uma instância de serviço em execução. Snowflake usa uma janela de estabilização de cinco minutos para evitar o dimensionamento frequente.

Observe os seguintes comportamentos de dimensionamento:

• O dimensionamento das instâncias de serviço é limitada pelos parâmetros MIN_INSTANCES e MAX_INSTANCES configurados para o serviço.

• Se o dimensionamento for necessário e os nós do pool de computação não tiverem a capacidade de recursos necessária para iniciar outra instância de serviço, o escalonamento automático do pool de computação poderá ser acionado. Para obter mais informações, consulte Dimensionamento automático de nós do pool de computação.

• Se você especificar os parâmetros MAX_INSTANCES e MIN_INSTANCES ao criar um serviço, mas não especificar os requisitos de CPU e memória para sua instância de serviço no arquivo de especificação de serviço, nenhum dimensionamento automático ocorrerá; o Snowflake inicia com o número de instâncias especificado pelo parâmetro MIN_INSTANCES e não realiza o dimensionamento automático.

Uso de modelos de especificação¶

Às vezes, você pode querer criar vários serviços usando a mesma especificação, mas com configurações diferentes. Por exemplo, você supõe que define uma variável de ambiente em uma especificação de serviço e deseja criar vários serviços usando a mesma especificação, mas valores diferentes para a variável de ambiente.

Os modelos de especificação permitem que você defina variáveis para valores de campo na especificação. Ao criar um serviço, você fornece valores para essas variáveis.

O uso de modelos de especificação é um processo de duas etapas:

1. Crie uma especificação usando variáveis como valores para vários campos de especificação. Use a sintaxe {{ variable_name }} para especificar essas variáveis. Por exemplo, a especificação a seguir usa uma variável chamada “tag_name” para o nome da tag de imagem, para que você especifique uma tag de imagem diferente para cada serviço.

   spec:
     containers:
     - name: echo
       image: myorg-myacct.registry.snowflakecomputing.com/tutorial_db/data_schema/tutorial_repository/my_echo_service_image:{{ tag_name }}
       ...
     endpoints:
     …
   

   Copy

2. Crie um serviço fornecendo o modelo de especificação em um comando CREATE SERVICE. Você usa SPECIFICATION_TEMPLATE ou SPECIFICATION_TEMPLATE_FILE para especificar o modelo. Use o parâmetro USING para especificar o valor da variável. Por exemplo, a instrução a seguir usa um modelo de especificação de um estágio Snowflake. O parâmetro USING define a variável tag_name para o valor 'latest'.

   CREATE SERVICE echo_service
      IN COMPUTE POOL tutorial_compute_pool
      FROM @STAGE SPECIFICATION_TEMPLATE_FILE='echo.yaml'
      USING (tag_name=>'latest');
   

   Copy

USING( var_name=>var_value, [var_name=>var_value, ... ] );

Exemplos¶

Esses exemplos mostram a criação de serviços usando modelos de especificação. Os comandos CREATE SERVICE nestes exemplos usam especificação inline.

CREATE SERVICE echo_service
   IN COMPUTE POOL tutorial_compute_pool
   MIN_INSTANCES=1
   MAX_INSTANCES=1
   FROM SPECIFICATION_TEMPLATE $$
      spec:
         containers:
         - name: echo
           image: {{ image_url }}
           env:
             SERVER_PORT: {{SERVER_PORT}}
             CHARACTER_NAME: Bob
           readinessProbe:
             port: {{SERVER_PORT}}
             path: /healthcheck
         endpoints:
         - name: echoendpoint
           port: {{SERVER_PORT}}
           public: true
         $$
      USING (image_url=>' "/tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest" ', SERVER_PORT=>8000 );

spec:
  containers:
  - name: echo
    image: /tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest
    env:
      SERVER_PORT: 8000
      CHARACTER_NAME: Bob
    readinessProbe:
      port: 8000
      path: /healthcheck
    endpoints:
    - name: echoendpoint
      port: 8000
      public: true

spec:
 containers:
 - name: echo
   image: /tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest
   env:
     SERVER_PORT: 8000
     CHARACTER_NAME: Bob
   …

CREATE SERVICE echo_service
  IN COMPUTE POOL tutorial_compute_pool
  MIN_INSTANCES=1
  MAX_INSTANCES=1
  FROM SPECIFICATION_TEMPLATE $$
     spec:
       containers:
       - name: echo
         image: /tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest
         env: {{env_values}}
         readinessProbe:
           port: {{SERVER_PORT}}    #this and next tell SF to connect to port 8000
           path: /healthcheck
       endpoints:
       - name: echoendpoint
         port: {{SERVER_PORT}}
         public: true
        $$
     USING (env_values=>'{"SERVER_PORT": 8000, "CHARACTER_NAME": "Bob"}' );

spec:
  container:
  - name: main
    image: /tutorial_db/data_schema/tutorial_repository/my_job_image:latest
    env:
      SNOWFLAKE_WAREHOUSE: tutorial_warehouse
    args:
    - "--query=select current_time() as time,'hello'"
    - "--result_table=results"

spec:
  container:
  - name: main
    image: /tutorial_db/data_schema/tutorial_repository/my_job_image:latest
    env:
      SNOWFLAKE_WAREHOUSE: tutorial_warehouse
    args: {{ARGS}}
  $$
  USING (ARGS=$$["--query=select current_time() as time,'hello'", "--result_table=results"]$$ );

Término do serviço¶

Quando você suspende um serviço (ALTER SERVICE … SUSPEND) ou descarta um serviço (DROP SERVICE), o Snowflake encerra todas as instâncias do serviço. Da mesma forma, quando você atualiza o código de serviço (ALTER SERVICE … <fromSpecification>), o Snowflake aplica atualizações contínuas encerrando e reimplementando uma instância de serviço por vez.

Ao encerrar uma instância de serviço, o Snowflake primeiro envia um sinal SIGTERM para cada contêiner de serviço. O contêiner tem a opção de processar o sinal e desligar normalmente em uma janela de 30 segundos. Caso contrário, após o período de carência, o Snowflake encerra todos os processos no contêiner.

Atualização do código de serviço e reimplementação do serviço¶

Após a criação de um serviço, use o comando ALTER SERVICE … <fromSpecification> para atualizar o código de serviço e reimplementar o serviço.

Primeiro, carregue o código do aplicativo modificado em seu repositório de imagens e, em seguida, chame ALTER SERVICE, fornecendo a especificação do serviço em linha ou especificando o caminho para um arquivo de especificação no estágio Snowflake. Por exemplo:

ALTER SERVICE echo_service
FROM SPECIFICATION $$
spec:
  …
  …
$$;

Ao receber a solicitação, o Snowflake reimplanta o serviço usando o novo código.

Quando você executa o comando CREATE SERVICE … <from-Specification>, o Snowflake registra a versão específica da imagem fornecida. O Snowflake implementa a mesma versão de imagem nos seguintes cenários, mesmo que a imagem no repositório tenha sido atualizada:

• Quando um serviço suspenso é retomado (usando ALTER SERVICE … RESUME).

• Quando o dimensionamento automático adiciona mais instâncias de serviço.

• Quando instâncias de serviço são reiniciadas durante a manutenção do cluster.

Mas se você chamar ALTER SERVICE … <fromSpecification>, isso fará com que o Snowflake use a versão mais recente no repositório para essa imagem.

Se você for o proprietário do serviço, a saída do comando DESCRIBE SERVICE incluirá a especificação do serviço, que inclui o resumo da imagem (o valor do campo sha256 na especificação), conforme mostrado abaixo:

spec:
containers:
- name: "echo"
    image: "/tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest"
    sha256: "@sha256:8d912284f935ecf6c4753f42016777e09e3893eed61218b2960f782ef2b367af"
    env:
      SERVER_PORT: "8000"
      CHARACTER_NAME: "Bob"
    readinessProbe:
      port: 8000
      path: "/healthcheck"
endpoints:
- name: "echoendpoint"
    port: 8000
    public: true

ALTER SERVICE pode afetar as comunicações (consulte Como usar um serviço) com o serviço.

• Se ALTER SERVICE … <fromSpecification> remover um ponto de extremidade ou remover permissões relevantes necessárias para usar um ponto de extremidade (consulte serviceRoles na referência de especificação), o acesso ao serviço falhará. Para obter mais informações, consulte Como usar um serviço.

• Enquanto a atualização estiver em andamento, novas conexões poderão ser roteadas para a nova versão. Se a nova versão do serviço não for compatível com versões anteriores, ela interromperá qualquer uso ativo do serviço. Por exemplo, consultas em andamento usando uma função de serviço podem falhar.

Concessão do privilégio USAGE em todos os pontos de extremidade usando a função de serviço padrão¶

Quando você cria um serviço (incluindo serviço de trabalho), o Snowflake também cria uma função de serviço padrão, chamada ALL_ENDPOINTS_USAGE. Esta função tem o privilégio USAGE em todos os pontos de extremidade que o serviço expõe. Você pode conceder a outras funções esta função de serviço padrão usando o comando GRANT SERVICE ROLE:

GRANT SERVICE ROLE my_echo_service_image!ALL_ENDPOINTS_USAGE TO ROLE some_other_role;

Usuários que estão usando some_other_role tem o privilégio USAGE em todos os pontos de extremidade do servidor.

Quando você descarta um serviço, o Snowflake descarta todas as funções de serviço (função de serviço padrão e funções de serviço definidas na especificação do serviço) associadas ao serviço e anula todas as concessões de função de serviço.

Concessão do privilégio USAGE a pontos de extremidade específicos usando funções de serviço definidas na especificação¶

Use funções de serviço para gerenciar acesso detalhado aos pontos de extremidade do servidor. Você define as funções de serviço, juntamente com a lista de pontos de extremidade que recebem o privilégio USAGE, na especificação do serviço.

A concessão de privilégios em pontos de extremidade específicos de um serviço é um processo de duas etapas:

1. Defina uma função de serviço: use uma especificação de serviço para definir uma função de serviço fornecendo um nome de função e uma lista de um ou mais pontos de extremidade para os quais você deseja conceder o privilégio USAGE. Por exemplo, no seguinte fragmento de especificação, o campo de nível superior serviceRoles define duas funções de serviço, cada uma com o privilégio USAGE em pontos de extremidade específicos.

   spec:
   ...
   serviceRoles:                 # Optional list of service roles
   - name: <svc_role_name1>
     endpoints:                  # endpoints that role can access
     - <endpoint_name1>
     - <endpoint_name2>
   - name: <svc_role_name2>
     endpoints:
     - <endpoint_name3>
     - <endpoint_name4>
   

   Copy

2. Conceda a função de serviço a outras funções. usando o comando GRANT SERVICE ROLE, você concede a função de serviço a outras funções (funções de conta, funções de aplicativo ou funções de banco de dados). Por exemplo:

   GRANT SERVICE ROLE <service-name>!<svc_role_name1> TO ROLE <another-role>
   

   Copy

Funções de serviço: como usar um serviço de uma consulta SQL¶

Uma função de serviço é uma função definida pelo usuário (UDF) que você cria usando CREATE FUNCTION (Snowpark Container Services). No entanto, em vez de escrever o código UDF diretamente, você associa a UDF ao seu ponto de extremidade do servidor. Observe que é possível associar uma função de serviço somente a um ponto de extremidade do servidor que ofereça suporte ao protocolo HTTP ou HTTPS.

Por exemplo, no Tutorial 1, você cria um serviço chamado echo_service que expõe um ponto de extremidade (ponto de extremidade de eco) conforme definido na especificação do serviço:

spec:
…
  endpoints:
  - name: echoendpoint
    port: 8080

echoendpoint é um nome de ponto de extremidade amigável que representa a porta correspondente (8080). Para se comunicar com esse ponto de extremidade de serviço, crie uma função de serviço fornecendo os parâmetros SERVICE e ENDPOINT conforme mostrado:

CREATE FUNCTION my_echo_udf (text varchar)
   RETURNS varchar
   SERVICE=echo_service
   ENDPOINT=echoendpoint
   AS '/echo';

O parâmetro AS fornece o caminho HTTP para o código de serviço. Você obtém esse valor de caminho a partir do código de serviço. Por exemplo, as seguintes linhas de código são do service.py no Tutorial 1.

@app.post("/echo")
def echo():
...

Quando você invoca a função de serviço, o Snowflake direciona a solicitação para o ponto de extremidade do serviço e caminho de serviço associado.

ALTER FUNCTION my_echo_udf(VARCHAR)
   SET SERVICE=other_service
   ENDPOINT=otherendpoint
   MAX_BATCH_ROWS=100

"Alex", "2014-01-01 16:00:00"
"Steve", "2015-01-01 16:00:00"
…

SELECT service_func(col1, col2) FROM input_table;

{
   "data":[
      [
         0,
         "Alex",
         "2014-01-01 16:00:00"
      ],
      [
         1,
         "Steve",
         "2015-01-01 16:00:00"
      ],
      …
      [
         <row_index>,
         "<column1>",
         "<column2>"
      ],
   ]
}

{
   "data":[
      [0, "a"],
      [1, "b"],
      …
      [ row_index,  output_column1]
   ]
}

USE ROLE service_owner;
GRANT USAGE ON service service_db.my_schema.my_service TO ROLE func_owner;

USE ROLE func_owner;
CREATE OR REPLACE test_udf(v VARCHAR)
  RETURNS VARCHAR
  SERVICE=service_db.my_schema.my_service
  ENDPOINT=endpointname1
  AS '/run';

SELECT test_udf(col1) FROM some_table;

ALTER FUNCTION test_udf(VARCHAR) SET
  SERVICE = service_db.other_schema.other_service
  ENDPOINT=anotherendpoint;

GRANT USAGE ON FUNCTION test_udf(varchar) TO ROLE func_user;
USE ROLE func_user;
SELECT my_test_udf('abcd');

Entrada: usando um serviço de fora do Snowflake¶

Um serviço pode expor um ou mais pontos de extremidade como públicos para permitir que os usuários utilizem o serviço na Web pública. Nesse caso, Snowflake gerencia o controle de acesso. Observe que a entrada é permitida somente com pontos de extremidade HTTP ou HTTPS.

Marque o ponto de extremidade como público em seu arquivo de especificação de serviço:

spec
  ...
  endpoints
  - name: <endpoint name>
    port: <port number>
    public: true

Comunicações serviço a serviço¶

Os serviços podem se comunicar entre si usando o nome DNS que o Snowflake atribui automaticamente a cada serviço. Para obter um exemplo, consulte Tutorial 3. Observe que, se um ponto de extremidade do servidor for criado apenas para permitir comunicações entre serviços, o protocolo TCP deverá ser usado.

O formato do nome DNS é:

<service-name>.<schema-name>.<db-name>.snowflakecomputing.internal

Use SHOW SERVICES (ou DESCRIBE SERVICE) para obter o nome DNS de um serviço. O nome DNS anterior é um nome completo. Os serviços criados no mesmo esquema podem se comunicar usando apenas o <nome-do-serviço>. Os serviços que estão no mesmo banco de dados, mas em esquemas diferentes, devem fornecer o nome do esquema, como <nome-do-serviço>.<nome-do-esquema>.

O Snowflake permite comunicações de rede entre serviços criados pela mesma função e bloqueia comunicações de rede entre serviços criados por funções diferentes. Se você quiser evitar que seus serviços se comuniquem entre si (por motivos como segurança), use diferentes funções do Snowflake para criar esses serviços.

Os nomes DNS têm as seguintes limitações:

• Seu banco de dados, esquema ou nomes de serviço devem ser etiquetas DNS válidas. (consulte também https://www.ietf.org/rfc/rfc1035.html#section-2.3.1). Caso contrário, a criação de um serviço falhará.

• Snowflake substitui um sublinhado (_) nos nomes (banco de dados, esquema e nome do serviço) por um traço (-) no nome DNS.

• Após criar um serviço, não altere o banco de dados ou o nome do esquema, pois o Snowflake não atualizará o nome DNS do serviço.

• Um nome DNS é apenas para comunicações internas no Snowflake entre serviços em execução na mesma conta. Não é acessível pela internet.