UI settings service

UI settings are configurable from the Advanced Settings page in Management and control the behavior of Kibana. uiSettings are stored in a config saved object and, as such, conform to the same conditions as other Saved Objects.

There are several ways to configure an advanced setting:

Keep in mind that once you add a new advanced setting, you cannot change or remove it without registering a migration in core.

The uiSettings service is the programmatic interface to Kibana’s Advanced Settings UI. Kibana plugins use the service to extend Kibana UI Settings Management with custom settings for their plugin.

Configuration through the Advanced Settings UI is restricted to users authorised to acces the Advanced Settings page. Users who don’t have permissions to change these values default to using the settings configured to the space they are in. Config saved objects can be shared between spaces.

[preview] This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. When a setting is configured as an override in kibana.yml, it will override any other value stored in the config saved object. If an override is misconfigured, it will fail config validation and prevent Kibana from starting up. The override applies to Kibana as a whole for all spaces and users and the option will be disabled in the Advanced Settings page. We refer to these as "global" overrides.

Use the top-level uiSettings key for this, for example:

# Display times in UTC
uiSettings:
  overrides:
    "dateFormat:tz": "UTC"

On the client, the uiSettings service is exposed directly from core and the client provides plugins access to the config entries stored in Elasticsearch.

In the interest of performance, uiSettings are cached. Any changes that require cache refreshes should register an instruction to reload the page when settings are configured in Advanced Settings using the requiresPageReload parameter.

import { CoreSetup, Plugin } from 'src/core/public';

export class MyPlugin implements Plugin<MyPluginSetup, MyPluginStart> {
  public setup(core: CoreSetup): MyPluginSetup {
    …
    core.uiSettings.getUpdate$().subscribe(({ key, newValue }) => {
      if (key === 'custom') {
        // do something with changes...
        myPluginService.register({
          …
        })
      }
    });
    …
  }

  public start(core: CoreStart): MyPluginStart {
    return {
      …
      settings: {
        getCustomValue: () => core.uiSettings.get('custom'),
        …
      },
    };
  }
}

On the server, uiSettings are exposed directly from core.

The following example shows how to register a new custom setting with a default value of 42. When registering a new setting, you must provide a schema against which validations are performed on read and write. All the other parameters are optional.

import { schema } from '@kbn/config-schema';
import type { CoreSetup,Plugin } from '@kbn/core/server';

export class MyPlugin implements Plugin {
  public setup(core: CoreSetup) {
    core.uiSettings.register({
      custom: {
        value: '42',
        schema: schema.string(),
      },
    });
    const router = core.http.createRouter();
    router.get({
      path: 'my_plugin/{id}',
      validate: …,
    },
    async (context, request, response) => {
      const customSetting = await context.uiSettings.client.get('custom');
      …
    });
  }
}

To change or remove a uiSetting, the whole config Saved Object needs to be migrated. uiSettings migrations are declared directly in the service.

For example, if we wanted to remove a custom setting, or rename my_setting:fourtyTwo to my_other_setting:fourtyTwo, we’d need two migration entries, one for each change targeting the version in which these changes apply:

export const migrations = {
  ...
  '8.1.0': (doc: SavedObjectUnsanitizedDoc<any>): SavedObjectSanitizedDoc<any> => ({
  ...doc,
  ...(doc.attributes && {
    attributes: Object.keys(doc.attributes).reduce(
      (acc, key) =>
        [
          // other settings to remove for 8.1.0...
          'custom',
        ].includes(key)
          ? {
              ...acc,
            }
          : {
              ...acc,
              [key]: doc.attributes[key],
            },
      {}
    ),
  }),
  references: doc.references || [],
  }),
  '8.2.0': (doc: SavedObjectUnsanitizedDoc<any>): SavedObjectSanitizedDoc<any> => ({
    ...doc,
    ...(doc.attributes && {
      attributes: Object.keys(doc.attributes).reduce(
        (acc, key) =>
          key.startsWith('my_setting:')
            ? {
                ...acc,
                [key.replace('my_setting', 'my_other_setting')]: doc.attributes[key],
              }
            : {
                ...acc,
                [key]: doc.attributes[key],
              },
        {}
      ),
    }),
    references: doc.references || [],
  }),
  …
}