Publish events from Google sources

You can enable the collecting and publishing of events from Google sources for a specific Eventarc Advanced bus by creating a GoogleApiSource resource.

Events from Google sources are directly triggered by an unmediated event such as the creation of a Cloud Run function or a status change to a Dataflow job. For more information, see Google event types supported by Eventarc.

Note the following:

  • By default, events are collected from the Google Cloud project where the GoogleApiSource resource exists. You can also use the gcloud CLI to collect events from multiple projects that are in the same organization as the GoogleApiSource resource. For more information, in this document, see Publish events from multiple projects.
  • You can publish events to a bus that is in a different Google Cloud project from the one in which the GoogleApiSource resource exists. You can configure this by using the gcloud CLI or by sending a request to the Eventarc API (but not through the Google Cloud console).
  • There is a limit of one GoogleApiSource resource per Google Cloud project per region.

Before you begin

Before you start, make sure that you have completed the following steps:

  1. If you are using the Google Cloud CLI to run the commands on this page, install and then initialize the gcloud CLI. If you previously installed the gcloud CLI, get the latest version by running gcloud components update.

  2. Enable the Eventarc API and the Eventarc Publishing API:

    Console

    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.

    Enable the APIs

    gcloud

    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

Enable events from Google sources

To publish events from Google sources, you must create a GoogleApiSource resource. This resource represents a subscription to Google API events in a specific Google Cloud project for a particular Eventarc Advanced bus.

You can enable the publishing of events from Google sources in the following ways:

  • In the Google Cloud console
  • By using the Google Cloud CLI in either your terminal or Cloud Shell
  • By sending a request to the Eventarc API

Console

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

    Go to Bus

  2. You can create a bus or, if you are updating a bus, click Edit.

  3. On the Edit bus page, to add a message source, click Add source.

    1. In the Add message source pane, for the Google API message provider, accept the default of google-api-source or enter a different message source name.
    2. Click Create.
  4. Click Save.

gcloud

  1. Open a terminal.

  2. You can enable events from Google sources by using the gcloud eventarc google-api-sources create command:

    gcloud eventarc google-api-sources create GOOGLE_API_SOURCE_NAME \
        --destination-message-bus=BUS_NAME \
        --destination-message-bus-project=BUS_PROJECT_ID

    Replace the following:

    • GOOGLE_API_SOURCE_NAME: the ID or fully qualified identifier of your GoogleApiSource resource which represents a subscription to Google API events for a particular bus
    • BUS_NAME: the ID or fully qualified identifier of the bus for which you want to subscribe to Google API events
    • BUS_PROJECT_ID: the Google Cloud project ID for the bus

    Optional: You can also use the following flags:

    • --async to return from the command immediately, without waiting for the operation in progress to complete.
    • --crypto-key to specify the fully qualified name of a customer-managed encryption key; if unspecified, Google-owned and managed keys are used.
    • --logging-config to configure the logging level which must be one of the following: NONE, DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT, EMERGENCY. For more information, see LogSeverity.

REST API

To enable events from Google sources, use the projects.locations.googleApiSources.create method.

Before using any of the request data, make the following replacements:

  • GOOGLE_API_SOURCE_NAME: the display name of the GoogleApiSource resource which represents a subscription to Google API events for a particular bus—for example, my_google_source.
  • LABEL_KEY and LABEL_VALUE: optional. A map of label key and value pairs that help you organize your Google Cloud resources. For more information, see What are labels?
  • ANNOTATION_KEY and ANNOTATION_VALUE: optional. A map of annotation key and value pairs of free-form text. You can use them to attach arbitrary information associated with the resource. For more information, see Annotations.
  • DESTINATION: the fully qualified identifier of the Eventarc Advanced bus to which Google source events should be published in the format projects/PROJECT_NAME/locations/LOCATION/messageBuses/BUS_NAME. For more information, see Create a bus to route messages.
  • ENCRYPT_KEY: optional. A Cloud KMS key that the GoogleApiSource resource should use for data encryption in the format projects/PROJECT_NAME/locations/LOCATION/keyRings/RING_NAME/cryptoKeys/KEY_NAME. For more information, see Use customer-managed encryption keys.
  • PROJECT_ID: the Google Cloud project ID in which to create the GoogleApiSource resource.
  • LOCATION: the supported region in which to create the GoogleApiSource resource—for example, us-central1.
  • LOG_SEVERITY: optional. The minimum severity of the event described in a log entry. One of: NONE, DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT, EMERGENCY. The default is NONE. For more information, see LogSeverity.

Request JSON body:

{
  "displayName": "GOOGLE_API_SOURCE_NAME",
  "labels": {"LABEL_KEY":"LABEL_VALUE"},
  "annotations": {"ANNOTATION_KEY":"ANNOTATION_VALUE"},
  "destination": "DESTINATION",
  "cryptoKeyName": "ENCRYPT_KEY",
  "loggingConfig": {"logSeverity":"LOG_SEVERITY"}
}

To send your request, expand one of these options:

If successful, the response body contains a newly created instance of Operation:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.eventarc.v1.OperationMetadata",
    "createTime": "2024-01-25T17:17:45.782370139Z",
    "target": "projects/PROJECT_ID/locations/LOCATION/googleApiSources/GOOGLE_API_SOURCE_NAME",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

Events from Google sources in the same Google Cloud project as the GoogleApiSource resource are now collected and published to the bus.

Disable events from Google sources

To disable the publishing of events from Google sources in a specific Google Cloud project to an Eventarc Advanced bus, you must delete the GoogleApiSource resource.

You can disable the publishing of events from Google sources in the following ways:

  • In the Google Cloud console
  • By using the gcloud CLI in either your terminal or Cloud Shell
  • By sending a request to the Eventarc API

Console

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

    Go to Bus details

  2. Click Edit.

  3. On the Edit bus page, to delete the Google API message provider, click Delete resource for the google-api-source message source (or the name you have given it).

  4. At the Delete resource prompt, click Confirm.

  5. Click Save.

gcloud

  1. Open a terminal.

  2. You can disable events from Google sources by using the gcloud eventarc google-api-sources delete command:

    gcloud eventarc google-api-sources delete GOOGLE_API_SOURCE_NAME \
        --location=REGION

    Replace the following:

    • GOOGLE_API_SOURCE_NAME: the ID or fully qualified identifier of the GoogleApiSource resource
    • REGION: the location of the GoogleApiSource resource

REST API

To disable events from Google sources, use the projects.locations.googleApiSources.delete method.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: the Google Cloud project ID in which the GoogleApiSource resource is created.
  • LOCATION: the region in which the GoogleApiSource resource is created—for example, us-central1.
  • GOOGLE_API_SOURCE_NAME: the name of the GoogleApiSource resource you want to delete.

To send your request, expand one of these options:

If successful, the response body contains a newly created instance of Operation:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.eventarc.v1.OperationMetadata",
    "createTime": "2024-01-25T17:17:45.782370139Z",
    "target": "projects/PROJECT_ID/locations/LOCATION/googleApiSources/GOOGLE_API_SOURCE_NAME",
    "verb": "delete",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

Events from Google sources in the same Google Cloud project as the deleted GoogleApiSource resource are no longer collected and published.

Publish events from multiple projects

To collect and publish Google source events from multiple Google Cloud projects, you must create a GoogleApiSource resource, and the projects must be in the same organization as the GoogleApiSource resource. For more information about organizations, see Resource hierarchy.

Note the following:

  • Event publishing from multiple projects must be configured using the gcloud CLI and is not displayed in the Google Cloud console.
  • If the project containing the GoogleApiSource resource is moved to a different organization, publishing events from multiple projects will no longer function as expected. You must update or re-create the GoogleApiSource resource.

1. Grant the Eventarc service agent the appropriate IAM role

To collect events at the organization level, use the gcloud organizations add-iam-policy-binding command to grant the Eventarc service agent the appropriate Identity and Access Management (IAM) role:

gcloud organizations add-iam-policy-binding ORGANIZATION_ID \
    --member="SERVICE_AGENT_EMAIL" \
    --role="roles/eventarc.multiProjectEventCollector"

Replace the following:

  • ORGANIZATION_ID: your organization resource ID.
  • SERVICE_AGENT_EMAIL: the email address for the Eventarc primary service agent in the project where you are creating the GoogleApiSource resource. The email address is in the following format:

    service-PROJECT_NUMBER@gcp-sa-eventarc.iam.gserviceaccount.com
    

    Replace PROJECT_NUMBER with your Google Cloud project number. You can find your project number on the Welcome page of the Google Cloud console or by running the following command:

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

2. Publish from all projects or a list of projects

To publish events from Google sources in multiple projects, use the gcloud eventarc google-api-sources create command in either of the following ways:

  • Publish from all Google Cloud projects in the same organization as the GoogleApiSource resource:

    gcloud eventarc google-api-sources create GOOGLE_API_SOURCE_NAME \
        --location=REGION \
        --destination-message-bus=BUS_NAME \
        --destination-message-bus-project=BUS_PROJECT_ID \
        --organization-subscription
  • Publish from a list of Google Cloud projects in the same organization as the GoogleApiSource resource:

    gcloud eventarc google-api-sources create GOOGLE_API_SOURCE_NAME \
        --location=REGION \
        --destination-message-bus=BUS_NAME \
        --destination-message-bus-project=BUS_PROJECT_ID \
        --project-subscriptions=LIST_OF_PROJECTS

    Replace the following:

    • GOOGLE_API_SOURCE_NAME: the ID or fully qualified identifier of the GoogleApiSource resource
    • REGION: the location of the GoogleApiSource resource
    • BUS_NAME: the ID or fully qualified identifier of the bus for which you want to subscribe to Google API events
    • BUS_PROJECT_ID: the Google Cloud project ID for the bus
    • LIST_OF_PROJECTS: a comma-delimited list of Google Cloud project IDs or project numbers. You can combine IDs and numbers in the same list. To publish events from the Google Cloud project containing the GoogleApiSource resource, you must explicitly include the project ID or number in the list.

What's next