Implantar uma função do Cloud Run

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

As implantações de função do Cloud Run usam automaticamente os buildpacks do Google Cloud e o Cloud Build para criar imagens de contêiner com base no código-fonte da função. Não é necessário instalar o Docker na máquina nem configurar 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 automaticamente o repositório do Artifact Registry chamado cloud-run-source-deploy, caso seu projeto ainda não tenha criado um com esse nome.

Se você tiver funções atuais e precisar usar o comando gcloud functions deploy, a API Cloud Functions v2 ou a configuração do Terraform google_cloudfunctions2_function para compatibilidade com versões anteriores, consulte Implantar funções com o comando gcloud functions deploy.

Antes de começar

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

  2. Ative as APIs Artifact Registry, Cloud Build, API Cloud Run Admin e API 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

  3. 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 implantar funções do Cloud Run, você ou seu administrador precisam conceder os seguintes papéis do IAM à conta de implantação e à conta de serviço:

Clique para conferir os papéis necessários para a conta do implantador

Para receber as permissões necessárias para criar e implantar a partir da origem, peça ao administrador para conceder a você os seguintes papéis do IAM:

Clique para conferir os papéis necessários para a conta de serviço do Cloud Build

O Cloud Build usa automaticamente a conta de serviço padrão do Compute Engine como a conta de serviço padrão do Cloud Build para criar seu código-fonte e o recurso do Cloud Run, a menos que você substitua esse comportamento. Para que o Cloud Build crie suas origens, peça ao administrador para conceder o papel Criador do Cloud Run (roles/run.builder) à conta de serviço padrão do Compute Engine no seu projeto:

  gcloud projects add-iam-policy-binding PROJECT_ID \
      --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
      --role=roles/run.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 do projeto e o número do projeto, consulte Criar e gerenciar projetos.

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

Clique para conferir os papéis necessários para a conta de serviço se estiver usando o Eventarc

Opcionalmente, se você estiver usando o Eventarc, conceda os seguintes papéis à sua conta de serviço:

Para mais informações sobre como conceder papéis específicos aos gatilhos do Eventarc, consulte Papéis e permissões para destinos do Cloud Run.

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

Criar e implantar uma função

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

Console

  1. No console do Google Cloud , acesse a página Serviços do Cloud Run:

    Acessar o Cloud Run

  2. Clique em Escrever uma função.

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

  4. Na lista Região, use o valor padrão ou selecione a região em que você quer implantar a função.

  5. Na lista Ambiente de execução, use o valor padrão ou selecione uma versão do ambiente de execução.

  6. 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 gatilho do Eventarc precisa corresponder ao local do recurso 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.

  7. Em Autenticação, configure o seguinte:

    • Se você estiver criando uma função HTTP pública, por exemplo, um webhook, 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ê 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.

  8. Se preferir, atualize as seguintes configurações adicionais para suas funções:

    1. Defina Faturamento conforme necessário.

    2. Em Escalonamento de serviço, se você usar o escalonamento automático padrão do Cloud Run, especifique as instâncias mínimas. Se você usar o escalonamento manual, especifique o número de instâncias para o serviço.

    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:

  9. Clique em Criar e aguarde o Cloud Run criar o serviço usando uma revisão do marcador de posição.

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

  11. Na guia Origem, clique em Mostrar payload para conferir um exemplo de payload de eventos recebidos.

  12. Após a implantação, teste a função criada clicando no botão Testar.

gcloud

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

  2. Atualize os componentes gcloud para a versão mais recente:

    gcloud components update

  3. Execute o seguinte comando no diretório que contém o código de amostra:

    gcloud 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, como nodejs24, python314, go126, java25, dotnet10, ruby40 ou php85. 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 a Google Cloud região em que você quer implantar a função. Por exemplo, europe-west1.

    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 gatilho do Eventarc precisa corresponder ao local do recurso 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, é preciso criar o código da função em uma imagem de contêiner e definir o serviço do Cloud Run em uma configuração do Terraform usando o recurso