Creating a Waiter

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:

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

2. 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, use 300s.
   • [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 the runtime-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]',