This page describes how to configure Cloud Tasks queues using the gcloud
command of the Google Cloud CLI.
Configuring your Cloud Tasks queue
You can configure your Cloud Tasks queue when you create the queue or anytime afterwards, and the configuration will apply to all tasks in that queue.
There are three basic aspects to configuring your queues:
Configure routing (App Engine queues only)
The queue needs to know the name and version of the service that contains the appropriate worker. This is known as the target. There are three ways to set the target:
- Do not explicitly set the target. In this case, the default service is used.
- Explicitly declare the target in the task itself, by setting AppEngineRouting in AppEngineHttpRequest. This is the preferred method if you wish to use a target other than the default.
- Explicitly route all tasks in a queue to a non-default target by using appEngineRoutingOverride. This method overrides any routing that might be set in the task itself.
To use gcloud
to set up this non-default queue-level routing and thus override
any task-level routing:
gcloud tasks queues update [QUEUE_ID] \
--routing-override=service:[SERVICE],version:[VERSION]
where:
SERVICE
is the App Engine worker service responsible for task handling.VERSION
is the app version.
For example, if you set up a worker service called worker
to handle all tasks
in a queue called barbequeue
, you can route to that service and the default
version by calling:
gcloud tasks queues update barbequeue \
--routing-override=service:worker
Describe
the queue:
gcloud tasks queues describe barbequeue
The output should be something like:
appEngineRoutingOverride:
host: worker.[PROJECT_ID].appspot.com
service: worker
name: projects/[PROJECT_ID]/locations/[LOCATION_ID]/queues/barbequeue
rateLimits:
maxBurstSize: 100
maxConcurrentDispatches: 1000
maxDispatchesPerSecond: 500.0
retryConfig:
maxAttempts: 100
maxBackoff: 3600s
maxDoublings: 16
minBackoff: 0.100s
state: RUNNING
Remove the routing:
gcloud tasks queues update [QUEUE_ID] \
--clear-routing-override
Define rate limits
You can set the maximum rate and number of concurrent tasks that can be dispatched by a queue.
gcloud tasks queues update [QUEUE_ID] \
--max-dispatches-per-second=[DISPATCH_RATE] \
--max-concurrent-dispatches=[MAX_RUNNING]
where:
DISPATCH_RATE
is actually the rate at which tokens in the bucket are refreshed. In conditions where there is a relatively steady flow of tasks, this is the equivalent of the rate at which tasks are dispatched.MAX_RUNNING
is the maximum number of tasks in the queue that can run at once.
For example, if you created a queue called barbequeue
without setting any
parameters, you can update the maximum number of concurrent tasks by
calling:
gcloud tasks queues update barbequeue \
--max-concurrent-dispatches=20
Describe
the queue:
gcloud tasks queues describe barbequeue
The output should be:
name: projects/[PROJECT_ID]/locations/[LOCATION_ID]/queues/barbequeue
rateLimits:
maxBurstSize: 100
maxConcurrentDispatches: 20
maxDispatchesPerSecond: 500.0
retryConfig:
maxAttempts: 100
maxBackoff: 3600s
maxDoublings: 16
minBackoff: 0.100s
state: RUNNING
Defining processing rates using gcloud
commands versus using queue.yaml
The Cloud Tasks API approach for defining queue processing rates
differs slightly from the approach taken using the uploading of
queue.yaml
files, even though both methods result in queues using the same
underlying mechanism.
In both cases, the queue uses the token bucket algorithm to control the rate of task execution. Each named queue has a bucket that holds its tokens.
Each time your application executes a task, a token is removed from the bucket.
The queue continues processing tasks until its bucket runs
out of tokens. The system refills the bucket with new tokens continuously based
on the max_dispatches_per_second
rate that you specify for the queue. If your
queue contains tasks to process, and the queue's bucket contains tokens,
the system simultaneously processes as many tasks as there are tokens, up to
the max_concurrent_dispatches
value you have set.
Uneven load can allow the number of tokens in the bucket to grow significantly,
which can lead to bursts of processing when a burst of requests then comes in. In
this case, your queue may experience an actual dispatch rate that
exceeds your max_dispatches_per_second
rate, consuming system resources and
competing with user-serving requests. In cases where you are using queues to
manage dispatch rates based on relatively slow SLAs for downstream services,
this can lead to errors like HTTP 429
(Too Many Requests) or 503
(Service Unavailable).
When you use any Cloud Tasks API method, you have two fields to define the queue dispatch rate:
max_dispatches_per_second
max_concurrent_dispatches
as shown in the example above. A third field,
max_burst_size
, is calculated by the system based on the value you set for
max_dispatches_per_second
.
When you use the queue.yaml
method, you can set all three elements:
max_concurrent_requests
, which is equivalent tomax_concurrent_dispatches
rate
, which is equivalent tomax_dispatches_per_second
bucket_size
, which is equivalent tomax_burst_size
In most cases, using the Cloud Tasks API method and letting the
system set max_burst_size
produces a very efficient rate for managing request
bursts. In some cases, however, particularly when the desired
rate is relatively slow, either using the queue.yaml
method to manually set
bucket_size
to a small value, or setting your max_concurrent_dispatches
to
a small value via the Cloud Tasks API can give you more control.
Set retry parameters
If a task does not complete successfully, then Cloud Tasks will retry the task with exponential backoff according to the parameters you have set. You can specify the maximum number of times to retry failed tasks in the queue, set a time limit for retry attempts, and control the interval between attempts.
gcloud tasks queues update [QUEUE_ID] \
--max-attempts=[MAX_ATTEMPTS] \
--min-backoff=[MIN_INTERVAL] \
--max-backoff=[MAX_INTERVAL] \
--max-doublings=[MAX_DOUBLINGS] \
--max-retry-duration=[MAX_RETRY_DURATION]
where:
MAX_ATTEMPTS
is the maximum number of attempts for a task, including the first attempt. You can allow unlimited retries by setting this flag tounlimited
.MIN_INTERVAL
is the minimum amount of time to wait between retry attempts. The value must be a string that ends in "s," such as5s
.MAX_INTERVAL
is the maximum amount of time to wait between retry attempts. The value must be a string that ends in "s," such as5s
.MAX_DOUBLINGS
is the maximum number of times that the interval between failed task retries will be doubled before the increase becomes constant.MAX_RETRY_DURATION
is the maximum amount of time for retrying a failed task measured from when the task was first attempted. The value must be a string that ends in "s," such as5s
.
Verify your queue was configured successfully:
gcloud tasks queues describe [QUEUE_ID]
What's next
- Learn about creating HTTP Target tasks.
- Learn about creating App Engine tasks.
- Learn about setting up Cloud Logging
- Learn more about queue management in the RPC API reference.
- Learn more about queue management in the REST API reference.
- See the full list of Cloud Tasks
gcloud
commands.