Pubblica e ricevi eventi creando un bus e una registrazione (gcloud CLI)

Questa guida rapida mostra come pubblicare e ricevere messaggi di eventi creando un bus Eventarc Advanced e una registrazione nel tuo progetto Google Cloud.

  • Un bus ti consente di centralizzare il flusso di messaggi nel tuo sistema e funge da router. Riceve messaggi di eventi da un'origine messaggi o pubblicati da un provider e li valuta in base a una registrazione.

  • Una registrazione identifica un abbonamento a un particolare bus e definisce i criteri di corrispondenza per i messaggi, che vengono instradati di conseguenza a una o più destinazioni.

In questa guida rapida:

  1. Crea una subnet e abilita l'accesso privato Google.

  2. Creare un collegamento di rete.

  3. Crea un repository Artifact Registry standard.

  4. Eseguire il deployment di un servizio di ricezione di eventi in Cloud Run.

  5. Crea un bus Eventarc Advanced.

  6. Crea una registrazione Eventarc Advanced.

  7. Pubblica un messaggio di evento nel bus.

  8. Visualizza i dati sugli eventi nei log di Cloud Run.

Puoi completare questa guida rapida utilizzando gcloud CLI. Per completare i passaggi utilizzando la console Google Cloud , consulta Pubblicare e ricevere eventi creando un bus e una registrazione (console).

Prima di iniziare

I vincoli di sicurezza definiti dalla tua organizzazione potrebbero impedirti di completare i passaggi seguenti. Per informazioni sulla risoluzione dei problemi, vedi Sviluppare applicazioni in un ambiente Google Cloud vincolato.

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. Install the Google Cloud CLI.

  3. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  4. To initialize the gcloud CLI, run the following command: 

    gcloud init

  5. Create or select a Google Cloud project.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Enable the Artifact Registry, Cloud Build, Cloud Run, Compute Engine, and Eventarc APIs: 

    gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com compute.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com

  8. Install the Google Cloud CLI.

  9. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  10. To initialize the gcloud CLI, run the following command: 

    gcloud init

  11. Create or select a Google Cloud project.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  12. Make sure that billing is enabled for your Google Cloud project.

  13. Enable the Artifact Registry, Cloud Build, Cloud Run, Compute Engine, and Eventarc APIs: 

    gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com compute.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com

  14. Aggiorna i componenti di gcloud: 
    gcloud components update

  15. Accedi utilizzando il tuo account: 
    gcloud auth login

  16. Imposta la variabile di configurazione utilizzata in questa guida rapida: 
    REGION=REGION

    Sostituisci REGION con una località supportata per l'autobus.

  17. Se hai creato il progetto, ti viene assegnato il ruolo di base Proprietario (roles/owner). Per impostazione predefinita, questo ruolo Identity and Access Management (IAM) include le autorizzazioni necessarie per l'accesso completo alla maggior parte delle risorse Google Cloud e puoi saltare questo passaggio.

    Se non sei il creatore del progetto, le autorizzazioni richieste devono essere concesse al principal appropriato. Ad esempio, un'entità può essere un Account Google (per gli utenti finali) o un account di servizio (per applicazioni e carichi di lavoro di calcolo).

    Tieni presente che per impostazione predefinita, le autorizzazioni di Cloud Build includono le autorizzazioni per caricare e scaricare gli artefatti di Artifact Registry.

    Autorizzazioni obbligatorie

    Per ottenere le autorizzazioni necessarie per completare questa guida rapida, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

    Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

    Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

  18. Concedi i seguenti ruoli sul progetto all'account di servizio predefinito di Compute Engine. Questi ruoli sono necessari per creare ed eseguire il deployment dell'immagine container: 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/artifactregistry.writer
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/logging.logWriter
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/storage.objectUser

    Sostituisci PROJECT_NUMBER con il numero del tuo progetto Google Cloud. Puoi trovare il numero di progetto nella pagina Benvenuto della console Google Cloud o eseguendo questo comando:

    gcloud projects describe PROJECT_ID --format='value(projectNumber)'

  19. Per impostazione predefinita, solo i proprietari del progetto, gli editor del progetto e gli amministratori e gli invoker di Cloud Run possono chiamare i servizi Cloud Run. Per configurare l'autenticazione, concedi il ruolo Invoker di Cloud Run (run.invoker) nel tuo progetto Google Cloud a un account di servizio:
    1. Crea un account di servizio. A scopo di test, collegherai questo service account a una pipeline Eventarc Advanced per rappresentare l'identità della pipeline. 
      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
       Sostituisci SERVICE_ACCOUNT_NAME con un nome per il tuo account di servizio.
    2. Concedi il ruolo IAM roles/run.invoker all'account di servizio: 
      gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
    --role=roles/run.invoker

    Tieni presente che puoi configurare chi può accedere al tuo servizio Cloud Run in uno dei seguenti modi:

    • Concedi l'autorizzazione per selezionare service account o gruppi per consentire l'accesso al servizio. Tutte le richieste devono avere un'intestazione di autorizzazione HTTP contenente un token OpenID Connect firmato da Google per uno degli account di servizio autorizzati. Questo è il modo in cui viene configurato l'accesso in questa guida rapida.
    • Concedi l'autorizzazione a allUsers per consentire l'accesso non autenticato.

    Per saperne di più, consulta Controllo dell'accesso per Cloud Run.

Crea una subnet e abilita l'accesso privato Google

A meno che tu non crei un criterio dell'organizzazione che lo vieti, i nuovi progetti Google Cloud iniziano con una rete Virtual Private Cloud (VPC) predefinita (una rete VPC in modalità automatica) con una subnet in ogni regione. Alle subnet sono associati intervalli di indirizzi IP.

Poiché esegui il routing dei messaggi verso una destinazione Cloud Run utilizzando un indirizzo DNS, devi abilitare l'accesso privato Google nella subnet utilizzata nell'allegato di rete; in caso contrario, l'indirizzo DNS non può essere risolto. Per saperne di più sul networking privato e su Cloud Run, consulta Ricevere richieste dalle reti VPC.

Crea una subnet nella rete predefinita del progetto e utilizza il flag --enable-private-ip-google-access per abilitare l'accesso privato Google:

gcloud compute networks subnets create SUBNET_NAME \
    --network=default \
    --range=10.8.0.0/24 \
    --region=$REGION \
    --enable-private-ip-google-access

Sostituisci SUBNET_NAME con il nome della tua subnet, ad esempio my-subnet.

Gli intervalli di indirizzi IP delle subnet devono essere univoci e non devono sovrapporsi all'interno di una rete VPC e di una rete VPC in peering. Per saperne di più sui tipi di subnet e sugli intervalli di subnet validi, consulta Subnet.

Crea un collegamento di rete

Un collegamento di rete è una risorsa che consente a una rete VPC producer di avviare connessioni a una rete VPC consumer. Per pubblicare eventi, Eventarc Advanced utilizza il collegamento di rete per stabilire una connessione all'endpoint ospitato in una rete VPC.

Crea un collegamento di rete nella stessa rete e regione contenente l'endpoint di destinazione eventi e che accetta automaticamente le connessioni da qualsiasi interfaccia Private Service Connect che fa riferimento al collegamento di rete:

gcloud compute network-attachments create ATTACHMENT_NAME \
   --region=$REGION \
   --connection-preference=ACCEPT_AUTOMATIC \
   --subnets=SUBNET_NAME

Sostituisci ATTACHMENT_NAME con il nome dell'allegato di rete, ad esempio my-network-attachment.

Crea un repository standard Artifact Registry

Crea un repository standard di Artifact Registry per archiviare l'immagine container.

gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=$REGION

Sostituisci REPOSITORY con un nome univoco per il repository Artifact Registry, ad esempio my-repo.

Esegui il deployment di un servizio di ricezione di eventi in Cloud Run

Esegui il deployment di un servizio Cloud Run che registra i contenuti di un evento. Questo servizio è accessibile solo dalle reti VPC nello stesso progetto e l'URL del servizio non è direttamente accessibile perché il servizio consente solo chiamate autenticate.

  1. Clona il repository GitHub:

    git clone https://github.com/GoogleCloudPlatform/eventarc-samples.git

  2. Passa alla directory che contiene il codice campione di Cloud Run:

    cd eventarc-samples/eventarc-advanced-quickstart/

  3. Crea un'immagine container Docker ed eseguirne il push nel repository:

    gcloud builds submit \
    --tag $REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/log-events:v1

  4. Esegui il deployment dell'immagine container su Cloud Run:

    gcloud run deploy SERVICE_NAME \
    --image $REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/log-events:v1 \
    --platform managed \
    --ingress internal \
    --no-allow-unauthenticated \
    --region=$REGION

    Sostituisci SERVICE_NAME con il nome del tuo servizio, ad esempio my-service.

Quando viene visualizzato l'URL del servizio Cloud Run, il deployment è completato. Prendi nota di questo URL per poterlo utilizzare in un passaggio successivo.

Crea un bus Eventarc Advanced

Un bus riceve messaggi di eventi da un'origine messaggi o pubblicati da un provider e funge da router di messaggi.

Per maggiori informazioni, vedi Creare un bus per instradare i messaggi.

Crea un bus Eventarc Advanced nel tuo progetto utilizzando il comando gcloud beta eventarc message-buses create:

gcloud beta eventarc message-buses create BUS_NAME \
    --location=$REGION

Sostituisci BUS_NAME con l'ID o l'identificatore completo del bus, ad esempio my-bus.

Crea una registrazione Eventarc Advanced

Una registrazione determina quali messaggi vengono instradati a una destinazione e specifica anche la pipeline utilizzata per configurare una destinazione per i messaggi di evento.

Per ulteriori informazioni, vedi Creare una registrazione per ricevere eventi.

Quando utilizzi gcloud CLI, prima crei una pipeline, poi crei una registrazione:

  1. Crea una pipeline utilizzando il comando gcloud beta eventarc pipelines create:

    gcloud beta eventarc pipelines create PIPELINE_NAME \
    --destinations=http_endpoint_uri='CLOUD_RUN_SERVICE_URL',network_attachment=ATTACHMENT_NAME,google_oidc_authentication_service_account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --location=$REGION

    Sostituisci quanto segue:

    • PIPELINE_NAME: l'ID della pipeline o un nome completo.
    • CLOUD_RUN_SERVICE_URL: l'URL completo del tuo servizio Cloud Run, ad esempio https://SERVICE_NAME-abcdef-uc.a.run.app. Questa è la destinazione dei messaggi dell'evento.

    Tieni presente che la chiave google_oidc_authentication_service_account specifica un indirizzo email del account di servizio utilizzato per generare un token OIDC.

  2. Crea una registrazione utilizzando il comando gcloud beta eventarc enrollments create:

    gcloud beta eventarc enrollments create ENROLLMENT_NAME \
    --cel-match=MATCH_EXPRESSION \
    --destination-pipeline=PIPELINE_NAME \
    --message-bus=BUS_NAME \
    --message-bus-project=PROJECT_ID \
    --location=$REGION

    Sostituisci quanto segue:

    • ENROLLMENT_NAME: l'ID della registrazione o un nome completo.
    • MATCH_EXPRESSION: l'espressione di corrispondenza per questa registrazione utilizzando CEL, ad esempio, "message.type == 'hello-world-type'".

Pubblica un messaggio di evento nel bus

Per pubblicare direttamente un messaggio nel bus, puoi utilizzare il comando gcloud beta eventarc message-buses publish o inviare una richiesta all'API REST di pubblicazione di Eventarc. Per maggiori informazioni, vedi Pubblicare eventi direttamente.

Il messaggio deve essere in formato CloudEvents, una specifica per descrivere i dati degli eventi in modo comune. L'elemento data è il payload del tuo evento. In questo campo può essere inserito qualsiasi JSON ben formato. Per saperne di più sugli attributi di contesto CloudEvents, consulta Formato dell'evento.

Di seguito sono riportati esempi di pubblicazione diretta di un evento in un bus Eventarc Advanced:

Esempio 1

Puoi pubblicare un evento in un bus utilizzando gcloud CLI e un --event-data e altri flag di attributo evento:

gcloud beta eventarc message-buses publish BUS_NAME \
    --event-data='{"key": "hello-world-data"}' \
    --event-id=hello-world-id-1234 \
    --event-source=hello-world-source \
    --event-type=hello-world-type \
    --event-attributes="datacontenttype=application/json" \
    --location=$REGION

Esempio 2

Puoi pubblicare un evento in un bus come messaggio JSON utilizzando gcloud CLI e un flag --json-message:

gcloud beta eventarc message-buses publish BUS_NAME \
    --location=$REGION \
    --json-message='{"id": "hello-world-id-1234", "type":
 "hello-world-type", "source":
 "hello-world-source", "specversion": "1.0", "data":
 {"key": "hello-world-data"}}'

Dopo aver pubblicato un evento, dovresti ricevere un messaggio "Evento pubblicato correttamente".

Visualizza i dati sugli eventi nei log di Cloud Run

Dopo aver pubblicato un evento nel bus Eventarc Advanced, puoi controllare i log del servizio Cloud Run per verificare che l'evento sia stato ricevuto come previsto.

  1. Filtra le voci di log e restituisci l'output utilizzando il comando gcloud logging read:

    gcloud logging read 'textPayload: "hello-world-data"'

  2. Cerca una voce di log simile alla seguente:

    insertId: 670808e70002b5c6477709ae
labels:
instanceId: 007989f2a10a4a33c21024f2c8e06a9de65d9b4fdc2ee27697a50379b3fab2f975b9233dc357d50b06270829b9b479d5a1ee54a10fa2cb2d98c5f77a0895e2be0f9e6e4b20
logName: projects/PROJECT_ID/logs/run.googleapis.com%2Fstderr
receiveTimestamp: '2024-10-10T17:03:35.424659450Z'
resource:
labels:
...
type: cloud_run_revision
textPayload: "[2024-10-21 15:33:19,581] INFO in server: Body: b'{\"value\":\"hello-world-data\"\
  }'"
timestamp: '2024-10-10T17:03:35.177606Z'

Hai creato correttamente un bus e una registrazione Eventarc Advanced, hai pubblicato un messaggio di evento nel bus e hai verificato il risultato previsto nei log del servizio di ricezione eventi.

Esegui la pulizia

Al termine delle attività descritte in questa guida rapida, puoi evitare l'addebito di ulteriori costi eliminando le risorse che hai creato:

  1. Elimina una subnet VPC.

  2. Elimina un collegamento di rete VPC.

  3. Elimina un repository Artifact Registry.

  4. Elimina un servizio Cloud Run.

  5. Elimina le risorse Eventarc Advanced:

    1. Eliminare una registrazione.

    2. Elimina una pipeline.

    3. Elimina un bus.

In alternativa, puoi eliminare il tuo progetto Google Cloud per evitare addebiti. L'eliminazione del progetto Google Cloud interrompe la fatturazione di tutte le risorse utilizzate al suo interno.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Passaggi successivi