Eseguire il deployment dei servizi dal codice sorgente

Questa pagina descrive come eseguire il deployment di un nuovo servizio o di una nuova revisione del servizio su Cloud Run direttamente dal codice sorgente utilizzando un singolo comando gcloud CLI, gcloud run deploy con il flag --source. Per un esempio di procedura dettagliata per il deployment di un servizio Hello World, consulta Avvio rapido del deployment dall'origine.

Esistono due modi diversi per utilizzare questa funzionalità:

Tieni presente che i deployment delle origini utilizzano Artifact Registry per archiviare i container creati. Se il tuo progetto non ha già un repository Artifact Registry con il nome cloud-run-source-deploy nella regione in cui esegui il deployment, questa funzionalità crea automaticamente un repository Artifact Registry con il nome cloud-run-source-deploy.

Se nella directory del codice sorgente è presente un Dockerfile, il codice sorgente caricato viene creato utilizzando quel Dockerfile. Se non è presente alcun Dockerfile nella directory del codice sorgente, i buildpack di Google Cloud rilevano automaticamente il linguaggio che stai utilizzando e recuperano le dipendenze del codice per creare un'immagine container pronta per la produzione, utilizzando un'immagine di base sicura gestita da Google.

Per impostazione predefinita, le correzioni di sicurezza vengono applicate solo quando viene eseguito il deployment del servizio Cloud Run. Quando abiliti gli aggiornamenti automatici della sicurezza per un servizio, questo riceve automaticamente le patch senza tempi di inattività. Scopri di più sulla configurazione degli aggiornamenti della sicurezza.

Prima di iniziare

  • Assicurati di aver configurato un nuovo progetto per Cloud Run come descritto nella pagina di configurazione.

  • Se il tuo progetto è soggetto a un criterio dell'organizzazione con restrizioni di dominio che limitano le chiamate non autenticate, devi accedere al servizio di cui è stato eseguito il deployment come descritto in Test dei servizi privati.

  • 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

    Una volta abilitata l'API Cloud Run Admin, l'account di servizio predefinito di Compute Engine viene creato automaticamente.

Ruoli obbligatori

Per eseguire il deployment dall'origine, tu o il tuo amministratore dovete concedere all'account di deployment i seguenti ruoli IAM.

Fai clic per visualizzare i ruoli richiesti per l'account di deployment

Per ottenere le autorizzazioni necessarie per creare e implementare dal codice sorgente, chiedi all'amministratore di concederti i seguenti ruoli IAM:

Per un elenco di ruoli e autorizzazioni IAM associati a Cloud Run, consulta Ruoli IAM di Cloud Run e Autorizzazioni IAM di Cloud Run. Se il tuo servizio Cloud Run interagisce con le APIGoogle Cloud , come le librerie client Cloud, consulta la guida alla configurazione dell'identità di servizio. Per saperne di più sulla concessione dei ruoli, consulta Autorizzazioni di deployment e Gestire l'accesso.

Lingue supportate

Oltre alle origini con un Dockerfile, il deployment dall'origine supporta le seguenti lingue utilizzando i buildpack di Google Cloud:

Runtime Deployment dell'origine Configurazione buildpack
Vai Esegui il deployment di un servizio Go Configurare i buildpack Go
Node.js Esegui il deployment di un servizio Node.js Configura i buildpack Node.js
Python Esegui il deployment di un servizio Python Configura i buildpack Python
Java
(include Kotlin, Groovy, Scala)		 Esegui il deployment di un servizio Java Configurare i buildpack Java
.NET Esegui il deployment di un servizio .NET Configura i buildpack .NET
Ruby Esegui il deployment di un servizio Ruby Configurare i buildpack Ruby
PHP Esegui il deployment di un servizio PHP Configurare i buildpack PHP

Scopri di più sulle versioni delle lingue supportate.

Deployment dall'origine con build

Questa sezione descrive come utilizzare i buildpack di Google Cloud e Cloud Build per creare automaticamente immagini container dal codice sorgente senza dover installare Docker sulla tua macchina o configurare buildpack o Cloud Build.

Limitazioni

  • Il deployment dall'origine utilizza Artifact Registry e Cloud Build, pertanto questa funzionalità è disponibile solo nelle regioni supportate da Artifact Registry e Cloud Build.
  • Il deployment dall'origine è una funzionalità comoda e non consente la personalizzazione completa della build. Per un maggiore controllo, crea l'immagine container utilizzando Cloud Build, ad esempio, utilizzando gcloud builds submit, quindi esegui il deployment dell'immagine container utilizzando, ad esempio, gcloud run deploy --image.
  • Il deployment dall'origine con i buildpack di Google Cloud imposta la data dell'ultima modifica dei file di origine al 1° gennaio 1980. Questo è il comportamento predefinito dei buildpack ed è progettato per supportare build riproducibili. A seconda del framework linguistico, ciò può influire sulla memorizzazione nella cache lato browser dei file statici. Se la tua applicazione è interessata da questo problema, Google consiglia di disattivare le intestazioni HTTP etag e Last-Modified nella tua applicazione.
  • Il deployment dall'origine con i buildpack di Google Cloud utilizza sempre gcr.io/buildpacks/builder:latest. Se la lingua o la configurazione del sistema operativo che preferisci non è disponibile in latest, utilizza un builder specifico per creare un'immagine dell'applicazione utilizzando il builder che preferisci.

  • Puoi eseguire il deployment del servizio dal codice sorgente utilizzando Kotlin e altri linguaggi JVM come Java. La lingua che utilizzi deve essere conforme alle seguenti regole:

    • Puoi creare l'applicazione utilizzando Maven o Gradle.
    • Il file di build contiene tutti i plug-in necessari per le classi di prodotti.

Prima del deployment con la build

Prima di eseguire il deployment dall'origine con la build:

  • Segui i passaggi descritti in Prima di iniziare.

  • 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

Ruoli obbligatori

Per eseguire il deployment dall'origine con la build, tu o il tuo amministratore dovete concedere i seguenti ruoli IAM al account di servizio Cloud Build.

Fai clic per visualizzare i ruoli richiesti per il account di servizio Cloud Build

Cloud Build utilizza automaticamente l'account di servizio predefinito di Compute Engine come service account Cloud Build predefinito per creare il codice sorgente e la risorsa Cloud Run, a meno che tu non esegua l'override di questo comportamento. Per consentire a Cloud Build di creare le tue origini, chiedi all'amministratore di concedere il ruolo Cloud Run Builder (roles/run.builder) al account di servizio predefinito di Compute Engine sul tuo progetto:

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

Sostituisci PROJECT_NUMBER con il numero del tuo progetto Google Cloude PROJECT_ID con l'ID progetto Google Cloud. Per istruzioni dettagliate su come trovare l'ID progetto e il numero di progetto, vedi Creazione e gestione dei progetti.

La concessione del ruolo Cloud Run Builder all'account di servizio Compute Engine predefinito richiede un paio di minuti per la propagazione.

Per un elenco di ruoli e autorizzazioni IAM associati a Cloud Run, consulta Ruoli IAM di Cloud Run e Autorizzazioni IAM di Cloud Run. Se il tuo servizio Cloud Run interagisce con le APIGoogle Cloud , come le librerie client Cloud, consulta la guida alla configurazione dell'identità di servizio. Per saperne di più sulla concessione dei ruoli, consulta Autorizzazioni di deployment e Gestire l'accesso.

Esegui il deployment con la build

Per il deployment dal codice sorgente, fai clic sulla scheda con le istruzioni per l'utilizzo dello strumento che preferisci.

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. Passa alla directory di origine. La directory di origine utilizza un Dockerfile se presente, anche se non è obbligatorio.

  3. Crea ed esegui il deployment del tuo servizio:

    gcloud run deploy SERVICE --source .

    Sostituisci SERVICE con il nome che vuoi assegnare al servizio.

  4. Rispondi a eventuali richieste di installazione delle API necessarie rispondendo y quando richiesto. Devi farlo solo una volta per progetto. Rispondi agli altri prompt fornendo la piattaforma e la regione, se non hai impostato valori predefiniti per questi elementi come descritto nella pagina di configurazione.

  5. Attendi il completamento della build e del deployment. Al termine, Cloud Run mostra un messaggio di operazione riuscita.

    6. Dopo il deployment, questa revisione del servizio gestisce il 100% del traffico.

    Cloud Code

    Per eseguire il deployment dal codice sorgente utilizzando Cloud Code, leggi le guide per IntelliJ e Visual Studio Code.

    Interfaccia a riga di comando di Gemini

    Utilizza il comando /deploy nello strumento Gemini CLI per eseguire il deployment di un servizio Cloud Run dal codice sorgente.

    Per utilizzare la Gemini CLI con l'estensione Cloud Run, segui questi passaggi:

    1. Installa l'ultima versione di Gemini CLI in uno dei seguenti ambienti di sviluppo:

      • Terminale
      • Cloud Shell
      • VS Code utilizzando la modalità agente di Gemini Code Assist (vedi la scheda "VS Code")

    2. Installa l'estensione Cloud Run:

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

    3. Accedi a Google Cloud CLI:

      gcloud auth login

    4. Configura le Credenziali predefinite dell'applicazione:

      gcloud auth application-default login

    5. Passa alla directory del codice sorgente.

    6. Avvia Gemini CLI:

      gemini

    7. Crea ed esegui il deployment del tuo servizio:

      /deploy
      • Se ti viene chiesto di fornire il Google Cloud progetto, inserisci il nome del progetto.
      • Se ti viene chiesto di selezionare uno strumento, seleziona deploy_local_folder.

    8. Attendi il completamento della build e del deployment. Al termine, Cloud Run mostra un messaggio di operazione riuscita.

    MCP

    Per eseguire il deployment di un servizio Cloud Run dal codice sorgente da un client Model Context Protocol (MCP), installa il server Model Context Protocol (MCP) di Cloud Run.

    Le istruzioni di installazione variano a seconda del client MCP. Spesso richiedono l'aggiunta delle seguenti righe al file JSON delle impostazioni:

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

    Scrivi

    Puoi archiviare la specifica di Compose in un file YAML e poi eseguirne il deployment dal codice sorgente come servizio Cloud Run utilizzando un singolo comando gcloud.

    1. Passa alla directory di origine. La directory di origine utilizza un Dockerfile se presente, anche se non è obbligatorio.

    2. Nella directory del progetto, crea un file compose.yaml con le definizioni del servizio.

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

      Puoi anche specificare altre opzioni di configurazione, come variabili di ambiente, secret e montaggi volumi.

    3. Per eseguire il deployment dei servizi, esegui il comando gcloud beta run compose up:

      gcloud beta run compose up compose.yaml

    4. Rispondi y a eventuali richieste di installazione dei componenti necessari o di attivazione delle API.

    5. (Facoltativo) Rendi pubblico il servizio se vuoi consentire l'accesso non autenticato al servizio.

    Dopo il deployment, viene visualizzato l'URL del servizio Cloud Run. Copia questo URL e incollalo nel browser per visualizzare il contenitore in esecuzione. Puoi disattivare l'autenticazione predefinita dalla console Google Cloud .

Esegui il deployment dall'origine senza build

Puoi eseguire il deployment degli artefatti di origine direttamente in Cloud Run, ignorando il passaggio di Cloud Build. In questo modo, anziché creare un'immagine container dall'origine, puoi caricare un archivio precompilato della tua applicazione direttamente in un bucket Cloud Storage. Cloud Run prende quindi questo archivio e lo esegue direttamente su un'immagine di base. Questo approccio comporta tempi di deployment notevolmente più rapidi.

Limitazioni

Il deployment nell'origine senza build supporta solo quanto segue:

  • Servizi Cloud Run.
  • Runtime supportati (nessun supporto per Dockerfile).
  • Archivio di origine (.tar.gz) <= 250 MiB.
  • Il binario (ad esempio, binario Go) o lo script (ad esempio, script Python) deve essere compatibile con l'architettura x86.
  • L'origine deve essere autonoma, con tutte le dipendenze pacchettizzate. L'immagine di base del runtime contiene solo il sistema operativo minimo e alcune librerie di lingue.

Prima di eseguire il deployment senza build

Per utilizzare la funzionalità "deploy without build":

  • Assicurati di aver seguito i passaggi descritti in Prima di iniziare.

  • Abilita le API Cloud Run e Cloud Storage:

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

  • Devi installare le dipendenze dell'applicazione localmente prima del deployment, in quanto non verranno installate (nessuna build).

Esegui il deployment senza build

Questa sezione descrive come eseguire il deployment dell'artefatto direttamente in Cloud Run senza utilizzare la build.

gcloud

Per eseguire il deployment di una directory di origine locale, utilizza il flag --no-build per indicare al comando deploy di ignorare il passaggio di Cloud Build:

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

Sostituisci quanto segue:

  • SERVICE_NAME: il nome del tuo servizio Cloud Run.
  • APPLICATION_PATH: la posizione dell'applicazione nel file system locale.
  • BASE_IMAGE: l'immagine di base del runtime che vuoi utilizzare per la tua applicazione. Ad esempio us-central1-docker.pkg.dev/serverless-runtimes/google-24-full/runtimes/nodejs24.
  • COMMAND: il comando con cui viene avviato il container.
  • ARG: un argomento che invii al comando del container. Se utilizzi più argomenti, specifica ciascuno su una riga separata.

YAML

Puoi archiviare la specifica del servizio in un file YAML e poi eseguirne il deployment utilizzando gcloud CLI o l'editor della console Google Cloud service.yaml.

  1. Crea un bucket di archiviazione per contenere l'applicazione:

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

    Sostituisci quanto segue:

  2. Crea un archivio con l'origine dell'applicazione utilizzando zip o tar, ad esempio:

    tar -cvzf ARCHIVE_NAME APPLICATION_PATH

    Sostituisci quanto segue:

    • ARCHIVE_NAME: il nome dell'archivio da creare. Ad esempio, app.tar.gz.
    • APPLICATION_PATH: la posizione dell'applicazione nel file system locale. Ad esempio, ~/my-application. Per archiviare la directory di lavoro corrente, imposta questo valore su *.

  3. Carica l'archivio dell'applicazione su Cloud Storage:

    gcloud storage cp ARCHIVE_NAME gs://BUCKET_NAME

    Sostituisci quanto segue:

    • ARCHIVE_NAME: il percorso locale dell'archivio creato in precedenza. Ad esempio, app.tar.gz.
    • BUCKET_NAME: il nome del bucket che hai creato in precedenza. Ad esempio, my-bucket.

  4. Crea un nuovo file service.yaml con i seguenti contenuti:

    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

    Sostituisci quanto segue:

    • SERVICE_NAME: il nome del tuo servizio Cloud Run. I nomi dei servizi devono contenere al massimo 49 caratteri e devono essere univoci per regione e progetto.
    • BUCKET_NAME: il nome del bucket che hai creato in precedenza. Ad esempio, my-bucket.
    • ARCHIVE_NAME: il percorso locale dell'archivio creato in precedenza. Ad esempio, app.tar.gz.
    • BASE_IMAGE: l'immagine di base del runtime che vuoi utilizzare per la tua applicazione. Ad esempio, us-central1-docker.pkg.dev/serverless-runtimes/google-24-full/runtimes/nodejs24.
    • COMMAND: il comando con cui deve avviarsi il container.
    • ARG1: l'argomento che stai inviando al comando del container. Se utilizzi più argomenti, specifica ciascuno su una riga separata, ad esempio come mostrato, ARG-N.

  5. Esegui il deployment del nuovo servizio:

    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

Esempi di deployment dal codice sorgente senza build

Questa sezione mostra esempi di deployment dall'origine senza utilizzare la build.

Node.js

Crea un servizio Node.js:

  1. Crea una nuova directory denominata helloworld e cambia directory in questa directory:

    mkdir helloworld
cd helloworld

  2. Crea un file package.json con i seguenti contenuti:

    {
  "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. Nella stessa directory, crea un file index.js e copia al suo interno le seguenti righe:

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

    Questo codice crea un server web di base in ascolto sulla porta definita dalla variabile di ambiente PORT.

  4. Nella directory helloworld, esegui questo comando per installare le dipendenze del servizio localmente:

    npm install

  5. Nella directory helloworld, esegui il deployment del servizio utilizzando il flag --no-build, che indica al comando deploy di ignorare il passaggio di Cloud Build:

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

    Sostituisci quanto segue:

    • REGION: la regione in cui è stato eseguito il deployment del servizio.

Python

Crea un servizio Python:

  1. Crea una nuova directory denominata helloworld e cambia directory in questa directory:

    mkdir helloworld
cd helloworld

  2. Crea un file denominato main.py e incolla il seguente codice:

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

    Questo codice risponde alle richieste con il nostro saluto "Hello World". La gestione HTTP viene eseguita da un server web Gunicorn nel contenitore. Quando viene richiamato direttamente per l'utilizzo in locale, questo codice crea un server web di base che rimane in ascolto tramite la porta definita dalla variabile di ambiente PORT.

  3. Crea un file denominato requirements.txt e incolla il seguente codice:

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

    Questo codice aggiunge i pacchetti necessari per l'esempio.

  4. Esegui il vendoring delle dipendenze:

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

  5. Esegui il deployment del servizio utilizzando gcloud CLI. Il flag --no-build indica al comando deploy di ignorare il passaggio di 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

Sostituisci REGION con la regione in cui è stato eseguito il deployment del servizio.

Risoluzione dei problemi

Questa sezione fornisce alcuni suggerimenti per la risoluzione dei problemi relativi al deployment dall'origine senza utilizzare la build.

Sviluppo locale

Il deployment dal codice sorgente senza utilizzare la build funziona in modo simile al montaggio del codice o dell'eseguibile sull'immagine di base.

Ad esempio:

  1. Crea una copia di tutti i contenuti:

    cp -R python/hello-world/ workspace

  2. Esegui l'immagine di base come utente root con l'origine montata. Se necessario, puoi includere -p 8080:8080 se devi utilizzare curl da una macchina host.

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

    Sostituisci LOCAL_PATH con la posizione dei file di origine locali.

  3. Esegui il server:

    python main.py

Log esecuzione

Il log di esecuzione è utile per il debug dell'errore di deployment. Nella Google Cloud console, vai a Osservabilità > Log.

Autorizzazione negata per l'accesso a Cloud Storage

Se il tuo servizio Cloud Run riscontra errori "Autorizzazione negata" quando tenta di accedere agli oggetti Cloud Storage, devi concedere il ruolo roles/storage.objectViewer al account di servizio Cloud Run:

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

Sostituisci quanto segue:

  • PROJECT: il tuo ID progetto Google Cloud .
  • SERVICE_ACCOUNT: il account di servizio Cloud Run. Ad esempio, service-123@serverless-robot-staging.iam.gserviceaccount.com.

Automatizzare la creazione dal codice sorgente

Come best practice per evitare modifiche senza controllo della versione nell'origine locale, Google consiglia di eseguire il deployment automatico quando le modifiche vengono inviate al repository Git. Per semplificare questa operazione, puoi connettere e configurare il deployment continuo al tuo servizio Cloud Run. Se colleghi i tuoi repository GitHub a Cloud Run, puoi configurare le build ed eseguire il deployment dei repository senza scrivere Dockerfile o file di build.

Per configurare le build automatizzate, configura l'automazione come descritto nella pagina delle build continue, assicurandoti di scegliere l'opzione per la creazione di origini con i buildpack.

Passaggi successivi

Dopo aver eseguito il deployment di un servizio Cloud Run, puoi:

Scopri di più sulle configurazioni di deployment dell'origine:

Puoi automatizzare le build e i deployment dei tuoi servizi Cloud Run utilizzando i trigger di Cloud Build: