Trigger functions from Cloud Storage using Eventarc

This tutorial shows you how to deploy an event-driven function in Cloud Run,and use Eventarc to trigger the function in response toCloud Storage events using the Google Cloud CLI.

By specifying filters for an Eventarc trigger, you canconfigure the routing of events, including the event source and the eventtarget. For the example in this tutorial, an update to a Cloud Storage bucket triggersthe event, and a request is sent to your function in the form of an of HTTP request.

Objectives

In this tutorial, you will:

  1. Create a Cloud Storage bucket to be the event source.
  2. Deploy an event-driven function.
  3. Create an Eventarc trigger.
  4. Trigger the function by uploading a file to Cloud Storage.

Costs

In this document, you use the following billable components of Google Cloud:

To generate a cost estimate based on your projected usage, use thepricing calculator.

New Google Cloud users might be eligible for afree trial.

Before you begin

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

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

  2. Install the Google Cloud CLI.

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

  4. Toinitialize the gcloud CLI, run the following command:

    gcloudinit

  5. 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 role (roles/resourcemanager.projectCreator), which contains theresourcemanager.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 createPROJECT_ID

      ReplacePROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set projectPROJECT_ID

      ReplacePROJECT_ID with your Google Cloud project name.

  6. Verify that billing is enabled for your Google Cloud project.

  7. Install the Google Cloud CLI.

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

  9. Toinitialize the gcloud CLI, run the following command:

    gcloudinit

  10. 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 role (roles/resourcemanager.projectCreator), which contains theresourcemanager.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 createPROJECT_ID

      ReplacePROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set projectPROJECT_ID

      ReplacePROJECT_ID with your Google Cloud project name.

  11. Verify that billing is enabled for your Google Cloud project.

  12. If you are not using Cloud Shell, update the Google Cloud CLIcomponents and log in using your account:
    gcloudcomponentsupdategcloudauthlogin
  13. Enable the APIs:
    gcloudservicesenableartifactregistry.googleapis.com\cloudbuild.googleapis.com\eventarc.googleapis.com\run.googleapis.com\storage.googleapis.com
  14. Set the configuration variables to use in this tutorial:
    exportREGION=us-central1gcloudconfigsetrun/region${REGION}gcloudconfigsetrun/platformmanagedgcloudconfigseteventarc/location${REGION}

  15. If you are under a domain restriction organization policyrestricting unauthenticated invocations for your project, you will need to access your deployed service as described underTesting private services.

Set required roles

You or your administrator must grant the deployer account, the trigger identity,and optionally, the Pub/Sub service agent and the Cloud Storageservice agent the following IAM roles.

Required roles for the deployer account

  1. If you are the project creator, you are granted thebasic Owner role(roles/owner). By default, this Identity and Access Management (IAM) roleincludes the permissions necessary for full access to most Google Cloudresources and you can skip this step.

    If you are not the project creator, required permissions must be granted onthe project to the appropriateprincipal. For example, a principal can bea Google Account (for end users) or a service account (for applications andcompute workloads). For more information, see theRoles and permissions pagefor your event destination.

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

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

    You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

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

Required roles for the trigger identity

  1. Make note of theCompute Enginedefault service account as you will you attach it to an Eventarc trigger to representthe identity of the trigger for testing purposes. This service account is automatically createdafter enabling or using a Google Cloud service that uses Compute Engine, and with thefollowing email format:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    ReplacePROJECT_NUMBER with your Google Cloudproject number. You can find your project number on theWelcomepage of the Google Cloud console or by running the following command:

    gcloudprojectsdescribePROJECT_ID--format='value(projectNumber)'

    For production environments, we strongly recommendcreating a new service accountand granting it one or more IAM roles that contain theminimum permissions requiredand follow the principle ofleast privilege.

    Note:

    Theiam.automaticIamGrantsForDefaultServiceAccounts organization policy constraint prevents the Editor role from being automatically granted to default service accounts. If you created your organization after May 3, 2024, this constraint is enforced by default.

    We strongly recommend that you enforce this constraint to disable the automatic role grant. If you disable the automatic role grant, you must decide which roles to grant to the default service accounts, and thengrant these roles yourself.

    If the default service account already has the Editor role, we recommend that you replace the Editor role with less permissive roles.To safely modify the service account's roles, usePolicy Simulator to see the impact of the change, and thengrant and revoke the appropriate roles.

  2. By default, Cloud Run services are only callable by ProjectOwners, Project Editors, and Cloud Run Admins and Invokers.You cancontrolaccess on a per-service basis; however, for testing purposes, grant theCloud RunInvoker role (run.invoker) on the Google Cloud project to theCompute Engine service account. This grants the role on allCloud Run services and jobs in a project.
    gcloudprojectsadd-iam-policy-bindingPROJECT_ID\--member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com\--role=roles/run.invoker

    Note that if you create a trigger for an authenticatedCloud Run service without granting the Cloud RunInvoker role, the trigger is created successfully and is active. However, thetrigger will not work as expected and a message similar to the following appearsin the logs:

    The request was not authenticated. Either allowunauthenticated invocations or set the proper Authorization header.
  3. Grant theEventarcEvent Receiver role (roles/eventarc.eventReceiver) on theproject to the Compute Engine default service account so thatthe Eventarc trigger can receive events from event providers.
    gcloudprojectsadd-iam-policy-bindingPROJECT_ID\--member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com\--role=roles/eventarc.eventReceiver

Optional role for the Cloud Storage service agent

  • Before creating a trigger for direct events from Cloud Storage,grant thePub/SubPublisher role (roles/pubsub.publisher) to theCloud Storage service agent:

    SERVICE_ACCOUNT="$(gcloudstorageservice-agent--project=PROJECT_ID)"gcloudprojectsadd-iam-policy-bindingPROJECT_ID\--member="serviceAccount:${SERVICE_ACCOUNT}"\--role='roles/pubsub.publisher'

Optional role for the Pub/Sub service agent

  • If you enabled the Cloud Pub/Sub service agent on or before April8, 2021, to support authenticated Pub/Sub push requests, granttheServiceAccount Token Creator role (roles/iam.serviceAccountTokenCreator)to the service agent. Otherwise, this role is granted by default:
    gcloudprojectsadd-iam-policy-bindingPROJECT_ID\--member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com\--role=roles/iam.serviceAccountTokenCreator

Create a Cloud Storage bucket

Create a Cloud Storage bucket to use as the event source:

gcloudstoragebucketscreate-lus-central1gs://PROJECT_ID-bucket/
Note: The Cloud Storage bucket must reside in the sameGoogle Cloud project andregion or multi-region as the Eventarc trigger.

Write an event-driven function

To write an event-driven function, follow these steps:

Node.js

  1. Create a new directory namedhelloGCS and change directory into it:

       mkdir helloGCS   cd helloGCS

  2. Create apackage.json file in thehelloGCS directory to specifyNode.js dependencies:

    {"name":"nodejs-docs-samples-functions-v2-storage","version":"0.0.1","private":true,"license":"Apache-2.0","author":"Google LLC","repository":{"type":"git","url":"https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git"},"engines":{"node":">=16.0.0"},"scripts":{"test":"c8 mocha -p -j 2 test/*.test.js --timeout=60000"},"dependencies":{"@google-cloud/functions-framework":"^3.0.0"},"devDependencies":{"c8":"^10.0.0","mocha":"^10.0.0","sinon":"^18.0.0","supertest":"^7.0.0"}}

  3. Create anindex.js file in thehelloGCS directory with the followingNode.js sample:

    constfunctions=require('@google-cloud/functions-framework');// Register a CloudEvent callback with the Functions Framework that will// be triggered by Cloud Storage.functions.cloudEvent('helloGCS',cloudEvent=>{console.log(`Event ID:${cloudEvent.id}`);console.log(`Event Type:${cloudEvent.type}`);constfile=cloudEvent.data;console.log(`Bucket:${file.bucket}`);console.log(`File:${file.name}`);console.log(`Metageneration:${file.metageneration}`);console.log(`Created:${file.timeCreated}`);console.log(`Updated:${file.updated}`);});

Python

  1. Create a new directory namedhelloGCS and change directory into it:

       mkdir helloGCS   cd helloGCS

  2. Create arequirements.txt file in thehelloGCS directory, to specifyPython dependencies:

    functions-framework==3.9.2cloudevents==1.11.0

    This adds packages needed by the sample.

  3. Create amain.py file in thehelloGCS directory with the followingPython sample:

    fromcloudevents.httpimportCloudEventimportfunctions_framework# Triggered by a change in a storage bucket@functions_framework.cloud_eventdefhello_gcs(cloud_event:CloudEvent)->tuple:"""This function is triggered by a change in a storage bucket.    Args:        cloud_event: The CloudEvent that triggered this function.    Returns:        The event ID, event type, bucket, name, metageneration, and timeCreated.    """data=cloud_event.dataevent_id=cloud_event["id"]event_type=cloud_event["type"]bucket=data["bucket"]name=data["name"]metageneration=data["metageneration"]timeCreated=data["timeCreated"]updated=data["updated"]print(f"Event ID:{event_id}")print(f"Event type:{event_type}")print(f"Bucket:{bucket}")print(f"File:{name}")print(f"Metageneration:{metageneration}")print(f"Created:{timeCreated}")print(f"Updated:{updated}")returnevent_id,event_type,bucket,name,metageneration,timeCreated,updated

Deploy an event-driven function

Deploy the function namedhelloworld-events by running the following commandin the directory that contains the sample code:

Node.js

gcloud run deploy helloworld-events \      --source . \      --function helloGCS \      --base-imageBASE_IMAGE \      --region us-central1

ReplaceBASE_IMAGE with the base image environment for your function,for example,nodejs24. For more details about baseimages and the packages included in each image, seeSupported language runtimes and base images.

Python

gcloud run deploy helloworld-events \      --source . \      --function hello_gcs \      --base-imageBASE_IMAGE \      --region us-central1

ReplaceBASE_IMAGE with the base image environment for your function,for example,python313. For more details about baseimages and the packages included in each image, seeSupported language runtimes and base images.

When the deployment is complete, the Google Cloud CLI displays a URL whereyour service is running.

Create an Eventarc trigger

The Eventarc trigger sends events from theCloud Storage bucket to yourhelloworld-events Cloud Runservice.

  1. Create a trigger that filters Cloud Storage events:

    gcloudeventarctriggerscreateTRIGGER_NAME\--location=${REGION}\--destination-run-service=helloworld-events\--destination-run-region=${REGION}\--event-filters="type=google.cloud.storage.object.v1.finalized"\--event-filters="bucket=PROJECT_ID-bucket"\--service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Replace:

    • TRIGGER_NAME with the name for your trigger.
    • PROJECT_ID with your Google Cloud project ID.
    • PROJECT_NUMBER with your Google Cloud project number.

    Note that when creating an Eventarc trigger for the firsttime in a Google Cloud project, there might be a delay in provisioningthe Eventarc service agent. This issue can usually be resolvedby attempting to create the trigger again. For more information, seePermission denied errors.

  2. Confirm that the trigger was successfully created. Note that although yourtrigger is created immediately, it can take up to two minutes for a triggerto be fully functional.

    gcloudeventarctriggerslist--location=${REGION}

    The output should be similar to the following:

    NAME: helloworld-eventsTYPE: google.cloud.storage.object.v1.finalizedDESTINATION: Cloud Run service: helloworld-eventsACTIVE: YesLOCATION: us-central1

Generate and view an event

Upload a text file to the Cloud Storage bucket to generate an eventwhich is routed to the function. TheCloud Run function logs the event in the service logs.

  1. Upload a text file to Cloud Storage, to generate an event:

     echo "Hello World" > random.txt gcloud storage cp random.txt gs://PROJECT_ID-bucket/random.txt

    The upload generates an event and the Cloud Runfunction logs the event's message.

  2. To view the log entry:

    1. Filter the log entries and return the output in JSON format:

      gcloud logging read "resource.labels.service_name=helloworld-events AND textPayload:random.txt" --format=json

    2. Look for a log entry similar to:

      [  {   ....    "resource": {      "labels": {        ....        "location": "us-central1",        .....        "service_name": "helloworld-events"      },    },    "textPayload": "File: random.txt",     .....  }]
      Note: If you don't see a log entry, wait a few minutes and retry thegcloud logging read command. The trigger can take up to two minutesafter being created to start filtering events.

      Logs might take a few moments to appear. If you don't see them immediately,check again after a minute.

After you see the log entry, this confirms that you have successfully deployed an event-driven function that was triggered when a text file was uploaded to Cloud Storage.

Success: You deployed an event-driven function in Cloud Runand used Eventarc to trigger the function in response toCloud Storage events.

Clean up

If you created a new project for this tutorial,delete the project.If you used an existing project and want to keep it without the changes addedin this tutorial,delete the resources created for the tutorial.

Delete the project

The easiest way to eliminate billing is to delete the project that you created for the tutorial.

To delete the 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 anappspot.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 theManage resources page.

    Go to Manage resources

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

Delete tutorial resources

  1. Delete the Cloud Run service you deployed in this tutorial:

    gcloudrunservicesdeleteSERVICE_NAME

    WhereSERVICE_NAME is your chosen service name.

    You can also delete Cloud Run services from theGoogle Cloud console.

  2. Remove any gcloud CLI default configurations you added duringthe tutorial setup.

    For example:

    gcloud config unset run/region

    or

    gcloud config unset project

  3. Delete other Google Cloud resources created in this tutorial:

    • Delete the Eventarc trigger:
      gcloud eventarc triggers deleteTRIGGER_NAME
      ReplaceTRIGGER_NAME with the name of yourtrigger.

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-17 UTC.