Panoramica del processo di compilazione

Questa guida mostra la panoramica del processo di compilazione per le funzioni di cui è stato eseguito il deployment utilizzando il comando gcloud functions. Per informazioni sulla processo di compilazione per le funzioni di cui è stato eseguito il deployment utilizzando il comando gcloud run, consulta:

Quando esegui il deployment del codice sorgente della funzione utilizzando il comando gcloud functions deploy, il codice sorgente viene archiviato in un bucket Cloud Storage. Cloud Build quindi compila automaticamente il codice in un'immagine container ed esegue il push dell'immagine in un registry di immagini.

Il processo di creazione dell'immagine è completamente automatico e non richiede alcun input diretto da parte tua. Tutte le risorse utilizzate nel processo di compilazione vengono eseguite nel tuo progetto utente.

L'esecuzione del processo di compilazione all'interno del progetto comporta quanto segue:

  • Hai accesso diretto a tutti i log di compilazione.

  • Non è presente una quota preimpostata per il momento di compilazione, anche se Cloud Build ha la propria quota di concorrenza predefinita.

  • Puoi visualizzare l'immagine container corrente e quelle di cui è stato eseguito il deployment in precedenza, entrambe archiviate in Artifact Registry.

  • Cloud Storage viene utilizzato nel progetto per archiviare la directory del codice sorgente per le funzioni. Tieni presente quanto segue:

    • Se crei una funzione utilizzando Google Cloud CLI, viene creato un bucket di caricamento per contenere il codice sorgente. Questo bucket di caricamento si chiama gcf-v2-uploads-PROJECT_NUMBER-REGION.cloudfunctions.appspot.com.
    • Dopo il caricamento, il codice della funzione viene archiviato in un bucket di origine separato:
      • Se utilizzi la crittografia predefinita, questo bucket si chiama gcf-v2-sources-PROJECT_NUMBER-REGION.
      • Se proteggi i tuoi dati con CMEK, il bucket si chiama gcf-v2-sources-PROJECT_NUMBER-REGION-CMEK_KEY_HASH.
    • Sia i bucket di origine che quelli di caricamento non hanno un periodo di conservazione.

Caratteristiche del processo di compilazione

Il processo di compilazione presenta le seguenti caratteristiche:

  • L'API Cloud Build deve essere abilitata per il tuo progetto.

    Per attivare l'API manualmente, fai clic sul link precedente, seleziona il tuo progetto dal menu a discesa e segui le istruzioni per attivare l'interfaccia utente.

  • Poiché l'intero processo di compilazione avviene nel contesto del progetto, il progetto è soggetto ai prezzi delle risorse incluse:

    • Per i prezzi di Cloud Build, consulta la pagina Prezzi. Questo processo utilizza le dimensioni dell'istanza predefinite di Cloud Build, poiché queste istanze sono preriscaldate e sono disponibili più rapidamente. Cloud Build offre un livello gratuito: consulta il documento relativo ai prezzi per ulteriori dettagli.

    • Per informazioni sui prezzi di Cloud Storage, consulta la pagina Prezzi. Cloud Storage offre un livello gratuito: consulta il documento relativo ai prezzi per ulteriori dettagli.

    • Per i prezzi di Artifact Registry, consulta la pagina Prezzi.

  • Poiché il processo di compilazione è soggetto alla fatturazione, al progetto deve essere associato un account di fatturazione Cloud.

Visualizza i log delle immagini di build

Un vantaggio principale dell'avere il processo di creazione dell'immagine nel progetto utente è l'accesso ai log di compilazione. Puoi utilizzare gcloud CLI o la Google Cloud console per accedere ai log, che sono disponibili tramite Cloud Logging.

gcloud

  1. Esegui il deployment della funzione utilizzando il gcloud functions deploy comando.

  2. L'URL dei log viene visualizzato nella risposta nella finestra del terminale. Ad esempio:

    Deploying function (may take a while - up to 2 minutes)...⠹
**For Cloud Build Stackdriver Logs**, visit:
https://console.cloud.google.com/logs/viewer?project=&advancedFilter=resource.type%
3Dbuild%0Aresource.labels.build_id%3D38d5b662-2315-45dd-8aa2-
380d50d4f5e8%0AlogName%3Dprojects%2F%
2Flogs%2Fcloudbuild
Deploying function (may take a while - up to 2 minutes)...done.

Google Cloud console

Per visualizzare i log delle funzioni nella pagina Cloud Run:

  1. Vai a Cloud Run

  2. Fai clic sulla funzione scelta nell'elenco visualizzato.

  3. Fai clic sulla scheda LOG per visualizzare i log della richiesta e del contenitore per tutte le revisioni di questa funzione. Puoi filtrare in base al livello di gravità dei log.

Registry delle immagini

Artifact Registry viene utilizzato per archiviare le immagini create dal codice sorgente della funzione. Le immagini vengono archiviate in un repository chiamato REGION-docker.pkg.dev/PROJECT_ID/gcf-artifacts nello stesso progetto in cui è creata la funzione.

Per specificare un repository Artifact Registry autogestito, esegui il seguente comando:

gcloud functions deploy FUNCTION_NAME \
   --docker-repository=REPOSITORY \
   [FLAGS...]

Sostituisci quanto segue:

  • FUNCTION_NAME: il nome della funzione.
  • REPOSITORY: il nome del repository Artifact Registry completamente qualificato, nel seguente formato:projects/PROJECT_NAME/locations/LOCATION/repositories/REPOSITORY.

Quando specifichi un repository Artifact Registry in un progetto o una regione diversa, potresti dover prendere in considerazione configurazioni aggiuntive:

Configurazioni IAM:

  • Configurazioni IAM: assicurati che l'account di servizio di compilazione abbia accesso autorizzato in lettura e scrittura a REPOSITORY.
  • Configurazioni di rete: assicurati che la destinazione REPOSITORY sia accessibile dalla configurazione del progetto attuale.
  • Configurazioni dei Controlli di servizio VPC: assicurati che l'account di servizio di compilazione possa raggiungere la destinazione REPOSITORY all'interno del perimetro VPC-SC.
  • Limitazioni della residenza dei dati: la specifica di un REPOSITORY in una regione diversa da quella in cui si trova la funzione comporterà il trasferimento dei dati tra regioni.

Proteggi la tua build con i pool privati

Per consentire alle funzioni di utilizzare le dipendenze (ad esempio i pacchetti npm), per impostazione predefinita Cloud Build ha accesso a internet illimitato durante il processo di compilazione. Se hai configurato un perimetro Controlli di servizio VPC (VPC SC) e vuoi limitare l'accesso della compilazione solo alle dipendenze memorizzate all'interno del perimetro, puoi utilizzare la funzionalità Pool di worker privati di Cloud Build.

In generale, segui questi passaggi per configurare il tuo pool privato:

  1. Crea il tuo pool di worker privato. Consulta l'articolo Creare e gestire i pool privati.

  2. Configura il perimetro dei Controlli di servizio VPC. Consulta Utilizzo dei Controlli di servizio VPC.

  3. Se il pool di worker privato si trova in un progetto diverso dalla funzione, devi concedere all'account di servizio agente di servizio Cloud Functions (service-FUNCTION_PROJECT_NUMBER@gcf-admin-robot.iam.gserviceaccount.com) il ruolo cloudbuild.workerPoolUser in modo che il servizio Cloud Build possa accedere al pool di worker.

    gcloud projects add-iam-policy-binding PRIVATE_POOL_PROJECT_ID \
    --member serviceAccount:service-FUNCTION_PROJECT_NUMBER@gcf-admin-robot.iam.gserviceaccount.com
    --role roles/cloudbuild.workerPoolUser

    Sostituisci FUNCTION_PROJECT_NUMBER con il numero del progetto in cui viene eseguita la funzione e PRIVATE_POOL_PROJECT_ID con l'ID del progetto in cui si trova il pool di worker. Per ulteriori informazioni, consulta Eseguire le build in un pool privato.

  4. Esegui il deployment della funzione da compilare utilizzando un pool privato:

    gcloud functions deploy FUNCTION_NAME \
   --runtime RUNTIME \
   --build-worker-pool PRIVATE_POOL_NAME
   [FLAGS...]

    Sostituisci FUNCTION_NAME con il nome della funzione, RUNTIME con il runtime in uso e PRIVATE_POOL_NAME con il nome del pool.

Per interrompere l'utilizzo di un determinato pool privato e utilizzare il pool Cloud Build predefinito, utilizza il flag --clear-build-worker-pool al momento del nuovo deployment.

gcloud functions deploy FUNCTION_NAME \
   --runtime RUNTIME \
   --clear-build-worker-pool
   [FLAGS...]

Sostituisci FUNCTION_NAME con il nome della funzione e RUNTIME con il runtime in uso.

Proteggi la tua build con un account di servizio personalizzato

Il codice sorgente della funzione viene inviato a Cloud Build per essere conteggiata. La funzione containerizzata viene archiviata in Artifact Registry ed eseguita in Cloud Run come servizio. Le funzioni Cloud Run sfruttano Cloud Build per la creazione e il deployment delle funzioni Cloud Run. Per impostazione predefinita, le funzioni Cloud Run utilizzano l'account di servizio Cloud Build predefinito come principale durante l'esecuzione della compilazione. A partire da luglio 2024, Cloud Build ha modificato il comportamento predefinito per l'utilizzo degli account di servizio nei nuovi progetti. A seguito di questa modifica, i nuovi progetti che eseguono il deployment di funzioni per la prima volta potrebbero utilizzare un account di servizio Cloud Build predefinito con autorizzazioni insufficienti per la creazione di una funzione.

Per i Google Cloud progetti creati prima di luglio 2024, Cloud Build utilizza l'account di servizio Cloud Build precedente. Questo account di servizio è stato progettato per aiutare gli utenti a eseguire un'ampia gamma di casi d'uso che potrebbero essere troppo permissivi per le esigenze del tuo progetto. Se vuoi spostare i progetti esistenti da questo account di servizio, puoi seguire questi passaggi per proteggere ulteriormente l'ambiente di compilazione delle funzioni:

Impedire l'utilizzo del account di servizio Cloud Build legacy per la compilazione

Puoi verificare che il tuo progetto utilizzi l'account di servizio Cloud Build precedente esaminando i dettagli della build della funzione. L'account di servizio di compilazione predefinito ha il seguente formato:

PROJECT_NUMBER@cloudbuild.gserviceaccount.com.

Puoi disattivare forzatamente l'utilizzo di questo account di servizio impostando il vincolo del criterio dell'organizzazione cloudbuild.useBuildServiceAccount su Not Enforced. In alternativa, la rimozione di tutte le concessioni di ruolo limiterà la sua capacità di accedere Google Cloud alle risorse.

Impedire l'utilizzo dell'account di servizio Compute predefinito per la compilazione

L'account di servizio Compute predefinito ha il formatoPROJECT_NUMBER-compute@developer.gserviceaccount.com. Puoi disattivare l'impostazione predefinita utilizzata per la compilazione impostando il criterio dell'organizzazione cloudbuild.useComputeServiceAccount su Not Enforced. In alternativa, la disattivazione di questo account di servizio ne impedisce l'utilizzo per accedere alle risorse Google Cloud .

Fornisci un account di servizio per la creazione di funzioni

Nell'ambito della configurazione di una funzione, puoi specificare un account di servizio di compilazione quando esegui il deployment della funzione. Quando non è possibile utilizzare l'account di servizio Cloud Build legacy e l'account di servizio Compute predefinito per la compilazione, devi specificare un account di servizio di compilazione per eseguire il deployment di una funzione, come descritto in questa sezione.

Se le modifiche descritte in Modifica dell'account di servizio Cloud Build ti interessano, puoi procedere nel seguente modo:

  • Consulta le indicazioni di Cloud Build sulle modifiche all'account di servizio predefinito e disattiva queste modifiche.

  • Aggiungi il ruolo Account Cloud Build (roles/cloudbuild.builds.builder) all'account di servizio Compute Engine predefinito.

  • Crea un account di servizio Cloud Build personalizzato per i deployment delle funzioni.

Ecco alcuni scenari in cui potresti voler fornire un account di servizio diverso da utilizzare quando Cloud Build esegue la compilazione della funzione:

  • Vuoi un maggiore controllo sugli account di servizio da aggiungere al perimetro VPC-SC.

  • Vuoi che Cloud Build venga eseguito con autorizzazioni diverse da quelle dell'account di servizio predefinito senza dover revocare ogni autorizzazione singolarmente.

  • Vuoi impostare autorizzazioni granulari di Cloud Build specificamente per le tue funzioni e non condividere un account di servizio Cloud Build ottimizzato per altri scopi.

  • La tua organizzazione ha disattivato l'utilizzo dell'account di servizio predefinito.

Le seguenti sezioni mostrano come creare un account di servizio Cloud Build personalizzato per i deployment delle funzioni.

Crea un account di servizio

Crea un nuovo account di servizio come descritto in Creare un account di servizio.

Concedi autorizzazioni

L'account di servizio che utilizzi avrà bisogno dei seguenti ruoli:

  • roles/logging.logWriter: obbligatoria per archiviare i log di compilazione in Cloud Logging.
  • roles/artifactregistry.writer: obbligatorio per archiviare le immagini di build in Artifact Registry. Per il comportamento predefinito, l'account di servizio deve avere accesso ai repository denominati "gcf-artifacts" e "cloud-run-source-deploy". L'accesso ai repository può essere impostato nel criterio IAM del repository. In alternativa, puoi fornire il tuo repository di elementi tramite il campo dockerRepository.
  • roles/storage.objectViewer: obbligatoria per recuperare il codice sorgente della funzione dal bucket Cloud Storage e per archiviare le immagini di compilazione in Container Registry. Per il comportamento predefinito, l'account di servizio deve avere accesso ai bucket denominati "run-sources-*", "gcf-v2-sources-*" e "gcf-v2-uploads-*". Questo può essere ottenuto aggiungendo una condizione IAM alla concessione del ruolo, ad esempio (resource.type == "storage.googleapis.com/Object" && (resource.name.startsWith("projects/_/buckets/gcf-v2-sources-") || resource.name.startsWith("projects/_/buckets/gcf-v2-uploads-") || resource.name.startsWith("projects/_/buckets/run-sources-")))

Concedi i seguenti ruoli utilizzando Google Cloud CLI o la Google Cloud console.

gcloud projects add-iam-policy-binding PROJECT_ID \
--member=serviceAccount:SA_EMAIL \
    --role=roles/logging.logWriter

gcloud projects add-iam-policy-binding PROJECT_ID \
--member=serviceAccount:SA_EMAIL \
--role=roles/artifactregistry.writer

gcloud projects add-iam-policy-binding PROJECT_ID \
--member=serviceAccount:SA_EMAIL \
--role=roles/storage.objectViewer

Sostituisci quanto segue:

Considerazioni sui Controlli di servizio VPC

Se disponi di un perimetro Controlli di servizio VPC che protegge sia il progetto sia l'API Cloud Run Functions e se utilizzi l'account di servizio predefinito di Compute Engine come ruolo Account di servizio Cloud Build per le funzioni Cloud Run, devi creare le seguenti regole in entrata:

  • Consenti l'accesso dell'account di servizio predefinito di Compute Engine a tutti i metodi delle API Cloud Storage e Cloud Logging.
  • Consenti all'account di servizio service-[PROJECT_NUMBER]@gcf-admin-robot.iam.gserviceaccount.com di accedere a tutti i metodi delle API Cloud Storage e Cloud Logging.

Esegui il deployment di una funzione con un account di servizio personalizzato

Per passare un account di servizio creato dall'utente, da utilizzare da Cloud Build, durante il deployment della funzione, esegui il seguente comando gcloud:

  • Il flag --build-service-account specifica un account di servizio IAM le cui credenziali verranno utilizzate per il passaggio di compilazione. Se non viene fornito un account di servizio personalizzato, la funzione utilizza l'account di servizio predefinito del progetto per Cloud Build.
  • Se vuoi, puoi utilizzare un pool privato, che specifichi utilizzando il flag --build-worker-pool.

gcloud functions deploy FUNCTION_NAME \
   --gen2 \
   --region=REGION \
   --project=PROJECT_ID \
   --runtime=RUNTIME \
   --entry-point=CODE_ENTRYPOINT \
   --build-service-account=projects/PROJECT_ID/serviceAccounts/SA_EMAIL \
   --memory=256Mi \
   --trigger-http \
   --source=.

Sostituisci quanto segue:

Concedi all'account di servizio Cloud Build l'accesso al perimetro dei Controlli di servizio VPC

Le funzioni Cloud Run utilizzano Cloud Build per compilare il codice sorgente in un contenitore eseguibile. Per utilizzare le funzioni Cloud Run con Controlli di servizio VPC, devi configurare l'account di servizio Cloud Build (predefinito o personalizzato) in modo che abbia accesso al perimetro del servizio.

Trova il nome dell'account di servizio

Se utilizzi l'account di servizio Cloud Build predefinito, puoi trovarne il nome come segue:

  1. Utilizza la pagina IAM nella Google Cloud console per trovare l'account di servizio Cloud Build.

    Apri IAM

  2. Assicurati che nel menu a discesa del progetto sia visualizzato il progetto corretto.

  3. Cerca cloudbuild.gserviceaccount.com. L'indirizzo email nel moduloPROJECT_NUMBER@cloudbuild.gserviceaccount.com è il nome dell'account di servizio.

Se hai un account di servizio Cloud Build personalizzato, utilizza questo nome.

Concedi all'account di servizio l'accesso al perimetro di servizio

Una volta ottenuto il nome dell'account di servizio, segui la guida Limitare l'accesso in base all'utente o all'account di servizio per creare un livello di accesso per l'account di servizio. Quindi, segui la procedura per aggiungere un livello di accesso a un perimetro esistente per aggiungere il livello di accesso al perimetro di servizio.