Summary

Fix #40255

Implement configuration deprecation management in new platform. core and plugins can now register deprecations to be used to mutates the raw configuration (by renaming or removing deprecated properties)

Actual implementation

The legacy config deprecation system was chaotic in the sense that deprecations were actually applied in different points (and time) in the code. However, the underneath implementation and API was pretty clever and NP implementation is strongly inspired by it.

core can now register deprecation providers using configService.addDeprecationProvider. Plugins can register the same providers when declaring their configuration using their PluginConfigDescriptor

 const configSchema = schema.object({
   someNewKey: schema.string({ defaultValue: 'a string' }),
 });
 
 type ConfigType = TypeOf<typeof configSchema>;
 
 export const config: PluginConfigDescriptor<ConfigType> = {
   schema: configSchema,
   deprecations: ({ rename, unused }) => [
     rename('someOldKey', 'someNewKey'),
     unused('deprecatedProperty'),
   ],
 };

By default, deprecations can only access a plugin's configuration schema, meaning that rename('someOldKey', 'someNewKey'), will actually rename myplugin.someOldKey to myplugin.someNewKey. However due to legacy and edge case requirements, we also expose APIs to access the whole config (renameFromRoot and unusedFromRoot)

Deprecations are not limited to rename and unused (even if they cover 99% of the needs) and any custom implementation of ConfigDeprecation can be returned by a provider.

RawConfigService and ConfigService changes

To properly manage and apply deprecations to the configuration values, I had to change these two services responsibilities a little. Now the RawConfigService returns the configuration values in a raw, Record<string, any> format instead of returning an actual Config object. This allows to move all configuration data manipulation logic in a single place (the config service). This is probably more coherent regarding what we could expect of a Raw[..]-type service anyway.

The most important change regarding ConfigService is in the schema validation timing: because of some edge cases of deprecations, it's no longer possible to validates a plugin's schema when registering it. Practical exemple is a property that would have been migrated from one plugin to another (and we got some of these in the legacy deprecations, such as rename('xpack.telemetry.enabled', 'telemetry.enabled'),). For this reason, global config validation is now done at a single point of time, just after plugins discovery.

Legacy deprecations in new platform

As legacy and new deprecation system are pretty close, I was able to create an adapter from legacy deprecations to new ones. the LegacyService now collect every legacy plugin's deprecation providers, adapt them, and register them in the new platform. That way, the NP configuration is properly aware of legacy deprecations and expose up to date values.

What remains to be done

• Totally removes the legacy deprecation system

UPDATE after discussion, this will be done after NP plugin migration, and is out of the scope of this PR

We are so close and yet so far. This impacts LegacyService and legacy code the most. Currently, the legacy service creates a LegacyConfig from the raw config's value, and calls findPluginSpecs with it. The config then enter in the legacy world/code, where discovered legacy plugins mutates the legacy configuration with both their schema, their value and their deprecations. This mutated legacy config is then considered the source of truth when we instanciate the legacy kibana server.

To be able to totally suppress the legacy deprecation system, we will need to remove the part where the deprecation are applied from legacy findPluginSpecs, get the non-migrated config back in legacyService, and then apply the new platform deprecation to it. However, all this code is strongly coupled atm, not typed (js, no ts), and lack test coverage, so I will need to be extremely careful with that part, and think that we might want to do it in a separate PR.

Checklist

Use strikethroughs to remove checklist items you don't feel are applicable to this PR.

- [ ] This was checked for cross-browser compatibility, including a check against IE11
- [ ] Any text added follows EUI's writing guidelines, uses sentence case text and includes i18n support

• Documentation was added for features that require explanation or tutorials
• Unit or functional tests were updated or added to match the most common scenarios
  - [ ] This was checked for keyboard-only and screenreader accessibility

For maintainers

- [ ] This was checked for breaking API changes and was labeled appropriately

• This includes a feature addition or change that requires a release note and was labeled appropriately

Dev Docs

New platform plugin's configuration now supports deprecation. Use the deprecations key of a plugin's config descriptor to register them.

 // my_plugin/server/index.ts
 import { schema, TypeOf } from '@kbn/config-schema';
 import { PluginConfigDescriptor } from 'kibana/server';
 
 const configSchema = schema.object({
   someNewKey: schema.string({ defaultValue: 'a string' }),
 });
 
 type ConfigType = TypeOf<typeof configSchema>;
 
 export const config: PluginConfigDescriptor<ConfigType> = {
   schema: configSchema,
   deprecations: ({ rename, unused }) => [
     rename('someOldKey', 'someNewKey'),
     unused('deprecatedProperty'),
   ],
 };