Publish events from Google sources

Advanced

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:

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

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

Go to Bus
You can create a bus or, if you are updating a bus, click Edit.
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.
Click Save.

gcloud

Open a terminal.
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:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json. Run the following command in the terminal to create or overwrite this file in the current directory:

cat > request.json << 'EOF'
{
  "displayName": "GOOGLE_API_SOURCE_NAME",
  "labels": {"LABEL_KEY":"LABEL_VALUE"},
  "annotations": {"ANNOTATION_KEY":"ANNOTATION_VALUE"},
  "destination": "DESTINATION",
  "cryptoKeyName": "ENCRYPT_KEY",
  "loggingConfig": {"logSeverity":"LOG_SEVERITY"}
}
EOF

Then execute the following command to send your REST request:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://eventarc.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/googleApiSources?googleApiSourceId=GOOGLE_API_SOURCE_NAME"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json. Run the following command in the terminal to create or overwrite this file in the current directory:

@'
{
  "displayName": "GOOGLE_API_SOURCE_NAME",
  "labels": {"LABEL_KEY":"LABEL_VALUE"},
  "annotations": {"ANNOTATION_KEY":"ANNOTATION_VALUE"},
  "destination": "DESTINATION",
  "cryptoKeyName": "ENCRYPT_KEY",
  "loggingConfig": {"logSeverity":"LOG_SEVERITY"}
}
'@  | Out-File -FilePath request.json -Encoding utf8

Then execute the following command to send your REST request:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://eventarc.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/googleApiSources?googleApiSourceId=GOOGLE_API_SOURCE_NAME" | Select-Object -Expand Content

APIs Explorer (browser)

Copy the request body and open the method reference page. The APIs Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Paste the request body in this tool, complete any other required fields, and click Execute.

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

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

Go to Bus details
Click Edit.
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).
At the Delete resource prompt, click Confirm.
Click Save.

gcloud

Open a terminal.
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:

curl (Linux, macOS, or Cloud Shell)

Execute the following command:

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://eventarc.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/googleApiSources/GOOGLE_API_SOURCE_NAME"

PowerShell (Windows)

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://eventarc.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/googleApiSources/GOOGLE_API_SOURCE_NAME" | Select-Object -Expand Content

APIs Explorer (browser)

Open the method reference page. The APIs Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Complete any required fields and click Execute.

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.

Publish events from Google sources

Before you begin

Console

gcloud

Enable events from Google sources

Console

gcloud

REST API

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

APIs Explorer (browser)

Disable events from Google sources

Console

gcloud

REST API

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

APIs Explorer (browser)

Publish events from multiple projects

1. Grant the Eventarc service agent the appropriate IAM role

2. Publish from all projects or a list of projects

What's next