ConfigDB structure¶
The configDB consists of two databases. One is used for runkey creation and one for reading runkeys. After creating a runkey in the staging area, the runkey has to be committed to the backend database for it to be available to other applications.
Creating a runkey¶
There are three main ways to create a runkey.
Direct interaction with the configDB API¶
The first option is to interact with the configDB HTTP-API endpoints directly, e.g. via a python or bash script. There a several endpoints available that allow you to create new objects and payloads. A list of all of these endpoints can be found here and an example for such a script here. After creating a runkey in the staging area it can be committed to the backend database. In addition to this, runkeys from the backend database can be cloned in the staging area and than edited.
Runkey creation via the UI¶
The runkey editor container is part of the configDB stack. It allows you to create, clone and commit runkeys via a browser-based user interface. On the landing page you will get an overview of all of the runkeys in the staging and storage database. You can than edit and commit staging area runkey, create new runkeys or even clone runkeys from the storage database into the staging area.
Runkey import from your file-system¶
To import or export runkey use the pyconfigdb package. It can be accessed via the pyconfigdb container and the cli script. The cli allows you list all runkeys of the staging area/backend, export from staging area/backend, import to the staging area, commit from staging area to backend, clone from backend to staging area and delete runkeys in the staging area.
E.g. to get a list of all available runkeys and than export one of them to your filesystem use:
The way this script maps the file system to the configdb runkeys is as followed: Each directory represents an object in the runkey and the files in a directory represent the payload connected to the object. The name of the directory will be used as the type of the object. Characters after a ~ will be ignored (e.g. both the felix~1 and felix~2 dirs will create an object with the type felix). Payloads containing the string "meta" will be classified as metadata and saved as searchable json files.
Searching for configs in a runkey¶
A main use case of these runkeys is to store configuration data for hardware components. The felix and optoboard microservices have the ability to read their settings and configuration directly from the configDB on startup. In order for these microservices to identify their hardware component in the runkey tree, the objects have to be associated with a metadata dataset containing a serial number (or any other key-value pair that allows for identification).
Therefor each object in the runkey tree should be saved with a metadata data set in addition to the acutal payload data. A payload marked as metadata will not be compressed in the backend and is therefor searchable directly in the database. Depending on the way used to create the runkey, the procedure to mark a payload as metadata differs: for the HTTP endpoints there is an option to set the attribute "meta": true, for the GUI there is a checkbox and for the import the metadata payload file has to include "meta" in its name.
After creating a compatible runkey, it can be searched for specific payloads either using the search-endpoint or the config-checker python package. The config-checker allows you to load configs from the database and also validate them. An example of both methods can be found here. The config-checker python package and more examples on how to use it can be found here.
A few slides explaining the config_checker package and the configdb-source can be found here.