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

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]',
           '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