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

Diretrizes gerais¶

Uma especificação de serviço/trabalho tem estes campos spec de nível superior:

• spec.containers (obrigatório): uma lista de um ou mais contêineres de aplicativos. Seu aplicativo conteinerizado deve ter pelo menos um contêiner.

• spec.endpoints (opcional): uma lista de pontos de extremidade que o serviço expõe. Você pode escolher um ponto de extremidade público, permitindo acesso de entrada de rede ao serviço.

• spec.volumes (opcional): uma lista de volumes de armazenamento para uso pelos contêineres.

• spec.logExporters (opcional): este campo gerencia o nível de logs de contêiner exportados para a tabela de eventos em sua conta.

As seguintes diretrizes de formato se aplicam aos campos name (nomes de contêiner, ponto de extremidade e volume):

• Pode ter até 63 caracteres

• Pode conter uma sequência de caracteres alfanuméricos minúsculos ou “-“

• Deve começar com um caractere alfabético

• Deve terminar com um caractere alfanumérico

As seções a seguir explicam cada um dos campos spec de nível superior.

Campo spec.containers (obrigatório)¶

O campo containers é uma lista de contêineres OCI no seu aplicativo. Para cada contêiner, apenas name e image são campos obrigatórios. O campo image refere-se ao 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

Quando você cria um serviço (ou trabalho), o Snowflake executa esses contêineres em um único nó no pool de computação especificado, compartilhando a mesma interface de rede. É possível executar diversas instâncias de serviço; nesse caso, cada conjunto desses contêineres em execução é conhecido como Instância de serviço.

As seções a seguir explicam os tipos de campos containers.

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

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

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

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

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

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

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

secrets:                            # optional list
  - snowflakeSecret:
    secretKeyRef:
    envVarName:                      # specify this or directoryPath
    directoryPath:                   # specify this or envVarName

Campo spec.endpoints (opcional)¶

Use o campo spec.endpoints para especificar uma lista de nomes para as portas de rede TCP que seu aplicativo expõe. O Snowpark Container Services pode expor zero a muitos pontos de extremidade. Use os seguintes campos para descrever um ponto de extremidade:

• name: nome exclusivo do ponto de extremidade. Ao se referir ao ponto de extremidade em uma função de serviço, você especifica esse nome.

• port: a porta de rede na qual seu aplicativo está escutando.

• protocol: o protocolo suportado pelo ponto de extremidade. Os valores aceitos são TCP, HTTP e HTTPS. Por padrão, o protocolo é HTTP. O protocolo deve ser HTTP ou HTTPS quando esse ponto de extremidade for público ou o destino de uma função de serviço (consulte Como usar um serviço).

• public: se você quiser que esse ponto de extremidade seja acessível pela internet, defina esse campo como true.

Exemplo

A seguir está a especificação do aplicativo usada no Tutorial 1:

spec:
  container:
  - name: echo
    image: <image-name>
    env:
      SERVER_PORT: 8000
      CHARACTER_NAME: Bob
    readinessProbe:
      port: 8000
      path: /healthcheck
  endpoint:
  - name: echoendpoint
    port: 8000
    public: true

Este contêiner de aplicativo expõe um ponto de extremidade. Também inclui o campo opcional public para permitir o acesso ao ponto de extremidade de fora do Snowflake (acesso à internet). Por padrão, public é false.

Campo spec.volumes (opcional)¶

Esta seção explica os campos spec.volumes e spec.containers.volumeMounts. volumes define um sistema de arquivos compartilhado. Um volumeMount define onde um volume aparece em contêineres. Vários contêineres podem compartilhar o mesmo volume. Portanto, volumes é um campo de nível spec e volumeMount faz parte de uma especificação de contêiner.

Use esses campos para descrever os volumes e montagens de volume

• Use spec.volumes para especificar os volumes disponíveis para seus contêineres. volumes é uma lista. Ou seja, pode haver vários volumes. Use os seguintes campos para descrever um volume:

  • name: nome exclusivo do volume. É referido por spec.containers.volumeMounts.name.

  • source: pode ser local, memory ou "@<nome do estágio>".

  • uid: para um volume de estágio Snowflake, esse é o uid do arquivo montado.

  • gid: para um volume de estágio Snowflake, este é o gid do arquivo montado.

  • size: para um volume de memória, esse é o tamanho do volume.

• Use spec.containers.volumeMounts para indicar onde os volumes especificados estão montados no sistema de arquivos do contêiner. containers.volumeMounts também é uma lista. Ou seja, cada contêiner pode ter múltiplas montagens de volume. Use os campos a seguir para descrever uma montagem de volume:

  • name: o nome do volume a ser montado. Um único contêiner pode fazer referência ao mesmo volume várias vezes.

  • mountPath: o caminho do arquivo onde o volume do contêiner deve ser montado.

Snowflake oferece suporte a estes tipos de volume para uso de contêineres de aplicativos: volumes locais, memória e estágio 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.

• Estágio Snowflake: você pode criar um estágio Snowflake e fornecer aos contêineres acesso conveniente aos arquivos preparados. As seguintes condições se aplicam quando você monta um estágio Snowflake:

  • Estágios externos não são suportados. Somente estágios internos do Snowflake com criptografia SSE são suportados. Use CREATE STAGE para criar esse estágio:

    CREATE STAGE my_stage ENCRYPTION = (type = 'SNOWFLAKE_SSE');
    

    Copy

  • Você pode montar um estágio ou subdiretório, por exemplo, @my_stage, @my_stage/folder, em um estágio. Não é possível montar um arquivo, por exemplo, @my_stage/folder/file, em um estágio.

  • A função de serviço determina as permissões concedidas aos contêineres para acessar um estágio montado. A função de serviço é a função usada para criar o serviço/trabalho. É também a função que o serviço/trabalho usa para todas as interações do Snowflake.

    Por exemplo, se a função de serviço não tiver o privilégio WRITE em um estágio, a montagem desse estágio será somente leitura. Ou seja, os containers só podem ler os arquivos do estágio. Se a função de serviço tiver o privilégio WRITE em um estágio, a montagem desse estágio oferecerá suporte para leitura e gravação. Snowflake carrega atualizações de arquivos de forma assíncrona.

  • Um contêiner que monta um estágio Snowflake normalmente é executado como um usuário root. 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 UID (ID do usuário) e o GID (ID do grupo) 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>
      

      Copy

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

      Para obter UID e GID do contêiner:

      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)
         

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, você também deve 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.

Campo spec.logExporters (opcional)¶

Use spec.logExporters para configurar como o Snowflake coleta os logs do seu aplicativo. Snowflake coleta a saída do seu código no contêiner do aplicativo para saída padrão ou erro padrão.

O Snowflake exporta esses registros para uma tabela de eventos na sua conta. Para obter mais informações, consulte Acesso a logs de contêiner locais. Use spec.logExporters.eventTableConfig para indicar quais logs você deseja salvar na tabela de eventos:

logExporters:
  eventTableConfig:
    logLevel: < INFO | ERROR | NONE >

Os valores logLevel aceitos são:

• INFO: exporte todos os logs do usuário.

• ERROR: exporte apenas os logs de erros. Snowflake exporta apenas os logs do fluxo stderr.

• NONE (padrão): não exporte logs para a tabela de eventos.

Sobre as unidades¶

Uma especificação de serviço assume valores numéricos em vários lugares. O Snowpark Container Services oferece suporte a diversas unidades para expressar esses valores. Para valores grandes e pequenos, você pode usar unidades binárias e decimais conforme mostrado. Na lista a seguir, “#” representa um valor inteiro.

• Unidades binárias:

  • numberKi significa number*1024. Por exemplo, memory: 4Ki é equivalente a memory: 4096.

  • numberMi significa number*1024^2.

  • numberGi significa number*1024^3.

• Unidades decimais:

  • numberk significa number*10^3. Por exemplo, memory: 4k é equivalente a memory: 4000.

  • numberM significa number*10^6.

  • numberG significa number*10^9.

• Unidades fracionárias:

  • numberm significa number*0.001. Por exemplo, cpu: 500m é equivalente a cpu: 0.5.