Implantar serviços do código-fonte

Nesta página, descrevemos como implantar um novo serviço ou uma revisão de serviço no Cloud Run diretamente do código-fonte usando um único comando da CLI gcloud, gcloud run deploy com a sinalização --source. Para conferir um exemplo de como implantar um serviço Hello World, consulte Implantar usando os guias de início rápido da origem.

Há duas maneiras diferentes de usar esse recurso:

Observe que as implantações de origem usam o Artifact Registry para armazenar contêineres criados. Se o projeto ainda não tiver um repositório do Artifact Registry com o nome cloud-run-source-deploy na região em que você está implantando, esse recurso cria automaticamente um repositório do Artifact Registry com o nome cloud-run-source-deploy de dados.

Se houver um Dockerfile no diretório de código-fonte, o código-fonte enviado será criado usando esse Dockerfile. Se nenhum Dockerfile estiver presente no diretório do código-fonte, os buildpacks do Google Cloud detectarão automaticamente a linguagem usada e buscarão as dependências do código para criar uma imagem de contêiner pronta para produção, usando uma imagem de base segura gerenciada pelo Google.

Por padrão, as correções de segurança só são aplicadas quando o serviço do Cloud Run é implantado. Quando você ativa as atualizações automáticas de segurança em um serviço, ele recebe patches automaticamente sem inatividade. Saiba mais sobre configurando atualizações de segurança.

Antes de começar

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

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

  • Enable the Cloud Run Admin API.

    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 API

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

Funções exigidas

Para implantar a partir da origem, você ou seu administrador precisa conceder à conta do implantador os seguintes papéis do IAM.

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:

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.

Idiomas compatíveis

Além de fontes com um Dockerfile, é possível implantar da fonte com as seguintes linguagens usando os buildpacks do Google Cloud:

Ambiente de execução Implantação de origem Configuração do buildpack
Go Implantar um serviço Go Configurar buildpacks do Go
Node.js Implantar um serviço Node.js Configurar buildpacks do Node.js
Python Implantar um serviço Python Configurar buildpacks do Python
Java
(inclui Kotlin, Groovy e Scala)		 Implantar um serviço Java Configurar buildpacks Java
.NET Implantar um serviço .NET Configurar buildpacks do .NET
Ruby Implantar um serviço Ruby Configurar buildpacks do Ruby
PHP Implantar um serviço PHP Configurar buildpacks do PHP

Leia mais detalhes sobre as versões de linguagem compatíveis.

Implantar da origem com build

Nesta seção, descrevemos como usar os buildpacks do Google Cloud e o Cloud Build para criar automaticamente imagens de contêiner do código fonte sem instalar o Docker na máquina ou configurar os buildpacks ou o Cloud Build.

Limitações

  • A implantação da origem usa o Artifact Registry e o Cloud Build. Portanto, esse recurso só está disponível em regiões compatíveis com o Artifact Registry e o Cloud Build.
  • A implantação a partir da origem é um recurso prático e não permite a personalização completa do build. Para ter mais controle, crie a imagem do contêiner usando o Cloud Build (usando gcloud builds submit, por exemplo) e, em seguida, implante a imagem do contêiner (usando gcloud run deploy --image, por exemplo).
  • A implantação de origem com buildpacks do Google Cloud define a data da última modificação dos arquivos de origem como 1º de janeiro de 1980. Esse é o comportamento padrão dos buildpacks e foi projetado para ser compatível com builds reproduzíveis. Dependendo do framework da linguagem, isso pode afetar o armazenamento em cache de arquivos estáticos no navegador. Se o aplicativo for afetado por isso, o Google recomenda desativar os cabeçalhos HTTP etag e Last-Modified.
  • A implantação de origem com buildpacks do Google Cloud sempre usa gcr.io/buildpacks/builder:latest. Se a configuração de idioma ou SO de sua preferência não estiver disponível em latest, use um builder específico para criar uma imagem de aplicativo usando o builder que você preferir.

  • É possível implantar o serviço a partir da origem usando o Kotlin e outras linguagens da JVM, como Java. A linguagem usada precisa obedecer às seguintes regras:

    • É possível criar o aplicativo usando Maven ou Gradle.
    • O arquivo de build contém todos os plug-ins necessários para as classes de produto.

Antes de implantar com build

Antes de implantar da origem com build:

  • Siga as etapas em Antes de começar.

  • Enable the Cloud Build API.

    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 API

Funções exigidas

Para implantar da origem com build, você ou seu administrador precisam conceder à conta de serviço do Cloud Build 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 Cloude 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 builder do Cloud Run à conta de serviço padrão do Compute Engine leva alguns minutos para se propagar.

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.

Implantar com build

Para fazer a implantação do código-fonte, clique na guia para ver instruções sobre como usar a ferramenta de sua escolha.

gcloud

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

  2. Mude para o diretório de origem. O diretório de origem usa um Dockerfile se estiver presente, embora não seja obrigatório.

  3. Crie e implante seu serviço:

    gcloud run deploy SERVICE --source .

    Substitua SERVICE pelo nome do serviço.

  4. Responda a todas as solicitações para instalar as APIs necessárias respondendo ao y quando solicitado. Você só precisa fazer isso uma vez para um projeto. Responda a outras solicitações fornecendo a plataforma e a região, se você não tiver definido os padrões delas, conforme descrito na página de configuração.

  5. Aguarde a conclusão da criação e da implantação. Quando terminar, o Cloud Run vai mostrar uma mensagem de sucesso.

    6. Após a implantação, essa revisão de serviço atende a 100% do tráfego.

    Cloud Code

    Para implantar do código-fonte usando o Cloud Code, leia os guias do IntelliJ e do Visual Studio Code.

    CLI do Gemini

    Use o comando /deploy na ferramenta CLI do Gemini para implantar um serviço do Cloud Run com base no código-fonte.

    Para usar a CLI do Gemini com a extensão do Cloud Run, siga estas etapas:

    1. Instale a versão mais recente da CLI do Gemini em um dos seguintes ambientes de desenvolvimento:

      • Terminal
      • Cloud Shell
      • VS Code usando o modo Agente do Gemini Code Assist (consulte a guia "VS Code")

    2. Instale a extensão do Cloud Run:

      gemini extensions install https://github.com/GoogleCloudPlatform/cloud-run-mcp

    3. Faça login na Google Cloud CLI:

      gcloud auth login

    4. Configure as Application Default Credentials:

      gcloud auth application-default login

    5. Mude para o diretório do código-fonte.

    6. Inicie a CLI do Gemini:

      gemini

    7. Crie e implante seu serviço:

      /deploy
      • Se for solicitado que você forneça o projeto Google Cloud , insira o nome do projeto.
      • Se for solicitado, selecione deploy_local_folder.

    8. Aguarde a conclusão da criação e da implantação. Quando terminar, o Cloud Run vai mostrar uma mensagem de sucesso.

    MCP

    Para implantar um serviço do Cloud Run com base no código-fonte de um cliente do Protocolo de Contexto de Modelo (MCP), instale o servidor do Protocolo de Contexto de Modelo (MCP) do Cloud Run.

    As instruções de instalação variam de acordo com o cliente do MCP. Muitas vezes, é necessário adicionar as seguintes linhas ao arquivo JSON de configurações:

    "mcpServers":{
  "cloud-run": {
    "command": "npx",
    "args": ["-y", "@google-cloud/cloud-run-mcp"]
  }
}

    Escrever

    É possível armazenar a especificação do Compose em um arquivo YAML e implantá-lo do código-fonte como um serviço do Cloud Run usando um único comando gcloud.

    1. Mude para o diretório de origem. O diretório de origem usa um Dockerfile se estiver presente, embora não seja obrigatório.

    2. No diretório do projeto, crie um arquivo compose.yaml com as definições de serviço.

      services:
  web:
    build: .
    ports:
      - "8080:8080"

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

    3. Para implantar os serviços, execute o comando gcloud beta run compose up:

      gcloud beta run compose up compose.yaml

    4. Responda y a todas as solicitações para instalar os componentes necessários ou ativar APIs.

    5. 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 esse URL e cole no navegador para ver o contêiner em execução. É possível desativar a autenticação padrão no console do Google Cloud .

Implantar da origem sem build

É possível implantar artefatos de origem diretamente no Cloud Run, ignorando a etapa do Cloud Build. Em vez de criar uma imagem de contêiner da origem, você pode fazer upload de um arquivo pré-empacotado do aplicativo diretamente para um bucket do Cloud Storage. Em seguida, o Cloud Run usa esse arquivo e o executa diretamente em uma imagem de base. Essa abordagem resulta em tempos de implantação muito mais rápidos.

Limitações

A implantação na origem sem build só é compatível com o seguinte:

  • Serviços do Cloud Run.
  • Ambientes de execução compatíveis (sem suporte a Dockerfile).
  • Arquivo de origem (.tar.gz) <= 250 MiB.
  • O binário (por exemplo, binário go) ou o script (por exemplo, script Python) precisa ser compatível com a arquitetura x86.
  • A origem precisa ser independente, com todas as dependências incluídas no pacote. A imagem de base do ambiente de execução contém apenas o sistema operacional mínimo e algumas bibliotecas de linguagem.

Antes de implantar sem build

Para usar o recurso "implantar sem build":

  • Siga as etapas em Antes de começar.

  • Ative as APIs Cloud Run e Cloud Storage:

    gcloud services enable run.googleapis.com \
  storage.googleapis.com

  • É necessário instalar as dependências do aplicativo localmente antes da implantação, porque elas não serão instaladas (sem build).

Implantar sem build

Esta seção descreve como implantar seu artefato diretamente no Cloud Run sem usar o build.

gcloud

Para implantar um diretório de origem local, use a flag --no-build para informar ao comando deploy que ignore a etapa do Cloud Build:

gcloud beta run deploy SERVICE_NAME \
  --source APPLICATION_PATH \
  --no-build \
  --base-image=BASE_IMAGE \
  --command=COMMAND \
  --args=ARG

Substitua:

  • SERVICE_NAME: o nome do seu serviço do Cloud Run;
  • APPLICATION_PATH: o local do aplicativo no sistema de arquivos local.
  • BASE_IMAGE: a imagem de base do ambiente de execução que você quer usar para seu aplicativo. Por exemplo, us-central1-docker.pkg.dev/serverless-runtimes/google-24-full/runtimes/nodejs24.
  • COMMAND: o comando com que o contêiner é iniciado.
  • ARG: um argumento que você envia para o comando do contêiner. Se você usar vários argumentos, especifique cada um em uma linha própria.

YAML

É possível armazenar a especificação do serviço em um arquivo YAML e implantá-lo usando a CLI gcloud ou o editor da console service.yaml Google Cloud .

  1. Crie um bucket de armazenamento para armazenar seu aplicativo:

    gcloud storage buckets create gs://BUCKET_NAME --location=BUCKET_LOCATION

    Substitua:

    • BUCKET_NAME: o nome que você quer dar ao bucket, sujeito aos requisitos de nomenclatura. Por exemplo, my-bucket.
    • BUCKET_LOCATION: o local do bucket. Por exemplo, US.

  2. Crie um arquivo com a origem do aplicativo usando zip ou tar. Por exemplo:

    tar -cvzf ARCHIVE_NAME APPLICATION_PATH

    Substitua:

    • ARCHIVE_NAME: o nome do arquivo a ser criado. Por exemplo, app.tar.gz.
    • APPLICATION_PATH: o local do seu aplicativo no sistema de arquivos local. Por exemplo, ~/my-application. Para arquivar o diretório de trabalho atual, defina esse valor como *.

  3. Faça upload do arquivo do aplicativo para o Cloud Storage:

    gcloud storage cp ARCHIVE_NAME gs://BUCKET_NAME

    Substitua:

    • ARCHIVE_NAME: o caminho local para o arquivo que você criou anteriormente. Por exemplo, app.tar.gz.
    • BUCKET_NAME: o nome do bucket que você criou anteriormente. Por exemplo, my-bucket.

  4. Crie um novo arquivo service.yaml com o seguinte conteúdo:

    apiVersion: serving.knative.dev/v2
kind: Service
metadata:
 name: SERVICE_NAME
spec:
 template:
   metadata:
     annotations:
       run.googleapis.com/sources: '{"": "gs://BUCKET_NAME/ARCHIVE_NAME"}'
       run.googleapis.com/base-images: '{"": "BASE_IMAGE"}'
   spec:
     containers:
     - image: scratch
       command:
       - COMMAND
       args:
       - ARG1
       - ARG-N
     runtimeClassName: run.googleapis.com/linux-base-image-update

    Substitua:

    • SERVICE_NAME: o nome do seu serviço do Cloud Run; Os nomes dos serviços precisam ter 49 caracteres ou menos e ser exclusivos para cada região e projeto;
    • BUCKET_NAME: o nome do bucket que você criou anteriormente. Por exemplo, my-bucket.
    • ARCHIVE_NAME: o caminho local para o arquivo que você criou anteriormente. Por exemplo, app.tar.gz.
    • BASE_IMAGE: a imagem de base de tempo de execução que você quer usar no aplicativo. Por exemplo, us-central1-docker.pkg.dev/serverless-runtimes/google-24-full/runtimes/nodejs24.
    • COMMAND: o comando que o contêiner vai usar para iniciar.
    • ARG1: o argumento que você está enviando para o comando do contêiner. Se você usar vários argumentos, especifique cada um em uma linha própria, por exemplo, ARG-N, como mostrado abaixo.

  5. Implante o novo serviço:

    gcloud run services replace service.yaml

API REST

API REST:

curl -H "Content-Type: application/json" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X POST \
-d '{"template": {"containers": [{"command": ["npm"], "args": ["start"], "image": "scratch", "baseImageUri": "google-22/nodejs22", "sourceCode": {"cloudStorageSource": {"bucket": "'GCS_BUCKET_NAME", "object":"ARCHIVE"}}}]}}' \
https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/services?serviceId=SERVICE_NAME

Exemplos de implantação da fonte sem build

Esta seção mostra exemplos de como implantar da origem sem usar o build.

Node.js

Crie um serviço do Node.js:

  1. Crie um novo diretório com o nome helloworld e altere o diretório nele:

    mkdir helloworld
cd helloworld

  2. Crie um arquivo package.json com o seguinte conteúdo:

    {
  "name": "helloworld",
  "description": "Simple hello world sample in Node",
  "version": "1.0.0",
  "private": true,
  "main": "index.js",
  "type": "module",
  "scripts": {
    "start": "node index.js"
  },
  "engines": {
    "node": ">=16.0.0"
  },
  "author": "Google LLC",
  "license": "Apache-2.0",
  "dependencies": {
    "express": "^4.17.1"
  }
}

  3. No mesmo diretório, crie um arquivo index.js e copie as seguintes linhas nele:

    import express from 'express';
const app = express();

app.get('/', (req, res) => {
  const name = process.env.NAME || 'World';
  res.send(`Hello ${name}!`);
});

const port = parseInt(process.env.PORT) || 8080;
app.listen(port, () => {
  console.log(`helloworld: listening on port ${port}`);
});

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

  4. No diretório helloworld, execute o seguinte comando para instalar as dependências do serviço localmente:

    npm install

  5. No diretório helloworld, implante o serviço usando a flag --no-build, que informa ao comando deploy para pular a etapa do Cloud Build:

    gcloud beta run deploy helloworld \
 --source . \
 --region=REGION \
 --no-build \
 --base-image=nodejs24 \
 --command=node \
 --args=index.js

    Substitua:

    • REGION: a região em que o serviço está implantado.

Python

Crie um serviço em Python:

  1. Crie um novo diretório com o nome helloworld e altere o diretório nele:

    mkdir helloworld
cd helloworld

  2. Crie um arquivo chamado main.py e cole o seguinte código nele:

    import os

from flask import Flask

app = Flask(__name__)


@app.route("/")
def hello_world():
    """Example Hello World route."""
    name = os.environ.get("NAME", "World")
    return f"Hello {name}!"


if __name__ == "__main__":
    app.run(debug=True, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))

    Esse código responde às solicitações com a saudação "Hello World". A manipulação de HTTP é feita por um servidor da Web Gunicorn no contêiner. Quando invocado diretamente para uso local, este código cria um servidor da Web básico que atende na porta definida pela variável de ambiente PORT.

  3. Crie um arquivo chamado requirements.txt e cole o seguinte código nele:

    Flask==3.0.3
gunicorn==23.0.0
Werkzeug==3.0.3

    Esse código adiciona os pacotes necessários para a amostra.

  4. Disponibilize as dependências:

    pip3 install -r requirements.txt --target=./vendor

  5. Implante o serviço usando a CLI gcloud. A flag --no-build instrui o comando deploy a ignorar a etapa do Cloud Build:

    gcloud beta run deploy helloworld \
  --source . \
  --region=REGION \
  --no-build \
  --base-image=python313 \
  --command=python \
  --args=main.py \
  --set-env-vars PYTHONPATH=./vendor

Substitua REGION pela região em que o serviço está implantado.

Solução de problemas

Nesta seção, você encontra algumas dicas para solucionar problemas de implantação da origem sem usar build.

Desenvolvimento local

A implantação da origem sem usar build funciona de maneira semelhante à montagem do código ou executável na imagem de base.

Exemplo:

  1. Faça uma cópia de todo o conteúdo:

    cp -R python/hello-world/ workspace

  2. Execute a imagem de base como usuário raiz com a origem montada. Você pode incluir -p 8080:8080 se precisar usar curl em uma máquina host.

    docker run -it -v "LOCAL_PATH" -u 0 us-central1-docker.pkg.dev/serverless-runtimes/google-22-full/runtimes/python313 /bin/bash`

    Substitua LOCAL_PATH pelo local dos seus arquivos de origem locais.

  3. Execute o servidor:

    python main.py

Registro de execução

O registro de execução é útil para depurar falhas de implantação. No Google Cloud console, acesse Observabilidade > Registros.

Permissão negada no acesso ao Cloud Storage

Se o serviço do Cloud Run estiver encontrando erros de "Permissão negada" ao tentar acessar objetos do Cloud Storage, conceda o papel roles/storage.objectViewer à conta de serviço do Cloud Run:

gcloud projects add-iam-policy-binding PROJECT \
  --member="SERVICE_ACCOUNT" \
  --role="roles/storage.objectViewer"

Substitua:

  • PROJECT: o ID do projeto Google Cloud .
  • SERVICE_ACCOUNT: sua conta de serviço do Cloud Run. Por exemplo, service-123@serverless-robot-staging.iam.gserviceaccount.com.

Como automatizar a criação a partir da fonte

Como prática recomendada para evitar alterações sem versão na fonte local, o Google recomenda que você implante automaticamente quando as alterações forem enviadas ao seu repositório Git. Para facilitar esse processo, é possível conectar e configurar a implantação contínua no serviço do Cloud Run. Ao conectar seus repositórios do GitHub ao Cloud Run, é possível configurar versões e implantar seus repositórios sem escrever Dockerfiles ou arquivos de criação.

Para configurar versões automatizadas, configure a automação conforme descrito na página de versões contínuas, certificando-se de escolher a opção de criar a fonte com os buildpacks.

A seguir

Depois de implantar um serviço do Cloud Run, é possível fazer o seguinte:

Saiba mais sobre as configurações de implantação de origem:

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