Guia de início rápido: criar e implantar um app da Web Java Spring Boot no Cloud Run

Saiba como usar um único comando para criar e implantar um aplicativo da Web "Hello World" com base em um exemplo de código para Google Cloud usando o Cloud Run.

Ao seguir as etapas deste guia de início rápido, o Cloud Run cria automaticamente um Dockerfile para você quando implanta do código-fonte.

Antes de começar

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Make sure that you have the following role or roles on the project: Cloud Run Admin, Cloud Run Source Developer, Logs Viewer

    Check for the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.

    3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

    4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

    Grant the roles

    1. In the Google Cloud console, go to the IAM page.

      Acessar o IAM
    2. Selecione o projeto.
    3. Clique em Conceder acesso.

    4. No campo Novos principais, digite seu identificador de usuário. Normalmente, é o endereço de e-mail de uma Conta do Google.

    5. Na lista Selecionar papel, escolha um.
    6. Para conceder outros papéis, adicione-os clicando em Adicionar outro papel.
    7. Clique em Salvar.

  5. Install the Google Cloud CLI.

  6. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

  7. Para inicializar a gcloud CLI, execute o seguinte comando: 

    gcloud init

  8. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  9. Verify that billing is enabled for your Google Cloud project.

  10. Make sure that you have the following role or roles on the project: Cloud Run Admin, Cloud Run Source Developer, Logs Viewer

    Check for the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.

    3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

    4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

    Grant the roles

    1. In the Google Cloud console, go to the IAM page.

      Acessar o IAM
    2. Selecione o projeto.
    3. Clique em Conceder acesso.

    4. No campo Novos principais, digite seu identificador de usuário. Normalmente, é o endereço de e-mail de uma Conta do Google.

    5. Na lista Selecionar papel, escolha um.
    6. Para conceder outros papéis, adicione-os clicando em Adicionar outro papel.
    7. Clique em Salvar.

  11. Install the Google Cloud CLI.

  12. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

  13. Para inicializar a gcloud CLI, execute o seguinte comando: 

    gcloud init

  14. Para definir o projeto padrão do serviço do Cloud Run: 
     gcloud config set project PROJECT_ID
     Substitua PROJECT_ID pelo ID do projeto Google Cloud .

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

  16. Enable the Cloud Run Admin API and Cloud Build APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

    Depois que a API Cloud Run Admin for ativada, a conta de serviço padrão do Compute Engine será criadas automaticamente.

  17. Verifique se você tem o papel de usuário da conta de serviço concedido na identidade de serviço. Por padrão, a identidade de serviço é a conta de serviço padrão do Compute Engine.

    Conceder os papéis

    Para conceder acesso ao recurso de identidade do serviço, use o comando gcloud iam service-accounts add-iam-policy-binding, substituindo as variáveis destacadas pelos valores apropriados:

          gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
          --member=user:PRINCIPAL \
          --role=roles/iam.serviceAccountUser

    Substitua:

    • SERVICE_ACCOUNT_EMAIL: o endereço de e-mail da conta de serviço que você está usando como identidade de serviço, como:
      • A conta de serviço padrão do Compute Engine: PROJECT_NUMBER-compute@developer.gserviceaccount.com
      • Uma conta de serviço criada por você: SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
    • PRINCIPAL: o identificador do usuário. Normalmente, é o endereço de e-mail da Conta do Google que está implantando o recurso do Cloud Run.
  18. Conceda à conta de serviço do Cloud Build o seguinte papel 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 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 Google Cloude PROJECT_ID pelo ID do projeto 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 builder do Cloud Run à conta de serviço padrão do Compute Engine leva alguns minutos para se propagar.
  19. Consulte os preços do Cloud Run ou estime os custos com a calculadora de preços.

    20. Crie o aplicativo de exemplo

    Para escrever um aplicativo em Java:

    Crie um aplicativo Spring Boot.

    1. No console, crie um novo projeto da Web vazio usando os comandos curl e unzip:

      curl https://start.spring.io/starter.zip \
   -d type=maven-project \
   -d dependencies=web \
   -d javaVersion=21 \
   -d name=helloworld \
   -d artifactId=helloworld \
   -d baseDir=helloworld \
   -o helloworld.zip
unzip helloworld.zip
cd helloworld

      Isso cria um projeto Spring Boot.

      Para usar o comando cURL acima no Microscoft Windows, você precisará de uma das linhas de comando a seguir ou terá que usar o Spring Initializr (configuração pré-carregada, link em inglês) para gerar o projeto:

    2. Atualize a classe HelloworldApplication em src/main/java/com/example/helloworld/HelloworldApplication.java adicionando um @RestController para processar o mapeamento / e adicione também um campo @Value para fornecer a variável de ambiente NAME:

      
package com.example.helloworld;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
public class HelloworldApplication {

  @Value("${NAME:World}")
  String name;

  @RestController
  class HelloworldController {
    @GetMapping("/")
    String hello() {
      return "Hello " + name + "!";
    }
  }

  public static void main(String[] args) {
    SpringApplication.run(HelloworldApplication.class, args);
  }
}

    3. Configure a porta do servidor para ser definida pela variável de ambiente PORT em src/main/resources/application.properties:

      server.port=${PORT:8080}

      Esse código cria um servidor da Web básico que realiza detecções na porta definida pela variável de ambiente PORT.

    4. Crie um arquivo project.toml no diretório raiz do aplicativo para especificar uma versão do Java:

      [[build.env]]
name =  "GOOGLE_RUNTIME_VERSION"
value = "21"

    O app está concluído e pronto para ser implantado.

    Implantar no Cloud Run da origem

    Importante: este guia de início rápido pressupõe que você tenha papéis de proprietário ou editor no projeto que está usando para este guia. Caso contrário, consulte o papel de desenvolvedor de origem do Cloud Run para ter acesso às permissões necessárias para implantar um recurso do Cloud Run a partir da origem.

    A implantação a partir da origem cria automaticamente uma imagem de contêiner com base no código-fonte e a implanta.

    Para implantar a partir da origem:

    1. No diretório que contém o arquivo pom.xml, implante o app usando o seguinte comando: 

      gcloud run deploy --source .

      1. Quando o nome do serviço for solicitado, pressione "Enter" para aceitar o nome padrão, por exemplo, helloworld.

      2. Se for solicitado que você ative APIs adicionais no projeto, por exemplo, a API Artifact Registry, responda pressionando y:

      3. Quando a região for solicitada, selecione a região que preferir, por exemplo, europe-west1.

      4. Se você for solicitado a criar um repositório na região especificada, responda pressionando y.

      5. Se for solicitado que você permita acesso público, siga estas etapas: responda y. Se houver um domínio, você não vai receber essa solicitação e a política de restrição da organização que impede isso. Para mais detalhes, consulte a seção Antes de começar.

      Aguarde alguns instantes até a conclusão da implantação. Em caso de sucesso, a linha de comando exibe o URL de serviço.

    2. Consulte o contêiner implantado abrindo o URL de serviço em um navegador da Web.

    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. 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) Ícone de folha Baixo CO2
    • europe-north2 (Estocolmo) Ícone de folha Baixo CO2
    • europe-southwest1 (Madri) Ícone de folha Baixo CO2
    • europe-west1 (Bélgica) Ícone de folha Baixo CO2
    • europe-west4 (Países Baixos) Ícone de folha Baixo CO2
    • europe-west8 (Milão)
    • europe-west9 (Paris) Ícone de folha Baixo CO2
    • me-west1 (Tel Aviv)
    • northamerica-south1 (México)
    • us-central1 (Iowa) Ícone de folha Baixo CO2
    • us-east1 (Carolina do Sul)
    • us-east4 (Norte da Virgínia)
    • us-east5 (Columbus)
    • us-south1 (Dallas) Ícone de folha Baixo CO2
    • us-west1 (Oregon) Ícone de folha Baixo CO2

    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)
    • europe-west12 (Turim)
    • europe-west2 (Londres, Reino Unido) Ícone de folha Baixo CO2
    • europe-west3 (Frankfurt, Alemanha)
    • europe-west6 (Zurique, Suíça) Ícone de folha Baixo CO2
    • me-central1 (Doha)
    • me-central2 (Damã)
    • northamerica-northeast1 (Montreal) Ícone de folha Baixo CO2
    • northamerica-northeast2 (Toronto) Ícone de folha Baixo CO2
    • southamerica-east1 (São Paulo, Brasil) Ícone de folha Baixo CO2
    • southamerica-west1 (Santiago, Chile) Ícone de folha Baixo CO2
    • 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 doGoogle Cloud .

    Limpar

    Para evitar cobranças extras na sua conta do Google Cloud , exclua todos os recursos implantados com este guia de início rápido.

    Excluir o repositório

    O Cloud Run não cobra quando o serviço implantado não está em uso. No entanto, ainda é possível receber cobranças pelo armazenamento da imagem do contêiner no Artifact Registry. Para excluir repositórios do Artifact Registry, siga as etapas em Excluir repositórios na documentação do Artifact Registry.

    Excluir o serviço

    Os serviços do Cloud Run não geram custos até receberem solicitações. Para excluir o serviço do Cloud Run, siga uma destas etapas:

    Console

    Para excluir um serviço, realize as etapas a seguir:

    1. No Google Cloud console, acesse o Cloud Run:

      Acessar o Cloud Run

    2. Localize o serviço que você quer excluir na lista de serviços e clique na caixa de seleção para marcá-lo.

    3. Clique em Excluir. Isso excluirá todas as revisões do serviço.

    gcloud

    Para excluir um serviço, execute o seguinte comando:

    gcloud run services delete SERVICE --region REGION

    Substitua:

    • SERVICE: nome do serviço.
    • REGION: Google Cloud região do serviço.

    Excluir o projeto de teste

    A exclusão do projeto Google Cloud interrompe o faturamento de todos os recursos nele. Para liberar todos os recursos Google Cloud no seu projeto, siga estas etapas:

    1. In the Google Cloud console, go to the Manage resources page.

      Go to Manage resources

    2. In the project list, select the project that you want to delete, and then click Delete.
    3. In the dialog, type the project ID, and then click Shut down to delete the project.

    A seguir

    Para mais informações sobre como criar um contêiner a partir do código-fonte e enviá-lo para um repositório, consulte: