Configuration Service

Configuration Service#

Squirro’s configuration service is the centralized repository for server, project, and user configuration.

Overview#

The configuration service is the central place for all Squirro configuration.

The configuration service can be used for user-defined settings. Note, however, that the maximum size of a value is around 4kb. As a result, the configuration service is not meant as a generic data storage layer.

Setting and Accessing Values#

User Interface#

The server-level settings are accessible through the Configuration screen in the Server space of the Squirro UI.

Any exposed value can be edited through the user interface. A built-in value that has been modified can be reset to its default value.

Additionally, custom settings can be added. When doing so, the data type can be selected, with the configuration service providing values of type string, number, boolean or dictionary (a rich JSON data structure).

Changes are not applied instantaneously, the Caching settings will affect how long it takes for services to see updates.

Automated Setting#

When provisioning a Squirro server automatically, for example with Ansible, you may want to seed some configuration settings.

This can be done by adding JSON files into the folder /etc/squirro/configuration.d. Only files with the .json extension are considered. The folder and its files need to be readable by the configuration service user (sqconfig). Files that are invalid or unreadable will prevent the configuration service from starting. Consult the log file /var/log/squirro/configuration/configuration.log to see details if that happens.

When adding or changing values in this folder, the sqconfigurationd service needs to be restarted (see Services). On top of that, the Caching settings will affect how long it takes for services to see updates.

Overwriting Built-in Settings#

To overwrite settings that Squirro provides out of the box, use a file with the following content:

{
    "key": "user.create",
    "default_value": false
}

This will change the key user.create to be disabled. This however merely changes the configuration service’s default value for the key. Server administrators can then change the key in the frontend.

If the same key is referenced in multiple files, the last one will win.

Add Custom Settings#

Additional settings can be added and will be exposed the same way as any built-in setting. The snippet for overwriting built-in settings will work for these too, but a few more keys are recommended:

{
    "key": "app.disabling-test",
    "namespace": "server",
    "help": "This help text is exposed to users when editing the key in the user interface.",
    "type": "boolean",
    "default_value": true
}

Handle Project Settings#

Project-specific settings are recorded in the project namespace. They can be defined either for all projects or for a specific one like this:

{
    "key": "app.project-test"
    "namespace": "project",
    "help": "A test for project setting. Value can be changed per project.",
    "type": "number",
    "default_value": 42
}

This declares a new configuration key app.project-test which can then be accessed through the API.

It is also possible to define a value for a specific project by providing the scope property:

{
    "key": "app.project-test"
    "namespace": "project",
    "scope": "XW1vSnxiRp-O4XCvJrA5Jg",
    "help": "A test for project setting. Value can be changed per project.",
    "type": "number",
    "default_value": 42
}

As of version 3.4.4 the project settings are also exposed outside of the API. See Project Configuration for more details.

Full Reference#

All the properties that can be set and their possible values.

Property

Description

key

The key with which the setting is exposed. The keys need to follow specific naming conventions, see the section Naming Keys.

Keys are globally unique, independent of their namespace. So if you declare a app.my-setting key in the user namespace, a different setting of the same name can not exist in the project namespace.

namespace

The namespace under which to expose the key. The key needs to be globally unique, so a server-level setting can not have the same key as a user-level setting for example.

Possible namespaces are:

  • server

  • project

  • user

scope

The namespace-specific scope in which a key is available.

Not used for server namespace.

For project and user namespaces this points to the project ID or user ID respectively. But in both cases it can be left out or set to null to define the global default value.

help

A description of the key’s purpose, presented to the administrator when editing the key in the user interface.

type

The value type. Possible types are:

  • string

  • number

  • boolean

  • dictionary (stored and represented as a JSON dictionary)

default_value

The default value for this setting. Manually defined settings, such as through the user interface or the API, will always take precedence over this.

Squirro Client

The configuration service can be accessed through the Python client. See the ConfigurationMixin documentation for the available methods.

Caching#

All configuration service lookups are cached, and there is no support for flushing the cached values (short of restarting all services). The config.cache-ttl setting determines how long the settings are cached.

That setting itself is cached as well, so changing it will also take some time to have an effect.

Naming Keys#

The configuration keys are validated to the following rules:

  • Include one or more sections separated by periods. To avoid naming clashes, we recommend you use the reserved app section.

  • Sections are lowercase and can not include any numbers or other characters.

  • The ultimate key (the part after the last period) can consist of lowercase letters, numbers, and dashes.

Contents