Executing asynchronous tasks Stay organized with collections Save and categorize content based on your preferences.
You can use Cloud Tasks to securely enqueue a task to beasynchronously processed by a Cloud Run service. Typical use casesinclude:
- Preserving requests through unexpected production incidents
- Smoothing traffic spikes by delaying work that is not user-facing
- Speeding user response time by delegating slow background operations to be handledby another service, such as database updates or batch processing
- Limiting the call rate to backing services like databases and third-party APIs
This page shows how to enqueue tasks that are securely pushed via the HTTPS protocolto a private Cloud Run service. It describes required behavior for theprivate Cloud Run service, required service account permissions,task queue creation, and task creation.
Before you start
Enable the Cloud Tasks API on the project you are using.
Deploying a Cloud Run service to handle tasks
To deploy a service that accepts tasks sent to the task queue,deploy the service in the same way as any otherCloud Run service. The Cloud Run service must return anHTTP200 code to confirm success after processing of the task is complete.
Tasks will be pushed to this Cloud Run service as HTTPS requests byCloud Tasks.
The response to Cloud Tasks must occur within itsconfiguredtimeout. Forworkloads that need to run longer than the maximum Cloud Taskstimeout, consider usingCloud Run jobs.
Creating a task queue
Command line
To create a task queue, use the command
gcloudtasksqueuescreateQUEUE-ID
replacingQUEUE-ID with the name you want to give to your task queue:it must be unique in your project. If you are prompted to create an App Engineapp in your project, respondy to create it. Cloud Tasks usesthis for the queue: make sure you choose the same location as you are using foryour Cloud Run service.
The default task queue configuration should work in most cases. However, youcan optionally set differentrate limits andretry parameters if you want.
Terraform
To learn how to apply or remove a Terraform configuration, seeBasic Terraform commands.
To create a task queue, add the following to your.tf file:
resource"google_cloud_tasks_queue""default"{name="cloud-tasks-queue-name"location="us-central1"}Apply the changes by enteringterraform apply.
Creating a service account to associate with the tasks
You must create a service account thatwill be associated with the enqueued tasks. This service account must have theCloud Run Invoker IAM role to allow the task queue to push tasks to theCloud Run service..
Console
In the Google Cloud console, go to theService Accountspage.
Select a project.
Enter a service account name to display in the Google Cloud console.
The Google Cloud console generates a service account ID based onthis name. Edit the ID if necessary. You cannot change the ID later.
Optional: Enter a description of the service account.
ClickCreate and continue.
Optional: Click theSelect a role field.
SelectCloud Run >Cloud Run Invoker.
ClickDone.
Command line
Create the service account:
gcloudiamservice-accountscreateSERVICE_ACCOUNT_NAME\--display-name"DISPLAYED_SERVICE_ACCOUNT_NAME"
Replace
- SERVICE_ACCOUNT_NAME with alower case name unique withinyour Google Cloud project, for example
my-invoker-service-account-name. - DISPLAYED_SERVICE_ACCOUNT_NAME with the name you want todisplay for this service account, for example, in the console, for example,
My Invoker Service Account.
- SERVICE_ACCOUNT_NAME with alower case name unique withinyour Google Cloud project, for example
For Cloud Run, give your service account permission to invokeyour service:
gcloudrunservicesadd-iam-policy-bindingSERVICE\--member=serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com\--role=roles/run.invoker
Replace
- SERVICE with the name of the service you want to beinvoked by Cloud Tasks.
- SERVICE_ACCOUNT_NAME with the name of the service account.
- PROJECT_ID with your Google Cloud project ID.
Grant your service account access to the project so that it haspermission to complete specific actions on the resources in your project:
gcloudprojectsadd-iam-policy-bindingRESOURCE_ID\--member=PRINCIPAL--role=roles/run.invoker
Replace
RESOURCE_ID: Your Google Cloud project ID.
PRINCIPAL: An identifier for the principal,or member, which usually has the following form:PRINCIPAL_TYPE:ID. For example,
user:my-user@example.com. For a full list of the values thatPRINCIPAL can have, see thePolicy Binding reference.
Terraform
To learn how to apply or remove a Terraform configuration, seeBasic Terraform commands.
Add the following to your.tf file:
Create the service account:
resource"google_service_account""default"{account_id="cloud-run-task-invoker"display_name="Cloud Run Task Invoker"}For Cloud Run, give your service account permission to invoke your service:
resource"google_cloud_run_service_iam_binding""default"{location=google_cloud_run_v2_service.default.locationservice=google_cloud_run_v2_service.default.namerole="roles/run.invoker"members=["serviceAccount:${google_service_account.default.email}"]}Apply the changes by enteringterraform apply.
Creating HTTP tasks with authentication tokens
When you create a task to send to the task queue, you specify the project,the location, queue name, theemail of the previously created service accountto associate with tasks, the URL of the private Cloud Run service thatwill run the task, and any other data you need to send. You can choose tohardcode these values, though values like the project ID, location, and service account emailcan bedynamically retrieved from theCloud Run metadata server.
Refer to theCloud Tasks API documentation for details on thetask request body.Note that requests that contain data payloads must use the HTTPPUT orPOST method.
The code that enqueues the tasks must have the necessary IAM permissions to doso, such as the Cloud Tasks Enqueuer role. Your code will have thenecessary IAM permissions if you use the default serviceaccount on Cloud Run.
The following examples create task requests that also include the creationof a header token. OIDC tokens are used in the examples. To use an OAuthtoken, replace the OIDC parameter with the language appropriate OAuth parameter in constructing the request.
Python
fromtypingimportOptionalfromgoogle.cloudimporttasks_v2defcreate_http_task_with_token(project:str,location:str,queue:str,url:str,payload:bytes,service_account_email:str,audience:Optional[str]=None,)->tasks_v2.Task:"""Create an HTTP POST task with an OIDC token and an arbitrary payload. Args: project: The project ID where the queue is located. location: The location where the queue is located. queue: The ID of the queue to add the task to. url: The target URL of the task. payload: The payload to send. service_account_email: The service account to use for generating the OIDC token. audience: Audience to use when generating the OIDC token. Returns: The newly created task. """# Create a client.client=tasks_v2.CloudTasksClient()# Construct the request body.task=tasks_v2.Task(http_request=tasks_v2.HttpRequest(http_method=tasks_v2.HttpMethod.POST,url=url,oidc_token=tasks_v2.OidcToken(service_account_email=service_account_email,audience=audience,),body=payload,),)# Use the client to build and send the task.returnclient.create_task(tasks_v2.CreateTaskRequest(parent=client.queue_path(project,location,queue),task=task,))Note therequirements.txt file:
google-cloud-tasks==2.18.0Java
importcom.google.cloud.tasks.v2.CloudTasksClient;importcom.google.cloud.tasks.v2.HttpMethod;importcom.google.cloud.tasks.v2.HttpRequest;importcom.google.cloud.tasks.v2.OidcToken;importcom.google.cloud.tasks.v2.QueueName;importcom.google.cloud.tasks.v2.Task;importcom.google.protobuf.ByteString;importjava.io.IOException;importjava.nio.charset.Charset;publicclassCreateHttpTaskWithToken{publicstaticvoidmain(String[]args)throwsIOException{// TODO(developer): Replace these variables before running the sample.StringprojectId="my-project-id";StringlocationId="us-central1";StringqueueId="my-queue";StringserviceAccountEmail="java-docs-samples-testing@java-docs-samples-testing.iam.gserviceaccount.com";createTask(projectId,locationId,queueId,serviceAccountEmail);}// Create a task with a HTTP target and authorization token using the Cloud Tasks client.publicstaticvoidcreateTask(StringprojectId,StringlocationId,StringqueueId,StringserviceAccountEmail)throwsIOException{// Instantiates a client.try(CloudTasksClientclient=CloudTasksClient.create()){Stringurl="https://example.com/taskhandler";// The full url path that the request will be sent toStringpayload="Hello, World!";// The task HTTP request body// Construct the fully qualified queue name.StringqueuePath=QueueName.of(projectId,locationId,queueId).toString();// Add your service account email to construct the OIDC token.// in order to add an authentication header to the request.OidcToken.BuilderoidcTokenBuilder=OidcToken.newBuilder().setServiceAccountEmail(serviceAccountEmail);// Construct the task body.Task.BuildertaskBuilder=Task.newBuilder().setHttpRequest(HttpRequest.newBuilder().setBody(ByteString.copyFrom(payload,Charset.defaultCharset())).setHttpMethod(HttpMethod.POST).setUrl(url).setOidcToken(oidcTokenBuilder).build());// Send create task request.Tasktask=client.createTask(queuePath,taskBuilder.build());System.out.println("Task created: "+task.getName());}}}Note thepom.xml file:
<?xmlversion='1.0'encoding='UTF-8'?><projectxmlns="http://maven.apache.org/POM/4.0.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0http://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><groupId>com.example.tasks</groupId><artifactId>cloudtasks-snippets</artifactId><packaging>jar</packaging><name>GoogleCloudTasksSnippets</name><!--Theparentpomdefinescommonstylechecksandtestingstrategiesforoursamples.Removingorreplacingitshouldnotaffecttheexecutionofthesamplesinanyway.--><parent><groupId>com.google.cloud.samples</groupId><artifactId>shared-configuration</artifactId><version>1.2.0</version></parent><properties><maven.compiler.target>1.8</maven.compiler.target><maven.compiler.source>1.8</maven.compiler.source><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding></properties><dependencyManagement><dependencies><dependency><groupId>com.google.cloud</groupId><artifactId>libraries-bom</artifactId><version>26.32.0</version><type>pom</type><scope>import</scope></dependency></dependencies></dependencyManagement><dependencies><dependency><groupId>com.google.cloud</groupId><artifactId>google-cloud-tasks</artifactId></dependency><dependency><groupId>junit</groupId><artifactId>junit</artifactId><version>4.13.2</version><scope>test</scope></dependency><dependency><groupId>com.google.truth</groupId><artifactId>truth</artifactId><version>1.4.0</version><scope>test</scope></dependency></dependencies></project>Go
import("context""fmt"cloudtasks"cloud.google.com/go/cloudtasks/apiv2"taskspb"cloud.google.com/go/cloudtasks/apiv2/cloudtaskspb")// createHTTPTaskWithToken constructs a task with a authorization token// and HTTP target then adds it to a Queue.funccreateHTTPTaskWithToken(projectID,locationID,queueID,url,email,messagestring)(*taskspb.Task,error){// Create a new Cloud Tasks client instance.// See https://godoc.org/cloud.google.com/go/cloudtasks/apiv2ctx:=context.Background()client,err:=cloudtasks.NewClient(ctx)iferr!=nil{returnnil,fmt.Errorf("NewClient: %w",err)}deferclient.Close()// Build the Task queue path.queuePath:=fmt.Sprintf("projects/%s/locations/%s/queues/%s",projectID,locationID,queueID)// Build the Task payload.// https://godoc.org/google.golang.org/genproto/googleapis/cloud/tasks/v2#CreateTaskRequestreq:=&taskspb.CreateTaskRequest{Parent:queuePath,Task:&taskspb.Task{// https://godoc.org/google.golang.org/genproto/googleapis/cloud/tasks/v2#HttpRequestMessageType:&taskspb.Task_HttpRequest{HttpRequest:&taskspb.HttpRequest{HttpMethod:taskspb.HttpMethod_POST,Url:url,AuthorizationHeader:&taskspb.HttpRequest_OidcToken{OidcToken:&taskspb.OidcToken{ServiceAccountEmail:email,},},},},},}// Add a payload message if one is present.req.Task.GetHttpRequest().Body=[]byte(message)createdTask,err:=client.CreateTask(ctx,req)iferr!=nil{returnnil,fmt.Errorf("cloudtasks.CreateTask: %w",err)}returncreatedTask,nil}Node.js
// Imports the Google Cloud Tasks library.const{CloudTasksClient}=require('@google-cloud/tasks');// Instantiates a client.constclient=newCloudTasksClient();asyncfunctioncreateHttpTaskWithToken(){// TODO(developer): Uncomment these lines and replace with your values.// const project = 'my-project-id';// const queue = 'my-queue';// const location = 'us-central1';// const url = 'https://example.com/taskhandler';// const serviceAccountEmail = 'client@<project-id>.iam.gserviceaccount.com';// const payload = 'Hello, World!';// Construct the fully qualified queue name.constparent=client.queuePath(project,location,queue);consttask={httpRequest:{headers:{'Content-Type':'text/plain',// Set content type to ensure compatibility your application's request parsing},httpMethod:'POST',url,oidcToken:{serviceAccountEmail,},},};if(payload){task.httpRequest.body=Buffer.from(payload).toString('base64');}console.log('Sending task:');console.log(task);// Send create task request.constrequest={parent:parent,task:task};const[response]=awaitclient.createTask(request);constname=response.name;console.log(`Created task${name}`);}createHttpTaskWithToken();Note thepackage.json file:
{"name":"appengine-cloudtasks","description":"Google App Engine Cloud Tasks example.","license":"Apache-2.0","author":"Google Inc.","private":true,"engines":{"node":">=16.0.0"},"files":["*.js"],"scripts":{"test":"c8 mocha -p -j 2 --timeout 30000","start":"node server.js"},"dependencies":{"@google-cloud/tasks":"^5.0.0","express":"^4.16.3"},"devDependencies":{"c8":"^10.0.0","chai":"^4.5.0","mocha":"^10.0.0","uuid":"^10.0.0"}}What's next
- Logging and viewing logs
- Monitoring health and performance
- Triggering from Pub/Sub
- Invoking with HTTPS
- Running services on a schedule
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-15 UTC.