Pubblicare e ricevere eventi creando un bus e una registrazione (Terraform)

Pubblicare e ricevere eventi creando un bus e una registrazione (Terraform)

Advanced

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

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

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

In questa guida rapida:

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

2. Crea un bus Eventarc Advanced.

3. Abilita gli eventi da origini Google.

4. Crea una pipeline e una registrazione Eventarc Advanced.

5. Pubblica un messaggio di evento nel bus creando un workflow.

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 Pubblicare eventi da un'origine Google.

Per saperne di più sull'utilizzo di Terraform, consulta la documentazione di Terraform 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 vincolato Google Cloud .

Accedi al tuo Google Cloud account. Se non hai mai utilizzato Google Cloud, crea un account per valutare il rendimento 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 workload.

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.

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.

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 Google Cloud console, attiva Cloud Shell.

   Attiva Cloud Shell

   Nella parte inferiore della Google Cloud console 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à inclusa e 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)
• Service Account Admin (roles/iam.serviceAccountAdmin)
• Service Account User (roles/iam.serviceAccountUser)
• Workflows Editor (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 per 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 consente di definire lo stato finale preferito per l'infrastruttura utilizzando la sintassi Terraform.

1. In Cloud Shell, imposta il progetto predefinito Google Cloud 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 Google Cloud progetto.

   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 una propria directory (chiamata anche modulo root). In Cloud Shell, crea una directory e un nuovo file all'interno della directory:

   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, nell'angolo in alto a destra di uno snippet di codice, fai clic su > Visualizza su GitHub.

Abilita API

Utilizza la google_project_service risorsa Terraform per abilitare le API richieste 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 google_service_account e google_project_iam_member risorse Terraform per creare l'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 di eventi

Utilizza la google_cloud_run_v2_service risorsa Terraform per creare un servizio Cloud Run come destinazione di eventi 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 Crea un bus per instradare i messaggi.

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

Utilizza la google_eventarc_message_bus risorsa Terraform 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"
}

Abilita gli eventi da origini Google

Per pubblicare eventi da origini Google, devi creare una GoogleApiSource risorsa che rappresenta un abbonamento agli eventi dell'API 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 Cloud progetto per regione supportata.

Utilizza la google_eventarc_google_api_source risorsa Terraform per abilitare gli eventi 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 un'origine Google vengono ora raccolti e pubblicati nel 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 google_eventarc_pipeline risorsa Terraform 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 dell'account di servizio 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 google_eventarc_enrollment risorsa Terraform 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 workflow. 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 eseguire questa operazione una sola volta per directory.

   terraform init

   Facoltativamente, per utilizzare la versione più recente del provider Google, includi l'opzione -upgrade:

   terraform init -upgrade

2. Esamina 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 il comando seguente 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 finché Terraform non visualizza il messaggio "Apply complete!".

Pubblica un messaggio di evento nel bus creando un workflow

Workflows è una piattaforma di orchestrazione completamente gestita che esegue i servizi in un ordine definito da te: un workflow. Crea un workflow 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 workflow nel nuovo file, quindi 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 workflow trasmette la regione in cui viene eseguito il deployment del workflow all' API di Wikipedia e restituisce un elenco di articoli correlati su Wikipedia.

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

   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 qualche minuto e riprova a eseguire il gcloud logging read comando.

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

Libera spazio

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

terraform destroy

Puoi anche eliminare il tuo Google Cloud progetto per evitare addebiti. L'eliminazione del 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 appspot.com URL, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.
1. Nella Google Cloud console, 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