Setting and Getting Data

This page explains how to set, get, and update variables using the Runtime Configurator. Variables are key value pairs that belong to a RuntimeConfig resource. Each key value pair contains data that you define. After creating a variable, you can set a watcher or waiter on it.

To learn more about variables and the Runtime Configurator service, see Runtime Configurator Fundamentals documentation.

To learn how to create a RuntimeConfig resource, see Creating and Deleting RuntimeConfig Resources.

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.

Creating a variable

A variable is a key value pair. A variable key can be flat or hierarchical. For example, all of the following are valid keys:

status
users/jane-smith/favorite-color
users/total

Only leaf node keys can have values. In the example above, you cannot assign a value to:

users
users/jane-smith

This is because both these keys contain other keys beneath them.

To create a variable, use Deployment Manager, the Google Cloud CLI, or the API.

Deployment Manager

To create a variable in Deployment Manager, specify the variable type:

runtimeconfig.v1beta1.variable

In the properties of the variable, provide the name, location, and value of the variable:

- name: [NAME]
  type: runtimeconfig.v1beta1.variable
  properties:
    parent: $(ref.[CONFIG_NAME].name)
    variable: [VARIABLE_KEY]
    [value | text]: [VARIABLE_VALUE]

where:

[NAME] is the arbitrary resource name for this variable. This is not the name of the variable itself.
[CONFIG_NAME] is the Config resource for this request.
[VARIABLE_KEY] is the key of this variable. For example, status and users/jane-smith/favorite_color are valid keys. Variable keys can contain /. A variable key can contain digits, letters, dashes, and slashes, and the max length for a name is 256 characters.
[VARIABLE_VALUE] is the value for this variable. Depending on whether you want to assign a value as plaintext, or as a based64 encoded string, choose either the value or text property:
- value: If providing a value as a base64 encoded string, use the value property.
- text: If providing a plaintext string, use the text property. The string must be valid UTF-8.

gcloud

To create a variable with the Google Cloud CLI, use the runtime-config configs variables set command:

gcloud beta runtime-config configs variables set [VARIABLE_KEY] \
    [VARIABLE_VALUE] --config-name [CONFIG_NAME] [--is-text]

where:

[VARIABLE_KEY] is the key of the variable. For example, status and users/jane-smith/favorite_color are valid keys. Variable keys can contain /. A variable key can contain digts, letters, dashes, and slashes, and the max length for a name is 256 characters.
[VARIABLE_VALUE] is the value of this variable. You can assign a value as plaintext, or as a based64 encoded string. If specifying a plaintext value, provide the --is-text flag; otherwise, the Google Cloud CLI will encode the value in base64 encoding.
```
gcloud beta runtime-config configs variables set [VARIABLE_KEY] \
      [VARIABLE_VALUE] --config-name [CONFIG_NAME] --is-text
```
You can also supply the variable value from a file. For example:
```
cat [FILE_NAME] | gcloud beta runtime-config configs variables set [VARIABLE_KEY] --config-name [CONFIG_NAME]
```
Note: You do not need to encode this value because gcloud will perform the encoding for you.
[CONFIG_NAME] is the name of the RuntimeConfig resource where this variable should be created in. For example, frontend-config.

For example:
```
gcloud beta runtime-config configs variables set example-variable \
      my-test-value --config-name example-config
```
The gcloud CLI returns a response like:

Created [https://runtimeconfig.googleapis.com/v1beta1/projects/[PROJECT_ID]/configs/[CONFIG_NAME]/variables/[VARIABLE_KEY]].

By default, any existing variables will be silently overwritten. If you want to preserve a variable that exists, include the --fail-if-present flag, which creates the new variable if it doesn't exist.

Similarly, you can also fail the request of the variable is absent by providing the --fail-if-absent flag.

For the complete reference for this gcloud command, read the runtime-config variables set reference documentation.

API

In the REST API, make a POST request to the following URI to create a new variable:

https://runtimeconfig.googleapis.com/v1beta1/projects/[PROJECT_ID]/configs/[CONFIG_NAME]/variables

where [PROJECT_ID] is the project ID for this request. The request payload contains the URI to the RuntimeConfig resource and either the plaintext value of the key, or the base64 encoded value:

{
   "name": "projects/[PROJECT_ID]/configs/[CONFIG_NAME]/variables/[VARIABLE_KEY]"
   "[value | text]": "[VARIABLE_VALUE]" # Choose either 'value' or 'text' but not both
}

where:

[PROJECT_ID] is the project ID for this request.
[CONFIG_NAME] is the name of this configuration.
[VARIABLE_KEY] is the key of the variable. For example, status and users/jane-smith/favorite_color. Variable keys can contain /. A variable key can contain digts, letters, dashes, and slashes, and the max length for a name is 256 characters.
[VARIABLE_VALUE] is the value for this variable. Depending on whether you want to assign a value as plaintext, or as a based64 encoded string, choose either the value or text property:
- value: If providing a value as a base64 encoded string, use the value property.
- text: If providing a plaintext string, use the text property. The string must be valid UTF-8.
If successful, the API returns a response like:
```
{
"name": "projects/[PROJECT_ID]/configs/[CONFIG_NAME]/variables/[VARIABLE_KEY]",
"value": "dGVhbA==",
"updateTime": "2016-04-11T21:49:00.773366134Z"
}
```
To learn more about the method, read the variables().create documentation.

Updating a variable

Deployment Manager

To update a variable in Deployment Manager:

Define or update your variable properties as described in Creating a variable.
Follow the steps to make the update request.

gcloud

Update a variable using the same process to create a variable.

API

In the REST API, make a PUT request to the following URI to update a variable:

https://runtimeconfig.googleapis.com/v1beta1/projects/[PROJECT_ID]/configs/[CONFIG_NAME]/variables/[VARIABLE_KEY]

where:

[PROJECT_ID] is the project ID for this request.
[CONFIG_NAME] is the name of this configuration.
[VARIABLE_VALUE] is the value for this variable. This is a string that has been base64 encoded.

The payload of the request must be:

{
   "[value | text]": "[VARIABLE_VALUE]" # Choose either 'value' or 'text' but not both
}

where [VARIABLE_VALUE] is the value for this variable. Depending on whether you want to assign a value as plaintext, or as a base64 encoded string, choose either the value or text property:

value: If providing a value as a base64 encoded string, use the value property.
text: If providing a plaintext string, use the text property. The string must be valid UTF-8.

If successful, the API returns a response like:

{
  "name": "projects/[PROJECT_ID]/configs/[CONFIG_NAME]/variables/[VARIABLE_KEY]",
  "value": "dGVhbA==",
  "updateTime": "2016-04-11T21:46:11.591713370Z",
  "state": "UPDATED"
}

To learn more about the method, read the variables().create documentation.

Getting a variable's value

Deployment Manager

Get a variable's value using one of the following methods:

gcloud

To create a variable with the Google Cloud CLI, use the runtime-config configs variables get-value command:

gcloud beta runtime-config configs variables get-value [VARIABLE_KEY] --config-name [CONFIG_NAME]

where:

[VARIABLE_KEY] is the key of the variable. For example, status, users/jane-smith/favorite_color.
[CONFIG_NAME] is the name of the RuntimeConfig resource for this variable. For example, website.

The gcloud CLI returns a response like:
```
example-value
```

You can also get a list of variables for which you have runtimeconfig.variables.get permission and their values by using the list command and supplying the --values flag. For example:

gcloud beta runtime-config configs variables list --config-name example-config --values

The gcloud CLI returns a list like so:

NAME                         UPDATE_TIME                     VALUE
not-my-favorite-color/shade  2016-04-18T21:14:59.932428461Z  orange
not-my-favorite-food/group   2016-04-18T21:14:59.932428461Z  vegetables

Any variables for which you do not have get permission will be omitted. That includes variables where you have list permission but not get permission.

For the complete reference for this gcloud command, read the runtime-config variables reference documentation.

API

In the REST API, make a GET request to the following URI to get a variable's value:

https://runtimeconfig.googleapis.com/v1beta1/projects/[PROJECT_ID]/configs/[CONFIG_NAME]/variables/[VARIABLE_KEY]

where:

[PROJECT_ID] is the project ID for this request.
[CONFIG_NAME] is the name of this configuration.
[VARIABLE_KEY] is the name for this request.

If successful, the API returns a response with the base64 encoded value of the variable:

{
  "name": "projects/[PROJECT_ID]/configs/[CONFIG_NAME]/variables/[VARIABLE_KEY]",
  "value": "[VARIABLE_VALUE]",
  "updateTime": "2016-04-11T21:49:00.773366134Z"
}

You must decode the value yourself to get the string. To learn more about the method, read the variables().get documentation.

If you want to get a list of variables for which you have runtimeconfig.variables.get permission and their values, use the returnValues method. For example:

GET uri: https://runtimeconfig.googleapis.com/v1beta1/projects/myproject/configs/example-config/variables?returnValues=True

The API returns all variables for which you have permission:

{
  "variables": [
    {
      "name": "projects/compute-writers-project/configs/example-config/variables/not-my-favorite-color/shade",
      "updateTime": "2016-04-18T21:14:59.932428461Z",
      "value": "b3Jhbmdl"
    }
  ]
}

Similarly, you must decode the value yourself to get the string.

To learn more about the method, read the variables().list documentation.

What's next?

Learn about Runtime Configurator.
Watching a Specific Variable.
Creating a Waiter.
Creating and Deleting RuntimeConfig Resources.
Refer to the v1beta1 reference.
Refer to the Quotas for Runtime Configurator.