Implemente serviços a partir do código-fonte

Esta página descreve como implementar um novo serviço ou uma revisão de serviço no Cloud Run diretamente a partir do código fonte através de um único comando da CLI gcloud, gcloud run deploy com a flag --source. Para um exemplo passo a passo da implementação de um serviço Hello World, consulte os Inícios rápidos de implementação a partir da origem.

Existem duas formas diferentes de usar esta funcionalidade:

Tenha em atenção que as implementações de origem usam o Artifact Registry para armazenar contentores criados. Se o seu projeto ainda não tiver um repositório do Artifact Registry com o nome cloud-run-source-deploy na região para a qual está a fazer a implementação, esta funcionalidade cria automaticamente um repositório do Artifact Registry com o nome cloud-run-source-deploy.

Se existir um Dockerfile no diretório do código-fonte, o código-fonte carregado é criado com esse Dockerfile. Se não existir nenhum Dockerfile no diretório de código-fonte, os buildpacks do Google Cloud detetam automaticamente a linguagem que está a usar e obtêm as dependências do código para criar uma imagem de contentor pronta para produção, usando uma imagem base segura gerida pela Google.

Por predefinição, as correções de segurança só são aplicadas quando o serviço do Cloud Run é implementado. Quando ativa as atualizações de segurança automáticas para um serviço, esse serviço recebe patches automaticamente sem tempo de inatividade. Saiba mais sobre a configuração das atualizações de segurança.

Antes de começar

  • Certifique-se de que configurou um novo projeto para o Cloud Run, conforme descrito na página de configuração.

  • Se estiver ao abrigo de uma política da organização de restrição de domínio que restringe invocações não autenticadas para o seu projeto, tem de aceder ao serviço implementado conforme descrito em Testar serviços privados.

  • 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 de ativar a API Cloud Run Admin, a conta de serviço predefinida do Compute Engine é criada automaticamente.

Funções necessárias

Para implementar a partir da origem, o utilizador ou o administrador tem de conceder à conta de implementação as seguintes funções de IAM.

Clique para ver as funções necessárias para a conta do implementador

Para receber as autorizações necessárias para criar e implementar a partir da origem, peça ao seu administrador para lhe conceder as seguintes funções de IAM:

Para ver uma lista de funções e autorizações de IAM associadas ao Cloud Run, consulte os artigos Funções de IAM do Cloud Run e Autorizações de IAM do Cloud Run. Se o seu serviço do Cloud Run interage com Google Cloud APIs, como as bibliotecas cliente da Google Cloud, consulte o guia de configuração da identidade do serviço. Para mais informações sobre a atribuição de funções, consulte as autorizações de implementação e faça a gestão do acesso.

Idiomas suportados

Além das origens com um Dockerfile, a implementação a partir da origem suporta os seguintes idiomas através dos buildpacks do Google Cloud:

Tempo de execução Implementação da origem Configuração do Buildpack
Ir Implemente um serviço Go Configure os buildpacks do Go
Node.js Implemente um serviço Node.js Configure buildpacks do Node.js
Python Implemente um serviço Python Configure os buildpacks do Python
Java
(inclui Kotlin, Groovy e Scala)		 Implemente um serviço Java Configure os buildpacks Java
.NET Implemente um serviço .NET Configure buildpacks .NET
Ruby Implemente um serviço Ruby Configure os buildpacks do Ruby
PHP Implemente um serviço PHP Configure os buildpacks do PHP

Leia mais detalhes sobre as versões de idiomas suportadas.

Implemente a partir da origem com compilação

Esta secção descreve como usar os buildpacks do Google Cloud e o Cloud Build para criar automaticamente imagens de contentores a partir do seu código-fonte sem ter de instalar o Docker no seu computador nem configurar buildpacks ou o Cloud Build.

Limitações

  • A implementação a partir da origem usa o Artifact Registry e o Cloud Build, pelo que esta funcionalidade só está disponível nas regiões suportadas pelo Artifact Registry e pelo Cloud Build.
  • A implementação a partir da origem é uma funcionalidade de conveniência e não permite a personalização total da compilação. Para ter mais controlo, crie a imagem de contentor com o Cloud Build, por exemplo, usando o gcloud builds submit e, em seguida, implemente a imagem de contentor usando, por exemplo, o gcloud run deploy --image.
  • A implementação a partir da origem com os buildpacks do Google Cloud define a data da última modificação dos ficheiros de origem como 1 de janeiro de 1980. Este é o comportamento predefinido dos buildpacks e foi concebido para suportar compilações reproduzíveis. Dependendo da sua framework de idiomas, isto pode afetar o armazenamento em cache no navegador de ficheiros estáticos. Se a sua aplicação for afetada por esta situação, a Google recomenda que desative os cabeçalhos HTTP etag e Last-Modified na sua aplicação.
  • A implementação a partir da origem com os buildpacks do Google Cloud usa sempre o gcr.io/buildpacks/builder:latest. Se o seu idioma preferencial ou configuração do SO não estiver disponível no latest, use um criador específico para criar uma imagem da aplicação com o seu criador preferencial.

  • Pode implementar o seu serviço a partir da origem usando Kotlin e outras linguagens JVM, como Java. A linguagem que usa tem de estar em conformidade com as seguintes regras:

    • Pode criar a aplicação através do Maven ou do Gradle.
    • O ficheiro de compilação contém todos os plug-ins necessários para as classes de produtos.

Antes de implementar com a compilação

Antes de implementar a partir da origem com a compilação:

  • Siga os passos 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 necessárias

Para implementar a partir da origem com a compilação, o utilizador ou o administrador tem de conceder à conta de serviço do Cloud Build as seguintes funções de IAM.

Clique para ver as funções necessárias para a conta de serviço do Cloud Build

O Cloud Build usa automaticamente a conta de serviço predefinida do Compute Engine como a conta de serviço predefinida do Cloud Build para compilar o seu código-fonte e o recurso do Cloud Run, a menos que substitua este comportamento. Para que o Cloud Build compile as suas origens, peça ao administrador para conceder a função Cloud Run Builder (roles/run.builder) à conta de serviço predefinida 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 seu Google Cloud número do projeto e PROJECT_ID pelo seu Google Cloud ID do projeto. Para ver instruções detalhadas sobre como encontrar o ID e o número do projeto, consulte o artigo Criar e gerir projetos.

A concessão da função de criador do Cloud Run à conta de serviço predefinida do Compute Engine demora alguns minutos a propagar.

Para ver uma lista de funções e autorizações de IAM associadas ao Cloud Run, consulte os artigos Funções de IAM do Cloud Run e Autorizações de IAM do Cloud Run. Se o seu serviço do Cloud Run interage com Google Cloud APIs, como as bibliotecas cliente da Google Cloud, consulte o guia de configuração da identidade do serviço. Para mais informações sobre a atribuição de funções, consulte as autorizações de implementação e faça a gestão do acesso.

Implemente com a compilação

Para implementar a partir do código fonte, clique no separador com instruções sobre como usar a ferramenta da 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. Altere 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 implemente o seu serviço:

    gcloud run deploy SERVICE --source .

    Substitua SERVICE pelo nome que quer para o seu serviço.

  4. Responda a todas as instruções para instalar as APIs necessárias respondendo y quando lhe for pedido. Só tem de fazer isto uma vez por projeto. Responda a outros pedidos fornecendo a plataforma e a região, se não tiver definido predefinições para estas, conforme descrito na página de configuração.

  5. Aguarde pela conclusão da compilação e da implementação. Quando terminar, o Cloud Run apresenta uma mensagem de êxito.

    6. Após a implementação, esta revisão do serviço publica 100% do tráfego.

    Cloud Code

    Para implementar a partir da origem com o Cloud Code, leia os guias do IntelliJ e do Visual Studio Code.

    CLI do Gemini

    Use o comando /deploy na ferramenta Gemini CLI para implementar um serviço do Cloud Run a partir do código fonte.

    Para usar a Gemini CLI com a extensão do Cloud Run, siga estes passos:

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

      • Terminal
      • Cloud Shell
      • VS Code com o modo de agente do Gemini Code Assist (consulte o separador "VS Code")

    2. Instale a extensão do Cloud Run:

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

    3. Inicie sessão na CLI Google Cloud:

      gcloud auth login

    4. Configure as Credenciais padrão da aplicação:

      gcloud auth application-default login

    5. Altere para o diretório de código-fonte.

    6. Inicie a Gemini CLI:

      gemini

    7. Crie e implemente o seu serviço:

      /deploy
      • Se lhe for pedido que indique o Google Cloud projeto, introduza o nome do projeto.
      • Se lhe for pedido que selecione uma ferramenta, selecione deploy_local_folder.

    8. Aguarde pela conclusão da compilação e da implementação. Quando terminar, o Cloud Run apresenta uma mensagem de êxito.

    MCP

    Para implementar um serviço do Cloud Run a partir do código fonte de um cliente do protocolo Model Context Protocol (MCP), instale o servidor do protocolo Model Context Protocol (MCP) do Cloud Run.

    As instruções de instalação variam consoante o cliente do MCP. Muitas vezes, exigem a adição das seguintes linhas ao ficheiro JSON de definições:

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

    Compor

    Pode armazenar a sua especificação de composição num ficheiro YAML e, em seguida, implementá-la a partir do código fonte como um serviço do Cloud Run através de um único comando gcloud.

    1. Altere 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 ficheiro compose.yaml com as suas definições de serviço.

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

      Também pode especificar mais opções de configuração, como variáveis de ambiente, segredos e montagens de volumes.

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

      gcloud beta run compose up compose.yaml

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

    5. Opcional: tornar o seu serviço público se quiser permitir o acesso não autenticado ao serviço.

    Após a implementação, é apresentado o URL do serviço do Cloud Run. Copie este URL e cole-o no navegador para ver o contentor em execução. Pode desativar a autenticação predefinida na consola Google Cloud .

Implemente a partir da origem sem compilação

Pode implementar artefactos de origem diretamente no Cloud Run, ignorando o passo do Cloud Build. Em vez de criar uma imagem de contentor a partir da origem, pode carregar um arquivo pré-embalado da sua aplicação diretamente para um contentor do Cloud Storage. Em seguida, o Cloud Run usa este arquivo e executa-o diretamente numa imagem base. Esta abordagem resulta em tempos de implementação significativamente mais rápidos.

Limitações

A implementação na origem sem compilação só suporta o seguinte:

  • Serviços do Cloud Run.
  • Runtimes suportados (sem suporte de Dockerfile).
  • Arquivo de origem (.tar.gz) <= 250 MiB.
  • O ficheiro binário (por exemplo, go binary) ou o script (por exemplo, script python) tem de ser compatível com a arquitetura x86.
  • A origem tem de ser autónoma, com todas as dependências incluídas no pacote. A imagem base de tempo de execução contém apenas o sistema operativo mínimo e algumas bibliotecas de idiomas.

Antes de implementar sem compilação

Para usar a funcionalidade "Implementar sem compilação":

  • Certifique-se de que seguiu os passos descritos na secção Antes de começar.

  • Ative as APIs Cloud Run e Cloud Storage:

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

  • Tem de instalar as dependências da aplicação localmente antes da implementação, uma vez que não são instaladas (sem compilação).

Implemente sem compilação

Esta secção descreve como implementar o seu artefacto diretamente no Cloud Run sem usar a compilação.

gcloud

Para implementar um diretório de origem local, use a flag --no-build para indicar ao comando deploy que ignore o passo do Cloud Build:

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

Substitua o seguinte:

  • SERVICE_NAME: o nome do seu serviço do Cloud Run.
  • APPLICATION_PATH: a localização da sua aplicação no sistema de ficheiros local.
  • BASE_IMAGE: a imagem base de tempo de execução que quer usar para a sua aplicação. Por exemplo, us-central1-docker.pkg.dev/serverless-runtimes/google-24-full/runtimes/nodejs24.
  • COMMAND: o comando com o qual o contentor é iniciado.
  • ARG: um argumento que envia para o comando do contentor. Se usar vários argumentos, especifique cada um na sua própria linha.

YAML

Pode armazenar a especificação do serviço num ficheiro YAML e, em seguida, implementá-lo através da CLI gcloud ou do editor da Google Cloud consolaservice.yaml.

  1. Crie um contentor de armazenamento para alojar a sua aplicação:

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

    Substitua o seguinte:

  2. Crie um arquivo com a origem da sua aplicação através de zip ou tar, por exemplo:

    tar -cvzf ARCHIVE_NAME APPLICATION_PATH

    Substitua o seguinte:

    • ARCHIVE_NAME: o nome do arquivo a criar. Por exemplo, app.tar.gz.
    • APPLICATION_PATH: a localização da sua aplicação no sistema de ficheiros local. Por exemplo, ~/my-application. Para arquivar o diretório de trabalho atual, defina este valor como *.

  3. Carregue o arquivo da aplicação para o Cloud Storage:

    gcloud storage cp ARCHIVE_NAME gs://BUCKET_NAME

    Substitua o seguinte:

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

  4. Crie um novo ficheiro 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 o seguinte:

    • SERVICE_NAME: o nome do seu serviço do Cloud Run. Os nomes dos serviços têm de ter 49 carateres ou menos e têm de ser únicos por região e projeto.
    • BUCKET_NAME: o nome do contentor que criou anteriormente. Por exemplo, my-bucket.
    • ARCHIVE_NAME: o caminho local para o arquivo que criou anteriormente. Por exemplo, app.tar.gz.
    • BASE_IMAGE: a imagem base de tempo de execução que quer usar para a sua aplicação. Por exemplo, us-central1-docker.pkg.dev/serverless-runtimes/google-24-full/runtimes/nodejs24.
    • COMMAND: o comando com o qual o contentor deve ser iniciado.
    • ARG1: o argumento que está a enviar para o comando do contentor. Se usar vários argumentos, especifique cada um na sua própria linha, por exemplo, conforme mostrado, ARG-N.

  5. Implemente 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 implementação a partir da origem sem compilação

Esta secção mostra exemplos de como implementar a partir da origem sem usar a compilação.

Node.js

Crie um serviço Node.js:

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

    mkdir helloworld
cd helloworld

  2. Crie um ficheiro 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 ficheiro index.js e copie as seguintes linhas para o mesmo:

    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}`);
});

    Este código cria um servidor Web básico que escuta 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, implemente o serviço com a flag --no-build, que indica ao comando deploy para ignorar o passo do Cloud Build:

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

    Substitua o seguinte:

    • REGION: a região onde o seu serviço está implementado.

Python

Crie um serviço Python:

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

    mkdir helloworld
cd helloworld

  2. Crie um ficheiro denominado main.py e cole o seguinte código no mesmo:

    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)))

    Este código responde a pedidos com a nossa saudação "Hello World". O processamento de HTTP é feito por um servidor Web Gunicorn no contentor. Quando invocado diretamente para utilização local, este código cria um servidor Web básico que escuta na porta definida pela variável de ambiente PORT.

  3. Crie um ficheiro denominado requirements.txt e cole o seguinte código no mesmo:

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

    Este código adiciona os pacotes necessários para o exemplo.

  4. Forneça as dependências:

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

  5. Implemente o serviço através da CLI gcloud. A flag --no-build indica ao comando deploy que ignore o passo 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 onde o seu serviço está implementado.

Resolução de problemas

Esta secção dá algumas sugestões sobre a resolução de problemas de implementação a partir da origem sem usar a compilação.

Desenvolvimento local

A implementação a partir da origem sem usar a compilação funciona de forma semelhante à montagem do código ou do ficheiro executável na imagem base.

Por exemplo:

  1. Criar uma cópia de todo o conteúdo:

    cp -R python/hello-world/ workspace

  2. Execute a imagem base como utilizador root com a origem montada. Opcionalmente, pode incluir -p 8080:8080 se precisar de usar o curl a partir de um computador anfitrião.

    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 pela localização dos seus ficheiros de origem locais.

  3. Execute o servidor:

    python main.py

Registo de execução

O registo de execução é útil para depurar falhas de implementação. Na Google Cloud consola, aceda a Observabilidade > Registos.

Acesso ao Cloud Storage recusado

Se o seu serviço do Cloud Run estiver a receber erros "Acesso negado" ao tentar aceder a objetos do Cloud Storage, tem de conceder a função roles/storage.objectViewer à sua conta de serviço do Cloud Run:

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

Substitua o seguinte:

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

Automatizar a compilação a partir da origem

Como prática recomendada para evitar alterações sem versão na origem local, a Google recomenda que faça a implementação automaticamente quando as alterações são enviadas para o seu repositório Git. Para facilitar este processo, pode ligar e configurar a implementação contínua no seu serviço do Cloud Run. Ao associar os seus repositórios do GitHub ao Cloud Run, pode configurar compilações e implementar os seus repositórios sem escrever Dockerfiles nem ficheiros de compilação.

Para configurar compilações automatizadas, configure a automatização conforme descrito na página de compilações contínuas, certificando-se de que escolhe a opção para criar a origem com buildpacks.

O que se segue?

Depois de implementar um serviço do Cloud Run, pode fazer o seguinte:

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

Pode automatizar as compilações e as implementações dos seus serviços do Cloud Run usando acionadores do Cloud Build: