Runtime Configurator Fundamentals

This document provides an overview of the Runtime Configurator feature and describes the key concepts related to Runtime Configurator. To learn how to create a RuntimeConfig resource, read Creating and Deleting RuntimeConfig Resources.

What is Runtime Configurator?

The Runtime Configurator feature lets you define and store data as a hierarchy of key value pairs in Google Cloud Platform. You can use these key value pairs as a way to:

  • Dynamically configure services
  • Communicate service states
  • Send notification of changes to data
  • Share information between multiple tiers of services

For example, imagine a scenario where you have a cluster of nodes that run a startup procedure. During startup, you can configure your nodes to report their status to the Runtime Configurator, and then have another application query the Runtime Configurator and run specific tasks based on the status of the nodes.

The Runtime Configurator also offers a Watcher service and a Waiter service. The Watcher service watches a specific key pair and returns when the value of the key pair changes, while the Waiter service waits for a specific end condition and returns a response once that end condition has been met.

You use Runtime Configurator through using the gcloud CLI, or as a standalone API.

Concepts

  • Config resource

    A Config resource contains a hierarchical list of variables. You can create different configurations for different purposes. For example, you can separate configurations based on environment (prod, dev, test), based on different tiers of applications or services (back end, front end), or based on entities (one configuration per user of your application).

  • Variables

    Variables are key value pairs that belong to a RuntimeConfig resource. Variable keys have the following format:

    projects/[project_id]/configs/[CONFIG_ID]/variables/[VARIABLE_NAME]

    You can set, get, and watch variable values to communicate information to your applications, to signal a completed state, to send notification of data changes, and more. Variables are hierarchical, so your variable key could have several levels. For example, sample variable keys could be:

    webserver-1/users/name
webserver-1/users/favorite_color

  • Watchers

    You can use the watch() method to watch a variable and return when the variable changes, the watcher times out, or the watcher is deleted. Use the watch() functionality to dynamically configure your applications based on changes in your data.

  • Waiters

    If you create a Waiter resource to watch a specific path prefix, the waiter returns once the number of variables under the prefix reaches a particular amount. This is referred to as a Cardinality condition.

    For example, if you set a condition for the path /foo and the number of paths is set to 2, the following setup would meet the condition:

    • /foo/variable1 = "value1"
    • /foo/variable2 = "value2"
    • /bar/variable3 = "value3" # Not /foo path

    A waiter has both a failure and success condition that you can set.

    After you create a Waiter, the service returns an operation object that you poll for completion. The operation is complete when the one of the following occurs:

    • The success condition is met.
    • The failure condition is met.
    • The Waiter reached the timeout deadline specified in the initial request.

    Using a waiter is ideal for startup scenarios, where you might need to pause a deployment until a certain number of services is running.

What's next