This page explains how to create a Waiter resource. To learn more about waiters, read the Runtime Configurator Fundamentals.
A Waiter resource waits for a certain success or failure condition before returning a response. For both success and failure, you set a Cardinality condition, where the waiter waits for some number of variables to be created under a specific path prefix. After the variables have been created, the waiter returns. Your application code can then respond to its success or failure. If the current state of your variables already match either the success or failure end conditions, the waiter will return success or failure immediately.
Before you begin
- If you want to use the command-line examples in this guide, install the `gcloud` command-line tool.
- If you want to use the API examples in this guide, set up API access.
- Read Runtime Configurator Fundamentals.
- Read Creating and Deleting RuntimeConfig Resources.
- Read Setting and Getting Data.
Creating a waiter
To create a waiter:
Determine your success, and optionally, failure condition for the waiter.
For example, the following sample code sets the conditions for success and failure, where the waiter returns successfully if the number of paths under
/status/success
is three and fails if the path under/status/failure
is two:{ 'name': 'projects/[PROJECT_ID]/configs/[CONFIG_NAME]/waiters/[WAITER_NAME]', 'timeout': '360s', 'success': { 'cardinality': { 'path': '/status/success', 'number': 3 } }, 'failure': { 'cardinality': { 'path': '/status/failure', 'number': 2 } } }
Best practices for defining a waiter:
- Only one success condition and one failure condition is allowed per waiter.
- You should maintain one waiter per path.
- Failure conditions are always evaluated before success conditions.
- Do not overlap path prefixes between conditions.
Create the waiter.
Deployment Manager
To create a waiter in Deployment Manager, specify the waiter type:
runtimeconfig.v1beta1.waiter
In the properties of the waiter, provide the
name
,location
,timeout
, and the end conditions of the waiter:- name: [NAME] type: runtimeconfig.v1beta1.waiter properties: parent: $(ref.[CONFIG_NAME].name) waiter: [WAITER_NAME] timeout: [TIMEOUT_SECS] success: cardinality: path: [SUCCESS_PATH_PREFIX] number: [SUCCESS_NUMBER]
where:
[NAME]
is the resource name.[CONFIG_NAME]
is the Config resource for this request.[WAITER_NAME]
is the name for this waiter.[TIMEOUT_SECS]
is the number of seconds to wait before the waiter times out. For example, for 300 seconds, use300s
.[SUCCESS_PATH_PREFIX]
is the path prefix to watch for a success condition.[SUCCESS_NUMBER]
is the number of variables that exist under this path to be considered successful.
gcloud
With the Google Cloud CLI:
gcloud beta runtime-config configs waiters create [WAITER_NAME] \ --config-name [CONFIG_NAME] \ --success-cardinality-path [SUCCESS_PATH_PREFIX] \ --success-cardinality-number [SUCCESS_NUMBER] --timeout [TIMEOUT_SECS]
where:
[WAITER_NAME]
is the name for this waiter.[CONFIG_NAME]
is the RuntimeConfig resource for this request.[SUCCESS_PATH_PREFIX]
is the path prefix to watch for a success condition.[SUCCESS_NUMBER]
is the number of variables that exist under this path to be considered successful.[TIMEOUT_SECS]
the number of seconds to wait before the waiter times out.The gcloud CLI returns a response like:
Created [https://runtimeconfig.googleapis.com/v1beta1/projects/[PROJECT_ID]/configs/[CONFIG_NAME]/waiters/example-waiter].
After creating the waiter, the tool polls the related Operations resource until the waiter returns with one of the applicable responses.
For a complete reference for this
gcloud
command, read theruntime-config configs waiters
reference documentation.
API
In the API, make a
POST
request to the following URI:https://runtimeconfig.googleapis.com/v1beta1/projects/[PROJECT_ID]/configs/[CONFIG_NAME]/waiters
where:
[PROJECT_ID]
is the project ID for this request.[CONFIG_NAME]
is the name of the configuration for this request.
The request payload must contain the waiter name, the success condition, and the timeout duration:
{ 'name': 'projects/[PROJECT_ID]/configs/[CONFIG_NAME]/waiters/[WAITER_NAME]', 'timeout': '[TIMEOUT_SEC]', 'success': { 'cardinality': { 'path': '[SUCCESS_PATH_PREFIX]', 'number': '[SUCCESS_NUMBER]' } } }
where:
[PROJECT_ID]
is the project ID for this request.[CONFIG_NAME]
is the name of the configuration for this request.[WAITER_NAME]
is the name of the waiter to create.[TIMEOUT_SECS]
the number of seconds to wait before the waiter times out.[SUCCESS_PATH_PREFIX]
is the path prefix to watch for a success condition.[SUCCESS_NUMBER]
is the number of variables that exist under this path to be considered successful.
If successful, the request returns the name of the operations object that you poll for completion:
{ "name": "projects/[PROJECT_ID]/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]" }
Next, poll the waiter to periodically check when the waiter returns.
To learn more about the method, read the
waiters().create
documentation.
Polling a waiter
After creating a waiter, poll the related
Operations resource
to check whether the waiter has met one of the end conditions. If the waiter
has met an end condition or has timed out, the operation returns as done
and
returns a response based on the results of the waiter.
Use gcloud
or the API to poll a waiter.
gcloud
With the Google Cloud CLI, when you make a request to create a waiter, the tool automatically performs polling and waits for the waiter to return. The tool prints a response like the following while it is polling the waiter:
Waiting for waiter [WAITER_NAME] to finish...
If you don't want the tool to poll the waiter after creating it, supply
the --async
flag with your creation request.
API
In the REST API, make a GET
request to the following URI to get the
status of the waiter operation:
https://runtimeconfig.googleapis.com/v1beta1/projects/[PROJECT_ID]/configs/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]
where:
[PROJECT_ID]
is the project ID for this request.[CONFIG_NAME]
is the name of the configuration for this request.[WAITER_NAME]
is the name of the waiter to poll.
If the operation is still ongoing, the API returns a response like following, lacking a status:
{
"name": "projects/[PROJECT_NAME]/configs/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]"
}
If the operation is complete, the operation is marked as done
and returns
one of the responses described in the Waiter responses
section.
To learn more about the method, read the
waiters().create
documentation.
Waiter responses
Successful end condition
If the waiter has met a successful end condition, the operation returns the Waiter resource:
{
"name": "projects/[PROJECT_NAME]/configs/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]",
"done": true,
"response": {
"@type": "type.googleapis.com/google.cloud.runtimeconfig.v1beta1.Waiter",
"name": "projects/[PROJECT_NAME]/configs/[CONFIG_NAME]/waiters/[WAITER_NAME]",
"timeout": "360.000s",
"failure": {
"cardinality": {
"path": "[SUCCESS_PATH_PREFIX]",
"number": "[SUCCESS_NUMBER]"
}
},
"success": {
"cardinality": {
"path": "[FAILURE_PATH_PREFIX]",
"number": [FAILURE_NUMBER]
}
},
"createTime": "2016-04-12T18:02:13.316695490Z",
"done": true
}
}
Failure condition
If the waiter meets the failure end condition or timed out, the operation returns an error.
Failure condition was met
{
"name": "projects/[PROJECT_NAME]/configs/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]",
"done": true,
"error": {
"code": 9,
"message": "Failure condition satisfied."
}
}
Waiter timed out
{
"name": "projects/[PROJECT_NAME]/configs/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]",
"done": true,
"error": {
"code": 4,
"message": "Timeout expired."
}
}
What's next
- Learn about Runtime Configurator.
- Learn how to set and get variables.
- Set a Watcher a specific variable.
- Create and delete RuntimeConfig Resources.
- Refer to the v1beta1 reference.
- Refer to the Quotas for Runtime Configurator.