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. 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. 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:
| 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 |
O índice desta tarefa. Começa em 0 para a primeira tarefa e aumenta em 1 para cada tarefa sucessiva, até o número máximo de tarefas menos 1. Se você definir --parallelism como maior que 1, as tarefas poderão não seguir a ordem do índice. Por exemplo, a tarefa 2 pode ser iniciada antes da tarefa 1. |
0 |
CLOUD_RUN_TASK_ATTEMPT |
O número de novas tentativas para a tarefa. Começa em 0 na primeira tentativa e aumenta em 1 para cada nova tentativa sucessiva, até o valor máximo de novas 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 em cada um dos contêineres é 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 permanecem 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 informações a seguir se aplicam apenas aos serviços.
Escalonamento de serviços
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.
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:
- Se novas instâncias estiverem inicializando, como durante um escalonamento horizontal, as solicitações ficarão pendentes pelo menos durante o tempo médio de inicialização das instâncias de contêiner deste serviço. Isso inclui quando a solicitação inicia um escalonamento horizontal, como ao escalonar do zero.
- Se o tempo de inicialização for menor que 10 segundos, as solicitações ficarão pendentes por até 10 segundos.
- Se não houver instâncias no processo de inicialização e a solicitação não iniciar um escalonamento horizontal, as solicitações ficarão pendentes por até 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.
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 da alocação de CPU configurada.
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, novas solicitações recebidas serão encaminhadas para outras instâncias, e as solicitações atualmente processadas terão tempo para serem concluídas. 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. Consulte os exemplos de código
para saber como capturar o sinal SIGTERM.
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.
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.
Recursos da instância do contêiner
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, é 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 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 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.
Se o serviço não encontrar as bibliotecas fornecidas, atualize o caminho de pesquisa
do vinculador dinâmico adicionando a linha ENV LD_LIBRARY_PATH /usr/local/nvidia/lib64:${LD_LIBRARY_PATH}
ao Dockerfile.
Também é possível definir LD_LIBRARY_PATH como uma variável de ambiente para o
serviço Cloud Run, se você tiver uma imagem e não quiser
reconstruir a imagem com um Dockerfile atualizado.
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.129.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.
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:
| 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 (também disponível em registros). |
/computeMetadata/v1/instance/service-accounts/default/email |
E-mail da identidade do serviço desse 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 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.
Conexões de saída
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.