Adds developer docs for uiSettings #124648

TinaHeiligers · 2022-02-04T01:02:09Z

Resolves #123243
This PR fleshes out the uiSettings developer documentation adding sections for:

overview
client-side usage
server side usage
migrations
security concerns

elasticmachine · 2022-02-04T01:39:00Z

Pinging @elastic/kibana-core (Team:Core)

afharo

Thank you @TinaHeiligers for writing this up! I love the thorough explanation of this service.

I added a few comments as I was using this document as learning material for myself 😇

Also, do you think it's worth asking the Docs team to review this?

afharo · 2022-02-04T09:01:01Z

docs/developer/architecture/core/uisettings-service.asciidoc

-=== Server side usage
+=== Overview
+
+UI settings are configurable from the Advanced Settings page in Management and control the behavior of {kib}. `uiSettings` are stored in a `config` saved object and, as such, conform to the same conditions as other saved objects.


conform to the same conditions as other saved objects

Can we highlight the limitations/conditions that may affect this use case of SOs? Is it space-scoped? Migrations? Anything else?

I've linked the text to the saved objects service.

afharo · 2022-02-04T09:06:19Z

docs/developer/architecture/core/uisettings-service.asciidoc

@@ -38,3 +92,66 @@ export class MyPlugin implements Plugin {
 }

 ----
+
+Registeration only requires a schema for validation on read and write, all {kib-repo}blob/{branch}/docs/development/core/server/kibana-plugin-core-server.uisettingsparams.md[other parameters] are optional.


Suggested change

Registeration only requires a schema for validation on read and write, all {kib-repo}blob/{branch}/docs/development/core/server/kibana-plugin-core-server.uisettingsparams.md[other parameters] are optional.

Registration only requires a schema for validation on read and write, all {kib-repo}blob/{branch}/docs/development/core/server/kibana-plugin-core-server.uisettingsparams.md[other parameters] are optional.

afharo · 2022-02-04T09:07:04Z

docs/developer/architecture/core/uisettings-service.asciidoc

+
+Registeration only requires a schema for validation on read and write, all {kib-repo}blob/{branch}/docs/development/core/server/kibana-plugin-core-server.uisettingsparams.md[other parameters] are optional.
+
+See:


I read somewhere that we use Refer instead of See for accessibility

Better yet, I added links to the API docs directly from the relevant text 😉

afharo · 2022-02-04T09:10:10Z

docs/developer/architecture/core/uisettings-service.asciidoc

+
+There are several ways to configure an advanced setting:
+
+- Through the <<advanced-options, Advanced Settings UI>> (security restrictions apply)


nit: Can we add a link to the section where we explain the restrictions?

afharo · 2022-02-04T09:13:45Z

docs/developer/architecture/core/uisettings-service.asciidoc

+- {kib-repo}blob/{branch}/docs/development/core/server/kibana-plugin-core-server.uisettingsservicesetup.register.md[UI settings service Setup API docs]
+
+==== Migrations
+Because `uiSettings` are persisted in the `config` saved object, changing or removing a setting requires a migration of the whole saved object. For example, if we wanted to remove the `custom` setting in the example above and then also rename `my_setting:fourtyTwo` to `my_other_setting:fourtyTwo`, we'd have two migration entries, one for each change targeting the required versions:


As I'm reading this I'm wondering: do we have a deprecation policy/service for the UI Settings?

I'm thinking about the use case when a UI setting is globally overridden in kibana.yml, and then it's removed/renamed. Would it crash Kibana? How do we notify the user about the new name?

Plugins can leverage the optional deprecation parameter on registration for handling deprecation notices and renames etc. The deprecation warnings are rendered in Advanced Settings and should also be mirrored in the Configure Kibana guide (as we do in the docs for 7.17).

Renames and removals are all handled through config migrations, which take care of settings that have been changed in Advanced settings. I added examples of how to do both: remove a setting and rename a setting. These "sub-migrations" are all in core right now. There is an open issue to discuss potentially exposing a deprecation API that will allow settings-owners to declare their migration(s) on registration.

Overrides are validated at start-up and Kibana will throw a configuration error if there's an issue. I tried to explain that in this sentence:

If an override is misconfigured, it will fail config validation and will prevent Kibana from starting up.

However, at the moment, unrecognized settings don't cause issues. We still need to handle that. This is a good and a bad thing though, if someone has an override for a deprecated setting, it won't prevent Kibana from starting up 😉

@TinaHeiligers On this topic, maybe we should explicitly call out that 3rd party plugins cannot currently register migrations for their advanced settings? (i.e. at the moment, if a 3rd party plugin registers an advanced setting, it's essentially permanent and cannot be fixed without a manual migration, as we can't merge their migrations into core)

One other idea 🙂 maybe we can link to the docs on registering migrations from here.

Thank you both! I've added a tip about the deprecations parameter and updating the docs.

lukeelmers · 2022-02-04T15:03:03Z

docs/developer/architecture/core/uisettings-service.asciidoc

-=== Server side usage
+=== Overview
+
+UI settings are configurable from the Advanced Settings page in Management and control the behavior of {kib}. `uiSettings` are stored in a `config` saved object and, as such, conform to the same conditions as other saved objects.


nits/questions:

Should we link to the saved objects docs from here?

Do we capitalize Saved Objects in our docs? I'm never sure the right thing to do here, and I see a mix of both in the docs.

Maybe it depends on the context? Here I'm referring to Saved Objects as entities (proper nouns?), so I guess we should capitalize here too. 🤷‍♀️ . Lets go with that and see.

lukeelmers · 2022-02-04T15:33:09Z

docs/developer/architecture/core/uisettings-service.asciidoc

+- Locked via kibana.yml's {kib-repo}blob/{branch}/src/core/server/ui_settings/ui_settings_defaults_client.ts[uiSettings.overrides.<key>]
+- Through the client-side `uiSettings` Service
+- Through the server-side `uiSettings` Service


nit: In terms of structure, I'd consider treating these bullets as a sort of table of contents for the rest of the page, and make each entry an anchor link to a dedicated section on that topic. (You already have dedicated sections for client/server side, so it would mean making the overrides a dedicated section).

IMO a structure like this would help with the overall flow. Maybe something along the lines of:

Overview

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:

Through the Advanced Settings UI

Locked via kibana.yml’s uiSettings.overrides.<key>

Through the client-side uiSettings Service

Through the server-side uiSettings Service

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

Configuration with Advanced Settings UI

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 access 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.

Configuration with UI settings overrides

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 will 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.

Configuration on the client side

blahblah

Configuration on the server side

blahblahblah

Migrations

blahblahblah

lukeelmers · 2022-02-04T15:36:37Z

docs/developer/architecture/core/uisettings-service.asciidoc

+----
+{kib-repo}blob/{branch}/src/core/server/ui_settings/saved_objects/migrations.ts[`uiSettings` migrations] are declared directly in the `uiSettings` service.
+
+==== Security-related consideration


I'd consider merging this with a dedicated section on advanced settings ui (see my example above)

lukeelmers · 2022-02-04T15:51:04Z

docs/developer/architecture/core/uisettings-service.asciidoc

+- {kib-repo}blob/{branch}/docs/development/core/server/kibana-plugin-core-server.uisettingsservicesetup.register.md[UI settings service Setup API docs]
+
+==== Migrations
+Because `uiSettings` are persisted in the `config` saved object, changing or removing a setting requires a migration of the whole saved object. For example, if we wanted to remove the `custom` setting in the example above and then also rename `my_setting:fourtyTwo` to `my_other_setting:fourtyTwo`, we'd have two migration entries, one for each change targeting the required versions:


@TinaHeiligers On this topic, maybe we should explicitly call out that 3rd party plugins cannot currently register migrations for their advanced settings? (i.e. at the moment, if a 3rd party plugin registers an advanced setting, it's essentially permanent and cannot be fixed without a manual migration, as we can't merge their migrations into core)

lukeelmers · 2022-02-04T15:52:38Z

docs/developer/architecture/core/uisettings-service.asciidoc


-The program interface to <<advanced-options, UI settings>>.
-It makes it possible for Kibana plugins to extend Kibana UI Settings Management with custom settings.
+The `uiSettings` service is the programming interface to {kib} <<advanced-options, Advanced Settings UI>>. {kib} plugins use the service to extend Kibana UI Settings Management with custom settings for their plugin.


nit: programmatic interface? could probably go either way

lukeelmers · 2022-02-04T15:53:01Z

docs/developer/architecture/core/uisettings-service.asciidoc

+
+On the client, the `uiSettings` service is exposed directly from `core`.
+
+Users can adjust the settings via Management Advanced Settings UI. The client-side {kib-repo}blob/{branch}/docs/development/core/public/kibana-plugin-core-public.iuisettingsclient.md[`uiSettings` client] provides plugins access to the `config` entries stored in elasticsearch.


stored in {es}.

lukeelmers · 2022-02-04T15:53:31Z

docs/developer/architecture/core/uisettings-service.asciidoc

+
+Users can adjust the settings via Management Advanced Settings UI. The client-side {kib-repo}blob/{branch}/docs/development/core/public/kibana-plugin-core-public.iuisettingsclient.md[`uiSettings` 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 (or for whatever other reason) should register an instruction to reload the page when settings are configured in Advanced Settings using the `requiresPageReload` parameter.


nit: could probably drop the (or for whatever other reason) parenthetical

😆 good catch! That was a "bloop" from the rough draft!

lukeelmers · 2022-02-04T15:55:27Z

docs/developer/architecture/core/uisettings-service.asciidoc

+- {kib-repo}blob/{branch}/docs/development/core/server/kibana-plugin-core-server.uisettingsservicesetup.register.md[UI settings service Setup API docs]
+
+==== Migrations
+Because `uiSettings` are persisted in the `config` saved object, changing or removing a setting requires a migration of the whole saved object. For example, if we wanted to remove the `custom` setting in the example above and then also rename `my_setting:fourtyTwo` to `my_other_setting:fourtyTwo`, we'd have two migration entries, one for each change targeting the required versions:


One other idea 🙂 maybe we can link to the docs on registering migrations from here.

KOTungseth · 2022-02-04T16:14:52Z

@TinaHeiligers thank you for opening this PR! Is the plan to also update the Dev docs in the new docs system?

TinaHeiligers · 2022-02-04T18:36:19Z

@TinaHeiligers thank you for opening this PR! Is the plan to also update the Dev docs in the new docs system?

@KOTungseth I went hunting for these in the new docs system but couldn't find them 😱 . If you have a link, please send it my way, otherwise, we'll need new docs for those.

If you have a chance, I could use a hand with the language here too. I'm doing a second pass right now.

TinaHeiligers · 2022-02-04T22:01:48Z

docs/developer/architecture/core/uisettings-service.asciidoc

+
+[IMPORTANT]
+==============================================
+Migrations for 3rd party plugin advanced settings are not currently supported. If a 3rd party plugin registers an advanced setting, the setting is essentially permanent and cannot be fixed without manual intervention.


Explicitly point out that migrations for 3rd party plugin advanced settings aren't supported right now. cc @lukeelmers

👍 LGTM. Could consider linking to the GH issue, but I don't think it's critical.

TinaHeiligers · 2022-02-04T22:02:29Z

docs/developer/architecture/core/uisettings-service.asciidoc

+----
+
+[TIP]
+==============================================


This tip mentions how we warn users of future changes.

TinaHeiligers · 2022-02-04T22:03:36Z

docs/developer/architecture/core/uisettings-service.asciidoc

+
+UI settings are configurable from the Advanced Settings page in Management and control the behavior of {kib}. uiSettings are stored in a config saved object and, as such, conform to the same conditions as other <<saved-objects-service, Saved Objects>>.
+
+There are several ways to configure an advanced setting:


I've converted the bullet points into a sub-index for guiding readers through the contents on this page.

TinaHeiligers · 2022-02-04T22:07:20Z

docs/developer/architecture/core/uisettings-service.asciidoc

+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.
+
+[[uisettings-overrides]]
+=== Configuration with UI settings overrides


I was in two minds about explicitly mentioning overrides. We hadn't documented these in the past on purpose to limit their use. Folks generally discovered these by going through the code and if they had and something went wrong, we have to dig through and figure out where the issue is.

Explicitly documenting overrides here gives us the opportunity to warn about misconfiguration issues, limited validation, and how setting an override affects Kibana's behavior.

Maybe we add an experimental[] flag to this as a middle ground?

TinaHeiligers · 2022-02-04T22:08:07Z

docs/developer/architecture/core/uisettings-service.asciidoc

+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.
+
+[[client-side-usage]]
+=== Client side usage


We don't currently mention anything about the client-side service and how it's used. Now at least we do!

lukeelmers

🚀 Thanks for adding these!

lukeelmers · 2022-02-04T22:29:07Z

docs/developer/architecture/core/uisettings-service.asciidoc

+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.
+
+[[uisettings-overrides]]
+=== Configuration with UI settings overrides


Maybe we add an experimental[] flag to this as a middle ground?

lukeelmers · 2022-02-04T22:29:49Z

docs/developer/architecture/core/uisettings-service.asciidoc

+
+[IMPORTANT]
+==============================================
+Migrations for 3rd party plugin advanced settings are not currently supported. If a 3rd party plugin registers an advanced setting, the setting is essentially permanent and cannot be fixed without manual intervention.


👍 LGTM. Could consider linking to the GH issue, but I don't think it's critical.

lukeelmers · 2022-02-04T22:30:05Z

docs/developer/architecture/core/uisettings-service.asciidoc

+
+[TIP]
+==============================================
+Plugins can leverage the optional deprecation parameter on registration for handling deprecation notices and renames. The deprecation warnings are rendered in the Advanced Settings UI and should also be added to the Configure Kibana guide.


Maybe we link to Configure Kibana here?

kibana-ci · 2022-02-04T23:33:19Z

💚 Build Succeeded

Buildkite Build
Commit: 25d00cc

History

💚 Build #21975 succeeded f706ca2
💚 Build #21734 succeeded 7b5d9b6

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream

(cherry picked from commit 483483e)

kibanamachine · 2022-02-14T18:37:29Z

💚 All backports created successfully

Status	Branch	Result
✅	8.0
✅	8.1

Note: Successful backport PRs will be merged automatically after passing CI.

Questions ?

Please refer to the Backport tool documentation

(cherry picked from commit 483483e) Co-authored-by: Christiane (Tina) Heiligers <[email protected]>

Adds developer docs for uiSettings

7b5d9b6

TinaHeiligers added enhancement New value added to drive a business result technical debt Improvement of the software architecture and operational architecture backport:skip This commit does not require backporting docs DevDocs Feature:uiSettings labels Feb 4, 2022

TinaHeiligers marked this pull request as ready for review February 4, 2022 01:38

TinaHeiligers added the Team:Core Core services & architecture: plugins, logging, config, saved objects, http, ES client, i18n, etc label Feb 4, 2022

TinaHeiligers added release_note:skip Skip the PR/issue when compiling release notes v8.1.0 v8.2.0 labels Feb 4, 2022

afharo reviewed Feb 4, 2022

View reviewed changes

lukeelmers reviewed Feb 4, 2022

View reviewed changes

TinaHeiligers added 4 commits February 4, 2022 12:56

Rearranges the uiSettings page content

11cdf50

Applies peer reviewed suggestions

6c28050

Polish

841539d

Another try

f706ca2

TinaHeiligers commented Feb 4, 2022

View reviewed changes

TinaHeiligers requested a review from KOTungseth February 4, 2022 22:08

lukeelmers approved these changes Feb 4, 2022

View reviewed changes

Adds experimental flag to overrides, links to Configure Kibana

25d00cc

TinaHeiligers merged commit 483483e into elastic:main Feb 5, 2022

TinaHeiligers deleted the uiSettings-dev-docs branch February 5, 2022 00:30

TinaHeiligers mentioned this pull request Feb 8, 2022

Migrate uiSettings dev guide over to the new docs system #124910

Closed

TinaHeiligers added v8.0.0 v8.0.1 auto-backport Deprecated - use backport:version if exact versions are needed and removed backport:skip This commit does not require backporting labels Feb 14, 2022

kibanamachine pushed a commit to kibanamachine/kibana that referenced this pull request Feb 14, 2022

Adds developer docs for uiSettings (elastic#124648)

092f92c

(cherry picked from commit 483483e)

kibanamachine mentioned this pull request Feb 14, 2022

[8.0] Adds developer docs for uiSettings (#124648) #125564

Merged

kibanamachine pushed a commit to kibanamachine/kibana that referenced this pull request Feb 14, 2022

Adds developer docs for uiSettings (elastic#124648)

65c9cb1

(cherry picked from commit 483483e)

kibanamachine mentioned this pull request Feb 14, 2022

[8.1] Adds developer docs for uiSettings (#124648) #125565

Merged

kibanamachine added a commit that referenced this pull request Feb 14, 2022

Adds developer docs for uiSettings (#124648) (#125565)

60a5163

(cherry picked from commit 483483e) Co-authored-by: Christiane (Tina) Heiligers <[email protected]>

kibanamachine added a commit that referenced this pull request Feb 14, 2022

Adds developer docs for uiSettings (#124648) (#125564)

6b8ea28

(cherry picked from commit 483483e) Co-authored-by: Christiane (Tina) Heiligers <[email protected]>

	Registeration only requires a schema for validation on read and write, all {kib-repo}blob/{branch}/docs/development/core/server/kibana-plugin-core-server.uisettingsparams.md[other parameters] are optional.
	Registration only requires a schema for validation on read and write, all {kib-repo}blob/{branch}/docs/development/core/server/kibana-plugin-core-server.uisettingsparams.md[other parameters] are optional.


		Registeration only requires a schema for validation on read and write, all {kib-repo}blob/{branch}/docs/development/core/server/kibana-plugin-core-server.uisettingsparams.md[other parameters] are optional.

		See:


		There are several ways to configure an advanced setting:

		- Through the <<advanced-options, Advanced Settings UI>> (security restrictions apply)


		On the client, the `uiSettings` service is exposed directly from `core`.

		Users can adjust the settings via Management Advanced Settings UI. The client-side {kib-repo}blob/{branch}/docs/development/core/public/kibana-plugin-core-public.iuisettingsclient.md[`uiSettings` client] provides plugins access to the `config` entries stored in elasticsearch.


		Users can adjust the settings via Management Advanced Settings UI. The client-side {kib-repo}blob/{branch}/docs/development/core/public/kibana-plugin-core-public.iuisettingsclient.md[`uiSettings` 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 (or for whatever other reason) should register an instruction to reload the page when settings are configured in Advanced Settings using the `requiresPageReload` parameter.


		UI settings are configurable from the Advanced Settings page in Management and control the behavior of {kib}. uiSettings are stored in a config saved object and, as such, conform to the same conditions as other <<saved-objects-service, Saved Objects>>.

		There are several ways to configure an advanced setting:

Adds developer docs for uiSettings #124648

Adds developer docs for uiSettings #124648

Conversation

TinaHeiligers commented Feb 4, 2022

elasticmachine commented Feb 4, 2022

afharo left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TinaHeiligers Feb 4, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TinaHeiligers Feb 4, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Overview

Configuration with Advanced Settings UI

Configuration with UI settings overrides

Configuration on the client side

Configuration on the server side

Migrations

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

KOTungseth commented Feb 4, 2022

TinaHeiligers commented Feb 4, 2022 • edited Loading

TinaHeiligers Feb 4, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lukeelmers left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kibana-ci commented Feb 4, 2022

💚 Build Succeeded

History

kibanamachine commented Feb 14, 2022

💚 All backports created successfully

Questions ?

TinaHeiligers Feb 4, 2022 •

edited

Loading

TinaHeiligers Feb 4, 2022 •

edited

Loading

TinaHeiligers commented Feb 4, 2022 •

edited

Loading

TinaHeiligers Feb 4, 2022 •

edited

Loading