Environment

• YugabyteDB Anywhere - 2.14
• YugabyteDB Anywhere - 2.16
• YugabyteDB Anywhere - 2.18
• YugabyteDB Anywhere - 2.20

Issue

In older versions of YugabyteDB Anywhere, certain configuration settings could only be modified on a temporary basis and would revert to default whenever the YugabyteDB Anywhere containers were redeployed, such as during restarts through the Replicated console or minor version upgrades.

Resolution

Starting from YugabyteDB Anywhere Version 2.18, runtime configuration variables can be edited directly in the UI. We recommend this method if you are using 2.18 or higher.

Steps:

From the UI go to Admin -->  Advanced--> Customer Configuration:

For example, if you want to edit  blacklist_leader_wait_time_ms search for the configuration and edit it (Action --> Edit Configuration --> Save)

Overview

YugabyteDB Anywhere version 2.8 introduced runtime configuration settings that persist through restarts, redeployments, and upgrades. These settings are used to control features such as tablet leader blacklisting.

Warning: Inappropriate changes to runtime configuration settings may lead to system instability. Only modify runtime configuration settings when instructed to do so by Yugabyte Support.

Currently, these settings can only be modified using the YugabyteDB Anywhere REST API. A UI for modifying these settings will be included in a future YugabyteDB Anywhere release.

Steps

1. Find the Customer UUID.

Log into YugabyteDB Anywhere. Make a note of the hostname or IP address and port number (if applicable) of the YugabyteDB Anywhere node.

Click the "User" icon in the upper-right corner of the YugabyteDB Anywhere UI, then select User Profile. Make a note of the UUID listed under Customer ID. You will need this in a later step.

2. Generate a REST API authentication token. If you already have a REST API authentication token, skip this step and use the existing value of this token.

In the User Profile section of the YugabyteDB Anywhere UI, select the Generate Key button, then the Copy button to copy the authentication token to the clipboard. 

Important: Generating a new REST API authentication token will invalidate any existing token for this user. Be sure to verify whether or not this token is in use before generating a new token.

Important: Store this authentication token securely. Anyone with access to this token can use it to make changes to the environment, including making configuration changes, creating or deleting database Universes, etc.

3. Determine the correct scope for the setting.

Runtime Configuration settings must be set for a particular "scope".

Settings applied to the global scope  00000000-0000-0000-0000-000000000000 apply to every Customer, Provider, and Universe managed by the YugabyteDB Anywhere instance.

NOTE: Only the SuperAdmin user can modify runtime configuration variables at the global scope.

Settings applied to the Customer scope apply to every Provider and Universe associated with a Customer. Most YugabyteDB Anywhere environments have a single Customer.

Settings applied to the Provider or Universe scope apply to an individual Provider or Universe.

Settings for more specific scopes override settings for less specific scopes. For example, if the global scope has blacklist_leader_wait_time_ms set to 300000, while the Universe scope for the yugabyte-test Universe has blacklist_leader_wait_time_ms set to 600000, the more specific blacklist_leader_wait_time_ms setting of 600000 would be applied to the yugabyte-test Universe.

List Available Settings

curl --request GET \
--url https://${YBA_HOST}/api/v1/runtime_config/mutable_keys \
--header 'Content-Type: application/json' \
--header "X-AUTH-YW-API-TOKEN: $TOKEN"

Where ${YBA_HOST} is the hostname or IP address of the YugabyteDB Anywhere host and $TOKEN is the API token from step (2) above.

It may be helpful to pipe REST API output through the jq utility (if available) to improve readability. For example:

export YBA_HOST=$hostname
export TOKEN=<redacted>
curl --request GET \
--url https://${YBA_HOST}/api/v1/runtime_config/mutable_keys \
--header 'Content-Type: application/json' \
--header "X-AUTH-YW-API-TOKEN: $TOKEN" | jq
[
"yb.cloud.enabled",
"yb.security.discoveryURI",
"yb.audit.log.verifyLogging",
"yb.tls.skip_cert_validation",
"yb.proxy_endpoint_timeout",
...
]

Full details are available on the List mutable keys page of the REST API documentation.

Get Current Setting Value

To retrieve the value of a runtime configuration setting in the global scope:

curl --request GET \
--url https://${YBA_HOST}/api/v1/customers/${CUUID}/runtime_config/00000000-0000-0000-0000-000000000000/key/${KEY_NAME} \
--header 'Content-Type: application/json' \
--header "X-AUTH-YW-API-TOKEN: $TOKEN"

where ${YBA_HOST} is the hostname or IP address of the YugabyteDB Anywhere host, ${CUUID} is the Customer UUID from step (1) above, ${KEY_NAME} is the name of the key for the setting you wish to retrieve, and  $TOKEN is the API token from step (2) above.

For example:

export YBA_HOST=$hostname
export CUUID=11111111-2222-3333-4444-777777777777
export KEY_NAME=yb.metrics.db_read_write_test
export TOKEN=<redacted>
curl --request GET \
--url https://${YBA_HOST}/api/v1/customers/${CUUID}/runtime_config/00000000-0000-0000-0000-000000000000/key/${KEY_NAME} \
--header 'Content-Type: application/json' \
--header "X-AUTH-YW-API-TOKEN: $TOKEN"
false

NOTE: The API will report the message Key ${KEY_NAME} is not defined in scope ${SCOPE} for any setting that has not been set for the specified scope. This is expected behavior. 

NOTE: You can get a list of KEY_NAMEs for a scope (Universe UUID) by:

 curl --request GET --url \
  https://${YBA_HOST}/api/v1/customers/${CUUID}/runtime_config/$SCOPE?includeInherited=1 \
    --header 'Content-Type: text/plain' --header "X-AUTH-YW-API-TOKEN: $TOKEN" | jq

To retrieve the value of a runtime configuration setting in a different scope, specify the UUID of the scope.
Remember - this will only be available if it has been previously SET via the API.
For example, to retrieve the value of a setting at the Universe scope, specify the UUID of the Universe as the scope:

curl --request GET \
--url https://${YBA_HOST}/api/v1/customers/${CUUID}/runtime_config/${UUUID}/key/${KEY_NAME} \
--header 'Content-Type: application/json' \
--header "X-AUTH-YW-API-TOKEN: $TOKEN"

where ${UUUID} is the UUID of the Universe for which you wish to set the setting.

Full details are available on the Get a configuration key page of the REST API documentation.

Add or Modify a Setting Value

To set the value of a runtime configuration setting in the global scope:

curl --request PUT \
--url https://${YBA_HOST}/api/v1/customers/${CUUID}/runtime_config/00000000-0000-0000-0000-000000000000/key/${KEY_NAME} \
--header 'Content-Type: text/plain' \
--header "X-AUTH-YW-API-TOKEN: $TOKEN" \
--data 'value'

where ${YBA_HOST} is the hostname or IP address of the YugabyteDB Anywhere host, ${CUUID} is the Customer UUID from step (1) above, ${KEY_NAME} is the name of the key for the setting you wish to change, and  $TOKEN is the API token from step (2) above.

For example:

export YBA_HOST=$hostname
export CUUID=11111111-2222-3333-4444-777777777777
export KEY_NAME=yb.metrics.db_read_write_test
export TOKEN=<redacted>
curl --request PUT \
--url https://${YBA_HOST}/api/v1/customers/${CUUID}/runtime_config/00000000-0000-0000-0000-000000000000/key/${KEY_NAME} \
--header 'Content-Type: text/plain' \
--header "X-AUTH-YW-API-TOKEN: $TOKEN" \
--data 'false'
{"success":true}

Full details are available on the Update a configuration key page of the REST API documentation.

Revert a Setting Value to Default

To revert the value of a runtime configuration setting in the global scope back to default:

curl --request DELETE \
--url https://${YBA_HOST}/api/v1/customers/${CUUID}/runtime_config/00000000-0000-0000-0000-000000000000/key/${KEY_NAME} \
--header 'Content-Type: application/json' \
--header "X-AUTH-YW-API-TOKEN: $TOKEN"

where ${YBA_HOST} is the hostname or IP address of the YugabyteDB Anywhere host, ${CUUID} is the Customer UUID from step (1) above, ${KEY_NAME} is the name of the key for the setting you wish to retrieve, and  $TOKEN is the API token from step (2) above.

For example:

export YBA_HOST=$hostname
export CUUID=11111111-2222-3333-4444-777777777777
export KEY_NAME=yb.metrics.db_read_write_test
export TOKEN=<redacted>
curl --request DELETE \
--url https://${YBA_HOST}/api/v1/customers/${CUUID}/runtime_config/00000000-0000-0000-0000-000000000000/key/${KEY_NAME} \
--header 'Content-Type: text/plain' \
--header "X-AUTH-YW-API-TOKEN: $TOKEN"
{"success":true}

Full details are available on the Delete a configuration key page of the REST API documentation.

4. Alternative method of setting a value

The attached script, rest-call.sh can be used to set a TBA runtime configuration setting.
It requires

• the REST-API token as above
• the URL to the YBA host
• The SCOPE (Universe UUID) or leave empty for GLOBAL
• the name of the KEY you want to set
• The VALUE you want it set to.

Run the script without parameters to get the run instructions.