Esta página foi traduzida pela API Cloud Translation.

Implantar funções no Cloud Run

Esta página descreve como implantar e modificar funções no Cloud Run. Para conferir um exemplo de como implantar uma função Hello World, consulte Implantar uma função de exemplo.

Nos bastidores, as implantações de função do Cloud Run usam os buildpacks do Google Cloud e o Cloud Build para criar automaticamente imagens de contêiner do código-fonte da função sem ter que instalar o Docker na máquina ou configurar os buildpacks ou o Cloud Build.

As implantações de funções do Cloud Run também usam o Artifact Registry para armazenar artefatos e gerenciar imagens de contêineres. O Artifact Registry cria o Artifact Registry automaticamente repositório cloud-run-source-deploy caso seu projeto ainda não tenha criado um com este nome.

Antes de começar

Verifique se você configurou um novo projeto para o Cloud Run conforme descrito na página de configuração.

Ative o Artifact Registry, o Cloud Build, a API Cloud Run Admin e as APIs Cloud Logging:

 gcloud services enable artifactregistry.googleapis.com \
     cloudbuild.googleapis.com \
     run.googleapis.com \
     logging.googleapis.com

Se quiser, ative a API Eventarc para usar gatilhos de eventos:

 gcloud services enable eventarc.googleapis.com

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 receber as permissões necessárias para implantar os serviços do Cloud Run a partir da origem, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Desenvolvedor de origem do Cloud Run (roles/run.sourceDeveloper)
Usuário da conta de serviço (roles/iam.serviceAccountUser)

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 as APIs do Google 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.

Papéis da conta de serviço

Para que o Cloud Build consiga criar suas origens, conceda o papel Conta de serviço do Cloud Build para a conta de serviço padrão do Compute Engine. Basta executar o comando a seguir:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/cloudbuild.builds.builder

Substitua PROJECT_NUMBER pelo número do projeto do Google Cloud e PROJECT_ID pelo ID do projeto do Google Cloud. Para instruções detalhadas sobre como encontrar o ID e o número do projeto, consulte Criar e gerenciar projetos.

A concessão do papel de conta de serviço do Cloud Build à conta de serviço padrão do Compute Engine leva alguns minutos para se propagar.

Observação:

O iam.automaticIamGrantsForDefaultServiceAccounts restrição de política da organização impede que o papel de editor seja concedido automaticamente a contas de serviço padrão. Se você criou a organização após 3 de maio de 2024, essa restrição será aplicada por padrão.

É altamente recomendável aplicar essa restrição para desativar a concessão automática de papéis. Se você desativar a concessão automática de papéis, precisará decidir quais papéis conceder às contas de serviço padrão e, em seguida, conceder esses papéis por conta própria.

Se a conta de serviço padrão já tiver o papel de Editor, recomendamos que você o substitua por papéis menos permissivos. Para modificar com segurança os papéis da conta de serviço, use o Simulador de política para ver o impacto da alteração e, em seguida, conceda e revogue os papéis apropriados.

Opcionalmente, se você estiver usando o Eventarc, conceda os seguintes papéis para sua conta de serviço:
- Editor do Cloud Build (roles/cloudbuild.builds.editor)
- Administrador do Cloud Run (roles/run.admin)
- Criar contas de serviço (roles/iam.serviceAccountCreator)
- Chamador do Cloud Run (roles/run.invoker)
- Administrador do Eventarc (roles/eventarc.admin)
- Administrador de projetos do IAM (roles/resourcemanager.projectIamAdmin)
- Consumidor do Service Usage (roles/serviceusage.serviceUsageConsumer)
- Administrador do Storage (roles/storage.admin)
Para mais informações sobre como conceder papéis específicos ao Eventarc gatilhos, consulte Papéis e permissões para destinos do Cloud Run.

Criar e implantar uma função

É possível implantar uma função usando o console do Google Cloud ou a gcloud CLI. Clique na guia para ver instruções usando a ferramenta de sua preferência.

Console

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

Acessar o Cloud Run
Clique em Escrever uma função.
No campo Nome do serviço, insira um nome para descrever a função. Os nomes de serviço precisam começar com uma letra e conter até 49 caracteres, incluindo letras, números ou hifens. Os nomes de serviço não podem terminar com hifens e precisam 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.
Na lista Região, use o valor padrão ou selecione a região em que você quer implantar a função.
Na lista Ambiente de execução, use o valor padrão ou selecione uma versão do ambiente de execução.
Opcionalmente, na seção Gatilho, clique em Adicionar gatilho e selecione uma opção. O painel Gatilho do Eventarc é aberto. Nele, é possível modificar o detalhes a seguir para o gatilho:
1. No campo Nome do gatilho, digite um nome ou use o nome padrão.
2. Selecione um Tipo de acionador na lista para especificar um dos seguintes tipos de acionador:
  - Fontes do Google para especificar acionadores para Pub/Sub, Cloud Storage, Firestore, e outros provedores de eventos do Google.
  - Personalizado para produzir e consumir eventos do no código do aplicativo. Siga as instruções no painel Gatilho do Eventarc para criar um canal. Um canal é um recurso usado como pipeline para entregar eventos personalizados de produtores a consumidores. Eventos personalizados são publicados em um canal, e um gatilho do Eventarc se inscreve nesses eventos.
  - Terceiros para integração com provedores que não são do Google que oferecem uma origem do Eventarc. Para mais informações, consulte Eventos de terceiros no Eventarc.
3. Selecione um Provedor de eventos na lista para selecionar um produto que ofereça o tipo de evento para acionar sua função. Para ver a lista de provedores de eventos, consulte Provedores e destinos de eventos.
4. Selecione um Tipo de evento na lista. A configuração do gatilho varia de acordo com o tipo de evento compatível: Para mais informações, consulte Tipos de eventos.
5. No campo Região, selecione um local. para o Eventarc gatilho. Em geral, o local de um acionador do Eventarc precisa corresponder ao local do recurso do Google Cloud que você quer monitorar para eventos. Na maioria dos cenários, você também precisa implantar a função na mesma região. Consulte Noções básicas sobre locais do Eventarc para mais detalhes sobre locais de acionador do Eventarc.
6. No campo Conta de serviço, selecione uma conta de serviço. Os acionadores do Eventarc são vinculados a contas de serviço para usar como uma identidade ao invocar a função. A conta de serviço do acionador do Eventarc precisa ter permissão para invocar a função. Por padrão, o Cloud Run usa a conta de serviço padrão do Compute Engine.
7. Se quiser, especifique o caminho do URL do serviço para enviar a solicitação recebida. Esse é o caminho relativo no serviço de destino para o qual os eventos do gatilho precisam ser enviados. Por exemplo: /, /route, route e route/subroute.
8. Depois de preencher os campos obrigatórios, clique em Salvar gatilho.
Em Autenticação, configure o seguinte:
- Se você estiver criando uma função HTTP pública, por exemplo, um webhook, selecione Permitir invocações não autenticadas. 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ê não tiver permissões (função de administrador do Cloud Run) para selecionar essa opção, o serviço será implantado e exigirá autenticação.
- Se você estiver criando uma função acionada por evento, selecione Exigir autenticação.
Se preferir, atualize as seguintes configurações adicionais para suas funções:
1. Defina a alocação e os preços de CPU conforme necessário.
2. Em Escalonamento automático do serviço, especifique as instâncias mínimas conforme necessário.
3. Defina as configurações de Controle de entrada conforme necessário.
4. Expanda a seção Contêineres, volumes, rede, segurança para definir outras configurações opcionais nas guias apropriadas:
Clique em Criar e aguarde o Cloud Run criar o serviço usando uma revisão do marcador de posição.
O console vai redirecionar você para a guia Origem, em que você pode ver o código-fonte da sua função. Clique em Salvar e implantar novamente.
Na guia Origem, clique em Mostrar payload para conferir um exemplo de payload de eventos recebidos.
Após a implantação, teste a função criada clicando no botão Testar.

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Atualize os componentes gcloud para a versão mais recente:
```
gcloud components update
```
Execute o seguinte comando no diretório que contém o código de amostra:
```
gcloud beta run deploy FUNCTION \
       --source . \
       --function FUNCTION_ENTRYPOINT \
       --base-image BASE_IMAGE \
       --region REGION
```
Substitua:
- FUNCTION pelo nome da função que você está implantando. É possível omitir esse parâmetro inteiramente, mas será solicitado o nome, se você omiti-lo.
- FUNCTION_ENTRYPOINT: o ponto de entrada da função no código-fonte. Esse é o código que o Cloud Run executa quando é executada. O valor dessa sinalização precisa ser um nome de função ou de classe totalmente qualificada no código-fonte.
- BASE_IMAGE com o ambiente de imagem base da sua função. Para mais detalhes sobre as imagens de base e os pacotes incluídos em cada imagem, consulte Imagens de base dos ambientes de execução.
- REGION com o Google Cloud região onde você quer implantar sua função. Por exemplo, us-central1.
Opcional:
- Se você estiver criando uma função HTTP pública, por exemplo, um webhook, especifique a flag --allow-unauthenticated. Essa flag atribui o papel de invocador do IAM do Cloud Run ao identificador especial allUser. É possível usar o IAM para editar essa configuração depois de criar o serviço. Se você está criando uma função acionada por evento ou serviço autenticado, é possível omitir essa flag.

Opcionalmente, depois de implantar a função, você pode adicionar acionadores do Eventarc a ela. Para adicionar um gatilho, execute o seguinte comando:

  gcloud eventarc triggers create EVENTARC_TRIGGER_NAME \
      --location=EVENTARC_TRIGGER_LOCATION \
      --destination-run-service=FUNCTION \
      --destination-run-region=REGION \
      --event-filters="type=EVENTARC_FILTER_TYPE" \
      --event-filters="EVENTARC_EVENT_FILTER" \
      --service-account=EVENTARC_TRIGGER_SERVICE_ACCOUNT

Substitua:

EVENTARC_TRIGGER_NAME com o nome do gatilho Eventarc.
EVENTARC_TRIGGER_LOCATION pelo local do Gatilho do Eventarc. Em geral, o local de um acionador do Eventarc precisa corresponder ao local do recurso do Google Cloud que você quer monitorar para eventos. Na maioria dos cenários, você também precisa implantar a função na mesma região. Consulte Noções básicas sobre locais do Eventarc para mais detalhes sobre locais de acionador do Eventarc.
FUNCTION pelo nome da função implantada.
REGION pela região do Cloud Run da função.
EVENTARC_FILTER_TYPE pelos filtros de evento que o acionador e monitores. Um evento que corresponde a todos os filtros de --event-filters aciona chamadas para sua função. Cada gatilho precisa ter um tipo de evento compatível no formato --event-filters="type=EVENTARC_FILTER_TYPE". Não é possível alterar esse tipo de evento após a criação. Para mudar EVENT_FILTER_TYPE, crie um novo gatilho e exclua o antigo. Opcional: é possível repetir a flag --event-filters com um filtro compatível no formato ATTRIBUTE=VALUE para adicionar mais filtros.
EVENTARC_TRIGGER_SERVICE_ACCOUNT com uma conta de serviço Os acionadores do Eventarc são vinculados a contas de serviço para usar como uma identidade ao invocar a função. A conta de serviço do acionador do Eventarc precisa ter permissão para invocar a função. Por padrão, o Cloud Run usa a conta de serviço padrão do Compute.

Terraform

Para gerenciar funções usando o Terraform, crie o código da função em uma imagem de contêiner e defina o serviço do Cloud Run em uma configuração do Terraform usando o recurso google_cloud_run_v2_service do Provedor do Google Cloud Platform.

Siga as instruções para criar uma função e criar uma imagem do contêiner. Copie o caminho completo da imagem do contêiner para a variável IMAGE_URL usada na próxima etapa.
Crie um novo arquivo main.tf com este conteúdo:
```
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 pelo ID do projeto do Google Cloud.
- REGION pela região do Google Cloud.
- SERVICE pelo nome do 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 por 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 tem 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.
Inicialize o Terraform:
```
terraform init
```
Aplique a configuração do Terraform:
```
terraform apply
```
Confirme que você quer aplicar as ações descritas digitando yes.

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 produtos do Google Cloud usados pelo serviço do Cloud Run. O uso de produtos do Google Cloud em vários locais pode afetar a latência e o custo do 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)
europe-north1 (Finlândia) Baixo CO₂
europe-southwest1 (Madri) Baixo CO₂
europe-west1 (Bélgica) Baixo CO₂
europe-west4 (Países Baixos) Baixo CO₂
europe-west8 (Milão)
europe-west9 (Paris) Baixo CO₂
me-west1 (Tel Aviv)
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)
europe-west10 (Berlim) Baixo CO₂
europe-west12 (Turim)
europe-west2 (Londres, Reino Unido) Baixo CO₂
europe-west3 (Frankfurt, Alemanha) Baixo CO₂
europe-west6 (Zurique, Suíça) Baixo CO₂
me-central1 (Doha)
me-central2 (Damã)
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)
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 do Google Cloud.

Ativar novas tentativas do evento

O Eventarc usa o Pub/Sub como camada de transporte e tem uma política de nova tentativa padrão que pode não funcionar bem para sua função.

Depois de criar um gatilho do Eventarc, é altamente atualizando a política de nova tentativa Eventarc e configuração tópico de mensagens inativas no Pub/Sub

Modificar uma função

É possível modificar a configuração ou o código da função:

Modificar configuração

Para modificar parâmetros de configuração, como a alocação de CPU, memória e conectividade da VPC:

Console

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

Acessar o Cloud Run
Localize o serviço que você quer atualizar na lista de serviços e clique nele para abrir os detalhes.
Clique em Editar e implantar nova revisão para exibir o formulário de implantação da revisão.
Modifique qualquer definição de configuração.
Clique em Implantar e aguarde a conclusão da implantação.

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Para atualizar uma ou mais configurações de serviço, use o comando gcloud beta run services update SERVICE com as flags de linha de comando da configuração que você quer atualizar. Substitua SERVICE pelo nome do serviço.

Implantar novamente o novo código-fonte

É possível modificar a imagem base, o ambiente de execução e o código-fonte da função usando o console do Google Cloud ou a CLI gcloud.

Clique na guia para ver instruções usando a ferramenta de sua preferência.

Console

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

Acessar o Cloud Run
Localize a função que você quer atualizar na lista de serviços e clique nele para abrir os detalhes dessa função.
Navegue até a guia Origem e clique em Editar origem.
Clique em Editar atualizações de ambiente de execução e segurança ao lado de Imagem base, selecione um Ambiente de execução ou Ambiente diferente da lista conforme necessário e clique em Salvar.
Modifique o Ponto de entrada da função conforme necessário.
Na seção Arquivos, selecione Adicionar arquivo para criar um novo arquivo. Renomear arquivo para renomear um arquivo. ou Excluir arquivo para excluir um arquivo.
Na seção Código, modifique seu código-fonte conforme necessário.
Clique em Salvar e reimplantar e aguarde a conclusão da implantação.

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Execute o seguinte comando no diretório que contém o código-fonte da função:
```
gcloud beta run deploy FUNCTION \
       --source . \
       --function FUNCTION_ENTRYPOINT \
       --base-image BASE_IMAGE \
       --region REGION
```
Substitua:
- FUNCTION pelo nome da função que você quer modificar.
- FUNCTION_ENTRYPOINT: pelo ponto de entrada para sua função no código-fonte.
- BASE_IMAGE com o ambiente de imagem base da sua função. Na maioria dos casos, é possível especificar o ID do ambiente de execução, por exemplo, nodejs22:
  
  Como alternativa, se quiser usar um pacote de sistema específico na pilha ou especificar a região de onde é feito o download da imagem base, você pode especificar uma das seguintes opções:
  - O caminho completo da imagem de base, como us-central1-docker.pkg.dev/serverless-runtimes/google-22-full/runtimes/nodejs22. Essa opção permite especificar a imagem de base, um pacote de sistema específico na pilha e a região de origem do download da imagem de base.
  - O alias do caminho completo da imagem de base, como google-22/nodejs22 ou google-22-full/nodejs22. Essa opção de alias mais curta permite especificar a imagem de base e um pacote de sistema específico na pilha.
  Para mais detalhes sobre imagens de base e os pacotes incluídos em cada imagem, consulte Imagens de base do ambiente de execução.
- REGION pela região do Google Cloud em que você quer implantar a função. Por exemplo, us-central1.
Sinalizações opcionais

É possível configurar as seguintes sinalizações opcionais ao modificar sua função:
- Flags Build environment variables para especificar variáveis de ambiente durante a etapa de build, como para configurar certificados específicos no momento do build ou parâmetros.
- Sinalizações do pool de workers para especificar qual pool de workers usar no VPC Service Controls um contexto de build protegido.
- Contas de serviço de build personalizadas para especificar uma alternativa conta de serviço de build padrão para aumentar a segurança.
- Flag Atualizações automáticas de imagem de base para desativar as atualizações automáticas. Por padrão, as funções têm com atualizações de segurança ativadas.

A seguir

Depois de implantar uma nova função, é possível realizar estas ações:

Conferir ou excluir funções
Gerenciar serviços
Ver registros
Crie contêineres de função na sua própria toolchain e implante no Cloud Run
Acionar com eventos
Acionar funções do Cloud Storage usando Eventarc

Implantar funções no Cloud Run

Antes de começar

Funções exigidas

Papéis da conta de serviço

Criar e implantar uma função

Console

gcloud

Terraform

Locais do Cloud Run

Sujeitas aos preços do nível 1

Sujeitas aos preços do nível 2

Ativar novas tentativas do evento

Modificar uma função

Modificar configuração

Console

gcloud

Implantar novamente o novo código-fonte

Console

gcloud

Sinalizações opcionais

A seguir