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

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Nesta página, listamos os principais requisitos e comportamentos de contêineres no Cloud Run. Há algumas diferenças entre os serviços do Cloud Run e os jobs do Cloud Run, que são chamados quando necessário.

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.

As listas de manifestos usadas para imagens de várias arquiteturas não são compatíveis.

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

Para os serviços do Cloud Run, o contêiner precisa detectar solicitações no 0.0.0.0 na porta para as quais as solicitações são enviadas. 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. Dentro das instâncias de contêiner do Cloud Run, o valor da variável de ambiente PORT sempre reflete a porta para a qual as solicitações são enviadas. O padrão é 8080.

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 da instância do contêiner. Caso contrário, a solicitação é finalizada e um erro 504 é retornado.

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 aos contêineres em execução:

Nome Descrição Exemplo
PORT A porta que o servidor HTTP deve detectar. 8080
K_SERVICE O nome do serviço do Cloud Run em execução. hello-world
K_REVISION O nome da revisão do Cloud Run em execução. hello-world.1
K_CONFIGURATION O nome da configuração do Cloud Run que criou a revisão. hello-world

Variáveis de ambiente para jobs

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

Nome Descrição Exemplo
CLOUD_RUN_JOB O nome do job do Cloud Run em execução. hello-world
CLOUD_RUN_EXECUTION O nome da execução do Cloud Run. hello-world-abc
CLOUD_RUN_TASK_INDEX Para cada tarefa, isso será definido como um valor exclusivo entre 0 e o número de tarefas menos 1. 0
CLOUD_RUN_TASK_ATTEMPT O número de novas tentativas para a tarefa. Começa em 0 na primeira tentativa. incrementos em 1 a cada nova tentativa até o valor máximo de tentativas. 0
CLOUD_RUN_TASK_COUNT O número de tarefas definidas no parâmetro --tasks. 1

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

Para serviços do Cloud Run, os nomes de cabeçalho são restritos a arquivos ASCII que não são espaços em branco para impressão e não podem conter dois-pontos. Os valores do cabeçalho são restritos 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 do seu 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 do contêiner.
  • Os dados gravados no sistema de arquivos não permanecem quando a instância do contêiner é interrompida.

Ciclo de vida da instância de contêiner

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 informações a seguir se aplicam apenas aos serviços.

Escalonamento de serviços

Para os serviços do Cloud Run, em resposta a solicitações recebidas, um serviço é escalonado automaticamente para um determinado número de instâncias de contêiner, cada uma executando a imagem do contêiner implantada.

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

Inicialização

Para os serviços do Cloud Run, as instâncias de contêiner precisam detectar solicitações dentro de 4 minutos após o início. 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 à instância do contêiner assim que ela estiver detectando na porta configurada.

Uma solicitação que aguarda o início de uma instância de contêiner será mantida em uma fila por no máximo 10 segundos.

É 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.

Como processar uma solicitação

Para os serviços do Cloud Run, a CPU sempre é alocada quando a instância do contêiner está processando pelo menos uma solicitação.

Inativo

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

A CPU alocada para uma instância de contêiner inativo depende da alocação de CPU configurada.

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

Desligamento

Para serviços do Cloud Run, uma instância de contêiner inativa pode ser encerrada a qualquer momento, inclusive as instâncias mantidas com um número mínimo de instâncias. Se uma instância de contêiner que estiver processando solicitações precisar ser encerrada, novas solicitações recebidas serão encaminhadas para outras instâncias, e as solicitações atualmente processadas terão tempo para serem concluídas.

Antes de encerrar uma instância de contêiner, o Cloud Run envia um sinal SIGTERM, indicando o início de um período de 10 segundos antes do desligamento real, em que o Cloud Run envia um sinal SIGKILL. Durante esse período, a instância de contêiner recebe uma CPU alocada e é faturada. Se a instância de contêiner não capturar o sinal SIGTERM, ela será encerrada imediatamente. Consulte os exemplos de código para saber como capturar o sinal SIGTERM.

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.

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. Se a instância de contêiner não capturar o sinal SIGTERM, ela será encerrada imediatamente. Consulte os exemplos de código para saber como capturar o sinal SIGTERM.

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.

Recursos da instância do contêiner

CPU

Por padrão, cada instância de contêiner do Cloud Run recebe a vCPU que foi configurada (1 por padrão).

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.

A instância do contêiner pode ser executada em vários núcleos simultaneamente.

Para serviços do Cloud Run, é possível especificar que a CPU seja sempre alocada durante a vida útil da instância ou que seja alocada apenas durante a inicialização da instância do contêiner e o processamento da solicitação. Consulte Alocação de CPU para ver detalhes.

Se você tiver configurado várias instâncias mínimas, elas também estarão sujeitas à configuração de alocação de 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.

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).

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

Simultaneidade (serviços)

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

Sandbox de instâncias 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.

Servidor de metadados da instância do contêiner

As instâncias de contêiner do Cloud Run expõem um servidor de metadados que pode ser usado para recuperar detalhes sobre sua instância de contêiner, como o ID do projeto, região, código da instância ou contas de serviço. Ele também pode ser usado para gerar tokens na conta de serviço do ambiente de execução.

É possível acessar esses dados a partir do servidor de metadados usando simples 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:

Caminho Descrição
/computeMetadata/v1/project/project-id ID do projeto do serviço ou job do Cloud Run
/computeMetadata/v1/project/numeric-project-id Número do projeto do serviço ou job do Cloud Run
/computeMetadata/v1/instance/region A região deste serviço ou job do Cloud Run retorna projects/PROJECT-NUMBER/regions/REGION
/computeMetadata/v1/instance/id Identificador exclusivo da instância do contêiner (também disponível em logs).
/computeMetadata/v1/instance/service-accounts/default/email E-mail da conta de serviço do ambiente de execução deste serviço ou job do Cloud Run.
/computeMetadata/v1/instance/service-accounts/default/token Gera um token de acesso do OAuth2 para a conta de serviço desse serviço ou job do Cloud Run. O agente de serviço do Cloud Run é usado para buscar um token. Esse endpoint retornará uma resposta JSON com um atributo access_token. Saiba mais sobre como extrair e usar esse token de acesso.

O Cloud Run não fornece detalhes sobre a zona do Google Cloud onde as instâncias de contêiner 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 dos arquivos usados no contêiner precisam ser compatíveis com UTF-8: UTF-8 ou algo que possa ser convertido automaticamente para UTF-8. Caso contrário, a imagem do contêiner poderá não ser implantada. Essa restrição se aplica somente aos nomes de arquivos: não há restrições quanto à codificação de caracteres usada no conteúdo.

Se você usar nomes de arquivos com outras codificações, precisará converter esses nomes de arquivo em UTF-8 antes de tentar implantar.

Tempo limite das solicitações de saída

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