O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Implantar imagens de contêiner em serviços do Cloud Run

Nesta página, descrevemos como implantar imagens de contêiner em um novo serviço do Cloud Run ou em uma nova revisão de um serviço do Cloud Run.

A imagem do contêiner é importada pelo Cloud Run quando implantada. O Cloud Run mantém essa cópia da imagem do contêiner enquanto ela estiver sendo usada por uma revisão de serviço. As imagens de contêiner não são obtidas do repositório de contêineres quando uma nova instância do Cloud Run é iniciada.

Para conferir um exemplo de instruções de implantação de um novo serviço, consulte o Guia de início rápido sobre como implantar um contêiner de amostra.

Antes de começar

Se você precisa seguir uma política da organização de restrição de domínio que restringe invocações não autenticadas para seu projeto, será necessário acessar o serviço implantado, conforme descrito em Como testar serviços particulares.

Funções exigidas

Para obter as permissões necessárias para implantar serviços do Cloud Run, solicite ao seu administrador que lhe conceda as seguintes funções do IAM:

Desenvolvedor do Cloud Run (roles/run.developer) no serviço Cloud Run
Usuário da conta de serviço (roles/iam.serviceAccountUser) na identidade do serviço
Leitor do Artifact Registry (roles/artifactregistry.reader) no repositório do Artifact Registry da imagem do contêiner implantada
Se você estiver usando uma conta de serviço entre projetos para implantar um serviço: Criador do token da conta de serviço (roles/iam.serviceAccountTokenCreator) na identidade do serviço

Para uma lista de papéis e permissões do IAM associados ao Cloud Run, consulte Papéis do IAM do Cloud Run e Permissões do IAM do Cloud Run. Se o serviço do Cloud Run interage com APIs doGoogle Cloud , como as bibliotecas de cliente do Cloud, consulte o guia de configuração de identidade de serviço. Para mais informações sobre como conceder papéis, consulte permissões de implantação e gerenciar acesso.

Registros e imagens de contêiner compatíveis

É possível usar diretamente imagens de contêiner armazenadas no Artifact Registry ou imagens públicas do Docker Hub ou do GitHub Container Registry. O Google recomenda o uso do Artifact Registry. As imagens públicas do GitHub Container Registry e do Docker Hub são armazenadas em cache por até uma hora.

É possível usar imagens de contêiner de outros registros públicos ou privados (como JFrog Artifactory ou Nexus) ou imagens privadas do GitHub Container Registry configurando um repositório remoto do Artifact Registry.

Considere apenas o Docker Hub para implantar imagens de contêiner conhecidas, como Imagens oficiais do Docker ou Imagens do OSS patrocinadas pelo Docker. Para maior disponibilidade, o Google recomenda implantar essas imagens do Docker Hub ou do GitHub Container Registry usando um repositório remoto do Artifact Registry.

O Cloud Run não suporta camadas de imagem de contêiner maiores que 9,9 GB ao implantar a partir do Docker Hub ou de um repositório remoto do Artifact Registry com um registro externo.

Implantar um novo serviço

É possível especificar uma imagem de contêiner com uma tag (por exemplo, us-docker.pkg.dev/my-project/container/my-image:latest) ou com um resumo exato (por exemplo, us-docker.pkg.dev/my-project/container/my-image@sha256:41f34ab970ee...).

A implantação de um serviço pela primeira vez cria a primeira revisão dele. Observe que as revisões são imutáveis. Se você implantar a partir de uma tag de imagem de contêiner, ela será resolvida para um resumo, e a revisão sempre exibirá esse resumo específico.

Console

Para implantar uma imagem de contêiner, realize as etapas a seguir:

No console Google Cloud , acesse a página do Cloud Run:

Acessar o Cloud Run
Clique em Implantar contêiner para mostrar o formulário Criar serviço.
No formulário, selecione a opção de implantação.
1. Se você quiser implantar um contêiner manualmente, selecione Implantar uma revisão de uma imagem de contêiner atual e especifique a imagem.
2. Se você quiser automatizar a implantação contínua, selecione Implantar continuamente novas revisões de um repositório de origem e siga as instruções para implantações contínuas.
Insira um nome de serviço. Os nomes dos serviços precisam ter 49 caracteres ou menos e ser exclusivos por região e projeto. Não é possível alterar o nome de um serviço depois e ele fica visível publicamente.
No campo Região, Selecione a região em que você quer que o serviço esteja localizado.

O seletor de região indica o nível de preço, a disponibilidade de mapeamentos de domínio e destaca regiões com o impacto de carbono mais baixo.
Em Autenticação, configure o seguinte:
- Se você estiver criando uma API ou um site público, selecione Permitir acesso público. A seleção atribui o papel de chamador do IAM ao identificador especial allUser. É possível usar o IAM para editar essa configuração depois de criar o serviço.
- Se você quiser que um serviço seguro seja protegido por autenticação, selecione Exigir autenticação.
Defina o faturamento conforme necessário.
Em Escalonamento de serviço, se você usar o Cloud Run autoscaling padrão, especifique opcionalmente as infrações mínimas. Se você usar o escalonamento manual, especifique o número de instâncias para o serviço.
Defina as configurações de Entrada no formato conforme necessário.
Clique em Contêineres, rede e segurança para definir outras configurações opcionais nas guias apropriadas:
Após concluir a configuração do serviço, clique em Criar para implantar a imagem no Cloud Run e aguarde a conclusão da implantação.
Clique no link da URL exibida para abrir o endpoint exclusivo e estável do seu serviço implantado.

gcloud

No console do Google Cloud , ative o Cloud Shell.

Ativar o Cloud Shell

Na parte de baixo do console Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
Para implantar uma imagem de contêiner, realize as etapas a seguir:
1. Execute este comando:
```
gcloud run deploy SERVICE --image IMAGE_URL
```
  Substitua:
  - SERVICE: o nome do serviço em que você quer implantar. Os nomes dos serviços precisam ter 49 caracteres ou menos e ser exclusivos por região e projeto. Se o serviço ainda não existir, esse comando criará o serviço durante a implantação. É possível omitir esse parâmetro inteiramente, mas será solicitado o nome do serviço, se você omiti-lo.
  - IMAGE_URL: uma referência à imagem de contêiner, por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL segue o formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG . Se você não fornecer a sinalização --image, o comando de implantação tentará implantar a partir do código-fonte.
  Se você estiver criando uma API pública ou um site, permita o acesso público ao serviço usando a flag --allow-unauthenticated. Isso atribui o papel do IAM de Chamador do Cloud Run a allUsers. Também é possível especificar --no-allow-unauthenticated para impedir o acesso público. Se você omitir qualquer uma dessas sinalizações, será solicitado a confirmar quando o comando deploy é executado.
2. Aguarde a conclusão da implantação. Após a conclusão bem-sucedida, uma mensagem de sucesso é exibida com o URL do serviço implantado.
Para implantar em um local diferente daquele que você definiu por meio das propriedades run/region gcloud, use:
```
gcloud run deploy SERVICE --region REGION
```

YAML

É possível armazenar a especificação do serviço em um arquivo YAML e implantá-la usando a CLI gcloud.

Crie um novo arquivo service.yaml com o seguinte conteúdo:
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
spec:
  template:
    spec:
      containers:
      - image: IMAGE
```
Substitua:
- SERVICE: o nome do seu serviço do Cloud Run. Os nomes dos serviços precisam ter 49 caracteres ou menos e ser exclusivos por região e projeto.
- IMAGE pelo URL da imagem de contêiner.
Também é possível definir outras configurações, como variáveis de ambiente ou limites de memória.
Implante o novo serviço usando o seguinte comando:
```
gcloud run services replace service.yaml
```
Por padrão, o comando gcloud run services replace usa o arquivo service.yaml, se ele estiver presente.
Como opção, torne seu serviço público se você quiser permitir o acesso não autenticado ao serviço.

Terraform

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform.

Adicione o seguinte a umgoogle_cloud_run_v2_service Recurso na sua configuração do Terraform:

  provider "google" {
    project = "PROJECT-ID"
  }

  resource "google_cloud_run_v2_service" "default" {
    name     = "SERVICE"
    location = "REGION"
    client   = "terraform"

    template {
      containers {
        image = "IMAGE_URL"
      }
    }
  }

  resource "google_cloud_run_v2_service_iam_member" "noauth" {
    location = google_cloud_run_v2_service.default.location
    name     = google_cloud_run_v2_service.default.name
    role     = "roles/run.invoker"
    member   = "allUsers"
  }

Substitua:

PROJECT-ID: o Google Cloud ID do projeto
REGION: a região Google Cloud
SERVICE: o nome do seu serviço do Cloud Run. Os nomes dos serviços precisam ter 49 caracteres ou menos e ser exclusivos por região e projeto.
IMAGE_URL: uma referência à imagem de contêiner, por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. A URL segue o formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

Essa configuração permite acesso público (o equivalente a --allow-unauthenticated). Para tornar o serviço privado, remova a estrofe google_cloud_run_v2_service_iam_member.

Escrever

Você pode armazenar seusCompor especificação em umYAML arquivo e, em seguida, implante-o como um serviço do Cloud Run usando umcomando gcloud único.

Para implantar um arquivo compose.yaml como um serviço do Cloud Run, siga estas etapas:

No diretório do seu projeto, crie um arquivo compose.yaml com as definições do seu serviço.
```
services:
  web:
    image: IMAGE
    ports:
      - "8080:8080"
```
Substitua IMAGE_URL pela URL da sua imagem de contêiner.

Também é possível especificar mais opções de configuração, como variáveis de ambiente, secrets e montagens de volume.

Implantar o serviço

Para implantar os serviços, execute o comando gcloud run compose up:
```
gcloud run compose up compose.yaml
```
Responda y a quaisquer solicitações para instalar componentes necessários ou para habilitar APIs.
Opcional: torne seu serviço público se você quiser permitir o acesso não autenticado ao serviço.

Após a implantação, o URL do serviço do Cloud Run é exibido. Copie este URL e cole-o no seu navegador para visualizar o contêiner em execução. Você pode desativar a autenticação padrão em Google Cloud console.

MCP

Use um agente de IA para implantar seu serviço usando o servidor MCP oficial do Cloud Run.

Para obter os melhores resultados, configure seu agente para priorizar as ferramentas MCP em vez da CLI gcloud antes de começar a usar este servidor MCP.

Para configurar o servidor MCP remoto do Cloud Run, siga as instruções no guia Usar o servidor MCP remoto do Cloud Run.
Para implantar o serviço a partir de uma imagem de contêiner de exemplo helloworld, instrua seu agente com o seguinte prompt: Deploy service "helloworld" to Cloud Run from the container image us-docker.pkg.dev/cloudrun/container/hello.

O agente usa a ferramenta deploy_service_from_image para implantar uma imagem de contêiner como um serviço do Cloud Run.

Usar o comando /deploy

Você pode usar o comando /deploy para implantar rapidamente um serviço usando o servidor MCP do Cloud Run. Você pode precisar navegar pelo menu do seu chatbot para encontrar a ferramenta ou o comando necessário.

Para implantar o diretório de trabalho atual no Cloud Run, execute o comando /deploy a seguir:

/deploy SERVICE_NAME \
    --project PROJECT_ID \
    --region REGION \

Substitua:

SERVICE_NAME: o nome do serviço do Cloud Run
PROJECT_ID: o Google Cloud ID do projeto
REGION: o nome da região.

Bibliotecas de cliente

Para criar um novo serviço usando código, siga estas etapas:

API REST

Para implantar um novo serviço, envie uma solicitação HTTP POST ao endpoint service da API Cloud Run Admin.

Por exemplo, usando curl:

curl -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -X POST \
  -d '{template: {containers: [{image: "IMAGE_URL"}]}}' \
  https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/services?serviceId=SERVICE

Substitua:

ACCESS_TOKEN: um token de acesso válido para uma conta com as permissões do IAM para implantar serviços. Por exemplo, se você fez login no gcloud, é possível recuperar um token de acesso usando gcloud auth print-access-token. Em uma instância de contêiner do Cloud Run, é possível recuperar um token de acesso por meio do servidor de metadados da instância de contêiner.
IMAGE_URL: uma referência à imagem de contêiner, por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL segue o formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .
SERVICE: o nome do serviço em que você quer fazer a implantação. Os nomes dos serviços precisam ter 49 caracteres ou menos e ser exclusivos por região e projeto.
REGION: a Google Cloud região do serviço.
PROJECT-ID: o ID do projeto do Google Cloud .

Locais do Cloud Run

O Cloud Run é regional, o que significa que a infraestrutura que executa seus serviços do Cloud Run está localizada em uma região específica e é gerenciada pelo Google para estar disponível de maneira redundante em todas as zonas da região.

Atender aos seus requisitos de latência, disponibilidade ou durabilidade são os principais fatores para selecionar a região em que seus serviços do Cloud Run são executados. Geralmente, é possível selecionar a região mais próxima de seus usuários, mas considere a localização dos outros Google Cloud produtos usados pelo serviço do Cloud Run. Usando Google Cloud A distribuição conjunta de produtos em vários locais pode afetar a latência e o custo do seu serviço.

O Cloud Run está disponível nas regiões a seguir:

Sujeitas aos preços do nível 1

asia-east1 (Taiwan)
asia-northeast1 (Tóquio)
asia-northeast2 (Osaka)
asia-south1 (Mumbai, Índia)
asia-southeast3 (Bangkok)
europe-north1 (Finlândia) Baixo CO₂
europe-north2 (Estocolmo) Baixo CO₂
europe-southwest1 (Madrid) Baixo CO₂
europe-west1 (Bélgica) Baixo CO₂
europe-west4 (Países Baixos) Baixo CO₂
europe-west8 (Milão) Baixo CO₂
europe-west9 (Paris) Baixo CO₂
me-west1 (Tel Aviv)
northamerica-south1 (México)
us-central1 (Iowa) Baixo CO₂
us-east1 (Carolina do Sul)
us-east4 (Norte da Virgínia)
us-east5 (Columbus)
us-south1 (Dallas) Baixo CO₂
us-west1 (Oregon) Baixo CO₂

Sujeitas aos preços do nível 2

africa-south1 (Johannesburgo)
asia-east2 (Hong Kong)
asia-northeast3 (Seul, Coreia do Sul)
asia-southeast1 (Singapura)
asia-southeast2 (Jacarta)
asia-south2 (Déli, Índia)
australia-southeast1 (Sydney)
australia-southeast2 (Melbourne)
europe-central2 (Varsóvia, Polônia) Baixo CO₂
europe-west10 (Berlim)
europe-west12 (Turim) Baixo CO₂
europe-west2 (Londres, Reino Unido) Baixo CO₂
europe-west3 (Frankfurt, Alemanha)
europe-west6 (Zurique, Suíça) Baixo CO₂
me-central1 (Doha)
me-central2 (Dammam)
northamerica-northeast1 (Montreal) Baixo CO₂
northamerica-northeast2 (Toronto) Baixo CO₂
southamerica-east1 (São Paulo, Brasil) Baixo CO₂
southamerica-west1 (Santiago, Chile) Baixo CO₂
us-west2 (Los Angeles) Baixo CO₂
us-west3 (Salt Lake City)
us-west4 (Las Vegas)

Se você já criou um serviço do Cloud Run, é possível visualizar a região no painel do Cloud Run no console doGoogle Cloud .

Implantar uma nova revisão de um serviço atual

É possível implantar uma nova revisão usando o console Google Cloud , a linha de comando gcloud ou um arquivo de configuração YAML.

A alteração de qualquer configuração resulta na criação de uma nova revisão, mesmo que não haja alterações na imagem do contêiner. Cada revisão criada é imutável.

A imagem do contêiner é importada pelo Cloud Run quando implantada. O Cloud Run mantém essa cópia da imagem do contêiner enquanto ela estiver sendo usada por uma revisão de serviço.

Console

Para implantar uma nova revisão de um serviço atual, realize as etapas a seguir:

No Google Cloud console, acesse o Cloud RunServiços página:

Acessar o Cloud Run
Clique no serviço que deseja atualizar na lista de serviços.
Na aba Containers, você pode configurar o seguinte:
Na guia Rede, é possível configurar o seguinte:
Na aba Segurança, você pode configurar o seguinte:
Na guia Escalonamento, é possível configurar o seguinte:
1. escalonamento automático ou escalonamento manual
2. Preferências de faturamento
3. Tempo limite da solicitação e simultaneidade
Clique em Ver diferenças e reimplantar, depois em Implantar alterações para implantar suas alterações.

gcloud

No console do Google Cloud , ative o Cloud Shell.

Ativar o Cloud Shell

Na parte de baixo do console Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
Para implantar uma imagem de contêiner, realize as etapas a seguir:
1. Execute o comando:
```
gcloud run deploy SERVICE --image IMAGE_URL
```
  Substitua:
  - SERVICE: o nome do serviço em que você está fazendo a implantação. É possível omitir esse parâmetro inteiramente, mas será solicitado o nome do serviço, se você omiti-lo.
  - IMAGE_URL: uma referência à imagem de contêiner, por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL segue o formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .
  O sufixo de revisão é atribuído automaticamente para novas revisões. Se você quiser fornecer seu próprio sufixo de revisão, use o parâmetro de CLI gcloud revision-suffix.
2. Aguarde a conclusão da implantação. Após a conclusão bem-sucedida, uma mensagem de sucesso é exibida com o URL do serviço implantado.

YAML

Se você precisar fazer o download ou visualizar a configuração de um serviço existente, use o seguinte comando para salvar os resultados em um arquivo YAML:

gcloud run services describe SERVICE --format export > service.yaml

Em um arquivo YAML de configurações de serviço, modifique qualquer atributo filho spec.template conforme necessário para atualizar as configurações de revisão. Em seguida, implante a nova revisão:

gcloud run services replace service.yaml

Por padrão, o comando gcloud run services replace usa o arquivo service.yaml, se ele estiver presente.

Terraform

Configure o Terraform conforme descrito no exemplo Como implantar um novo serviço.

Faça uma alteração no arquivo de configuração.
Aplique a configuração do Terraform:
```
terraform apply
```
Confirme que você quer aplicar as ações descritas digitando yes.

Observação: a menos que uma mudança de configuração seja necessária, nenhuma nova revisão será criada.

Cloud Code

Para implantar uma nova revisão de um serviço existente comCódigo na Nuvem, veja oIntelliJ eVisual Studio Code guias.

Escrever

Você pode armazenar sua Especificação Compose em um arquivo YAML e, em seguida, implantá-la como uma revisão de serviço do Cloud Run usando um único comando gcloud.

Para implantar um arquivo compose.yaml como uma revisão de serviço do Cloud Run, siga estas etapas:

No diretório do seu projeto, crie um arquivo compose.yaml com as definições do seu serviço.
```
services:
  web:
    image: IMAGE
    ports:
      - "8080:8080"
```
Substitua IMAGE_URL pela URL da sua imagem de contêiner.

Também é possível especificar mais opções de configuração, como variáveis de ambiente, secrets e montagens de volume.

Implantar o serviço

Para implantar os serviços, execute o comando gcloud run compose up:
```
gcloud run compose up compose.yaml
```
Responda y a quaisquer solicitações para instalar componentes necessários ou para habilitar APIs.
Opcional: torne seu serviço público se você quiser permitir o acesso não autenticado ao serviço.

Bibliotecas de cliente

Para implantar uma nova revisão do código:

API REST

Para implantar uma nova revisão, envie uma solicitação HTTP PATCH para o endpoint service da API Cloud Run Admin.

Por exemplo, usando curl:

curl -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -X PATCH \
  -d '{template: {containers: [{image: "IMAGE_URL"}]}}' \
  https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/services/SERVICE

Substitua:

ACCESS_TOKEN: um token de acesso válido para uma conta que tem as permissões IAM para implantar revisões. Por exemplo, se você fez login no gcloud, é possível recuperar um token de acesso usando gcloud auth print-access-token. Em uma instância de contêiner do Cloud Run, é possível recuperar um token de acesso por meio do servidor de metadados da instância de contêiner.
IMAGE_URL: uma referência à imagem de contêiner, por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL segue o formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .
SERVICE: o nome do serviço em que você está fazendo a implantação.
REGION: a Google Cloud região do serviço.
PROJECT-ID: o ID do projeto do Google Cloud .

Locais do Cloud Run

O Cloud Run está disponível nas regiões a seguir:

Sujeitas aos preços do nível 1

asia-east1 (Taiwan)
asia-northeast1 (Tóquio)
asia-northeast2 (Osaka)
asia-south1 (Mumbai, Índia)
asia-southeast3 (Bangkok)
europe-north1 (Finlândia) Baixo CO₂
europe-north2 (Estocolmo) Baixo CO₂
europe-southwest1 (Madrid) Baixo CO₂
europe-west1 (Bélgica) Baixo CO₂
europe-west4 (Países Baixos) Baixo CO₂
europe-west8 (Milão) Baixo CO₂
europe-west9 (Paris) Baixo CO₂
me-west1 (Tel Aviv)
northamerica-south1 (México)
us-central1 (Iowa) Baixo CO₂
us-east1 (Carolina do Sul)
us-east4 (Norte da Virgínia)
us-east5 (Columbus)
us-south1 (Dallas) Baixo CO₂
us-west1 (Oregon) Baixo CO₂

Sujeitas aos preços do nível 2

africa-south1 (Johannesburgo)
asia-east2 (Hong Kong)
asia-northeast3 (Seul, Coreia do Sul)
asia-southeast1 (Singapura)
asia-southeast2 (Jacarta)
asia-south2 (Déli, Índia)
australia-southeast1 (Sydney)
australia-southeast2 (Melbourne)
europe-central2 (Varsóvia, Polônia) Baixo CO₂
europe-west10 (Berlim)
europe-west12 (Turim) Baixo CO₂
europe-west2 (Londres, Reino Unido) Baixo CO₂
europe-west3 (Frankfurt, Alemanha)
europe-west6 (Zurique, Suíça) Baixo CO₂
me-central1 (Doha)
me-central2 (Dammam)
northamerica-northeast1 (Montreal) Baixo CO₂
northamerica-northeast2 (Toronto) Baixo CO₂
southamerica-east1 (São Paulo, Brasil) Baixo CO₂
southamerica-west1 (Santiago, Chile) Baixo CO₂
us-west2 (Los Angeles) Baixo CO₂
us-west3 (Salt Lake City)
us-west4 (Las Vegas)

Se você já criou um serviço do Cloud Run, é possível visualizar a região no painel do Cloud Run no console doGoogle Cloud .

Validar a configuração com um teste

Você pode validar as configurações de serviço sem implantá-las ou persistir as alterações usando a flag --dry-run.

Quando você especifica a flag --dry-run, o comando realiza as seguintes ações:

Valida a configuração.
Ignora o processo de build se você estiver implantando a partir da origem.
Não define políticas do Identity and Access Management.
Imprime uma mensagem de sucesso da validação.

Para validar uma implantação de imagem de contêiner:

gcloud beta run deploy SERVICE \
    --image IMAGE_URL \
    --dry-run

Substitua:

SERVICE: o nome do serviço em que você está fazendo a implantação.
IMAGE_URL: uma referência à imagem de contêiner, por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL segue o formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .

Implantar imagens de outros projetos Google Cloud

Para implantar imagens de outros projetos do Google Cloud , você ou seu administrador precisam conceder à conta do implantador e ao agente de serviço do Cloud Run os papéis necessários do IAM.

Para as funções necessárias para a conta de implantação, consulte funções necessárias.

Para conceder ao agente de serviço do Cloud Run os papéis necessários, consulte as instruções a seguir:

No console do Google Cloud , abra o projeto do seu serviço do Cloud Run.

Acessar a página do IAM
Selecione Incluir concessões de papel fornecidas pelo Google.
Copie o e-mail do agente de serviço do Cloud Run. Ele tem o sufixo @serverless-robot-prod.iam.gserviceaccount.com.
Abra o projeto com o registro do contêiner que você quer usar.

Acessar a página do IAM
Clique em Adicionar para adicionar um novo principal.
No campo Novos principais, cole o e-mail da conta de serviço que você copiou anteriormente.
No menu Selecionar um papel, clique em Artifact Registry -> Leitor do Artifact Registry.
Implante a imagem do contêiner no projeto que contém o serviço do Cloud Run.

Nota: Para maior segurança, conceda acesso ao repositório do Artifact Registry que contém suas imagens de contêiner.

Implantar imagens de outros registros

Para implantar imagens de contêiner públicas ou privadas que não estejam armazenadas no Artifact Registry ou no Docker Hub, ou que não sejam imagens públicas no GitHub Container Registry, configure um repositório remoto do Artifact Registry.

Os repositórios remotos do Artifact Registry permitem:

Implante qualquer imagem de contêiner pública.
Implante imagens de contêiner de repositórios privados que exigem autenticação, por exemplo, JFrog Artifactory ou Nexus.

Como alternativa, se não for possível usar um repositório remoto do Artifact Registry, é possível extrair e enviar imagens de contêiner temporariamente para o Artifact Registry usando docker push para implantá-las no Cloud Run. A imagem do contêiner é importada pelo Cloud Run quando implantada, de modo que, depois da implantação, é possível excluir a imagem do Artifact Registry.

Implantar vários contêineres em um serviço (sidecars)

Em uma implantação do Cloud Run com arquivos secundários, há um contêiner de entrada que processa todas as solicitações HTTPS de entrada na porta do contêiner especificada, e há um ou mais contêineres de arquivo secundário. Os arquivos secundários não podem detectar as solicitações HTTP de entrada na porta do contêiner de entrada, mas podem se comunicar entre si e com o contêiner de entrada usando uma porta localhost. A porta do localhost usada varia de acordo com os contêineres usados.

No diagrama a seguir, o contêiner de entrada se comunica com o arquivo secundário usando localhost:5000.

Vários contêineres do Cloud Run

É possível implantar até 10 contêineres por instância, incluindo o contêiner de entrada. Todos os contêineres em uma instância compartilham o mesmo namespace de rede e também podem compartilhar arquivos por meio do volume compartilhado na memória, conforme mostrado no diagrama.

É possível implantar vários contêineres no ambiente de execução de primeira ou segunda geração.

Se você usarfaturamento baseado em solicitações (O padrão do Cloud Run), os sidecars recebem alocação de CPU apenas nestes cenários:

A instância está processando pelo menos uma solicitação.
O contêiner de entrada está sendo iniciado.

Se o arquivo secundário precisar usar a CPU fora do processamento de solicitações (por exemplo, para coleta de métricas), configure a definição de faturamento para faturamento com base em instâncias do seu serviço. Para obter mais informações, consulte Configurações de faturamento (serviços).

Se você usa o faturamento baseado em solicitações, configure uma sondagem de inicialização para garantir que o arquivo secundário não tenha a CPU limitada na inicialização.

Você pode exigir que todas as implantações usem um sidecar específico criando políticas de organização personalizadas.

Casos de uso

Os casos de uso de arquivos secundários em um serviço do Cloud Run incluem:

Monitoramento, geração de registros e rastreamento de aplicativos
UsandoNginx, Envoy ou Apache2 como proxy na frente do contêiner do seu aplicativo
Adicionar filtros de autenticação e autorização (por exemplo, Open Policy Agent)
Como executar proxies de conexão de saída, como o proxy do Alloy DB Auth

Implantar um serviço com contêineres de arquivos secundários

É possível implantar vários arquivos secundários em um serviço do Cloud Run usando o Google Cloud console, a Google Cloud CLI, o YAML ou o Terraform.

Console

Para implantar um novo serviço com sidecars:

No Google Cloud console, acesse o Cloud RunServiços página:

Acessar o Cloud Run
Clique em Implantar contêiner para mostrar o formulário Criar serviço.
Forneça o nome do serviço e o URL para a imagem do contêiner de entrada que você quer implantar.
Clique em Contêineres, rede, segurança.
No card Editar contêiner, configure o contêiner de entrada conforme necessário.
Clique em Adicionar contêiner e configure um contêiner secundário que você quer adicionar com o contêiner de entrada. Se o sidecar depender de outro contêiner no serviço, indique isso no menu Ordem de inicialização do contêiner. Repita este passo para cada contêiner secundário que você estiver implantando.
Clique em Criar.

Para configurar um serviço atual com arquivos secundários:

No Google Cloud console, acesse o Cloud RunServiços página:

Acessar o Cloud Run
Para implantar em um serviço atual, clique nele.
Clique na guia Contêineres.
Clique em Adicionar contêiner e configure um contêiner secundário que você deseja adicionar junto com o contêiner de entrada. Se o sidecar depender de outro contêiner no serviço, indique isso no menu Ordem de inicialização do contêiner. Repita essa etapa para cada contêiner secundário que estiver implantando.
Clique em Ver diferença e reimplantar.
Para enviar todo o tráfego para a nova revisão, selecione Veicular esta revisão imediatamente. Para um lançamento gradual, desmarque essa caixa de seleção. Isso resulta em uma implantação em que nenhum tráfego é enviado para a nova revisão. Siga as instruções para os lançamentos graduais após a implantação.
Clique em Implantar mudanças.

gcloud

No console do Google Cloud , ative o Cloud Shell.

Ativar o Cloud Shell

Na parte de baixo do console Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
Para implantar vários contêineres em um serviço, execute o seguinte comando:
```
gcloud run deploy SERVICE \
 --container INGRESS_CONTAINER_NAME \
 --image='INGRESS_IMAGE' \
 --port='CONTAINER_PORT' \
 --container SIDECAR_CONTAINER_NAME \
 --image='SIDECAR_IMAGE'
```
Substitua:
- SERVICE: o nome do serviço em que você está fazendo a implantação. É possível omitir esse parâmetro inteiramente, mas será solicitado o nome do serviço, se você omiti-lo.
- INGRESS_CONTAINER_NAME: um nome para o contêiner que recebe as solicitações — por exemplo, app.
- INGRESS_IMAGE: uma referência à imagem do contêiner que vai receber solicitações, por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest.
- CONTAINER_PORT: a porta onde o contêiner de entrada escuta as solicitações recebidas. Ao contrário de um serviço de contêiner único, para um serviço com arquivos secundários, não há uma porta padrão para o contêiner de entrada. É necessário configurar explicitamente a porta do contêiner para o contêiner de entrada, e apenas um contêiner pode expor a porta.
- SIDECAR_CONTAINER_NAME: um nome para o contêiner sidecar, por exemplo, sidecar.
- SIDECAR_IMAGE: uma referência à imagem do contêiner de arquivo secundário
Se você quiser configurar cada contêiner no comando de implantação, forneça a configuração de cada contêiner após os parâmetros container, por exemplo:
```
gcloud run deploy SERVICE \
  --container CONTAINER_1_NAME \
  --image='INGRESS_IMAGE' \
  --set-env-vars=KEY=VALUE \
  --port='CONTAINER_PORT' \
  --container SIDECAR_CONTAINER_NAME \
  --image='SIDECAR_IMAGE' \
  --set-env-vars=KEY_N=VALUE_N
```
Importante: ao usar a flag --container, é necessário especificar todas as flags que não estejam no nível do contêiner antes das flags no nível do contêiner. Caso contrário, o implantar falha com uma mensagem de erro. Por exemplo, no comando "gcloud run services deploy service --execution-environment=gen2 --container app --memory=1G", o sinalizador --execution-environment deve ser passado antes do sinalizador --container.
Aguarde a conclusão da implantação. Após a conclusão bem-sucedida, uma mensagem de sucesso é exibida com o URL do serviço implantado.

YAML

Estas instruções mostram um arquivo YAML básico para o serviço do Cloud Run com arquivos secundários. Crie um arquivo chamado service.yaml e adicione o seguinte a ele:

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  annotations:
  name: SERVICE
spec:
  template:
    spec:
      containers:
      - image: INGRESS_IMAGE
        ports:
          - containerPort: CONTAINER_PORT
      - image: SIDECAR_IMAGE

Substitua:

SERVICE: o nome do seu serviço do Cloud Run. Os nomes dos serviços precisam ter 49 caracteres ou menos.
CONTAINER_PORT: a porta onde o contêiner de entrada escuta as solicitações recebidas. Ao contrário de um serviço de contêiner único, para um serviço com arquivos secundários, não há uma porta padrão para o contêiner de entrada. É necessário configurar explicitamente a porta do contêiner para o contêiner de entrada, e apenas um contêiner pode expor a porta.
INGRESS_IMAGE: uma referência à imagem do contêiner que vai receber solicitações, por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest.
SIDECAR_IMAGE: uma referência à imagem do contêiner de arquivo secundário. É possível especificar vários arquivos secundários adicionando mais elementos containers à matriz no YAML.

Depois de atualizar o YAML para incluir os contêineres de entrada e de arquivo secundário, implante no Cloud Run usando o comando:

gcloud run services replace service.yaml

Por padrão, o comando gcloud run services replace usa o arquivo service.yaml, se ele estiver presente.

Terraform

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform.

Adicione o seguinte a umgoogle_cloud_run_v2_service Recurso na sua configuração do Terraform:

resource "google_cloud_run_v2_service" "default" {
  name     = "SERVICE"
  location = "REGION"
  ingress = "INGRESS_TRAFFIC_ALL"
  template {
    containers {
      name = "INGRESS_CONTAINER_NAME"
      ports {
        container_port = CONTAINER_PORT
      }
      image = "INGRESS_IMAGE"
      depends_on = ["SIDECAR_CONTAINER_NAME"]
    }
    containers {
      name = "SIDECAR_CONTAINER_NAME"
      image = "SIDECAR_IMAGE"
      }
    }
  }

O CONTAINER_PORT representa a porta em que o contêiner de entrada detecta solicitações recebidas. Ao contrário de um serviço de contêiner único, para um serviço com arquivos secundários, não há uma porta padrão para o contêiner de entrada. É necessário configurar explicitamente a porta do contêiner para o contêiner de entrada, e apenas um contêiner pode expor a porta.

Recursos importantes disponíveis para implantações com arquivos secundários

Ordem de inicialização

É possível especificar a ordem de inicialização do contêiner em uma implantação com vários contêineres se você tiver dependências que exigem que alguns contêineres sejam iniciados antes de outros na implantação.

Se você tiver contêineres que dependem de outros contêineres, você deve usar healthchecks em sua implantação. Se você usar verificações de integridade, o Cloud Run seguirá a ordem de inicialização do contêiner e inspecionará a integridade de cada contêiner, garantindo que cada um seja aprovado com sucesso antes que o Cloud Run inicie o próximo contêiner no pedido. Se você não usar verificações de integridade, os contêineres íntegros serão iniciados mesmo que os contêineres de que dependem não estejam em execução.

Trocar dados de arquivos entre sidecars

Vários contêineres em uma única instância podem acessar um volume na memória compartilhado, acessível a cada contêiner por meio dos pontos de montagem criados. Isso é usado com frequência para compartilhar arquivos entre contêineres. Por exemplo, um contêiner secundário de telemetria pode coletar registros de um contêiner de aplicativo.

Comunicação entre sidecars

Dois contêineres da mesma instância podem se comunicar entre si na rede local.

Considere este exemplo de serviço:

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: example
spec:
  template:
    spec:
      containers:
      - name: ingress
        image: ...
        ports:
          - containerPort: 8080
      - name: sidecar
        image: ...

Cada instância desse serviço vai executar dois contêineres: um chamado ingress e outro chamado sidecar.

As solicitações que chegam ao serviço são enviadas ao contêiner ingress na porta 8080. Em um serviço com vários contêineres, apenas um pode ser configurado como o contêiner de entrada que processa todas as solicitações recebidas, e esse precisa ser o contêiner para o qual um containerPort está configurado.

Os contêineres ingress e sidecar podem se comunicar entre si em http://localhost. Por exemplo, se o contêiner sidecar detectar solicitações na porta 5000, o contêiner ingress poderá se comunicar com ele em http://localhost:5000.

Como os contêineres têm nomes, eles podem até se comunicar entre si usando o nome do contêiner. Por exemplo, se o contêiner sidecar escutar solicitações na porta 5000, então o contêiner ingress poderá se comunicar com sidecar usando em http://sidecar:5000.

Adapte seus contêineres para o Cloud Run.

A maioria dos contêineres que você criar ou encontrar será compatível com o contrato de tempo de execução de contêiner do Cloud Run . No entanto, talvez seja necessário alterar alguns contêineres criados para facilitar o desenvolvimento local ou esperar o controle total da máquina para torná-los compatíveis com os ambientes de execução do Cloud Run.

Mova os pontos de montagem para a sua configuração do Cloud Run.

Os scripts de inicialização do contêiner precisam presumir que as montagens já estão concluídas antes de chamar o contêiner. Mova todas as operações de montagem para a configuração de recursos do Cloud Run.

Mude para um usuário não raiz quando possível

Prefira contêineres que não usam nem dependem do usuário raiz. Essa prática reduz o risco de vulnerabilidade do seu serviço do Cloud Run, diminui a superfície de ataque do contêiner, limita o acesso de invasores aos seus sistemas de arquivos e segue o princípio de privilégio mínimo.

Use a instrução USER no seu Dockerfile para alternar para uma identidade com menos privilégios, já que o padrão é executar como root. O Cloud Run utiliza o usuário especificado no seu Dockerfile para executar o seu contêiner.

Auditoria para uso de binários `setuid`

A execução de binários setuid vai falhar quando executada nos contêineres do Cloud Run.

Se você estiver usando o Docker ou o Podman localmente, use o argumento --cap-drop=setuid. Alternativamente, verifique se os binários dos quais você depende não têm o bit setuid definido.

Verifique se os contêineres raiz são compatíveis com os namespaces do usuário.

Teste suas mudanças localmente ou em uma VM avaliando o código ao executar em namespaces de usuário, como ao usar o recurso userns-remap do Docker, executar o contêiner no Podman sem raiz ou implantar essas mudanças em VMs que executam o Container-Optimized OS do Google com o argumento --userns-remap=default no comando docker run.

Desativar a verificação de integridade da implantação

Por padrão, o Cloud Run verifica se a implantação está íntegra iniciando uma instância e aguardando a aprovação da sonda de inicialização. Se a verificação de integridade falhar, a revisão será marcada como não íntegra e o tráfego não será encaminhado para ela.

Caso não seja necessário ou para aumentar a velocidade de implantação, a verificação de integridade da implantação pode ser desativada:

gcloud

Para desativar a verificação de integridade da implantação, use a flag --no-deploy-health-check:

gcloud run deploy --image IMAGE_URL --no-deploy-health-check

Substitua:

IMAGE_URL: uma referência à imagem de contêiner, por exemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL segue o formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .

Use --deploy-health-check para reativar a verificação de integridade da implantação se ela tiver sido desativada anteriormente.

YAML

Para desativar a verificação de integridade da implantação, adicione a anotação run.googleapis.com/health-check-disabled com o valor 'true' a spec.template.metadata.annotations.

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/health-check-disabled: 'true'

Terraform

Para desativar a verificação de integridade da implantação, defina o argumento health_check_disabled como true no bloco template.

resource "google_cloud_run_v2_service" "default" {
  name     = "SERVICE"
  ...
  template {
    health_check_disabled = true
    ...
  }
}

A seguir

Depois de implantar um novo serviço, é possível realizar estas ações:

Automatize as compilações e as implantações dos serviços do Cloud Run usando os gatilhos do Cloud Build:

Configurar implantação contínua

Também é possível usar o Cloud Deploy para configurar um pipeline de entrega contínua que implanta serviços do Cloud Run em vários ambientes:

Implantar um app no Cloud Run usando o Cloud Deploy

Implantar imagens de contêiner em serviços do Cloud Run Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Funções exigidas

Registros e imagens de contêiner compatíveis

Implantar um novo serviço

Console

gcloud

YAML

Terraform

Escrever

MCP

Bibliotecas de cliente

API REST

Locais do Cloud Run

Sujeitas aos preços do nível 1

Sujeitas aos preços do nível 2

Implantar uma nova revisão de um serviço atual

Console

gcloud

YAML

Terraform

Cloud Code

Escrever

Bibliotecas de cliente

API REST

Locais do Cloud Run

Sujeitas aos preços do nível 1

Sujeitas aos preços do nível 2

Validar a configuração com um teste

Implantar imagens de outros projetos Google Cloud

Implantar imagens de outros registros

Implantar vários contêineres em um serviço (sidecars)

Casos de uso

Implantar um serviço com contêineres de arquivos secundários

Console

gcloud

YAML

Terraform

Recursos importantes disponíveis para implantações com arquivos secundários

Ordem de inicialização

Trocar dados de arquivos entre sidecars

Comunicação entre sidecars

Adapte seus contêineres para o Cloud Run.

Mova os pontos de montagem para a sua configuração do Cloud Run.

Mude para um usuário não raiz quando possível

Auditoria para uso de binários setuid

Verifique se os contêineres raiz são compatíveis com os namespaces do usuário.

Desativar a verificação de integridade da implantação

gcloud

YAML

Terraform

A seguir

Implantar imagens de contêiner em serviços do Cloud Run

Auditoria para uso de binários `setuid`