Pubblica e ricevi eventi creando un bus e una registrazione (Terraform)

Pubblica e ricevi eventi creando un bus e una registrazione (Terraform)

Avanzate

Questa guida rapida mostra come utilizzare Terraform per creare un bus Eventarc Advanced e la registrazione nel tuo progetto Google Cloud in modo da poter pubblicare e ricevere messaggi di eventi.

• Un bus funge da router centrale, ricevendo messaggi dalle origini eventi o pubblicati dai provider.

• Una registrazione indirizza i messaggi ricevuti dal bus a una o più destinazioni tramite una pipeline di elaborazione.

In questa guida rapida:

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

2. Crea un bus Eventarc Advanced.

3. Attiva gli eventi dalle origini Google.

4. Crea una pipeline e una registrazione Eventarc Advanced.

5. Pubblica un messaggio di evento nel bus creando un flusso di lavoro.

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

Puoi completare la maggior parte dei passaggi di questa guida rapida utilizzando Terraform. Per completare tutti i passaggi utilizzando Google Cloud CLI, consulta Pubblica eventi da un'origine Google.

Per saperne di più sull'utilizzo di Terraform, consulta la documentazione Terraform su Google Cloud.

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.

Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei carichi di lavoro.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Resource Manager and Identity and Access Management (IAM) APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Resource Manager and Identity and Access Management (IAM) APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

1. Nella console Google Cloud , attiva Cloud Shell.

   Attiva Cloud Shell

   Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.

Terraform è integrato nell'ambiente Cloud Shell e puoi utilizzare Cloud Shell per eseguire il deployment delle risorse Terraform senza dover installare Terraform.

Ruoli obbligatori

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

• Cloud Run Admin (roles/run.admin)
• Eventarc Developer (roles/eventarc.developer)
• Eventarc Message Bus Admin (roles/eventarc.messageBusAdmin)
• Logs View Accessor (roles/logging.viewAccessor)
• Project IAM Admin (roles/resourcemanager.projectIamAdmin)
• Amministratore service account (roles/iam.serviceAccountAdmin)
• Utente Service Account (roles/iam.serviceAccountUser)
• Editor di workflow (roles/workflows.editor)

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.

Prepararsi a eseguire il deployment di Terraform

Prima di eseguire il deployment di qualsiasi risorsa Terraform, devi creare un file di configurazione Terraform. Un file di configurazione Terraform ti consente di definire lo stato finale preferito per la tua infrastruttura utilizzando la sintassi Terraform.

1. In Cloud Shell, imposta il progetto Google Cloud predefinito in cui vuoi applicare la configurazione Terraform. Devi eseguire questo comando una sola volta per progetto e puoi eseguirlo in qualsiasi directory:

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Sostituisci PROJECT_ID con l'ID del tuo progetto Google Cloud .

   Tieni presente che le variabili di ambiente vengono sostituite se imposti valori espliciti nel file di configurazione Terraform.

2. Ogni file di configurazione Terraform deve avere la propria directory (chiamata anche modulo radice). In Cloud Shell, crea una directory e un nuovo file al suo interno:

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

   Sostituisci DIRECTORY con il nome della directory Terraform.

   Il nome file deve avere l'estensione .tf. Ad esempio, in questa guida rapida, il file di configurazione è main.tf.

Definisci la configurazione Terraform

Copia i seguenti snippet di codice Terraform nel file main.tf. In alternativa, per copiare l'intero esempio di codice da GitHub, fai clic su > Visualizza su GitHub nell'angolo in alto a destra di uno snippet di codice.

Abilita API

Utilizza la risorsa Terraform google_project_service per abilitare le API necessarie per applicare la configurazione Terraform:

# Enable APIs
resource "google_project_service" "apis" {
  for_each = toset([
    "eventarc.googleapis.com",
    "eventarcpublishing.googleapis.com",
    "run.googleapis.com"
  ])
  service            = each.key
  disable_on_destroy = false
}

Crea un account di servizio

A scopo di test, crea un account di servizio dedicato e concedigli ruoli IAM specifici.

Utilizza le risorse Terraform google_service_account e google_project_iam_member per creare il account di servizio e concedergli i ruoli necessari per pubblicare e ricevere eventi:

# Used to retrieve project information later
data "google_project" "project" {}

# Create a dedicated service account
resource "google_service_account" "default" {
  account_id   = "eventarc-advanced-sa"
  display_name = "Eventarc Advanced quickstart service account"
}

# Grant permission to receive Eventarc events
resource "google_project_iam_member" "eventreceiver" {
  project = data.google_project.project.id
  role    = "roles/eventarc.eventReceiver"
  member  = "serviceAccount:${google_service_account.default.email}"
}

# Grant permission to invoke Cloud Run services
resource "google_project_iam_member" "runinvoker" {
  project = data.google_project.project.id
  role    = "roles/run.invoker"
  member  = "serviceAccount:${google_service_account.default.email}"
}

Crea una destinazione evento

Utilizza la risorsa Terraform google_cloud_run_v2_service per creare un servizio Cloud Run come destinazione evento che registra i contenuti di un evento:

# Deploy Cloud Run service
resource "google_cloud_run_v2_service" "default" {
  name     = "example-service"
  location = "us-central1"

  deletion_protection = false # set to "true" in production

  template {
    containers {
      # This sample container listens to HTTP requests and logs received events
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
    service_account = google_service_account.default.email
  }

  depends_on = [google_project_service.apis]
}

Crea un bus Eventarc Advanced

Un bus riceve messaggi di eventi da un'origine di messaggi o pubblicati da un provider e funge da router di messaggi. Per saperne di più, consulta la sezione Creare un bus per instradare i messaggi.

Nota: puoi creare un bus per Google Cloud progetto per regione supportata.

Utilizza la risorsa Terraform google_eventarc_message_bus per creare un bus Eventarc Advanced:

# Create an Eventarc Advanced bus
resource "google_eventarc_message_bus" "default" {
  location       = "us-central1"
  message_bus_id = "example-bus"
}

Attivare gli eventi dalle origini Google

Per pubblicare eventi da origini Google, devi creare una risorsa GoogleApiSource che rappresenti un abbonamento agli eventi API di Google per un determinato bus Eventarc Advanced. Per saperne di più, consulta Pubblicare eventi da origini Google.

Nota: puoi creare una risorsa GoogleApiSource per Google Cloudprogetto per regione supportata.

Utilizza la risorsa Terraform google_eventarc_google_api_source per attivare gli eventi provenienti da origini Google:

# Enable events from Google API sources
resource "google_eventarc_google_api_source" "default" {
  location             = "us-central1"
  google_api_source_id = "example-google-api-source"
  destination          = google_eventarc_message_bus.default.id
}

Tutti i tipi di eventi Google supportati inviati direttamente da una fonte Google vengono ora raccolti e pubblicati nel tuo bus.

Crea una pipeline Eventarc Advanced

Una pipeline consente di configurare una destinazione di destinazione e offre anche la possibilità di trasformare gli eventi corrispondenti prima di inviarli alla destinazione.

Utilizza la risorsa Terraform google_eventarc_pipeline per creare una pipeline:

# Create an Eventarc Advanced pipeline
resource "google_eventarc_pipeline" "default" {
  location    = "us-central1"
  pipeline_id = "example-pipeline"
  destinations {
    http_endpoint {
      uri = google_cloud_run_v2_service.default.uri
    }
    authentication_config {
      google_oidc {
        service_account = google_service_account.default.email
      }
    }
  }
}

La destinazione dell'evento è l'URL completo del servizio Cloud Run, ad esempio https://SERVICE_NAME-abcdef-uc.a.run.app. L'indirizzo email del service account viene utilizzato per generare un token OIDC.

Nota: la creazione di una pipeline può richiedere diversi minuti.

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 eventi. Per saperne di più, consulta Crea una registrazione per ricevere eventi.

Utilizza la risorsa Terraform google_eventarc_enrollment per creare una registrazione:

# Create an Eventarc Advanced enrollment
resource "google_eventarc_enrollment" "default" {
  location      = "us-central1"
  enrollment_id = "example-enrollment"
  message_bus   = google_eventarc_message_bus.default.id
  destination   = google_eventarc_pipeline.default.id
  cel_match     = "message.type == 'google.cloud.workflows.workflow.v1.created'"
}

L'espressione di corrispondenza per la registrazione utilizza Common Expression Language (CEL) per pubblicare messaggi di eventi ogni volta che viene creato un flusso di lavoro. In un passaggio successivo, creerai un workflow.

Applica la configurazione Terraform

Utilizza Terraform CLI per eseguire il provisioning dell'infrastruttura in base al file di configurazione. Per saperne di più, consulta Comandi Terraform di base.

1. Inizializza Terraform. Devi farlo solo una volta per directory.

   terraform init

   (Facoltativo) Per utilizzare l'ultima versione del provider Google, includi l'opzione -upgrade:

   terraform init -upgrade

2. Rivedi la configurazione e verifica che le risorse che Terraform creerà o aggiornerà corrispondano alle tue aspettative:

   terraform plan

   Correggi la configurazione in base alle esigenze.

3. Applica la configurazione Terraform eseguendo questo comando e inserendo yes al prompt:

   terraform apply

   In genere, applichi l'intera configurazione contemporaneamente. Tuttavia, puoi anche scegliere come target una risorsa specifica. Ad esempio:

   terraform apply -target="google_eventarc_message_bus.default"

   Attendi che Terraform visualizzi il messaggio "Apply complete!" (Applicazione completata).

Pubblica un messaggio di evento nel bus creando un flusso di lavoro

Workflows è una piattaforma di orchestrazione completamente gestita che esegue i servizi in un ordine definito da te: un workflow. Crea un flusso di lavoro per generare un tipo di evento supportato da un'origine Google.

1. Nella tua directory home, crea un nuovo file denominato myWorkflow.yaml.

2. Copia e incolla il seguente flusso di lavoro nel nuovo file, poi salvalo:

   main:
       params: [input]
       steps:
       - checkSearchTermInInput:
           switch:
               - condition: '${"searchTerm" in input}'
                 assign:
                   - searchTerm: '${input.searchTerm}'
                 next: readWikipedia
       - getLocation:
           call: sys.get_env
           args:
               name: GOOGLE_CLOUD_LOCATION
           result: location
       - setFromCallResult:
           assign:
               - searchTerm: '${text.split(location, "-")[0]}'
       - readWikipedia:
           call: http.get
           args:
               url: 'https://en.wikipedia.org/w/api.php'
               query:
                   action: opensearch
                   search: '${searchTerm}'
           result: wikiResult
       - returnOutput:
               return: '${wikiResult.body[1]}'
   

   Questo flusso di lavoro trasmette la regione in cui viene eseguito il deployment del workflow all'API Wikipedia e restituisce un elenco di articoli correlati su Wikipedia.

3. Esegui il deployment del workflow utilizzando il comando gcloud workflows deploy:

   gcloud workflows deploy example-workflow --source=myWorkflow.yaml \
       --service-account=eventarc-advanced-sa@PROJECT_ID.iam.gserviceaccount.com \
       --location=us-central1

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 create dal tuo servizio:

   gcloud logging read 'jsonPayload.message: "Received event of type google.cloud.workflows.workflow.v1.created."'
   

2. Cerca una voce di log simile alla seguente:

   message: 'Received event of type google.cloud.workflows.workflow.v1.created.
   Event data: {"@type":"type.googleapis.com/google.events.cloud.workflows.v1.WorkflowEventData","payload":{"name":"projects/PROJECT_ID/locations/us-central1/workflows/example-workflow","state":"ACTIVE"...
   

Nota: se non vedi una voce di log, attendi alcuni minuti e riprova a eseguire il comando gcloud logging read.

Hai creato correttamente un bus e una registrazione Eventarc Advanced, hai attivato la pubblicazione di eventi da origini Google, hai creato un flusso di lavoro per generare un tipo di evento supportato da un provider Google e poi hai verificato il risultato previsto nei log del servizio di ricezione eventi.

Esegui la pulizia

Rimuovi le risorse applicate in precedenza con la configurazione Terraform eseguendo questo comando e inserendo yes al prompt:

terraform destroy

Puoi anche eliminare il tuo progetto Google Cloud per evitare addebiti. L'eliminazione del tuo progetto Google Cloud interrompe la fatturazione per tutte le risorse utilizzate al suo interno.

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:
• L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per, le attività descritte in questo documento, eliminerai anche tutto il lavoro che hai svolto nel progetto.
• Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.
1. Nella console Google Cloud , vai alla pagina Gestisci risorse.

   Vai a Gestisci risorse

2. Nell'elenco dei progetti, seleziona il progetto che vuoi eliminare, quindi fai clic su Elimina.
3. Nella finestra di dialogo, digita l'ID progetto, quindi fai clic su Chiudi per eliminare il progetto.

Passaggi successivi

• Pubblicare eventi direttamente
• Trasformare gli eventi ricevuti
• Formattare gli eventi ricevuti