Appendix E. YAML Configuration Properties

Documentation

VoltDB Home » Documentation » Using VoltDB
< previoustable of contentsnext >

Appendix E. YAML Configuration Properties

Configuration properties define the physical layout of a VoltDB database cluster at runtime — including the number of sites per hosts and K-safety value, among other things — as well as what features are in use and how they will operate. This appendix describes the syntax for specifying YAML properties as well as a table of all the supported configuration properties and their meaning.

Note

For a list and description of the equivalent configuration properties when running Volt in Kubernetes, see the appendix of Helm Properties in the Volt Kubernetes Administrator's Guide.

E.1. Understanding YAML Syntax

YAML is a simple syntax for describing properties and their values in text files. The advantage of YAML as a syntax is its simplicity and flexibility. YAML files are easy to read and easy to edit with a plain text editor. The properties are defined as a hierarchy, so related properties are grouped into sets of subproperties of a parent element.

There are actually two ways to specify YAML properties:

  • In a YAML file using indentation to describe the hierarchy of properties

  • On the command line, using dot notation to identify a property and its value on a single line

The following sections provide an overview of both styles of YAML syntax and their uses.

E.1.1. YAML Files

When specifying a property in a YAML file, you represent the property hierarchy as a set of indented keywords on separate lines, each keyword terminated by a colon. The actual value for the final node of the hierarchy follows the colon. For example, the following YAML file defines two properties, both of which are children of the deployment and cluster elements:

deployment:
   cluster:
      sitesperhost: 12
      kfactor: 1

Certain elements can contain a list rather than individual subproperties. In this case, the child list elements are preceded by a hyphen. The child elements themselves can be either individual values or further subproperties. For example, the user property contains a list of users, each specifying a user name, password and comma-separated list of roles.

deployment:
  users:
    user:
    - name: Washington
      password: cherrytree
      roles: citizen,president
    - name: Jefferson
      password: monticello
      roles: citizen,administrator

One advantage of YAML is that you can modularize the configuration, putting different options into separate files. For example, you might choose to save the security settings separately from the configuration of the individual database features (export, command logging, etc.) that are in use. You can then combine the configuration options on the command line when you initialize the database root directory:

$ voltdb init -f -D ~/mydbroot --config=features.yaml,security.yaml

For more on the YAML syntax, visit https//yaml.org/.

E.1.2. Dot Notation

YAML is easy to read and easy to edit in text files. However, the multi-line format is not well suited to command line options. As an alternative, you can use dot notation for specifying YAML properties on shell commands, such as voltadmin get and set.

Dot notation separates the elements of a YAML property with periods. For example, the following command fetches the current value of the sitesperhost property, which is a child of deployment and cluster:

$ voltadmin get deployment.cluster.sitesperhost
---
deployment:
  cluster:
    sitesperhost: 12

You can retrieve a specific value by specifying the dot notation for the scalar property, as in the preceding example. Or you can display a group of properties by specifying their parent element, like so:

$ voltadmin get deployment.cluster
---
deployment:
  cluster:
    sitesperhost: 12
    kfactor: 1

You can also specify a new value for a scalar property by using the dot notation for the property followed by an equals sign and the new value, as in the following voltadmin set command:

$ voltadmin set deployment.systemsettings.query.timeout=5000
INFO: The configuration update succeeded.

Of course, there are only some properties that can be changed on the fly (that is, while the database is running). The table of configuration properties in Table E.1, “Complete List of Volt Configuration Properties” includes a checkmark next to those properties that can be changed dynamically.

E.1.2.1. Identifying Individual Elements of a YAML List

Some configuration properties are lists. So normally the only way to see the values for an element of a property would be to show all of the elements of the property. For example, the voltadmin get deployment.users.user command shows you all of the user accounts defined for the database:

$ voltadmin get deployment.users.user
---
deployment:
  users:
    user:
    - name: "Washington"
      roles: "citizen,president"
      password: "cherrytree"
      plaintext: true
      expires: null
    - name: "Jefferson"
      roles: "citizen,administrator"
      password: "monticello"
      plaintext: true
      expires: null

However, as a shortcut Volt lets you identify the specific element of the list you want to operate on by specifying the unique identifier for that list in square brackets after the property name. For example, the following command displays the properties associated with the Jefferson account only:

$ voltadmin get deployment.users.user[Jefferson]
---
deployment:
  users:
    user:
    - name: "Jefferson"
      roles: "citizen,administrator"
      password: "monticello"
      plaintext: true
      expires: null

You can also use the unique name to assign values to other subproperties. For example, the following example changes the list of roles for the Jefferson account:

$ voltadmin set deployment.users.user[Jefferson].roles="citizen,president,administrator"
INFO: The configuration update succeeded.

In most cases, the unique identifier is the name property of the list element (as is true for the list of user accounts, export properties and so on). For those cases where a unique identifier does not already exist, the YAML schema includes a nickname property so you can assign a unique identifier to list elements. For example, the import configuration list does not have a unique identifier, so you can use a nickname instead. The following import configuration has assigned a nickname so the properties can be modified individually.

$ voltadmin get deployment.import
---
deployment:
  import:
    configuration:
    - nickname: "employees"
      enabled: true
      type: "KAFKA"
      format: "csv"
      version: "10"
      module: null
      priority: 4
      property:
      - name: "broker"
        value: "kafkasvr:9092"
      - name: "topics"
        value: "employees"
      - name: "procedure"
        value: "EMPLOYEE.insert"
      format-property: []
$ voltadmin set deployment.import.configuration[employees].priority=6
INFO: The configuration update succeeded.

Without the nicknames, you would need to save the current configuration to a file (with the voltadmin get deployment --output={filename} command), edit the file as desired, then reapply the changes using the voltadmin update command.

< previoustable of contentsnext >