Use queue.yaml to manage queues

While you can use a queue.yaml file to manage queues, mixing queue management methods can cause unexpected results. This guide explains the risks of mixing these methods and shows you how to resolve common configuration problems.

The Cloud Tasks API provides an independent interface to the App Engine Task Queue service. Using this interface, you can manage queues through the Google Cloud console or the Google Cloud CLI. Queues that you create with the Cloud Tasks API are accessible from the App Engine SDK—a collection of platform-specific APIs, standalone tools, and runtime files—and queues created with the App Engine SDK are accessible from the Cloud Tasks API.

To maintain compatibility, you can use queue.yaml, the configuration file for the App Engine SDK, to create and configure queues for the Cloud Tasks API. However, managing queues using this file as well as the Cloud Tasks API can cause issues that are detailed in this guide.

Before you begin

If you are new to Cloud Tasks or App Engine, use the Cloud Tasks API exclusively to manage your queues and avoid using queue.yaml. Cloud Tasks queue management methods give you more options for creating, updating, and deleting queues.

If you are an existing queue.yaml user, consider switching to Cloud Tasks queue management methods only if you understand the risks of mixing queue management methods.

Enforce a queue management method

To prevent mixing queue management methods, you can create a web app or command-line tool for creating, updating, and deleting queues. Whether that tool uses Cloud Tasks queue management methods or queue.yaml is an implementation detail that users don't need to be aware of. By enforcing usage of the tool, you can ensure that there is no inadvertent mixing of methods. Grant the Cloud Tasks Queue Admin Identity and Access Management (IAM) role to the tool and require users to authenticate. For more information about access management, see Secure queue configuration.

Queue configuration delays

Queue configuration changes can require several minutes to take effect. For example, after calling CreateQueue or UpdateQueue, several minutes might pass before you can successfully call CreateTask on that queue.

App Engine default queue

The App Engine queue named default receives special treatment in the App Engine SDK and in the Cloud Tasks API.

When is the default queue created?

If the default queue doesn't exist, it is created in these situations:
  • When a task is first added to the default queue using the App Engine SDK
  • When a queue.yaml file that specifies a default queue is uploaded
  • When CreateQueue or UpdateQueue is called to create the default queue
What restrictions does Cloud Tasks enforce?

To preserve compatibility with App Engine, Cloud Tasks enforces these restrictions regarding the default queue:
  • The Cloud Tasks API doesn't automatically create the default queue or any other queue
  • If a queue named default is created, it must be a queue using App Engine tasks
  • Calling GetQueue on the default queue returns a not found error if the queue doesn't yet exist
  • The default queue doesn't appear in the ListQueues output until it is created
  • You can modify the default queue configuration using the UpdateQueue call
  • After it is created, you can't delete the default queue

Risks of mixing queue management methods

For the underlying service,