Automatizzare le build in risposta a eventi Pub/Sub

1ª gen. 2ª gen.

I trigger Pub/Sub di Cloud Build ti consentono di eseguire build in risposta a eventi pubblicati tramite Pub/Sub. Google Cloud Puoi utilizzare le informazioni di un evento Pub/Sub per parametrizzare la build e decidere se deve essere eseguita in risposta all'evento. I trigger Pub/Sub possono essere configurati per ascoltare qualsiasi argomento Pub/Sub.

Questa pagina spiega come creare un trigger Pub/Sub per automatizzare le build in risposta a eventi su Artifact Registry e Cloud Storage.

Nota: i trigger Pub/Sub sono un tipo di trigger associato a Cloud Build. I trigger Pub/Sub utilizzati in contesti aggiuntivi all'interno di Google Cloud potrebbero non fare riferimento ai trigger Pub/Sub di Cloud Build, se non diversamente specificato.

Limitazioni

I trigger Pub/Sub di Cloud Build non sono supportati quando vengono utilizzati i Controlli di servizio VPC.

Prima di iniziare

• Enable the Cloud Build API.

  Enable the API

• Assicurati che il codice sorgente contenga un file di configurazione della build o un Dockerfile nel repository.

• Per utilizzare i comandi gcloud in questa pagina, installa Google Cloud CLI.

  Nota :se hai già installato gcloud CLI, assicurati di avere l'ultima versione disponibile eseguendo gcloud components update.

Creazione di un trigger di build che risponde agli eventi Artifact Registry

Puoi creare un trigger Pub/Sub che risponde agli eventi di Artifact Registry, ad esempio quando le immagini vengono inviate, taggate o eliminate. Questa sezione descrive come creare un trigger Pub/Sub che richiama una build quando un nuovo tag viene inviato a un'immagine esistente. Se non hai familiarità con Artifact Registry, consulta la panoramica di Artifact Registry.

Nota :i trigger Pub/Sub non possono creare repository GitHub Enterprise, Bitbucket Data Center e Bitbucket Server tramite l'integrazione nativa di Cloud Build. Per clonare e creare repository tramite il sistema di gestione del codice sorgente esterno, consulta Creazione e gestione dei trigger di build per scoprire come specificare una configurazione di build inline.

Console

Per creare un trigger che ascolti un nuovo tag inviato a un'immagine esistente in Artifact Registry utilizzando la console Google Cloud :

1. Apri la pagina Trigger:

   Apri la pagina Trigger

2. Seleziona il progetto nella parte superiore della pagina e fai clic su Apri.

3. Fai clic su Crea trigger.

4. Inserisci le seguenti impostazioni del trigger:

   • Nome: inserisci un nome per il trigger.

   • Regione: seleziona la regione per il trigger.

     • Se il file di configurazione della build associato al trigger specifica un pool privato, Cloud Build utilizza il pool privato per eseguire la build. In questo caso, la regione specificata nel trigger deve corrispondere a quella in cui hai creato il pool privato.
     • Se il file di configurazione della build associato al trigger non specifica un pool privato, Cloud Build utilizza il pool predefinito per eseguire la build nella stessa regione del trigger.

   • (Facoltativo) Descrizione: inserisci una descrizione per il trigger.

   • Evento: seleziona Messaggio Pub/Sub come evento per richiamare il trigger.

   • Sottoscrizione: seleziona l'argomento Pub/Sub a cui vuoi abbonarti come evento di trigger. Nel menu a discesa vengono visualizzati tutti gli argomenti esistenti nel tuo progetto.

     • Argomento Pub/Sub: seleziona l'argomento gcr dal menu a discesa o crealo manualmente seguendo le istruzioni riportate in Configurazione delle notifiche Pub/Sub.
     Nota: dopo aver creato il trigger, verrà creata automaticamente una sottoscrizione per il trigger. Puoi visualizzare il tuo abbonamento nella pagina Sottoscrizioni Pub/Sub.

   • Origine: seleziona l'origine da compilare quando viene eseguito il trigger Pub/Sub. Puoi specificare 1ª generazione o 2ª generazione come origine.

     Nota: la regione del repository deve corrispondere a quella del trigger.

     • Repository: seleziona il repository che ti interessa dall'elenco dei repository disponibili.

     • Branch o Tag: specifica un'espressione regolare con il valore del ramo o del tag da soddisfare. Per informazioni sulla sintassi accettabile delle espressioni regolari, vedi sintassi RE2.

     • Controllo dei commenti: se hai selezionato Richiesta di pull (solo app GitHub) come Evento, scegli una delle seguenti opzioni per controllare se una build verrà eseguita automaticamente dal trigger:

       Avviso: qualsiasi utente con accesso in lettura al repository può inviare una richiesta di pull, il che può comportare l'esecuzione di una build che include modifiche al codice sorgente nella richiesta di pull. Per disabilitare questo comportamento, ti consigliamo di utilizzare le approvazioni manuali per limitare le build quando esegui richieste di pull sui repository pubblici. Per ulteriori informazioni sui privilegi dei trigger in fase di build, consulta Trigger di build e service account Cloud Build.

       • Obbligatorio tranne che per proprietari e collaboratori: quando una richiesta pull viene creata o aggiornata da un proprietario o un collaboratore del repository, le build vengono eseguite automaticamente dal trigger. Se un collaboratore esterno avvia l'azione, le build verranno eseguite solo dopo che un proprietario o un collaboratore avrà commentato /gcbrun la richiesta di pull.

       • Obbligatorio: quando una richiesta di pull viene creata o aggiornata da un collaboratore, le build vengono eseguite solo dopo che un proprietario o un collaboratore ha commentato /gcbrun la richiesta di pull. Le build vengono eseguite ogni volta che viene apportata una modifica a una richiesta di pull.

       • Non richiesto: quando una richiesta pull viene creata o aggiornata da qualsiasi collaboratore, le build vengono eseguite automaticamente dai trigger.

   • Configurazione: seleziona il file di configurazione della build (che si trova nel repository remoto) o crea un file di configurazione della build incorporato da utilizzare per la build.

     • Tipo: seleziona il tipo di configurazione da utilizzare per la build.
       • File di configurazione di Cloud Build (yaml o json): utilizza un file di configurazione della build per la configurazione.
       • Dockerfile: utilizza un Dockerfile per la configurazione.
       • Buildpacks: utilizza i buildpack per la configurazione.

     • Posizione: specifica la posizione per la configurazione.

       • Repository: se il file di configurazione si trova nel repository remoto, fornisci la posizione del file di configurazione della build, della directory Dockerfile o della directory dei buildpack. Se il tipo di configurazione della build è Dockerfile o un buildpack, devi fornire un nome per l'immagine risultante e, facoltativamente, un timeout per la build. Dopo aver fornito il nome dell'immagine Dockerfile o del buildpack, vedrai un'anteprima del comando docker build o pack che verrà eseguito dalla build.
       • (Facoltativo) Variabili di ambiente Buildpack: se hai selezionato buildpacks come tipo di configurazione, fai clic su Aggiungi variabile di ambiente Pack per specificare le variabili di ambiente e i valori di Buildpack. Per scoprire di più sulle variabili di ambiente buildpack, consulta Variabili di ambiente.

       • Inline: se hai selezionato File di configurazione di Cloud Build (yaml o json) come opzione di configurazione, puoi specificare la configurazione della build in linea. Fai clic su Apri editor per scrivere il file di configurazione della build nella consoleGoogle Cloud utilizzando la sintassi YAML o JSON. Fai clic su Fine per salvare la configurazione della build.

         Nota: il supporto della configurazione di build in linea non è disponibile per Dockerfile o buildpack.

   • (Facoltativo) Sostituzioni: se hai selezionato il file di configurazione della build come opzione di configurazione della build, puoi scegliere di definire variabili di sostituzione specifiche per il trigger utilizzando questo campo.

     Nell'esempio seguente, vogliamo ottenere il nome del tag immagine dal payload e l'azione associata all'evento gcr. A questo scopo, crea variabili di sostituzione utilizzando le associazioni di payload.

     Specifica le seguenti variabili e i seguenti valori:

     Nome variabile	Valore variabile
     _IMAGE_TAG	$(body.message.data.tag)
     _ACTION	$(body.message.data.action)

     body.message fa riferimento a PubSubMessage pubblicato dagli editori e utilizzato dai sottoscrittori. Per visualizzare altri esempi di payload di notifica Pub/Sub, consulta Esempi di notifiche.

     Nota: la definizione delle variabili di sostituzione è facoltativa, ma è obbligatoria se vuoi configurare il filtro personalizzato per i messaggi Pub/Sub (vedi Filtri di seguito per maggiori informazioni).

   • Filtri (facoltativo): puoi creare filtri all'interno di un trigger che determinano se il trigger eseguirà o meno una build in risposta al payload in entrata specificando filtri sulle variabili di sostituzione. L'espressione del filtro deve restituire true affinché una build venga eseguita.

     Consigliamo di utilizzare il filtro quando configuri i trigger Pub/Sub su argomenti con più messaggi. I filtri possono essere utilizzati per controllare con precisione le build eseguite in risposta ai messaggi Pub/Sub in entrata. Per scoprire di più sui rischi associati alla configurazione di un trigger senza filtri, consulta Rischi associati a un trigger non filtrato.

     Nell'esempio seguente, vogliamo che il trigger esegua una build se viene inserito un nuovo tag in un'immagine esistente. Utilizziamo gli operatori della condizione di filtro per verificare se la variabile _IMAGE_TAG corrisponde a un nome tag esistente e se la variabile _ACTION corrisponde a INSERT per cercare i dati appena aggiunti.

     Specifica quanto segue come filtri:

     • _IMAGE_TAG != ""
     • _ACTION == INSERT
     Nota: puoi anche nidificare le condizioni specificando i seguenti operatori booleani: && (e) e || (o). Il simbolo ! (non) non è supportato.

     La sintassi di filtraggio nei trigger Pub/Sub utilizza Common Expression Language (CEL) per la valutazione delle espressioni. Per saperne di più su CEL, consulta il repository cel-spec.

5. Fai clic su Crea per creare il trigger di build.

gcloud

Per creare un trigger che ascolti un nuovo tag di cui è stato eseguito il push a un'immagine esistente in Artifact Registry utilizzando i comandi gcloud:

1. Apri una finestra del terminale.

2. Esegui il comando gcloud per creare un trigger di build nel tuo progetto. Nell'esempio seguente, il trigger è configurato per rispondere alle build con un tag corrispondente a prod e un'azione corrispondente a INSERT in base al payload specificato definito dalla variabile di sostituzione _IMAGE_TAG.

    gcloud builds triggers create pubsub \
      --region=REGION \
      --name=TRIGGER_NAME \
      --repository=projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME/repositories/REPO_NAME \
      --topic=projects/PROJECT_ID/topics/TOPIC_NAME \
      --build-config=BUILD_CONFIG \ # or --inline-config=INLINE_BUILD_CONFIG
      --substitutions=\
        '_IMAGE_TAG_="$(body.message.data.tag)",' \
        '_ACTION="$(body.message.data.action)"' \
      --subscription-filter='_IMAGE_TAG != "" && _ACTION == "INSERT"' \
      --tag=TAG_NAME  # or --branch=BRANCH_NAME
   

Dove:

• REGION è la regione del trigger.
• TRIGGER_NAME è il nome dell'attivatore.
• PROJECT_ID è l'ID del tuo progetto Cloud.
• CONNECTION_NAME è il nome della connessione host.
• REPO_NAME è il nome del tuo repository.
• TOPIC_NAME è il nome dell'argomento Pub/Sub a cui ti sei iscritto.
• BUILD_CONFIG è il percorso del file di configurazione della build.
• INLINE_BUILD_CONFIG è il percorso del file di configurazione della build incorporato.
• TAG_NAME è il nome del tag se vuoi impostare l'attivatore in modo che si basi su un tag.
• BRANCH_NAME è il nome del ramo se vuoi impostare il trigger per la creazione di una build su un ramo.

Creazione di un trigger di build che risponde agli eventi di Cloud Storage

Puoi creare un trigger Pub/Sub che risponde agli eventi Cloud Storage come quando un nuovo binario viene inviato a un bucket di archiviazione esistente. Questa sezione spiega come creare un trigger Pub/Sub che risponde con una build quando viene eseguito il deployment di un nuovo binario in un bucket caricato. Se non hai dimestichezza con Cloud Storage, consulta le guide rapide.

Console

Per creare un trigger che ascolta gli eventi Cloud Storage utilizzando la console Google Cloud :

1. Apri la pagina Trigger:

   Apri la pagina Trigger

2. Seleziona il progetto nella parte superiore della pagina e fai clic su Apri.

3. Fai clic su Crea trigger.

4. Inserisci le seguenti impostazioni del trigger:

   • Nome: inserisci un nome per il trigger.

   • Regione: seleziona la regione per il trigger.

     • Se il file di configurazione della build associato al trigger specifica un pool privato, Cloud Build utilizza il pool privato per eseguire la build. In questo caso, la regione specificata nel trigger deve corrispondere a quella in cui hai creato il pool privato.
     • Se il file di configurazione della build associato al trigger non specifica un pool privato, Cloud Build utilizza il pool predefinito per eseguire la build nella stessa regione del trigger.

   • (Facoltativo) Descrizione: inserisci una descrizione per il trigger.

   • Evento: seleziona Messaggio Pub/Sub come evento per richiamare il trigger.

   • Sottoscrizione: seleziona l'argomento Pub/Sub a cui vuoi abbonarti come evento di trigger. Nel menu a discesa vengono visualizzati tutti gli argomenti esistenti nel tuo progetto.

     • Argomento Pub/Sub: seleziona l'argomento gcs dal menu a discesa o crealo manualmente seguendo le istruzioni riportate in Configurazione delle notifiche Pub/Sub per Cloud Storage.
     Nota: dopo aver creato il trigger, verrà creata automaticamente una sottoscrizione per il trigger. Puoi visualizzare il tuo abbonamento nella pagina Sottoscrizioni Pub/Sub.

   • Origine: seleziona l'origine da compilare quando viene eseguito il trigger Pub/Sub. Puoi specificare 1ª generazione o 2ª generazione come origine.

     Nota: la regione del repository deve corrispondere a quella del trigger.

     • Repository: seleziona il repository che ti interessa dall'elenco dei repository disponibili.

     • Branch o Tag: specifica un'espressione regolare con il valore del ramo o del tag da soddisfare. Per informazioni sulla sintassi accettabile delle espressioni regolari, vedi sintassi RE2.

     • Controllo dei commenti: se hai selezionato Richiesta di pull (solo app GitHub) come Evento, scegli una delle seguenti opzioni per controllare se una build verrà eseguita automaticamente dal trigger:

       Avviso: qualsiasi utente con accesso in lettura al repository può inviare una richiesta di pull, il che può comportare l'esecuzione di una build che include modifiche al codice sorgente nella richiesta di pull. Per disabilitare questo comportamento, ti consigliamo di utilizzare le approvazioni manuali per limitare le build quando esegui richieste di pull sui repository pubblici. Per ulteriori informazioni sui privilegi dei trigger in fase di build, consulta Trigger di build e service account Cloud Build.

       • Obbligatorio tranne che per proprietari e collaboratori: quando una richiesta pull viene creata o aggiornata da un proprietario o un collaboratore del repository, le build vengono eseguite automaticamente dal trigger. Se un collaboratore esterno avvia l'azione, le build verranno eseguite solo dopo che un proprietario o un collaboratore avrà commentato /gcbrun la richiesta di pull.

       • Obbligatorio: quando una richiesta di pull viene creata o aggiornata da un collaboratore, le build vengono eseguite solo dopo che un proprietario o un collaboratore ha commentato /gcbrun la richiesta di pull. Le build vengono eseguite ogni volta che viene apportata una modifica a una richiesta di pull.

       • Non richiesto: quando una richiesta pull viene creata o aggiornata da qualsiasi collaboratore, le build vengono eseguite automaticamente dai trigger.

   • Configurazione: seleziona il file di configurazione della build (che si trova nel repository remoto) o crea un file di configurazione della build incorporato da utilizzare per la build.

     • Tipo: seleziona il tipo di configurazione da utilizzare per la build.
       • File di configurazione di Cloud Build (yaml o json): utilizza un file di configurazione della build per la configurazione.
       • Dockerfile: utilizza un Dockerfile per la configurazione.
       • Buildpacks: utilizza i buildpack per la configurazione.

     • Posizione: specifica la posizione per la configurazione.

       • Repository: se il file di configurazione si trova nel repository remoto, fornisci la posizione del file di configurazione della build, della directory Dockerfile o della directory dei buildpack. Se il tipo di configurazione della build è Dockerfile o un buildpack, devi fornire un nome per l'immagine risultante e, facoltativamente, un timeout per la build. Dopo aver fornito il nome dell'immagine Dockerfile o del buildpack, vedrai un'anteprima del comando docker build o pack che verrà eseguito dalla build.
       • (Facoltativo) Variabili di ambiente Buildpack: se hai selezionato buildpacks come tipo di configurazione, fai clic su Aggiungi variabile di ambiente Pack per specificare le variabili di ambiente e i valori di Buildpack. Per scoprire di più sulle variabili di ambiente buildpack, consulta Variabili di ambiente.

       • Inline: se hai selezionato File di configurazione di Cloud Build (yaml o json) come opzione di configurazione, puoi specificare la configurazione della build in linea. Fai clic su Apri editor per scrivere il file di configurazione della build nella consoleGoogle Cloud utilizzando la sintassi YAML o JSON. Fai clic su Fine per salvare la configurazione della build.

         Nota: il supporto della configurazione di build in linea non è disponibile per Dockerfile o buildpack.

   • (Facoltativo) Sostituzioni: se hai selezionato il file di configurazione della build come opzione di configurazione della build, puoi scegliere di definire variabili di sostituzione specifiche per il trigger utilizzando questo campo.

     In questo esempio, vogliamo monitorare il deployment di un nuovo binario quando viene caricato in un bucket. Per ottenere questi dati, possiamo creare variabili di sostituzione utilizzando i binding del payload.

     Specifica le seguenti variabili e i seguenti valori:

     Nome variabile	Valore variabile
     _EVENT_TYPE	$(body.message.attributes.eventType)
     _BUCKET_ID	$(body.message.attributes.bucketId)
     _OBJECT_ID	$(body.message.attributes.objectId)

     body.message fa riferimento a PubSubMessage pubblicato dagli editori e utilizzato dai sottoscrittori. Per visualizzare altri esempi di payload di notifica Pub/Sub, consulta Esempi di notifiche.

     Nota: la definizione delle variabili di sostituzione è facoltativa, ma è obbligatoria se vuoi configurare il filtro personalizzato per i messaggi Pub/Sub (vedi Filtri di seguito per maggiori informazioni).

   • Filtri (facoltativo): puoi creare filtri all'interno di un trigger che determinano se il trigger eseguirà o meno una build in risposta al payload in entrata specificando filtri sulle variabili di sostituzione. L'espressione del filtro deve restituire true affinché una build venga eseguita.

     Consigliamo di utilizzare il filtro quando configuri i trigger Pub/Sub su argomenti con più messaggi. I filtri possono essere utilizzati per controllare con precisione le build eseguite in risposta ai messaggi Pub/Sub in entrata. Per scoprire di più sui rischi associati alla configurazione di un trigger senza filtri, consulta Rischi associati a un trigger non filtrato.

     Poiché vogliamo che l'attivatore esegua una build se il nuovo binario è stato implementato in un bucket specifico, possiamo utilizzare l'operatore "==" per verificare le corrispondenze esatte. Puoi anche utilizzare la parola chiave "matches" se vuoi trovare corrispondenze tramite espressione regolare.

     Specifica quanto segue come filtri:

     • _EVENT_TYPE == OBJECT_FINALIZE
     • _OBJECT_ID partite ^<object-id>$
     • _BUCKET_ID partite ^<bucket-id>$

5. Fai clic su Crea per creare il trigger di build.
.

gcloud

Rischi associati a un trigger non filtrato

Se non hai configurato filtri sul trigger Pub/Sub, il trigger potrebbe richiamare un numero infinito di build se modifica un artefatto o un oggetto che pubblica involontariamente un nuovo messaggio nell'argomento a cui è in ascolto. Ad esempio, il trigger potrebbe richiamare un numero infinito di build se:

• Punti per un argomento gcr.
• Crea qualsiasi immagine o tag in gcr.
• Punta a un argomento gcs per un oggetto specifico nel bucket e lo modifica.

Se si verifica un loop infinito, puoi eliminare il trigger o aggiornarlo in modo che punti a un argomento separato per evitare di incorrere in costi aggiuntivi per ogni build richiamata.

Passaggi successivi

• Scopri come avviare manualmente le build utilizzando i comandi gcloud o l'API Cloud Build.
• Scopri come creare e gestire i trigger.
• Scopri come visualizzare i risultati della build.
• Scopri come risolvere gli errori di build.