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, os jobs 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.

Requisitos de contêineres

Ao implantar contêineres no Cloud Run, os seguintes requisitos precisam ser atendidos:

O contêiner implantado nos serviços precisa detectar solicitações na porta correta

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 secundários. 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 pode detectar em 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.

Conectividade de rede VPC

O Cloud Run permite que você se conecte a uma rede VPC usando a VPC direta.

• Para enviar tráfego para recursos particulares na rede VPC configurada, como bancos de dados ou serviços internos, use a saída de VPC direta.
• Para receber tráfego de recursos ou endereços IP privados na rede VPC ou sub-rede configurada, use a entrada de VPC direta.

Cada recurso do Cloud Run é compatível com as seguintes configurações de VPC direta:

• Serviços: somente saída
• Jobs: somente saída

Ao usar a VPC direta, esses endereços IP não são estáticos.

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:

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

Para serviços, o Cloud Run restringe os nomes de cabeçalho a caracteres ASCII imprimíveis que não sejam espaços em branco 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 persistem 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 alocação de memória 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, os eventos ou a utilização da CPU. Também é possível usar o escalonamento manual se você 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 secundários.

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

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 com um número mínimo de instâncias. Se uma instância que estiver processando solicitações precisar ser encerrada, as solicitações 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 gerenciador 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

Use os códigos de saída do job para conferir se ele foi concluído com sucesso ou se encontrou erros. Os códigos de saída são valores numéricos que correspondem à conclusão bem-sucedida ou a tipos específicos de erros.

A tabela a seguir especifica os 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. Consulte Encerramento para detalhes e recomendações sobre como lidar com isso.

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

O contêiner é executado em um controlador cgroup que restringe a CPU, a RAM e outros recursos aos que foram configurados para o contêiner.

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

• CPU
• Memória
• 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 a vida útil 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 um número de 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

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.

Restrições de segurança de contêineres

As seguintes restrições se aplicam aos contêineres executados no Cloud Run. Elas se aplicam independentemente do usuário do Linux que a imagem do contêiner especifica para execução.

Privilégios reduzidos

No Cloud Run, os contêineres não recebem os recursos raiz do limite de segurança da instância. Os contêineres não podem realizar ações reservadas para o host, como as seguintes:

• Adicionar ou remover recursos do kernel do Linux
• Como usar recursos específicos do kernel
• Manipulação de dispositivos
• Acessar determinados recursos de hardware

O escalonamento de privilégios também é desativado nos contêineres. O uso de binários sudo e setuid não é compatível com o Cloud Run.

Seus contêineres não terão acesso de gravação à maioria dos arquivos e diretórios em /dev, /proc e /sys.

Não há um equivalente do Cloud Run para o modo --privileged do Docker.

Isolamento de contêiner

O Cloud Run executa seus contêineres em namespaces de usuário, rede, PID e outros namespaces do Linux, isolando-os uns dos outros e da própria instância. Isso restringe alguns recursos de rede e impede que os contêineres raiz sejam executados como "raiz verdadeira".

Montagens limitadas de sistemas de arquivos de dentro de contêineres

O caminho compatível para montar sistemas de arquivos no Cloud Run é pelo recurso de montagens de volume totalmente gerenciadas na configuração do contêiner do Cloud Run.

Outros mecanismos de montagem de dentro de contêineres de usuário não são compatíveis e não funcionam. Os mecanismos não compatíveis incluem, entre outros:

• Executar um processo de montagem dentro do contêiner para montar qualquer um dos seguintes: NFS, Filestore, SMB/CIFS ou qualquer outro sistema de arquivos de rede.
• Fazer chamadas do sistema que realizariam ações equivalentes.

Além disso, o Cloud Run não é compatível com montagens de volume aninhadas que montam um volume dentro de outro.

Nenhuma alteração no horário do sistema

Não é possível alterar o horário do sistema usando as chamadas do sistema adjtimex e adjtime, nem qualquer ferramenta que permita que o contêiner faça isso.

Restrições de chamadas de sistema e de processos

Perfis de segurança básicos, semelhantes aos perfis de segurança seccomp para Docker, são aplicados a cada um dos seus contêineres.

O uso de eBPF e outros recursos de segurança no nível do kernel que não são protegidos ou limitados por namespaces do Linux estão desativados e não são compatíveis com o uso dentro de contêineres.

O uso de outras chamadas do sistema ou o acesso a arquivos do sistema que exigem privilégios de raiz na instância do Cloud Run também podem ser restritos por esse motivo.

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 do arquivo que um processo pode abrir. Isso se aplica ao contêiner e a qualquer processo filho que ele criar (forks). Esse é um limite rígido. Se você exceder o limite, sua instância poderá ficar sem descritores do arquivo/soquetes.

Limites no ambiente de segunda geração

Com exceção dos limites do descritor do arquivo descritos anteriormente, os limites no ambiente de segunda geração são os limites padrão do Linux.

Por exemplo, os limites do número de descritores do 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 65535. 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 sinalizações 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 o usuário raiz e, em seguida, usar o comando su para alternar para outro usuário no ambiente de 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 em execução

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

Comunicação entre contêineres da mesma instância

O Cloud Run adiciona uma entrada ao arquivo /etc/hosts em cada contêiner. Essa entrada mapeia os nomes de serviço para o endereço IP do localhost (127.0.0.1). Isso permite que os contêineres se comuniquem entre si usando o nome do contêiner.

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 zona doCloud de Confiance 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.