Publish events to a Cloud Run job

Publish events to a Cloud Run job

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 acts as a central router, receiving messages from event sources or published by providers.

• An enrollment routes messages received by the bus to one or more destinations through a processing pipeline.

In this quickstart, you:

1. Deploy a Cloud Run job.

2. Create an Eventarc Advanced bus.

3. Create an Eventarc Advanced enrollment.

4. Publish an event message to the bus.

5. View the event data in the logs and confirm that the Cloud Run job successfully executed.

You can complete this quickstart using the 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.

Install the Google Cloud CLI.

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

To initialize the gcloud CLI, run the following command:

gcloud init

Create or select 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 (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.

• 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.

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Run and Eventarc APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com 

Install the Google Cloud CLI.

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

To initialize the gcloud CLI, run the following command:

gcloud init

Create or select 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 (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.

• 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.

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Run and Eventarc APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com 

1. Update gcloud components:

   gcloud components update

2. Sign in using your account:

   gcloud auth login

3. Set the configuration variable used in this quickstart:

   REGION=REGION

   Replace REGION with a supported location for the bus—for example, us-central1.

4. 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).

   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 Run Developer (roles/run.developer)
   • 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.

5. To give Eventarc Advanced the necessary permissions to execute a Cloud Run job, ask your administrator to grant the Cloud Run Invoker (roles/run.invoker) IAM role on your Google Cloud project to a service account:
   1. Create a service account. For testing purposes, you will attach this service account to an Eventarc Advanced pipeline to represent the identity of the pipeline.

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      Replace SERVICE_ACCOUNT_NAME with a name for your service account.
   2. Grant the roles/run.invoker IAM role to the service account:

      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
          --role=roles/run.invoker

Deploy a Cloud Run job

Deploy a Cloud Run job as your event destination. Unlike a Cloud Run service, which listens for and serves requests, a Cloud Run job only runs its tasks and exits when finished. A job does not listen for or serve requests.

Other event destinations—such as a Pub/Sub topic, Workflows, or another HTTP endpoint—are supported. For more information, see Event providers and destinations.

Deploy a job from a sample container by using the gcloud run jobs deploy command.

gcloud run jobs deploy JOB_NAME --image us-docker.pkg.dev/cloudrun/container/job:latest \
    --region=$REGION

Replace JOB_NAME with a unique name for the Cloud Run job—for example, my-job.

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.

Create an Eventarc Advanced bus in your project by using the gcloud eventarc message-buses create command:

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

Replace BUS_NAME with the ID of your bus or a fully qualified name—for example, my-bus.

Create an Eventarc Advanced enrollment

An enrollment determines which messages are routed to a destination. It also specifies the pipeline used to configure the destination for the event messages. In this case, the target destination is a Cloud Run job.

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

Note: Creating a pipeline might take more than 10 minutes.

When using the gcloud CLI, you first create a pipeline, and then create an enrollment:

1. Create a pipeline by using the gcloud eventarc pipelines create command:

   gcloud eventarc pipelines create PIPELINE_NAME \
       --destinations=http_endpoint_uri='https://REGION-run.googleapis.com/apis/run.googleapis.com/v1/namespaces/PROJECT_NUMBER/jobs/JOB_NAME:run',http_endpoint_message_binding_template='{"body": ""}',oauth_token_authentication_service_account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
       --input-payload-format-json= \
       --location=$REGION

   Replace the following:

   • PIPELINE_NAME: the ID of the pipeline or a fully qualified name—for example, my-pipeline.
   • PROJECT_NUMBER: your Google Cloud project number. You can retrieve your project number by running the following command:

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

   Note the following:

   • The http_endpoint_message_binding_template key transforms the event into the format expected by the Cloud Run Admin API. When defining a message binding, you must configure an input format to access the payload.
   • The oauth_token_authentication_service_account key specifies a service account email. This email is used to generate an OAuth token typically used only when calling Google APIs hosted on *.googleapis.com.

2. Create an enrollment by using the gcloud eventarc enrollments create command:

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

   Replace the following:

   • ENROLLMENT_NAME: the ID of the enrollment or a fully qualified name—for example, my-enrollment.

   • MATCH_EXPRESSION: the matching expression for this enrollment using CEL—for example:

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

Publish an event message to the bus

To directly publish a message to your bus, 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, 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.

The following are examples of directly publishing an event to an Eventarc Advanced bus:

Example 1

Publish an event to a bus by 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

Example 2

Publish an event to a bus as a JSON message by 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, check the logs of your Cloud Run job to verify that the event was received as expected.

1. Filter the log entries and return the output by using the gcloud logging read command:

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

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

   insertId: 670808e70002b5c6477709ae
   labels:
   instanceId: 007989f2a10a4a33c21024f2c8e06a9de65d9b4fdc2ee27697a50379b3fab2f975b9233dc357d50b06270829b9b479d5a1ee54a10fa2cb2d98c5f77a0895e2be0f9e6e4b20
   logName: projects/PROJECT_ID/logs/run.googleapis.com%2Fstderr
   receiveTimestamp: '2025-10-06T21:15:22.988264020Z'
   resource:
   labels:
   ...
   type: cloud_run_revision
   textPayload: "[2025-10-06 21:15:22,676] INFO in server: Body: b'{\"key\": \"hello-world-data\"\
     }'"
   timestamp: '2025-10-06T21:15:22.675530Z'
   

   Note: If you don't see a log entry, wait a few minutes and retry the gcloud logging read command.

3. Confirm that the Cloud Run job executed successfully by using the gcloud run jobs describe command:

   gcloud run jobs describe JOB_NAME \
       --region=$REGION
   

   You should receive output similar to the following:

   ✔ Job JOB_NAME in region us-central1
   Executed 1 time
   ...
   

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.

Clean up

To help avoid continued billing after you finish this quickstart, delete the resources that you created:

1. Delete a Cloud Run job.

2. Delete Eventarc Advanced resources:

   1. Delete an enrollment.

   2. Delete a pipeline.

   3. Delete a bus.

Alternatively, delete your Google Cloud project to help 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.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

What's next

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