Esta página apresenta os principais requisitos e comportamentos dos contentores no Cloud Run. Existem algumas diferenças entre os serviços do Cloud Run e as tarefas do Cloud Run: estas são indicadas quando apropriado.
Idiomas e imagens compatíveis
A imagem do contentor pode executar código escrito na linguagem de programação da sua escolha e usar qualquer imagem base, desde que respeite as restrições indicadas nesta página.
Os ficheiros executáveis na imagem do contentor têm de ser compilados para Linux de 64 bits. O Cloud Run suporta especificamente o formato ABI Linux x86_64.
O Cloud Run aceita imagens de contentores nos formatos de imagem Docker Image Manifest V2, Schema 1, Schema 2 e OCI. O Cloud Run também aceita imagens de contentores comprimidas com Zstd.
Se implementar uma imagem de várias arquiteturas,
a lista de manifestos
tem de incluir linux/amd64.
Para funções implementadas com o Cloud Run, pode usar uma das imagens base de tempo 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 o horário de apoio técnico do tempo de execução para ver os tempos de execução suportados.
Ouvir pedidos na porta correta (serviços)
Um serviço do Cloud Run inicia instâncias do Cloud Run para processar pedidos recebidos. Uma instância do Cloud Run tem sempre um único contentor de entrada que escuta os pedidos e, opcionalmente, um ou mais contentores auxiliares. Os seguintes detalhes de configuração de portas aplicam-se apenas ao contentor de entrada e não aos sidecars.
O contentor de entrada numa instância tem de ouvir pedidos em 0.0.0.0 na porta para a qual os pedidos são enviados.
Em particular, o contentor de entrada não deve ouvir em 127.0.0.1.
Por predefinição, os pedidos são enviados para 8080, mas pode configurar o Cloud Run
para enviar pedidos para a porta da sua escolha. O Cloud Run injeta a variável de ambiente PORT no contentor de entrada.
O contentor em execução numa execução de tarefa tem de terminar após a conclusão
Para tarefas do Cloud Run, o contentor tem de sair com o código de saída 0 quando a tarefa for concluída com êxito e sair com um código de saída diferente de zero quando a tarefa falhar.
Uma vez que as tarefas não devem processar pedidos, o contentor não deve escutar numa porta nem iniciar um servidor Web.
Encriptação da camada de transporte (TLS)
O contentor não deve implementar diretamente nenhuma segurança da camada de transporte. O TLS é terminado pelo Cloud Run para HTTPS e gRPC e, em seguida, os pedidos são enviados por proxy como HTTP/1 ou gRPC para o contentor sem TLS.
Se configurar um serviço do Cloud Run para usar HTTP/2 ponto a ponto, o seu contentor tem de processar pedidos no formato de texto não cifrado HTTP/2 (h2c), porque o TLS continua a ser terminado automaticamente pelo Cloud Run.
Respostas (serviços)
Para os serviços do Cloud Run, o contentor tem de enviar uma resposta no prazo especificado na definição de limite de tempo do pedido após receber um pedido, incluindo o tempo de arranque do contentor. Caso contrário, o pedido é terminado e é devolvido um erro 504.
Cookies e colocação em cache de respostas
Se a resposta do seu serviço do Cloud Run contiver um cabeçalho Set-Cookie, o Cloud Run define o cabeçalho Cache-Control como private para que
a resposta não seja colocada em cache. Isto impede que outros utilizadores obtenham o cookie.
Variáveis de ambiente
Estão disponíveis diferentes conjuntos de variáveis de ambiente para serviços e tarefas do Cloud Run.
Variáveis de ambiente para serviços
As seguintes variáveis de ambiente são adicionadas automaticamente a todos os contentores em execução, exceto PORT. A variável PORT só é adicionada ao contentor de entrada:
| Nome | Descrição | Exemplo |
|---|---|---|
PORT |
A porta que o seu servidor HTTP deve escutar. | 8080 |
K_SERVICE |
O nome do serviço do Cloud Run que está a ser executado. | hello-world |
K_REVISION |
O nome da revisão do Cloud Run que está a ser executada. | 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 trabalhos
Para tarefas do Cloud Run, são definidas as seguintes variáveis de ambiente:
| Nome | Descrição | Exemplo |
|---|---|---|
CLOUD_RUN_JOB |
O nome da tarefa do Cloud Run que está a ser executada. | hello-world |
CLOUD_RUN_EXECUTION |
O nome da execução do Cloud Run que está a ser executada. | hello-world-abc |
CLOUD_RUN_TASK_INDEX |
O índice desta tarefa. Começa em 0 para a primeira tarefa e aumenta 1 para cada tarefa sucessiva, até ao número máximo de tarefas menos 1. Se definir --parallelism como superior a 1, as tarefas podem 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 vezes que esta tarefa foi repetida. Começa em 0 para a primeira tentativa e aumenta 1 para cada nova tentativa sucessiva, até ao 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 pedido e resposta (serviços)
Para serviços do Cloud Run, os nomes dos cabeçalhos estão restritos a ASCII não imprimível e sem espaços em branco, e não podem conter dois pontos. Os valores dos cabeçalhos estão restritos a carateres ASCII visíveis, além de espaço e tabulação horizontal, de acordo com a norma IETF RFC 7230
Acesso ao sistema de ficheiros
O sistema de ficheiros em cada um dos seus contentores é gravável e está sujeito ao seguinte comportamento:
- Este é um sistema de ficheiros na memória, pelo que a escrita no mesmo usa a memória da instância.
- Os dados escritos no sistema de ficheiros não persistem quando a instância é parada.
Tenha em atenção que não pode especificar um limite de tamanho para este sistema de ficheiros. Por isso, pode usar potencialmente toda a memória alocada à sua instância escrevendo no sistema de ficheiros na memória, o que fará com que a instância falhe. Pode evitar este problema se usar um volume na memória dedicado com um limite de tamanho.
Ciclo de vida da instância
As caraterísticas do ciclo de vida diferem para as tarefas e os serviços do Cloud Run, pelo que são descritas separadamente nas subsecções seguintes.
Para serviços
O seguinte aplica-se apenas a serviços.
Dimensionamento de serviços
Por predefinição, um serviço do Cloud Run é dimensionado automaticamente para o número de instâncias necessárias para processar todos os pedidos, eventos ou utilização da CPU recebidos. Opcionalmente, pode usar o dimensionamento manual se precisar de mais controlo sobre o comportamento de dimensionamento.
Cada instância executa um número fixo de contentores: um contentor de entrada e, opcionalmente, um ou mais contentores auxiliares.
Quando uma revisão não recebe tráfego, é reduzida ao número mínimo de instâncias configurado (zero por predefinição).
Arranque
Para os serviços do Cloud Run, as suas instâncias têm de ouvir pedidos no prazo de 4 minutos após o início, e todos os contentores na instância têm de estar em bom estado. Durante este tempo de arranque, as instâncias recebem CPU. Pode ativar o aumento da CPU no arranque para aumentar temporariamente a atribuição da CPU durante o arranque da instância para reduzir a latência do arranque.
Os pedidos são enviados para o contentor de entrada assim que este estiver a ouvir no porto configurado.
Um pedido à espera de uma instância é mantido pendente numa fila da seguinte forma:
Os pedidos ficam pendentes até 3, 5 vezes o tempo de arranque médio das instâncias de contentores deste serviço ou 10 segundos, consoante o que for superior.
Pode configurar uma sondagem de arranque para determinar se o contentor foi iniciado e está pronto para processar pedidos.
Para um serviço do Cloud Run composto por instâncias de vários contentores, pode especificar a sequência em que os contentores são iniciados na instância configurando a ordem de arranque dos contentores.
Processar um pedido
Para os serviços do Cloud Run, a CPU é sempre atribuída a todos os contentores, incluindo os sidecars, numa instância, desde que a revisão do Cloud Run esteja a processar, pelo menos, um pedido.
Inativo
Para os serviços do Cloud Run, uma instância inativa é uma instância que não está a processar pedidos.
A CPU alocada a todos os contentores numa instância inativa depende das definições de faturação configuradas.
A menos que uma instância tenha de ser mantida inativa devido à definição de configuração do número mínimo de instâncias, não é mantida inativa durante mais de 15 minutos.
Encerrar
Para os serviços do Cloud Run, uma instância inativa pode ser encerrada em qualquer altura, incluindo instâncias mantidas ativas devido a um número mínimo de instâncias configurado. Se for necessário encerrar uma instância que esteja a processar pedidos, os pedidos já em processamento têm tempo para serem concluídos e os novos pedidos recebidos são encaminhados para outras instâncias. Em casos excecionais, o Cloud Run pode iniciar um encerramento e enviar um sinal SIGTERM para um contentor que ainda esteja a processar pedidos.
Antes de encerrar uma instância, o Cloud Run envia um sinal SIGTERM a todos os contentores numa instância, indicando o início de um período de 10 segundos antes do encerramento real, altura em que o Cloud Run envia um sinal SIGKILL.
Durante este período, a instância tem CPU atribuída 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, é encerrada imediatamente. Nos serviços que usam o ambiente de execução de segunda geração, recomendamos que instale um controlador SIGTERM no seu contentor para receber um aviso quando o Cloud Run estiver prestes a encerrar uma instância.
Encerramento forçado
Se um ou mais contentores do Cloud Run excederem o limite total de memória do contentor, a instância é terminada. Todos os pedidos que ainda estão a ser processados na instância terminam com um erro HTTP 500.
Para empregos
Para tarefas do Cloud Run, as instâncias de contentores são executadas até que a instância de contentor termine ou até que o tempo limite da tarefa seja atingido ou até que o contentor falhe.
Códigos de saída
Pode usar códigos de saída de tarefas para ver se a tarefa foi concluída com êxito ou se encontrou erros. Os códigos de saída são valores numéricos que correspondem à conclusão com êxito ou a tipos específicos de erros.
A tabela seguinte especifica os códigos de saída comuns e as respetivas definições:
| Código de saída | Sinal | Descrição |
|---|---|---|
| 0 | Tarefa concluída com êxito. | |
| 4 | SIGILL |
A tarefa tentou aceder à memória num endereço incorreto. |
| 7 | SIGBUS |
A tarefa tentou aceder à memória fora dos respetivos limites atribuídos. |
| 9 | SIGKILL |
A tarefa é terminada à força, por ação do utilizador ou intervenção manual. |
| 11 | SIGSEGV |
A tarefa tentou aceder a memória não autorizada. |
| 15 | SIGTERM |
Quando uma tarefa excede o respetivo limite de tempo configurado, recebe um sinal SIGTERM. O servidor de aplicações envia o sinal SIGTERM para que a instância do contentor seja encerrada. Se a instância não for encerrada automaticamente alguns segundos após receber SIGTERM, o Cloud Run envia um sinal SIGKILL para uma terminação forçada. Se a instância sair corretamente com SIGTERM, pode comunicar um código de erro diferente; caso contrário, devolve SIGTERM. |
Encerramento forçado
Uma instância de contentor do Cloud Run que excede o limite de memória permitido é terminada. Todos os pedidos que ainda estão a ser processados na instância do contentor terminam com um erro HTTP 500.
Se uma tarefa exceder o tempo limite da tarefa,
o Cloud Run envia um sinal "SIGTERM" a indicar o início de um
período de 10 segundos antes de o encerramento real
ocorrer. Nesse momento, o Cloud Run envia um sinal
SIGKILL, encerrando a instância do contentor.
Durante este período, as instâncias de contentores têm CPU atribuída durante todo o respetivo ciclo de vida e são faturadas.
Consulte o exemplo de código SIGTERM
para saber como capturar o sinal SIGTERM.
Recursos de instâncias de contentores
As secções seguintes descrevem os recursos da instância do contentor:
CPU
Por predefinição, a cada contentor do Cloud Run numa instância é atribuído o vCPU que foi configurado (1 por predefinição). É possível configurar limites de CPU em cada contentor separadamente.
Uma vCPU é implementada como uma abstração do hardware subjacente para fornecer o tempo de CPU aproximadamente equivalente de um único hiperthread de hardware em plataformas de CPU variáveis. Todas as plataformas de CPU usadas pelo Cloud Run suportam o conjunto de instruções AVX2. Tenha em atenção que o contrato do contentor não contém detalhes adicionais da plataforma da CPU.
O contentor pode ser executado em vários núcleos em simultâneo.
Para os serviços do Cloud Run, a atribuição de CPU depende da faturação selecionada.
Se selecionar a faturação baseada em instâncias, a CPU é atribuída durante a vida útil da instância. Se selecionar a faturação baseada em pedidos (predefinição), a CPU é atribuída quando as instâncias estão a processar pedidos. Consulte as definições de faturação para ver detalhes.
Se configurou um número de instâncias mínimas, tem de usar a faturação baseada em instâncias para que a CPU seja alocada fora dos pedidos.
Pode ativar o aumento da CPU no arranque para aumentar temporariamente a atribuição da CPU durante o arranque da instância de modo a reduzir a latência do arranque.
Memória
Por predefinição, a cada contentor do Cloud Run é alocada a memória configurada (512 MiB por predefinição). É possível configurar limites de memória em cada contentor separadamente.
As utilizações típicas da memória incluem:
- Código carregado na memória para executar o serviço
- Escrever no sistema de ficheiros
- Processos adicionais em execução no contentor, como um servidor nginx
- Sistemas de colocação em cache na memória, como o OpCache do PHP
- Utilização de memória por pedido
- Volumes na memória partilhados
GPU
Pode configurar um contentor numa instância do Cloud Run para aceder a uma GPU. Se o serviço do Cloud Run for implementado com contentores auxiliares, apenas um contentor na implementação pode aceder à GPU. Consulte o artigo Configure a GPU para ver os requisitos e os detalhes.
Bibliotecas NVIDIA
Por predefinição, todas as bibliotecas de controladores NVIDIA L4 estão montadas em /usr/local/nvidia/lib64. O Cloud Run anexa automaticamente este caminho à variável de ambiente LD_LIBRARY_PATH (ou seja, ${LD_LIBRARY_PATH}:/usr/local/nvidia/lib64) do contentor com a GPU. Isto permite que o linker dinâmico encontre as bibliotecas de controladores da NVIDIA. O linker pesquisa e resolve caminhos
pela ordem em que os lista na variável de ambiente LD_LIBRARY_PATH. Todos os valores que especificar nesta variável têm precedência sobre o caminho predefinido das bibliotecas do controlador do Cloud Run /usr/local/nvidia/lib64.
Se quiser usar uma versão do CUDA superior a 12.2,
a forma mais fácil é depender de uma imagem base da 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 ao LD_LIBRARY_PATH. Consulte a matriz de compatibilidade da NVIDIA
para determinar que versões do CUDA são compatíveis com a versão do controlador da NVIDIA
fornecida (535.216.03).
Simultaneidade (serviços)
Para os serviços do Cloud Run, cada instância do Cloud Run está predefinida para várias concorrências, em que o contentor de entrada pode receber mais do que um pedido em simultâneo. Pode alterar esta opção definindo a simultaneidade.
Sandbox de contentores
Se usar o ambiente de execução de primeira geração, os contentores do Cloud Run são colocados em sandbox com a sandbox de tempo de execução do contentor gVisor. Conforme documentado na referência de compatibilidade de chamadas do sistema gVisor, algumas chamadas do sistema podem não ser suportadas por esta sandbox de contentor.
Se usar o ambiente de execução de segunda geração,
tem compatibilidade total com o Linux.
As tarefas do Cloud Run usam sempre o ambiente de execução de segunda geração.
No ambiente de execução de segunda geração, /sys/class/dmi/id/product_name está definido como Google Compute Engine.
O ambiente de execução de segunda geração executa o código do serviço num espaço de nomes de processo separado, pelo que é iniciado como o processo de inicialização do contentor, que tem uma semântica de processo especial. No ambiente de execução de primeira geração, o código do serviço não é executado como o processo de inicialização do contentor.
Limites de descritores de ficheiros
Os ambientes de primeira e segunda geração do Cloud Run definem um limite para o número de descritores de ficheiros que um processo pode abrir, que é de 25 000. Isto aplica-se ao contentor e a qualquer processo secundário que crie (forks). Este é um limite rígido. Se exceder o limite, a sua instância pode ficar sem descritores de ficheiros/sockets.
Limites no ambiente de segunda geração
Os limites no ambiente de segunda geração são limites padrão do Linux.
Por exemplo, os limites do número de descritores de ficheiros que podem ser
abertos (conforme capturado em: /proc/sys/fs/file-max) usam o valor predefinido de cerca de
10% da memória. Consulte file-max e file-nr
na documentação do kernel para ver 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á a usar o valor predefinido
de 65535. Consulte max-map-count
na documentação do kernel para ver detalhes.
Contentores privilegiados e binários setuid
O Cloud Run não suporta contentores privilegiados. Consequentemente, o Cloud Run não suporta ficheiros binários que usam flags setuid para utilizadores não raiz, como gcsfuse ou sudo, e pode falhar devido a autorizações insuficientes.
Uma alternativa é executar estes ficheiros binários como o utilizador root e, em seguida, usar o comando su para mudar para outro utilizador no tempo 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'
Utilizador de execução
Se o nome de utilizador não existir, o Cloud Run executa o contentor como o utilizador raiz (uid=0).
Servidor de metadados de instância
As instâncias do Cloud Run expõem um servidor de metadados que pode usar para obter detalhes sobre os seus contentores, como o ID do projeto, a região, o ID da instância ou as contas de serviço. Também pode usar o servidor de metadados para gerar tokens para a identidade do serviço.
Para aceder aos dados do servidor de metadados, use pedidos HTTP para o ponto final http://metadata.google.internal/ com o cabeçalho Metadata-Flavor: Google. Não são necessárias bibliotecas cliente. Para mais informações, consulte o artigo
Obter metadados.
A tabela seguinte apresenta algumas das informações do servidor de metadados disponíveis:
| Caminho | Descrição |
|---|---|
/computeMetadata/v1/project/project-id |
ID do projeto ao qual o serviço ou a tarefa do Cloud Run pertence |
/computeMetadata/v1/project/numeric-project-id |
Número do projeto ao qual o serviço ou a tarefa do Cloud Run pertence |
/computeMetadata/v1/instance/region |
Região deste serviço ou tarefa do Cloud Run, devolve projects/PROJECT-NUMBER/regions/REGION |
/computeMetadata/v1/instance/id |
Identificador exclusivo da instância (também disponível nos registos). |
/computeMetadata/v1/instance/service-accounts/default/email |
Email da identidade do serviço deste serviço ou tarefa do Cloud Run. |
/computeMetadata/v1/instance/service-accounts/default/token |
Gera uma chave de acesso OAuth2 para a conta de serviço deste serviço ou tarefa do Cloud Run. O agente de serviço do Cloud Run é usado para obter um token. Este ponto final devolve uma resposta JSON com um atributo access_token. Leia mais sobre como extrair e usar este token de acesso. |
Tenha em atenção que o Cloud Run não fornece detalhes sobre a
Google Cloud zona em que as instâncias
estão a ser executadas. Consequentemente, o atributo de metadados /computeMetadata/v1/instance/zone devolve sempre projects/PROJECT-NUMBER/zones/REGION-1.
Nomes dos ficheiros
Os nomes dos ficheiros que usa nos contentores têm de ser compatíveis com UTF-8, ou seja, UTF-8 ou algo que possa ser convertido automaticamente em UTF-8 de forma segura. Se os nomes dos seus ficheiros usarem codificações diferentes, execute a compilação do Docker numa máquina com nomes de ficheiros compatíveis com UTF-8 e evite copiar ficheiros para um contentor que contenha nomes UTF-8 incompatíveis.
A implementação do contentor falha se os nomes dos ficheiros não forem compatíveis com UTF-8. Tenha em atenção que não existe restrição na codificação de carateres que usa num ficheiro.
Tempos limite de pedidos de saída
Para serviços e tarefas do Cloud Run, existe um limite de tempo após 10 minutos de tempo de inatividade para pedidos do seu contentor para a VPC. Para pedidos do seu contentor à Internet, existe um limite de tempo após 20 minutos de tempo de inatividade.
Reposicionamentos de ligações de saída
As streams de ligação do seu contentor para a VPC e a Internet podem ser terminadas e substituídas ocasionalmente quando a infraestrutura subjacente é reiniciada ou atualizada. Se a sua aplicação reutilizar ligações de longa duração, recomendamos que a configure para restabelecer as ligações de forma a evitar a reutilização de uma ligação inativa.