Contrato de ambiente de execução de contêiner

Nesta página, listamos os principais requisitos e comportamentos de contêineres no Cloud Run. A página também destaca as diferenças entre os serviços do Cloud Run, os jobs do Cloud Run e os pools de workers do Cloud Run, quando apropriado.

Linguagens e imagens compatíveis

Sua imagem de contêiner pode executar o código escrito na linguagem de programação de sua escolha e usar qualquer imagem de base, desde que respeite as restrições listadas nesta página.

Os executáveis na imagem do contêiner precisam ser compilados para Linux de 64 bits. O Cloud Run é compatível especificamente com o formato ABI do Linux x86_64.

O Cloud Run aceita imagens de contêiner no manifesto de imagem do Docker V2, no Esquema 1, no Esquema 2 e nos formatos de imagem OCI. O Cloud Run também aceita imagens de contêiner compactadas com Zstd.

Se você estiver implantando uma imagem de multiarquitetura, a lista de manifestos precisará incluir linux/amd64.

Para funções implantadas com o Cloud Run, é possível usar uma das imagens de base do ambiente de execução do Cloud Run publicadas pelos buildpacks do Google Cloud para receber atualizações automáticas de segurança e manutenção. Consulte a Programação de suporte do ambiente de execução os ambientes de execução compatíveis.

Como detectar solicitações na porta correta (serviços)

Um serviço do Cloud Run inicia instâncias do Cloud Run para processar solicitações recebidas. Uma instância do Cloud Run sempre tem um único contêiner de entrada para detecção e, opcionalmente, um ou mais contêineres de arquivo secundário. Os seguintes detalhes de configuração de porta se aplicam apenas ao contêiner de entrada, não aos de arquivo secundário.

O contêiner de entrada em uma instância precisa detectar solicitações em 0.0.0.0 na porta para a qual as solicitações são enviadas. O contêiner de entrada não deve detectar 127.0.0.1. Por padrão, as solicitações são enviadas para 8080, mas é possível configurar o Cloud Run para enviar solicitações à porta de sua escolha. O Cloud Run injeta a variável de ambiente PORT no contêiner de entrada.

O contêiner que está sendo executado em um job precisa sair após a conclusão

Para jobs do Cloud Run, o contêiner precisa sair com o código de saída 0 quando o job for concluído e sair com um código de saída diferente de zero quando o job falhar.

Como os jobs não devem atender a solicitações, o contêiner não pode detectar uma porta ou iniciar um servidor da Web.

Criptografia da camada de transporte (TLS)

O contêiner não deve implementar nenhuma segurança de camada de transporte (TLS, na sigla em inglês) diretamente. O TLS é encerrado pelo Cloud Run para HTTPS e gRPC e, em seguida, as solicitações são encaminhadas por proxy como HTTP/1 ou gRPC para o contêiner sem TLS.

Se você configurar um serviço do Cloud Run para usar o HTTP/2 de ponta a ponta, o contêiner precisará processar solicitações no formato HTTP/2 de texto não criptografado (h2c), porque o TLS ainda está sendo encerrado automaticamente pelo Cloud Run.

Respostas (serviços)

Para os serviços do Cloud Run, a instância de contêiner precisa enviar uma resposta no tempo especificado na configuração de tempo limite da solicitação depois que recebe uma solicitação, incluindo o tempo de inicialização do contêiner. Caso contrário, a solicitação é finalizada e um erro 504 é retornado.

Cookies e armazenamento em cache de resposta

Se a resposta do serviço do Cloud Run contiver um cabeçalho Set-Cookie, o Cloud Run definirá o cabeçalho Cache-Control como private para que a resposta não seja armazenada em cache. Isso impede que outros usuários recuperem o cookie.

Variáveis de ambiente

Diferentes conjuntos de variáveis de ambiente estão disponíveis para serviços e jobs do Cloud Run.

Variáveis de ambiente para serviços

As variáveis de ambiente a seguir são adicionadas automaticamente a todos os contêineres em execução, exceto PORT. A variável PORT só é adicionada ao contêiner de entrada:

Variáveis de ambiente para jobs

Para jobs do Cloud Run, as seguintes variáveis de ambiente são definidas:

Variáveis de ambiente para pools de workers

O Cloud Run define as seguintes variáveis de ambiente para pools de workers:

Requisitos de cabeçalho de solicitação e resposta (serviços)

Para serviços, o Cloud Run restringe os nomes de cabeçalho a arquivos ASCII que não são espaços em branco para impressão e não podem conter dois-pontos. O Cloud Run restringe os valores de cabeçalho a caracteres ASCII visíveis, além de espaço e tabulação horizontal, de acordo com o IETF RFC 7230.

Acesso ao sistema de arquivos

O sistema de arquivos de cada contêiner é gravável e está sujeito ao seguinte comportamento:

• Esse é um sistema de arquivos na memória. Portanto, gravar nele usa a memória da instância.
• Os dados gravados no sistema de arquivos não são mantidos quando a instância é interrompida.

Não é possível especificar um limite de tamanho para esse sistema de arquivos, portanto, você pode usar toda a memória alocada para sua instância gravando no sistema de arquivos na memória, o que causará uma falha na instância. É possível evitar esse problema se usar um volume na memória dedicado com um limite de tamanho.

Ciclo de vida da instância

As características do ciclo de vida são diferentes para jobs e serviços do Cloud Run. Portanto, elas são descritas separadamente nas subseções a seguir.

Para serviços

As características a seguir se aplicam apenas aos serviços.

Escalonamento de serviços

Por padrão, um serviço do Cloud Run é escalonado automaticamente para o número de instâncias necessárias para lidar com todas as solicitações recebidas, eventos ou utilização da CPU. Você também pode usar o escalonamento manual se precisar de mais controle sobre o comportamento de escalonamento.

Cada instância executa um número fixo de contêineres: um contêiner de entrada e, opcionalmente, um ou mais contêineres de arquivo secundário.

Quando uma revisão não recebe tráfego, ela é escalonada para o número mínimo de instâncias configuradas (zero por padrão).

Inicialização

Para os serviços do Cloud Run, as instâncias precisam ouvir solicitações dentro de quatro minutos após serem iniciadas e todos os contêineres na instância precisam estar íntegros. Durante esse tempo de inicialização, as instâncias de contêiner são alocadas na CPU. É possível ativar a otimização da CPU de inicialização para aumentar temporariamente a alocação de CPU durante a inicialização de instâncias de contêiner para reduzir a latência da inicialização.

As solicitações serão enviadas para o contêiner de entrada assim que ele estiver detectando a porta configurada.

Uma solicitação que aguarda uma instância será mantida pendente em uma fila da seguinte maneira:

As solicitações ficarão pendentes por até 3,5 vezes o tempo médio de inicialização das instâncias de contêiner desse serviço ou 10 segundos, o que for maior.

É possível configurar uma sondagem de inicialização para determinar se o contêiner foi iniciado e se está pronto para atender às solicitações.

Para um serviço do Cloud Run que consiste em instâncias de vários contêineres, é possível especificar a sequência em que os contêineres são iniciados na instância configurando a ordem de inicialização de contêiner.

Como processar uma solicitação

Para os serviços do Cloud Run, a CPU é sempre alocada para todos os contêineres, incluindo arquivos secundários em uma instância, desde que a revisão do Cloud Run esteja processando pelo menos uma solicitação.

Inativo

Para os serviços do Cloud Run, uma instância inativa é aquela que não está processando nenhuma solicitação.

A CPU alocada para todos os contêineres em uma instância inativa depende das configurações de faturamento configuradas.

A menos que uma instância precise permanecer inativa devido à configuração do número mínimo de instâncias, ela não ficará inativa por mais de 15 minutos.

Encerrar

Para serviços do Cloud Run, uma instância inativa pode ser encerrada a qualquer momento, inclusive as instâncias mantidas ativas devido a um número mínimo configurado de instâncias. Se uma instância que estiver processando solicitações precisar ser encerrada, as solicitações já em andamento terão tempo para serem concluídas, e as novas solicitações recebidas serão encaminhadas para outras instâncias. Em casos excepcionais, o Cloud Run pode iniciar um encerramento e enviar um sinal SIGTERM para um contêiner que ainda esteja processando solicitações.

Antes de encerrar uma instância, o Cloud Run envia um sinal SIGTERM para todos os contêineres em uma instância, indicando o início de um período de 10 segundos antes que o encerramento real ocorra. Nesse ponto, o Cloud Run envia um sinal SIGKILL. Durante esse período, a instância recebe uma CPU alocada e é faturada. Nos serviços que usam o ambiente de execução de primeira geração, se a instância não capturar o sinal SIGTERM, ela será imediatamente encerrada. Em serviços que usam o ambiente de execução de segunda geração, recomendamos instalar um handler SIGTERM no contêiner para receber um aviso quando o Cloud Run estiver prestes a encerrar uma instância.

Encerramento forçado

Se um ou mais contêineres do Cloud Run excederem o limite total de memória do contêiner, a instância será encerrada. Todas as solicitações que ainda estão em processamento na instância terminam com um erro HTTP 500.

Para jobs

Para jobs do Cloud Run, as instâncias de contêiner são executadas até que a instância de contêiner saia ou até que o tempo limite da tarefa seja atingido ou até que o contêiner falhe.

Códigos de saída

É possível usar códigos de saída de job para saber se o job foi concluído com sucesso ou se encontrou erros. Os códigos de saída são valores numéricos que mapeiam para conclusão bem-sucedida ou tipos específicos de erros.

A tabela a seguir especifica códigos de saída comuns e as definições deles:

Encerramento forçado

Uma instância de contêiner do Cloud Run que excede o limite de memória permitido é encerrada. Todas as solicitações que ainda estão em processamento na instância de contêiner terminam com um erro HTTP 500.

Se uma tarefa exceder o tempo limite da tarefa, o Cloud Run enviará um sinal "SIGTERM" indicando o início de um período de 10 segundos antes que o encerramento real ocorra. A execução envia um sinal SIGKILL, encerrando a instância do contêiner.

Durante esse período, as instâncias de contêiner são alocadas para todo o ciclo de vida da CPU e cobradas.

Consulte o mesmo exemplo de código SIGTERM para saber como capturar o sinal SIGTERM.

Para pools de workers

As características a seguir se aplicam apenas a pools de workers.

Escalonamento

Os pools de workers não são escalonados automaticamente. Escalone manualmente o número de instâncias que seu pool de workers do Cloud Run precisa para processar a carga de trabalho. Por padrão, o Cloud Run define o número de instâncias como 1. É possível aumentar ou diminuir esse número ou desativar o escalonamento definindo o número como 0. Para iniciar e permanecer ativa, sua carga de trabalho precisa ter pelo menos uma instância. Se você definir o número mínimo de instâncias como 0, a instância de worker não será iniciada, mesmo que a implantação seja bem-sucedida.

Inicialização

As instâncias de pool de workers do Cloud Run iniciam o contêiner com o ponto de entrada especificado na imagem do contêiner ou na configuração do pool de workers. Todos os contêineres na instância precisam estar íntegros.

Por padrão, as instâncias de contêiner do Cloud Run usam uma CPU. É possível aumentar ou diminuir esse valor com base nos seus requisitos.

É possível configurar uma sondagem de inicialização para determinar se o contêiner foi iniciado. A sondagem de inicialização permite que o Cloud Run inspecione a integridade de um contêiner dependente, garantindo que ele seja aprovado antes de iniciar o próximo contêiner. Se você não usar verificações de integridade, o Cloud Run vai iniciar os contêineres na ordem especificada, mesmo que os contêineres de que eles dependem não sejam iniciados.

Alocação de recursos

Os pools de workers não ficam inativos. Independente do estado, o Cloud Run sempre aloca CPU para todos os contêineres, incluindo arquivos secundários em uma instância do pool de workers. Enquanto estiver em execução, uma instância será considerada ativa e será cobrada de acordo.

Encerrar

O Cloud Run não reduzir escala vertical das instâncias do pool de workers com base em instâncias ociosas. Se uma instância de processamento de carga de trabalho precisar ser encerrada, o Cloud Run dará tempo para que as tarefas em andamento sejam concluídas e encaminhará novas cargas de trabalho para outras instâncias. O Cloud Run também pode iniciar um encerramento e enviar um sinal SIGTERM para um contêiner que ainda esteja processando uma carga de trabalho.

Antes de encerrar uma instância, o Cloud Run envia um sinal SIGTERM para todos os contêineres em uma instância. Esse sinal indica o início de um período de 10 segundos antes do encerramento real, em que o Cloud Run envia um sinal SIGKILL. Durante esse período de encerramento, a instância recebe uma CPU alocada e é faturada. Recomendamos instalar um manipulador de SIGTERM no contêiner para receber um aviso quando o Cloud Run estiver prestes a encerrar uma instância.

Encerramento forçado

Se um ou mais contêineres do Cloud Run excederem o limite total de memória do contêiner, o Cloud Run vai encerrar a instância. Todas as solicitações que ainda estão em processamento na instância terminam com um erro HTTP 500.

Recursos da instância do contêiner

As seções a seguir descrevem os recursos da instância de contêiner:

• CPU
• Memória
• GPU
• Simultaneidade

CPU

Cada contêiner do Cloud Run em uma instância, por padrão, recebe a vCPU que foi configurada (1 por padrão). É possível configurar limites de CPU em cada contêiner separadamente.

Uma vCPU é implementada como uma abstração do hardware subjacente para fornecer o tempo de CPU equivalente aproximado de um único hyper-thread de hardware em plataformas de CPU variáveis. Todas as plataformas de CPU usadas pelo Cloud Run são compatíveis com o conjunto de instruções AVX2. O contrato do contêiner não contém detalhes adicionais da plataforma de CPU.

O contêiner pode ser executado em vários núcleos simultaneamente.

Para serviços do Cloud Run, a alocação de CPU depende do faturamento selecionado.

Se você selecionar o faturamento com base em instâncias, a CPU será alocada durante o ciclo de vida da instância. Se você selecionar o faturamento com base em solicitações (padrão), a CPU será alocada quando as instâncias estiverem processando solicitações. Consulte as configurações de faturamento para mais detalhes.

Se você tiver configurado várias instâncias mínimas, use o faturamento com base em instâncias para que a CPU seja alocada fora das solicitações.

É possível ativar a otimização da CPU de inicialização para aumentar temporariamente a alocação de CPU durante a inicialização de instâncias para reduzir a latência da inicialização.

Memória

Por padrão, cada instância de contêiner do Cloud Run recebe a memória que foi configurada (512 MiB por padrão). É possível configurar limites de memória em cada contêiner separadamente.

Os usos típicos da memória incluem:

• Código carregado na memória para executar o serviço
• Gravação no sistema de arquivos
• Processos extras em execução no contêiner, como um servidor nginx
• Sistemas de armazenamento em cache na memória, como o OpCache do PHP
• Uso da memória por solicitação
• Volumes compartilhados na memória

GPU

É possível configurar um contêiner em uma instância do Cloud Run para acessar uma GPU. Se o serviço do Cloud Run for implantado com contêineres de arquivo secundário, apenas um contêiner na implantação pode acessar a GPU. Consulte Configure a GPU para conferir os requisitos e os detalhes.

Bibliotecas da NVIDIA

Por padrão, todas as bibliotecas de drivers da NVIDIA L4 são montadas em /usr/local/nvidia/lib64. O Cloud Run anexa automaticamente esse caminho à variável de ambiente LD_LIBRARY_PATH (ou seja, ${LD_LIBRARY_PATH}:/usr/local/nvidia/lib64) do contêiner com a GPU. Isso permite que o vinculador dinâmico encontre as bibliotecas de driver da NVIDIA. O vinculador pesquisa e resolve caminhos na ordem em que você os lista na variável de ambiente LD_LIBRARY_PATH. Todos os valores especificados nessa variável têm precedência sobre o caminho padrão das bibliotecas de driver do Cloud Run /usr/local/nvidia/lib64.

Se você quiser usar uma versão do CUDA maior que 12.2, a maneira mais fácil é depender de uma imagem base NVIDIA mais recente com pacotes de compatibilidade futura já instalados. Outra opção é instalar manualmente os pacotes de compatibilidade futura da NVIDIA e adicioná-los a LD_LIBRARY_PATH. Consulte a matriz de compatibilidade da NVIDIA para determinar quais versões do CUDA são compatíveis com a versão do driver fornecido (535.216.03).

Simultaneidade (serviços)

Para os serviços do Cloud Run, por padrão, cada instância do Cloud Run é definida como várias simultaneidades, em que o contêiner de entrada pode receber mais de uma solicitação ao mesmo tempo. Para alterar isso, defina a simultaneidade.

Sandbox de contêiner

Se você usa o ambiente de execução de primeira geração, as instâncias de contêiner do Cloud Run são colocadas no sandbox usando o sandbox de ambiente de execução de contêiner gVisor. Conforme documentado na referência de compatibilidade do syscall gVisor, algumas chamadas do sistema podem não ser compatíveis com esse sandbox de contêiner.

Se você usar o ambiente de execução de segunda geração, terá compatibilidade total com o Linux. Os jobs do Cloud Run sempre usam o ambiente de execução de segunda geração. No ambiente de execução de segunda geração, /sys/class/dmi/id/product_name é definido como Google Compute Engine.

O ambiente de execução de segunda geração executa o código de serviço em um namespace de processo separado, portanto, ele começa como o processo init do contêiner, que tem uma semântica de processo especial. No ambiente de execução de primeira geração, o código de serviço não é executado como o processo init do contêiner.

Limites do descritor de arquivos

Os ambientes de primeira e segunda geração do Cloud Run definem um limite de 25.000 para o número de descritores de arquivos que um processo pode abrir. Isso se aplica ao contêiner e a qualquer processo filho que ele cria (forks). Esse é um limite rígido. Se você exceder o limite, sua instância poderá ficar sem descritores de arquivo/soquetes.

Limites no ambiente de segunda geração

Exceto pelos limites de descritores de arquivos descritos anteriormente, os limites no ambiente de segunda geração são os padrões do Linux.

Por exemplo, os limites no número de descritores de arquivo que podem ser abertos (conforme capturado em: /proc/sys/fs/file-max) usam o valor padrão de cerca de 10% da memória. Consulte file-max e file-nr na documentação do kernel para mais detalhes.

Da mesma forma, o max_map_count (conforme capturado em /proc/sys/vm/max_map_count), que define o número de áreas de memória que um processo pode ter, está usando o padrão de 65.535. Consulte max-map-count na documentação do kernel para mais detalhes.

Contêineres privilegiados e binários setuid

O Cloud Run não é compatível com contêineres privilegiados. Consequentemente, o Cloud Run não é compatível com binários que usam flags setuid para usuários não raiz, como gcsfuse ou sudo, e pode falhar devido a permissões insuficientes.

Uma alternativa é executar esses binários como usuário raiz e usar o comando su para alternar para outro usuário durante a execução.

Por exemplo, no Dockerfile, remova a instrução USER e, no script de ponto de entrada, use a seguinte sequência:

gcsfuse ...                 # Run gcsfuse as root
su myuser -c "/yourapp.sh"  # Switch to 'myuser' and run 'yourapp.sh'

Usuário que está executando

Se o nome de usuário não existir, o Cloud Run vai executar o contêiner como usuário raiz (uid=0).

Servidor de metadados da instância

As instâncias do Cloud Run expõem um servidor de metadados que pode ser usado para recuperar detalhes sobre seus contêineres, como o ID do projeto, região, ID da instância ou contas de serviço. Também é possível usar o servidor de metadados para gerar tokens para a identidade do serviço.

Para acessar os dados do servidor de metadados, use solicitações HTTP para o endpoint http://metadata.google.internal/ com o cabeçalho Metadata-Flavor: Google: nenhuma biblioteca de cliente é necessária. Para mais informações, consulte Como conseguir metadados.

A tabela a seguir lista algumas das informações disponíveis do servidor de metadados:

O Cloud Run não fornece detalhes sobre a Google Cloud zona em que as instâncias estão sendo executadas. Como consequência, o atributo de metadados /computeMetadata/v1/instance/zone sempre retorna projects/PROJECT-NUMBER/zones/REGION-1.

Nomes de arquivos

Os nomes de arquivo usados nos contêineres precisam ser compatíveis com UTF-8, sejam eles UTF-8 ou algo que possa ser convertido automaticamente em UTF-8 com segurança. Se os nomes dos arquivos usarem codificações diferentes, execute o build do Docker em uma máquina com nomes de arquivo compatíveis com UTF-8 e evite copiar os arquivos para um contêiner que tenha nomes UTF-8 incompatíveis.

A implantação do contêiner falhará se os nomes dos arquivos não forem compatíveis com UTF-8. Não há restrição na codificação de caracteres usada em um arquivo.

Tempo limite das solicitações de saída

Para serviços e jobs do Cloud Run, há um tempo limite após 10 minutos de inatividade para solicitações do contêiner para a VPC. Para solicitações do contêiner para a Internet, há um tempo limite após 20 minutos de inatividade.

Redefinições de conexão de saída

Os streams de conexão do contêiner para a VPC e a Internet podem ser encerrados ocasionalmente e substituídos quando a infraestrutura subjacente for reiniciada ou atualizada. Se o aplicativo reutilizar conexões de longa duração, recomendamos configurá-lo para restabelecer as conexões e evitar a reutilização de uma conexão inativa.