Esegui il deployment delle funzioni in Cloud Run

Questa pagina descrive come eseguire il deployment e modificare le funzioni in Cloud Run. Per un esempio di procedura dettagliata per il deployment di una funzione Hello World, consulta Eseguire il deployment di una funzione di esempio.

Dietro le quinte, i deployment delle funzioni Cloud Run utilizzano i buildpack e Cloud Build di Google Cloud per creare automaticamente le immagini dei container dal codice sorgente della funzione senza dover installare Docker sulla tua macchina o configurare i buildpack o Cloud Build.

Anche i deployment delle funzioni Cloud Run utilizzano Artifact Registry per archiviare gli elementi e gestire le immagini container. Artifact Registry crea automaticamente il repository cloud-run-source-deploy se il progetto non ne ha già creato uno con questo nome.

Prima di iniziare

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

  2. Abilita le API Artifact Registry, Cloud Build, Cloud Run Admin e Cloud Logging:

     gcloud services enable artifactregistry.googleapis.com \
     cloudbuild.googleapis.com \
     run.googleapis.com \
     logging.googleapis.com

    Se vuoi, abilita l'API Eventarc per utilizzare gli trigger di eventi:

     gcloud services enable eventarc.googleapis.com

  3. Se il tuo progetto è soggetto a un criterio dell'organizzazione che limita le invocazioni non autenticate, dovrai accedere al servizio di cui è stato eseguito il deployment come descritto in Testare i servizi privati.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per eseguire il deployment dei servizi Cloud Run dall'origine, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

Per un elenco dei ruoli e delle autorizzazioni IAM associati a Cloud Run, consulta Ruoli IAM di Cloud Run e Autorizzazioni IAM di Cloud Run. Se il servizio Cloud Run interagisce con le API Google Cloud, come le librerie client di Cloud, consulta la guida alla configurazione dell'identità del servizio. Per ulteriori informazioni sulla concessione dei ruoli, consulta le autorizzazioni di deployment e gestisci l'accesso.

Ruoli per l'account di servizio

  • Affinché Cloud Build possa compilare le tue origini, concedi il ruolo Account di servizio Cloud Build all'account di servizio predefinito di Compute Engine eseguendo quanto segue:

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

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

    La propagazione del ruolo dell'account di servizio Cloud Build all'account di servizio predefinito di Compute Engine richiede un paio di minuti.

    • Crea ed esegui il deployment di una funzione

    Puoi eseguire il deployment di una funzione utilizzando la console Google Cloud o la gcloud CLI. Fai clic sulla scheda per visualizzare le istruzioni sull'utilizzo dello strumento che preferisci.

    Console

    1. Nella console Google Cloud, vai alla pagina Cloud Run:

      Vai a Cloud Run

    2. Fai clic su Scrivi una funzione.

    3. Nel campo Nome servizio, inserisci un nome per descrivere la funzione. I nomi dei servizi devono iniziare solo con una lettera e contenere un massimo di 49 caratteri, inclusi lettere, numeri o trattini. I nomi dei servizi non possono terminare con trattini e devono essere univoci per regione e progetto. Il nome di un servizio non può essere modificato in un secondo momento ed è visibile pubblicamente.

    4. Nell'elenco Regione, utilizza il valore predefinito o seleziona la regione in cui vuoi eseguire il deployment della funzione.

    5. Nell'elenco Runtime, utilizza il valore predefinito o seleziona una versione del runtime.

    6. Se vuoi, nella sezione Attivati, fai clic su Aggiungi attivatore e seleziona un'opzione. Viene visualizzato il riquadro Trigger Eventarc, in cui puoi modificare i seguenti dettagli dell'attivatore:

      1. Nel campo Nome attivatore, inserisci un nome per l'attivatore o utilizza il nome predefinito.

      2. Seleziona un Tipo di attivatore dall'elenco per specificare uno dei seguenti tipi di attivatore:

        • Origini Google per specificare gli trigger per Pub/Sub, Cloud Storage, Firestore e altri fornitori di eventi Google.

        • Personalizzato per produrre e utilizzare eventi dal codice dell'applicazione. Segui le istruzioni nel riquadro Trigger Eventarc per creare un canale. Un canale è una risorsa utilizzata come pipeline per inviare eventi personalizzati dai produttori ai consumatori. Gli eventi personalizzati vengono pubblicati in un canale e un trigger Eventarc si iscrive a questi eventi.

        • Di terze parti per l'integrazione con fornitori non Google che offrono un'origine Eventarc. Per ulteriori informazioni, consulta Eventi di terze parti in Eventarc.

      3. Seleziona un Fornitore di eventi dall'elenco per selezionare un prodotto che fornisca il tipo di evento per attivare la funzione. Per l'elenco dei fornitori di eventi, consulta Fornitori e destinazioni di eventi.

      4. Seleziona un Tipo di evento dall'elenco. La configurazione dell'attivatore varia a seconda del tipo di evento supportato. Per saperne di più, consulta Tipi di eventi.

      5. Nel campo Regione, seleziona una località per l'attivatore Eventarc. In generale, la posizione di un trigger Eventarc deve corrispondere alla posizione della risorsa Google Cloud per la quale vuoi monitorare gli eventi. Nella maggior parte degli scenari, devi anche eseguire il deployment della funzione nella stessa regione. Consulta la sezione Informazioni sulle località Eventarc per ulteriori dettagli sulle località dei trigger Eventarc.

      6. Nel campo Account di servizio, seleziona un account di servizio. Gli attivatori Eventarc sono collegati agli account di servizio da usare come identità quando viene invocata la funzione. L'account di servizio dell'attivatore Eventarc deve disporre dell'autorizzazione per richiamare la funzione. Per impostazione predefinita, Cloud Run utilizza l'account di servizio predefinito di Compute Engine.

      7. Se vuoi, specifica il percorso dell'URL del servizio a cui inviare la richiesta in arrivo. Si tratta del percorso relativo nel servizio di destinazione a cui devono essere inviati gli eventi per l'attivatore. Ad esempio: /, /route, route e route/subroute.

      8. Dopo aver compilato i campi obbligatori, fai clic su Salva trigger.

    7. In Autenticazione, configura quanto segue:

      • Se stai creando una funzione HTTP pubblica, ad esempio un webhook, seleziona Consenti chiamate non autenticate. Se selezioni questa opzione, viene assegnato il ruolo Invoker IAM all'identificatore speciale allUser. Puoi utilizzare IAM per modificare questa impostazione in un secondo momento dopo aver creato il servizio. Se non disponi delle autorizzazioni (ruolo Amministratore di Cloud Run) per selezionarlo, il servizio verrà disegnato e richiederà l'autenticazione.

      • Se stai creando una funzione attivata da evento, seleziona Richiedi autenticazione.

    8. Se vuoi, aggiorna le seguenti configurazioni aggiuntive per le funzioni:

      1. Imposta Allocazione e prezzi della CPU in base alle tue esigenze.

      2. In Scalabilità automatica del servizio, specifica le istanze minime come necessario.

      3. Imposta le impostazioni di Controllo ingressi in base alle tue esigenze.

      4. Espandi la sezione Container, volumi, networking, sicurezza per impostare altre impostazioni facoltative nelle schede appropriate:

    9. Fai clic su Crea e attendi che Cloud Run crei il servizio utilizzando una revisione segnaposto.

    10. La console ti reindirizzerà alla scheda Origine, dove potrai visualizzare il codice sorgente della funzione. Fai clic su Salva e ridistribuisci.

    11. Nella scheda Origine, se vuoi, puoi fare clic su Mostra payload per visualizzare un payload di esempio degli eventi in entrata.

    12. Dopo il deployment, testa la funzione creata facendo clic sul pulsante Testa.

    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. Aggiorna i componenti di gcloud alla versione più recente:

      gcloud components update

    3. Esegui il seguente comando nella directory che contiene il codice campione:

      gcloud beta run deploy FUNCTION \
       --source . \
       --function FUNCTION_ENTRYPOINT \
       --base-image BASE_IMAGE \
       --region REGION

      Sostituisci:

      • FUNCTION con il nome della funzione di cui stai eseguendo il deployment. Puoi omettere del tutto questo parametro, ma se lo fai ti verrà chiesto il nome.

      • FUNCTION_ENTRYPOINT con il punto di ingresso della funzione nel codice sorgente. Questo è il codice che Cloud Run esegue quando viene eseguita la funzione. Il valore di questo flag deve essere un nome di funzione o un nome di classe completamente qualificato esistente nel codice sorgente.

      • BASE_IMAGE con l'ambiente dell'immagine di base per la funzione. Per ulteriori dettagli sulle immagini di base e sui pacchetti inclusi in ogni immagine, consulta Immagini di base dei runtime.

      • REGION con la regione Google Cloud in cui vuoi eseguire il deployment della funzione. Ad esempio: us-central1.

      Facoltativamente,

      • Se stai creando una funzione HTTP pubblica, ad esempio un webhook, specifica il flag --allow-unauthenticated. Questo flag assegna il ruolo Invoker IAM di Cloud Run all'identificatore specialeallUser. Puoi utilizzare IAM per modificare questa impostazione in un secondo momento dopo aver creato il servizio. Se stai creando un servizio autenticato o una funzione attivata da eventi, puoi omettere questo flag.

    Facoltativamente, dopo aver eseguito il deployment della funzione, puoi aggiungere attivatori Eventarc. Per aggiungere un attivatore, esegui il seguente 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

    Sostituisci:

    • EVENTARC_TRIGGER_NAME con il nome dell'attivatore Eventarc.

    • EVENTARC_TRIGGER_LOCATION con la posizione per l'attivatore Eventarc. In generale, la posizione di un trigger Eventarc deve corrispondere alla posizione della risorsa Google Cloud per la quale vuoi monitorare gli eventi. Nella maggior parte degli scenari, devi anche eseguire il deployment della funzione nella stessa regione. Consulta la sezione Informazioni sulle località Eventarc per ulteriori dettagli sulle località dei trigger Eventarc.

    • FUNCTION con il nome della funzione di cui è stato eseguito il deployment.

    • REGION con la regione Cloud Run della funzione.

    • EVENTARC_FILTER_TYPE con i filtri evento monitorati dall'attivatore. Un evento che corrisponde a tutti i filtri --event-filters attiva le chiamate alla funzione. Ogni attivatore deve avere un tipo di evento supportato nel formato --event-filters="type=EVENTARC_FILTER_TYPE". Questo tipo di evento non può essere modificato dopo la creazione. Per modificareEVENT_FILTER_TYPE, crea un nuovo attivatore ed elimina quello precedente. Se vuoi, puoi ripetere il flag --event-filters con un filtro supportato nel formato ATTRIBUTE=VALUE per aggiungere altri filtri.

    • EVENTARC_TRIGGER_SERVICE_ACCOUNT con un account di servizio. Gli attivatori Eventarc sono collegati agli account di servizio da usare come identità quando viene invocata la funzione. L'account di servizio dell'attivatore Eventarc deve disporre dell'autorizzazione per richiamare la funzione. Per impostazione predefinita, Cloud Run utilizza l'account di servizio Compute predefinito.

    Terraform

    Per gestire le funzioni utilizzando Terraform, devi compilare il codice della funzione in un'immagine container, quindi definire il servizio Cloud Run in una configurazione Terraform utilizzando la risorsa google_cloud_run_v2_service del provider Google Cloud.

    1. Segui le istruzioni per la creazione di una funzione per creare un'immagine container. Copia il percorso completo dell'immagine container per la variabile IMAGE_URL utilizzata nel passaggio successivo.

    2. Crea un nuovo file main.tf con i seguenti contenuti:

      provider "google" {
  project = "PROJECT-ID"
}

resource "google_cloud_run_v2_service" "default" {
  name     = "SERVICE"
  location = "REGION"
  client   = "terraform"
  template {
    containers {
      image = "IMAGE_URL"
    }
  }
}

resource "google_cloud_run_v2_service_iam_member" "noauth" {
  location = google_cloud_run_v2_service.default.location
  name     = google_cloud_run_v2_service.default.name
  role     = "roles/run.invoker"
  member   = "allUsers"
}

      Sostituisci:

      • PROJECT-ID con l'ID progetto Google Cloud.
      • REGION con la regione Google Cloud.
      • SERVICE con il nome del servizio Cloud Run. I nomi dei servizi devono avere una lunghezza massima di 49 caratteri e devono essere univoci per regione e progetto.
      • IMAGE_URL con un riferimento all'immagine del container, ad esempio us-docker.pkg.dev/cloudrun/container/hello:latest. Se utilizzi Artifact Registry, il repository REPO_NAME deve essere già stato creato. L'URL ha la forma LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

      Questa configurazione consente l'accesso pubblico (l'equivalente di --allow-unauthenticated). Per rendere privato il servizio, rimuovi la stanza google_cloud_run_v2_service_iam_member.

    3. Inizializza Terraform:

      terraform init

    4. Applica la configurazione Terraform:

      terraform apply

      Conferma di voler applicare le azioni descritte inserendo yes.

    Località Cloud Run

    Cloud Run è un servizio a livello di regione, il che significa che l'infrastruttura che gestisce i tuoi servizi Cloud Run si trova in una regione specifica ed è gestita da Google in modo da essere disponibile in modo ridondante in tutte le zone all'interno della regione.

    Soddisfare i requisiti di latenza, disponibilità o durabilità è uno dei fattori principali per selezionare la regione in cui vengono eseguiti i servizi Cloud Run. In genere puoi selezionare la regione più vicina ai tuoi utenti, ma devi prendere in considerazione la posizione degli altri prodotti Google Cloud utilizzati dal servizio Cloud Run. L'utilizzo combinato dei prodotti Google Cloud in più località può influire sulla latenza e sul costo del servizio.

    Cloud Run è disponibile nelle seguenti regioni:

    Soggetto ai prezzi di Livello 1

    Soggetto ai prezzi di Livello 2

    • africa-south1 (Johannesburg)
    • asia-east2 (Hong Kong)
    • asia-northeast3 (Seul, Corea del Sud)
    • asia-southeast1 (Singapore)
    • asia-southeast2 (Giacarta)
    • asia-south2 (Delhi, India)
    • australia-southeast1 (Sydney)
    • australia-southeast2 (Melbourne)
    • europe-central2 (Varsavia, Polonia)
    • europe-west10 (Berlino) icona foglia Bassi livelli di CO2
    • europe-west12 (Torino)
    • europe-west2 (Londra, Regno Unito) icona foglia Bassi livelli di CO2
    • europe-west3 (Francoforte, Germania) icona foglia Bassi livelli di CO2
    • europe-west6 (Zurigo, Svizzera) icona foglia Bassi livelli di CO2
    • me-central1 (Doha)
    • me-central2 (Dammam)
    • northamerica-northeast1 (Montreal) icona foglia Bassi livelli di CO2
    • northamerica-northeast2 (Toronto) icona foglia Bassi livelli di CO2
    • southamerica-east1 (San Paolo, Brasile) icona foglia Bassi livelli di CO2
    • southamerica-west1 (Santiago, Cile) icona foglia Bassi livelli di CO2
    • us-west2 (Los Angeles)
    • us-west3 (Salt Lake City)
    • us-west4 (Las Vegas)

    Se hai già creato un servizio Cloud Run, puoi visualizzare la regione nella dashboard di Cloud Run nella console Google Cloud.

    Attivare i tentativi di ripetizione degli eventi

    Eventarc utilizza Pub/Sub come livello di trasporto e ha un criterio di ripetizione predefinito che potrebbe non funzionare bene per la tua funzione.

    Dopo aver creato un trigger Eventarc, ti consigliamo vivamente di aggiornare le norme di ripetizione in Eventarc e di configurare l'argomento per le email inutilizzate in Pub/Sub.

    Modificare una funzione esistente

    Puoi modificare la configurazione o il codice della funzione:

    Modifica configurazione

    Per modificare i parametri di configurazione, come l'allocazione della CPU, la memoria e la connettività VPC:

    Console

    1. Nella console Google Cloud, vai alla pagina Cloud Run:

      Vai a Cloud Run

    2. Individua il servizio che vuoi aggiornare nell'elenco dei servizi e fai clic per aprire i relativi dettagli.

    3. Fai clic su Modifica ed esegui il deployment di una nuova revisione per visualizzare il modulo di deployment della revisione.

    4. Modificare qualsiasi impostazione di configurazione.

    5. Fai clic su Esegui il deployment e attendi il completamento del deployment.

    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. Per aggiornare una o più impostazioni di configurazione del servizio, utilizza il comando gcloud beta run services update SERVICE con i flag della riga di comando della configurazione che vuoi aggiornare. Sostituisci SERVICE con il nome del servizio.

    Esegui nuovamente il deployment del nuovo codice sorgente

    Puoi modificare l'immagine di base, il runtime e il codice sorgente della funzione utilizzando la console Google Cloud o gCloud CLI.

    Fai clic sulla scheda per le istruzioni relative allo strumento che preferisci.

    Console

    1. Nella console Google Cloud, vai alla pagina Cloud Run:

      Vai a Cloud Run

    2. Individua la funzione che vuoi aggiornare nell'elenco Servizi e fai clic per aprire i dettagli della funzione.

    3. Vai alla scheda Origine e fai clic su Modifica origine.

    4. Fai clic su Modifica aggiornamenti di runtime e sicurezza accanto a Immagine di base, seleziona un Runtime o un Ambiente diverso dall'elenco in base alle esigenze e fai clic su Salva.

    5. Modifica l'entry point della funzione in base alle esigenze.

    6. Nella sezione File, seleziona Aggiungi file per creare un nuovo file, Rinomina file per rinominare un file o Elimina file per eliminare un file.

    7. Nella sezione Codice, modifica il codice sorgente in base alle tue esigenze.

    8. Fai clic su Salva e esegui nuovamente il deployment e attendi il completamento del deployment.

    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. Esegui il seguente comando nella directory che contiene il codice sorgente della funzione:

      gcloud beta run deploy FUNCTION \
       --source . \
       --function FUNCTION_ENTRYPOINT \
       --base-image BASE_IMAGE \
       --region REGION

      Sostituisci:

      • FUNCTION con il nome della funzione da modificare.

      • FUNCTION_ENTRYPOINT con il punto di ingresso della funzione nel codice sorgente.

      • BASE_IMAGE con l'ambiente dell'immagine di base per la funzione. Nella maggior parte dei casi, puoi specificare l'ID runtime, ad esempio nodejs22.

        In alternativa, se vuoi utilizzare un pacchetto di sistema specifico nello stack o specificare la regione da cui viene scaricata l'immagine di base, puoi specificare una delle seguenti opzioni:

        • Il percorso completo dell'immagine di base, ad esempio us-central1-docker.pkg.dev/serverless-runtimes/google-22-full/runtimes/nodejs22. Questa opzione ti consente di specificare l'immagine di base, un pacchetto di sistema specifico nello stack e la regione da cui viene scaricata l'immagine di base.
        • L'alias del percorso completo dell'immagine di base, ad esempio google-22/nodejs22 o google-22-full/nodejs22. Questa opzione di alias più breve consente di specificare l'immagine di base e un pacchetto di sistema specifico nello stack.

        Per maggiori dettagli sulle immagini di base e sui pacchetti inclusi in ogni immagine, vedi Immagini di base del runtime.

      • REGION con la regione Google Cloud in cui vuoi eseguire il deployment della funzione. Ad esempio: us-central1.

      Flag facoltativi

      Puoi configurare i seguenti flag facoltativi durante la modifica della funzione:

      • Variabili di ambiente di build flag per specificare le variabili di ambiente durante il passaggio di compilazione, ad esempio per configurare parametri o certificati specifici per il momento di compilazione.

      • Indicatori Pool di worker per specificare il pool di worker da utilizzare nel contesto di build protetto di Controlli di servizio VPC.

      • Account di servizio di compilazione personalizzati indicano la possibilità di specificare un'alternativa all'account di servizio di compilazione predefinito per una maggiore sicurezza.

      • Aggiornamenti automatici delle immagini di base per disattivare gli aggiornamenti automatici. Per impostazione predefinita, gli aggiornamenti della sicurezza automatici sono abilitati per le funzioni.

    Passaggi successivi

    Dopo aver eseguito il deployment di una nuova funzione, puoi: