Introduction to the new ESXi Configuration Store CLI (configstorecli)

I was looking into a customer inquiry this morning and found myself looking at the configstorecli, which is an ESXi Shell CLI that enables access to the new ESXi Configuration Store (ConfigStore). The goal of the ConfigStore, initially introduced in ESXi 7.0 Update 1, is to centrally manage all configurations for an ESXi host instead of relying on different methods including a variety of configuration files. There is actually not much documentation out there for configstorecli, other than this blog post by Duncan and these two VMware KBs (here and here).

While searching online, I ended up clicking Duncan's blog as I figured it probably has the best information and I do recall this topic awhile back on the change in behavior for renaming a standard virtual switch. I started to play with the configstore CLI and what was not immediately clear was how to actually use it, especially identifying some of the parameters it was looking for. I figured I might as well share some of my findings as I explore configstorecli a bit more.

My first observation is that the Config Store is a JSON document store and each configuration is stored as individual JSON documents. Before you can access a specific configuration, you first need to understand the schema. To view the entire schema, run the following command:

configstorecli schema list

Since the output is JSON, you can actually save the contents to a file on your desktop and use any JSON supported tool such as jq to explore further. In the example below, I have loaded an online copy of the configstorecli output from ESXi 7.0 Update 2 using my Chrome browser, which has this JSON Viewer extension installed. The benefit with a visual tool, is that you can easily expand or collapse specific nodes within the JSON document.

To interact with a specific configuration within the ESXi Config Store, users will need to provide the name of the Component, Group and Key.

• The Component is derived from the top level nodes of the JSON document. As of ESXi 7.0 Update 2 (Build 17630552), there currently 5 components: clusterstore, esx, esx_update, ha and vsan
• The Group are the nodes within a Group. Using the clusterstore example, there is only a single group called cluster_agent
• The Key are the nodes within a Component. Using the clusterstore example, there is also just a single Key called agent_settings

Now that we know the specific configuration that we want to query, we can now retrieve it using the config operation. We also need to specify the "state" of the Config Store that we wish to view the configuration and the following three options are supported:

• current - This is the current runtime configuration
• desired - This is the intended configuration, which may not have gone into effect (e.g. requires system reboot)
• default - This is the system default configuration

Note: Making modification to a specific configuration is only possible when choosing the current option, the other two only support a view only mode.

Using our clusterstore example, since we did not make any changes, neither current or desired will have any output. Hence, we will need to use the default option as shown in the command below:

configstorecli config default get -c clusterstore -g cluster_agent -k agent_settings

To modify a specific property within a configuration, you can either use the set or update operation. From my quick experiment, update feels like the HTTP Patch operation where you provide a JSON input file on the the properties you wish to add and if it does not exists, it will automatically create them for you. The set operation feels similiar to the HTTP PUT operation, where the original JSON file must be provided and it should contain the specific modifications you wish to make to the existing configuration. Duncan has already covered an example in his blog post, so I recommend giving that a read.

Finally, if you want to understand the list of ESXi configuration files that are managed by the Config Store, you can use the following command:

configstorecli files get

Hopefully this was a useful and quick introduction on how to use the new configstorecli, as I learn or experiment more, I will update this article to include more information. For now, I suspect most customers will not have to touch or interact with the configstorecli unless directed by VMware Engineering and/or GSS Support.