Publish and receive events by creating a bus and enrollment (console)

Publish and receive events by creating a bus and enrollment (console)

Advanced

This quickstart shows you how to publish and receive event messages by creating an Eventarc Advanced bus and enrollment in your Google Cloud project.

• A bus lets you centralize the flow of messages through your system, and acts as a router. It receives event messages from a message source or published by a provider, and evaluates them according to an enrollment.

• An enrollment identifies a subscription to a particular bus, and defines the matching criteria for messages, causing them to be routed accordingly to one or more destinations.

In this quickstart, you:

1. Create an Artifact Registry standard repository.

2. Deploy an event receiver service to Cloud Run.

3. Create an Eventarc Advanced bus.

4. Create an Eventarc Advanced enrollment.

5. Publish an event message to the bus.

6. View the event data in the Cloud Run logs.

You can complete most of the steps in this quickstart using the Google Cloud console. To complete all of the steps using the Google Cloud CLI, see Publish and receive events by creating a bus and enrollment (gcloud CLI).

Before you begin

Security constraints defined by your organization might prevent you from completing the following steps. For troubleshooting information, see Develop applications in a constrained Google Cloud environment.

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.

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

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

Verify that billing is enabled for your Google Cloud project.

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

Enable the APIs

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

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

Verify that billing is enabled for your Google Cloud project.

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

Enable the APIs

1. A few steps in this quickstart require that you use the gcloud CLI:
   1. Set up the gcloud CLI in one of the following development environments:

      Cloud Shell

      To use an online terminal with the gcloud CLI already set up, activate Cloud Shell:

      At the bottom of this page, a Cloud Shell session starts and displays a command-line prompt. It can take a few seconds for the session to initialize.

      Local shell

      To use a local development environment, follow these steps:

      1. Install the gcloud CLI.
      2. Initialize the gcloud CLI.
   2. Select your Google Cloud project:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

   3. Update gcloud components:

      gcloud components update

   4. Sign in using your account:

      gcloud auth login

   5. Set the configuration variable used in this quickstart:

      REGION=us-central1

2. If you are the project creator, you are granted the basic Owner role (roles/owner). By default, this Identity and Access Management (IAM) role includes the permissions necessary for full access to most Google Cloud resources and you can skip this step.

   If you are not the project creator, required permissions must be granted on the project to the appropriate principal. For example, a principal can be a Google Account (for end users) or a service account (for applications and compute workloads).

   Note that by default, Cloud Build permissions include permissions to upload and download Artifact Registry artifacts.

   Required permissions

   To get the permissions that you need to complete this quickstart, ask your administrator to grant you the following IAM roles on your project:

   • Cloud Build Editor (roles/cloudbuild.builds.editor)
   • 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)
   • Service Usage Admin (roles/serviceusage.serviceUsageAdmin)

   For more information about granting roles, see Manage access to projects, folders, and organizations.

   You might also be able to get the required permissions through custom roles or other predefined roles.

3. Grant roles on the project to the Compute Engine default service account. These roles are needed to build and deploy your container image.
   1. In the Google Cloud console, go to the IAM page.
      

      Go to IAM

   2. To modify roles for the service account if it already has roles on the resource, find a row containing the principal.

      or

      To grant roles to the service account when it doesn't have any roles on the resource, click Grant Access, and then enter the identifier for the Compute Engine default service account with the following form:

      [e-mail]

      Replace PROJECT_NUMBER with your Google Cloud project number. You can find your project number on the Welcome page of the Google Cloud console.

   3. Click Edit principal in the corresponding row.
   4. Click either Add role or Add another role.
   5. In the Select a role list, filter for and select the following roles:
      • Artifact Registry Writer: to upload Artifact Registry artifacts
      • Logs Writer: to write logs to Cloud Logging
      • Storage Object User: to access Cloud Storage objects
   6. Click Save.
4. By default, only Project Owners, Project Editors, and Cloud Run Admins and Invokers can call Cloud Run services. To set up authentication, grant the Cloud Run Invoker role on your Google Cloud project to a service account. For testing purposes, you will attach this service account to an Eventarc Advanced pipeline to represent the identity of the pipeline.
   1. In the Google Cloud console, go to the Service accounts page.
      

      Go to Service accounts

   2. Click Create service account.
   3. Enter a Service account name.
   4. Click Create and continue.
   5. In the Select a role list, filter for and select the Cloud Run Invoker role.
   6. Click Done.

   Note that you can configure who can access your Cloud Run service in either of the following ways:

   • Grant permission to select service accounts or groups to allow access to the service. All requests must have an HTTP Authorization header containing an OpenID Connect token signed by Google for one of the authorized service accounts. This is the way that access is configured in this quickstart.
   • Grant permission to allUsers to allow unauthenticated access.

   For more information, see Access control for Cloud Run.

Create an Artifact Registry standard repository

Create an Artifact Registry standard repository to store your container image.

1. In the Google Cloud console, go to the Repositories page.

   Go to Repositories

2. Click Create repository.

3. Enter a Name—for example, my-repo.

   For each repository location in a project, repository names must be unique.

4. For the repository Format, select Docker.

5. In the Region list, select us-central1 (Iowa).

6. Accept all the other defaults.

7. Click Create.

Deploy an event receiver service to Cloud Run

Deploy a Cloud Run service that logs the contents of an event. Other event destinations are supported such as a Pub/Sub topic, Workflows, or an HTTP endpoint. For more information, see Event providers and destinations.

1. In your terminal, clone the GitHub repository:

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

2. Change to the directory that contains the Cloud Run sample code:

   cd eventarc-samples/eventarc-advanced-quickstart/

3. Build a Docker container image and push the image to your repository:

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

   Replace REPOSITORY with the name of your Artifact Registry repository.

4. Deploy the container image to Cloud Run:

   1. In the Google Cloud console, go to the Cloud Run page.

      Go to Cloud Run

   2. Click Deploy container > Service.

   3. Select Deploy one revision from an existing container image.

   4. For the Container image URL, click Select to specify the Artifact Registry container image you previously created.

   5. Optionally, you can change the Service name—for example, to my-service.

   6. In the Region list, select us-central1 (Iowa).

   7. For Authentication, select Require authentication.

      This configures the service to only allow authenticated invocations.

   8. For Ingress, select All.

      This allows all requests, including requests directly from the internet to the run.app URL. For more information, see Restrict network ingress for Cloud Run.

   9. Accept all the other defaults.

   10. Click Create and wait for the deployment to finish.

Create an Eventarc Advanced bus

A bus receives event messages from a message source or published by a provider and acts as a message router.

For more information, see Create a bus to route messages.

Note: You can create one bus per Google Cloud project per supported region.

1. In the Google Cloud console, go to the Eventarc > Bus page.

   Go to Bus

2. Click Create bus.

3. On the Create a bus page, do the following:

   1. Enter a Bus name—for example, my-bus.
   2. In the Region list, select us-central1 (Iowa).

4. Accept all the other defaults.

5. Click Create.

Create an Eventarc Advanced enrollment

An enrollment determines which messages are routed to a destination and it also specifies the pipeline that is used to configure a destination for the event messages.

For more information, see Create an enrollment to receive events.

When using the Google Cloud console, you can create an enrollment and a pipeline at the same time.

Note: Creating an enrollment and pipeline might take more than 10 minutes.

1. To create an enrollment, in the Google Cloud console, go to the Eventarc > Pipelines page.

   Go to Pipelines

2. Click Create pipeline.

3. In the Pipeline details pane, do the following:

   1. Enter a Pipeline name—for example, my-pipeline.
   2. In the Region list, select us-central1 (Iowa). The pipeline must be created in the same region as the bus.
   3. Accept all the other defaults.
   4. Click Continue.

4. In the Enrollments pane, do the following:

   1. Click Add an enrollment.
   2. Enter an Enrollment name—for example, my-enrollment.
   3. In the Eventarc Advanced Bus list, select the bus you previously created.

   4. In the CEL expression field, write an evaluation expression using CEL. For example:

      message.type == "hello-world-type"
      

   5. Click Done.

   6. Click Continue.

   7. In the Event mediation pane, click Continue again.

5. In the Destination pane, do the following:

   1. In the Destination type list, select Cloud Run service (via HTTP) and then select the Cloud Run service you previously created.

   2. Select the Enable authentication checkbox.

      1. In the Auth header list, select OIDC token.

      2. In the Service account list, select the service account that you previously created and that will invoke your destination service. This service account email is used to generate the OIDC token.

6. Click Create.

Publish an event message to the bus

To directly publish a message to your bus, you can use the gcloud eventarc message-buses publish command or send a request to the Eventarc Publishing REST API. For more information, see Publish events directly.

The message must be in a CloudEvents format which is a specification for describing event data in a common way. The data element is the payload of your event. Any well-formed JSON can go in this field. For more information about CloudEvents context attributes, see Event format.

Publish an event to your Eventarc Advanced bus using the gcloud CLI and an --event-data and other event attribute flags:

gcloud 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

Or, publish an event to your Eventarc Advanced bus as a JSON message using the gcloud CLI and a --json-message flag:

gcloud 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"}}'

After publishing an event, you should receive an "Event published successfully" message.

View the event data in the Cloud Run logs

After publishing an event to your Eventarc Advanced bus, you can check the logs of your Cloud Run service to verify that the event was received as expected.

1. In the Google Cloud console, go to the Cloud Run page.

   Go to Cloud Run

2. On the Services page, click the name of your service.

3. Click the Logs tab.

4. You can filter the log entries and return the output. For example, you can search for hello-world-data.

5. Look for a log entry similar to the following:

   2025-02-27 08:36:44.350 EST [2025-02-27 13:36:44,352] INFO in server: Body: b'{"key": "hello-world-data"}'
   

   Note: If you don't see a log entry, wait a few minutes and retry the search.

You have successfully created an Eventarc Advanced bus and enrollment, published an event message to the bus, and verified the expected outcome in the logs of the event receiver service.

Clean up

When you finish the tasks that are described in this quickstart, you can avoid continued billing by deleting the resources that you created:

1. Delete an Artifact Registry repository.

2. Delete a Cloud Run service.

3. Delete Eventarc Advanced resources:

   1. Delete an enrollment.

   2. Delete a pipeline.

   3. Delete a bus.

Alternatively, you can delete your Google Cloud project to avoid incurring charges. Deleting your Google Cloud project stops billing for all the resources used within that project.

Caution: Deleting a project has the following effects:

• Everything in the project is deleted. If you used an existing project for the tasks in this document, when you delete it, you also delete any other work you've done in the project.
• Custom project IDs are lost. When you created this project, you might have created a custom project ID that you want to use in the future. To preserve the URLs that use the project ID, such as an appspot.com URL, delete selected resources inside the project instead of deleting the whole project.

If you plan to explore multiple architectures, tutorials, or quickstarts, reusing projects can help you avoid exceeding project quota limits.

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

What's next

• Publish events from Google sources
• Publish events directly
• Transform received events
• Format received events