Referência de especificação de serviço¶

Campos containers.name e containers.image¶

Para cada contêiner, apenas os campos nome e imagem são obrigatórios.

• name é o nome da imagem. Este nome pode ser usado para identificar um contêiner específico para fins de observabilidade (por exemplo, logs, metrics).

• image é o nome da imagem que você carregou em um repositório de imagens do Snowflake em sua conta Snowflake.

Por exemplo:

spec:
  containers:
    - name: echo
      image: /tutorial_db/data_schema/tutorial_repository/echo_service:dev

Campos containers.command e containers.args¶

Use esses campos opcionais para controlar qual executável é iniciado em seu contêiner e os argumentos que são passados para esse executável. É possível configurar padrões para eles no momento da criação da imagem, normalmente em um Dockerfile. Usar esses campos de especificação de serviço permite que você altere esses padrões (e, assim, altere o comportamento do contêiner) sem precisar reconstruir sua imagem de contêiner:

• containers.command substitui o Dockerfile ENTRYPOINT. Isso permite que você execute um executável diferente no contêiner.

• containers.args substitui o Dockerfile CMD. Isso permite fornecer diferentes argumentos ao comando (o executável).

Exemplo

Seu Dockerfile inclui o seguinte código:

ENTRYPOINT ["python3", "main.py"]
CMD ["Bob"]

Essas entradas Dockerfile executam o comando python3 e passam dois argumentos: main.py e Bob. Você pode substituir esses valores no arquivo de especificação da seguinte forma:

• Para substituir ENTRYPOINT, adicione o campo containers.command no arquivo de especificação:

  spec:
    containers:
    - name: echo
      image: <image_name>
      command:
      - python3.9
      - main.py
  

  Copy

• Para substituir o argumento “Bob”, adicione o campo containers.args no arquivo de especificação:

  spec:
    containers:
    - name: echo
      image: <image_name>
      args:
        - Alice
  

  Copy

Campo containers.env¶

Use o campo containers.env para definir variáveis de ambiente do contêiner. Todos os processos no contêiner têm acesso a estas variáveis de ambiente:

spec:
  containers:
  - name: <name>
    image: <image_name>
    env:
      ENV_VARIABLE_1: <value1>
      ENV_VARIABLE_2: <value2>
      …
      …

Exemplo

No Tutorial 1, o código do aplicativo (echo_service.py) lê as variáveis de ambiente conforme mostrado:

CHARACTER_NAME = os.getenv('CHARACTER_NAME', 'I')
SERVER_PORT = os.getenv('SERVER_PORT', 8080)

Observe que o exemplo passa valores padrão das variáveis para a função getenv. Se as variáveis de ambiente não forem definidas, esses padrões serão usados.

• CHARACTER_NAME: quando o serviço Echo recebe uma solicitação HTTP POST com uma cadeia de caracteres (por exemplo, «Olá»), o serviço retorna «Eu disse Olá». Você pode substituir esse valor padrão no arquivo de especificação. Por exemplo, defina o valor como «Bob»; o serviço Echo retorna uma resposta «Bob disse Olá».

• SERVER_PORT: nesta configuração padrão, o serviço Echo escuta na porta 8080. Você pode substituir o valor padrão e especificar outra porta.

A especificação de serviço a seguir substitui esses dois valores de variável de ambiente:

spec:
  containers:
  - name: echo
    image: <image_name>
    env:
      CHARACTER_NAME: Bob
      SERVER_PORT: 8085
  endpoints:
  - name: echo-endpoint
    port: 8085

Observe que, como você alterou o número da porta em que seu serviço escuta, a especificação também deve atualizar o ponto de extremidade (valor endpoints.port field), conforme mostrado.

Campo containers.readinessProbe¶

Use o campo containers.readinessProbe para identificar uma sonda de prontidão em seu aplicativo. Snowflake chama essa investigação para determinar quando seu aplicativo está pronto para atender solicitações.

Snowflake faz uma solicitação HTTP GET para a análise de prontidão especificada, na porta e no caminho especificados, e procura que seu serviço retorne um status HTTP 200 OK para garantir que apenas contêineres íntegros tenham tráfego.

Use os seguintes campos para fornecer as informações necessárias:

• port: a porta de rede na qual o serviço está atendendo às solicitações de análise de prontidão. Você não precisa declarar esta porta como um ponto de extremidade.

• path: Snowflake faz solicitações HTTP GET ao serviço com este caminho.

Exemplo

No Tutorial 1, o código do aplicativo (echo_python.py) implementa a seguinte análise de prontidão:

@app.get("/healthcheck")
def readiness_probe():

Assim, o arquivo de especificação inclui o campo containers.readinessProbe:

spec:
  containers:
  - name: echo
    image: <image_name>
    env:
      SERVER_PORT: 8088
      CHARACTER_NAME: Bob
    readinessProbe:
      port: 8088
      path: /healthcheck
  endpoints:
  - name: echo-endpoint
    port: 8088

A porta especificada pela análise de prontidão não precisa ser um ponto de extremidade configurado. Seu serviço pode escutar em uma porta diferente apenas para fins de análise de prontidão.

Campo containers.volumeMounts¶

Como os campos spec.volumes e spec.containers.volumeMounts funcionam juntos, eles são explicados juntos em uma seção. Para obter mais informações, consulte Campo spec.volumes (opcional).

Campo containers.resources¶

Um pool de computação define um conjunto de recursos disponíveis (CPU, memória e armazenamento) e o Snowflake determina onde no pool de computação seus serviços serão executados.

É recomendável indicar explicitamente os requisitos de recurso para o contêiner específico e definir limites apropriados na especificação. Observe que os recursos especificados são limitados pela família de instâncias dos nós no seu pool de computação. Para obter mais informações, consulte CREATE COMPUTE POOL.

Use o campo containers.resources para especificar requisitos de recurso explícitos para o contêiner de aplicativo específico:

• containers.resources.requests: As solicitações que você especificar devem ser o uso médio de recurso que você prevê para seu serviço. O Snowflake usa essas informações para determinar o posicionamento da instância de serviço no pool de computação. O Snowflake garante que a soma das solicitações de recurso colocadas em um determinado nó se ajuste aos recursos disponíveis no nó.

• containers.resources.limits: Os limites especificados determinam que o Snowflake não aloque recursos maiores que os limites especificados. Assim, você pode evitar custos excedentes.

Você pode especificar solicitações e limites para os seguintes recursos:

• memory: esta é a memória necessária para o contêiner do seu aplicativo. É possível usar unidades decimais ou binárias para expressar os valores. Por exemplo, 2G representa uma solicitação de 2.000.000.000 bytes e 2Gi representa uma solicitação de 2 × 1.024 × 1.024 × 1.024 bytes.

  Ao especificar memória, é necessária uma unidade. Por exemplo, 100M ou 5Gi. As unidades suportadas são: M, Mi, G, Gi.

• cpu: refere-se a unidades de núcleo virtual (vCPU). Por exemplo, a unidade 1 CPU é equivalente a 1 vCPU. São permitidas solicitações fracionárias, como 0,5, que também pode ser expressa como 500m.

• nvidia.com/gpu: se GPUs forem necessários, eles deverão ser solicitados e também deverá haver um limit especificado para a mesma quantidade. Se o seu contêiner não especificar solicitações e limites para a capacidade de GPU, ele não poderá acessar GPUs. O número de GPUs que é possível solicitar é limitado pelo máximo de GPUs compatível com o INSTANCE_TYPE que você escolhe ao criar um pool de computação.

resource.requests e resource.limits são relativos à capacidade do nó (vCPU e memória) da família de instâncias do pool de computação associado.

• Se uma solicitação de recurso (CPU, memória ou ambos) não for fornecida, o Snowflake deriva uma para você:

  • Para cpu, o valor derivado é 0,5 ou o limite de cpu fornecido, o que for menor.

  • Para memory, o valor derivado é 0,5 GiB ou o limite de memory fornecido, o que for menor.

• Se um limite de recurso (CPU, memória ou ambos) não for fornecido, o Snowflake definirá os limites como padrão para a capacidade do nó para a família de instância do pool de computação associado.

• Se você fornecer resource.limits e eles excederem a capacidade do nó, o Snowflake limitará a capacidade do nó.

• O Snowflake avalia esses requisitos de recurso de forma independente para cpu e memory.

Observe que, se for teoricamente impossível para o Snowflake agendar o serviço no pool de computação fornecido, CREATE SERVICE falhará. Teoricamente impossível pressupõe que o pool de computação tenha o número máximo de nós permitidos e não haja outros serviços em execução no pool de computação. Ou seja, não há como o Snowflake alocar os recursos solicitados dentro dos limites do pool de computação. Se for teoricamente possível, mas os recursos necessários estiverem em uso, então CREATE SERVICE será bem-sucedido. Algumas instâncias de serviço relatarão o status indicando que o serviço não pode ser agendado devido a recursos insuficientes até que os recursos estejam disponíveis.

Exemplo 1

Na especificação a seguir, o campo containers.resources descreve os requisitos de recursos do contêiner:

spec:
  containers:
  - name: resource-test-gpu
    image: ...
    resources:
      requests:
        memory: 2G
        cpu: 0.5
        nvidia.com/gpu: 1
      limits:
        memory: 4G
        nvidia.com/gpu: 1

Neste exemplo, o Snowflake é solicitado a alocar pelo menos 2 GB de memória, um GPU e meio núcleo CPU para o contêiner. Ao mesmo tempo, o contêiner não pode usar mais de 4 GB de memória e um GPU.

Exemplo 2

Suponha o seguinte:

• Você cria um pool de computação de dois nós; cada nó tem 27 GB de memória e uma GPU:

  CREATE COMPUTE POOL tutorial_compute_pool
    MIN_NODES = 2
    MAX_NODES = 2
    INSTANCE_FAMILY = gpu_nv_s
  

  Copy

• Você cria um serviço que pede ao Snowflake para executar duas instâncias do serviço:

  CREATE SERVICE echo_service
    MIN_INSTANCES=2
    MAX_INSTANCES=2
    IN COMPUTE POOL tutorial_compute_pool
    FROM @<stage_path>
    SPEC=<spec-file-stage-path>;
  

  Copy

  Tanto MIN_INSTANCES quanto MAX_INSTANCES estão definidos como 2. Portanto, o Snowflake executará duas instâncias do serviço.

Agora, considere estes cenários:

• Se o seu serviço não incluir explicitamente os requisitos de recurso na especificação do aplicativo, o Snowflake decidirá se executará essas instâncias no mesmo nó ou em nós diferentes no pool de computação.

• Você inclui requisitos de recurso na especificação do serviço e solicita 10 GB de memória para o contêiner:

  - name: resource-test
    image: ...
    resources:
      requests:
        memory: 15G
  

  Copy

  O nó do pool de computação tem 27 GB de memória e o Snowflake não pode executar dois contêineres no mesmo nó. O Snowflake executará as duas instâncias de serviço em nós separados no pool de computação.

• Você inclui requisitos de recurso na especificação do serviço e solicita 1 GB de memória e uma GPU para o contêiner:

  spec:
    containers:
    - name: resource-test-gpu
      image: ...
      resources:
        requests:
          memory: 2G
          nvidia.com/gpu: 1
        limits:
          nvidia.com/gpu: 1
  

  Copy

  Você está solicitando um GPU por contêiner e cada nó possui apenas um GPU. Nesse caso, embora a memória não seja um problema, o Snowflake não pode agendar ambas as instâncias de serviço em um nó. Este requisito força o Snowflake a executar as duas instâncias de serviço em dois nós de pool de computação separados.

Campo containers.secrets¶

secrets:                                # optional list
  - snowflakeSecret:
      objectName: <object-name>         # specify this or objectReference
      objectReference: <reference-name> # specify this or objectName
    directoryPath: <path>               # specify this or envVarName
    envVarName: <name>                  # specify this or directoryPath
    secretKeyRef: username | password | secret_string # specify only with envVarName
  - snowflakeSecret: <object-name>      # equivalent to snowflakeSecret.objectName
    ...

Use o campo containers.secrets em sua especificação de serviço para fornecer credenciais gerenciadas pelo Snowflake aos seus contêineres de aplicativo. Comece armazenando as credenciais em objetos secretos do Snowflake. Em seguida, na especificação do serviço, faça referência ao objeto secreto e especifique onde colocar as credenciais dentro do contêiner.

A seguir está um resumo de como usar os campos containers.secrets:

• Especificar segredo do Snowflake: Use campo snowflakeSecret para especificar um nome de objeto ou uma referência de objeto do segredo do Snowflake. Referências de objeto são aplicáveis ao usar o Snowpark Container Services para criar um Native App (um aplicativo com contêineres).

  • Use secretKeyRef para fornecer o nome da chave no segredo do Snowflake.

• Especifique o posicionamento do segredo no contêiner do aplicativo: Use o campo envVarName para passar o segredo como variáveis de ambiente ou directoryPath para gravar os segredos em arquivos do contêiner locais.

Para obter mais informações, consulte Como passar credenciais para um contêiner usando segredos do Snowflake.

Observe que a função que está criando o serviço (função do proprietário) precisará do privilégio READ sobre os segredos referenciados.

Sobre os tipos de volume suportados¶

O Snowflake oferece suporte a estes tipos de volume para uso pelos contêineres de aplicativos: local, memória, bloco e estágio do Snowflake.

• Volume local: os contêineres em uma instância de serviço podem usar um disco local para compartilhar arquivos. Por exemplo, se seu aplicativo tiver dois contêineres—um contêiner de aplicativo e um analisador de logs—, o aplicativo poderá gravar logs no volume local e o analisador de logs poderá ler os logs.

  Observe que, se você estiver executando diversas instâncias de um serviço, somente contêineres pertencentes a uma instância de serviço poderão compartilhar volumes. Os contêineres que pertencem a diferentes instâncias de serviço não compartilham volumes.

• Memória: você pode usar um sistema de arquivos com suporte de RAM para uso em contêiner.

• Bloco: os contêineres também podem usar volumes de armazenamento em bloco. Para obter mais informações, consulte Uso de volumes de armazenamento em bloco com serviços.

• Estágio Snowflake: Também é possível dar aos contêineres acesso conveniente aos arquivos em um estágio Snowflake em sua conta. Para obter mais informações, consulte Usando volumes de estágio Snowflake com serviços.

Exemplo

Seu aplicativo de machine learning inclui os dois contêineres a seguir:

• Um contêiner app para o aplicativo principal

• Um contêiner logger-agent que coleta logs e os carrega no Amazon S3

Esses contêineres usam os dois volumes a seguir:

• Volume local: este aplicativo grava os logs que o agente de log lê.

• Estágio do Snowflake, @model_stage: o aplicativo principal lê arquivos deste estágio.

Na especificação de exemplo a seguir, o contêiner app monta os volumes logs e models, e o contêiner logging-agent monta apenas o volume logs:

spec:
  containers:
  - name: app
    image: <image1-name>
    volumeMounts:
    - name: logs
      mountPath: /opt/app/logs
    - name: models
      mountPath: /opt/models
  - name: logging-agent
    image: <image2-name>
    volumeMounts:
    - name: logs
      mountPath: /opt/logs
  volumes:
  - name: logs
    source: local
  - name: models
    source: "@model_stage"

Copy

Se diversas instâncias do serviço estiverem em execução, os contêineres logging-agent e app em uma instância de serviço compartilharão o volume logs. O volume logs não é compartilhado entre instâncias de serviço.

Se, além desses volumes, seu contêiner app também usar um volume de memória de 2 GB, revise a especificação para incluir o volume na lista volumes e também adicione outra montagem de volume nos contêineres app lista volumeMounts:

spec:
  containers:
  - name: app
    image: <image1-name>
    volumeMounts:
    - name: logs
      mountPath: /opt/app/logs
    - name: models
      mountPath: /opt/models
    - name: my-mem-volume
      mountPath: /dev/shm
  - name: logging-agent
    image: <image2-name>
    volumeMounts:
    - name: logs
      mountPath: /opt/logs
  volumes:
  - name: logs
    source: local
  - name: models
    source: "@model_stage"
  - name: "my-mem-volume"
    source: memory
    size: 2G

Copy

Observe que ao especificar memory como o volume source, também é necessário especificar o campo volumes.size para indicar o tamanho da memória. Para obter informações sobre as unidades de tamanho de memória que você pode especificar, consulte Sobre as unidades.

Sobre permissões de arquivo em volumes montados¶

Um contêiner que monta um estágio Snowflake ou um volume de armazenamento em bloco normalmente é executado como um usuário raiz. No entanto, às vezes o seu contêiner pode ser executado como um usuário não root. Por exemplo:

• Se o seu aplicativo usar uma biblioteca de terceiros, a biblioteca usará um usuário não root para executar o código do aplicativo dentro do contêiner.

• Por outros motivos, como segurança, você pode executar seu aplicativo como um usuário não root dentro do contêiner.

Para evitar possíveis erros relacionados às permissões do usuário do arquivo, é importante definir o ID do usuário (UID) e o ID de grupo (GID) do contêiner como parte da especificação. Isto é especialmente relevante para contêineres que usam um usuário e grupo específico para iniciar ou executar o aplicativo dentro do contêiner. Ao definir UID e GID apropriados, você pode usar um contêiner em execução como usuário não root. Por exemplo:

spec:
  ...

  volumes:
  - name: stagemount
    source: "@test"
    uid: <UID-value>
    gid: <GID-value>

Snowflake usa essas informações para montar o estágio com as permissões apropriadas.

Para obter o UID e GID do contêiner, faça o seguinte:

1. Execute o contêiner localmente usando docker run.

2. Procure o ID do contêiner usando o comando docker container list. Amostra de saída parcial:

   CONTAINER ID   IMAGE                       COMMAND
   —----------------------------------------------------------
   a6a1f1fe204d  tutorial-image         "/usr/local/bin/entr…"
   

3. Execute o comando docker id dentro do contêiner para obter UID e GID:

   docker exec -it <container-id> id
   

   Copy

   Exemplo de saída:

   uid=0(root) gid=0(root) groups=0(root)