Implements config deprecation in New Platform

docs/development/core/public/kibana-plugin-public.savedobjectsclient.find.md

@@ -9,5 +9,5 @@ Search for objects
 <b>Signature:</b>
 
 ```typescript
-find: <T extends SavedObjectAttributes>(options: Pick<SavedObjectFindOptionsServer, "search" | "filter" | "type" | "page" | "fields" | "searchFields" | "defaultSearchOperator" | "hasReference" | "sortField" | "perPage">) => Promise<SavedObjectsFindResponsePublic<T>>;
+find: <T extends SavedObjectAttributes>(options: Pick<SavedObjectFindOptionsServer, "search" | "filter" | "type" | "page" | "perPage" | "sortField" | "fields" | "searchFields" | "hasReference" | "defaultSearchOperator">) => Promise<SavedObjectsFindResponsePublic<T>>;
 ```

docs/development/core/public/kibana-plugin-public.savedobjectsclient.md

@@ -20,7 +20,7 @@ export declare class SavedObjectsClient
 |  [bulkGet](./kibana-plugin-public.savedobjectsclient.bulkget.md) |  | <code>(objects?: {</code><br/><code>        id: string;</code><br/><code>        type: string;</code><br/><code>    }[]) =&gt; Promise&lt;SavedObjectsBatchResponse&lt;SavedObjectAttributes&gt;&gt;</code> | Returns an array of objects by id |
 |  [create](./kibana-plugin-public.savedobjectsclient.create.md) |  | <code>&lt;T extends SavedObjectAttributes&gt;(type: string, attributes: T, options?: SavedObjectsCreateOptions) =&gt; Promise&lt;SimpleSavedObject&lt;T&gt;&gt;</code> | Persists an object |
 |  [delete](./kibana-plugin-public.savedobjectsclient.delete.md) |  | <code>(type: string, id: string) =&gt; Promise&lt;{}&gt;</code> | Deletes an object |
-|  [find](./kibana-plugin-public.savedobjectsclient.find.md) |  | <code>&lt;T extends SavedObjectAttributes&gt;(options: Pick&lt;SavedObjectFindOptionsServer, &quot;search&quot; &#124; &quot;filter&quot; &#124; &quot;type&quot; &#124; &quot;page&quot; &#124; &quot;fields&quot; &#124; &quot;searchFields&quot; &#124; &quot;defaultSearchOperator&quot; &#124; &quot;hasReference&quot; &#124; &quot;sortField&quot; &#124; &quot;perPage&quot;&gt;) =&gt; Promise&lt;SavedObjectsFindResponsePublic&lt;T&gt;&gt;</code> | Search for objects |
+|  [find](./kibana-plugin-public.savedobjectsclient.find.md) |  | <code>&lt;T extends SavedObjectAttributes&gt;(options: Pick&lt;SavedObjectFindOptionsServer, &quot;search&quot; &#124; &quot;filter&quot; &#124; &quot;type&quot; &#124; &quot;page&quot; &#124; &quot;perPage&quot; &#124; &quot;sortField&quot; &#124; &quot;fields&quot; &#124; &quot;searchFields&quot; &#124; &quot;hasReference&quot; &#124; &quot;defaultSearchOperator&quot;&gt;) =&gt; Promise&lt;SavedObjectsFindResponsePublic&lt;T&gt;&gt;</code> | Search for objects |
 |  [get](./kibana-plugin-public.savedobjectsclient.get.md) |  | <code>&lt;T extends SavedObjectAttributes&gt;(type: string, id: string) =&gt; Promise&lt;SimpleSavedObject&lt;T&gt;&gt;</code> | Fetches a single object |
 
 ## Methods

docs/development/core/server/kibana-plugin-server.configdeprecation.md

@@ -0,0 +1,18 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [ConfigDeprecation](./kibana-plugin-server.configdeprecation.md)
+
+## ConfigDeprecation type
+
+Configuration deprecation returned from [ConfigDeprecationProvider](./kibana-plugin-server.configdeprecationprovider.md) that handles a single deprecation from the configuration.
+
+<b>Signature:</b>
+
+```typescript
+export declare type ConfigDeprecation = (config: Record<string, any>, fromPath: string, logger: ConfigDeprecationLogger) => Record<string, any>;
+```
+
+## Remarks
+
+This should only be manually implemented if [ConfigDeprecationFactory](./kibana-plugin-server.configdeprecationfactory.md) does not provide the proper helpers for a specific deprecation need.
+

docs/development/core/server/kibana-plugin-server.configdeprecationfactory.md

@@ -0,0 +1,36 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [ConfigDeprecationFactory](./kibana-plugin-server.configdeprecationfactory.md)
+
+## ConfigDeprecationFactory interface
+
+Provides helpers to generates the most commonly used [ConfigDeprecation](./kibana-plugin-server.configdeprecation.md) when invoking a [ConfigDeprecationProvider](./kibana-plugin-server.configdeprecationprovider.md)<!-- -->.
+
+See methods documentation for more detailed examples.
+
+<b>Signature:</b>
+
+```typescript
+export interface ConfigDeprecationFactory 
+```
+
+## Methods
+
+|  Method | Description |
+|  --- | --- |
+|  [rename(oldKey, newKey)](./kibana-plugin-server.configdeprecationfactory.rename.md) | Rename a configuration property from inside a plugin's configuration path. Will log a deprecation warning if the oldKey was found and deprecation applied. |
+|  [renameFromRoot(oldKey, newKey)](./kibana-plugin-server.configdeprecationfactory.renamefromroot.md) | Rename a configuration property from the root configuration. Will log a deprecation warning if the oldKey was found and deprecation applied.<!-- -->This should be only used when renaming properties from different configuration's path. To rename properties from inside a plugin's configuration, use 'rename' instead. |
+|  [unused(unusedKey)](./kibana-plugin-server.configdeprecationfactory.unused.md) | Remove a configuration property from inside a plugin's configuration path. Will log a deprecation warning if the unused key was found and deprecation applied. |
+|  [unusedFromRoot(unusedKey)](./kibana-plugin-server.configdeprecationfactory.unusedfromroot.md) | Remove a configuration property from the root configuration. Will log a deprecation warning if the unused key was found and deprecation applied.<!-- -->This should be only used when removing properties from outside of a plugin's configuration. To remove properties from inside a plugin's configuration, use 'unused' instead. |
+
+## Example
+
+
+```typescript
+const provider: ConfigDeprecationProvider = ({ rename, unused }) => [
+  rename('oldKey', 'newKey'),
+  unused('deprecatedKey'),
+]
+
+```
+

docs/development/core/server/kibana-plugin-server.configdeprecationfactory.rename.md

@@ -0,0 +1,36 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [ConfigDeprecationFactory](./kibana-plugin-server.configdeprecationfactory.md) &gt; [rename](./kibana-plugin-server.configdeprecationfactory.rename.md)
+
+## ConfigDeprecationFactory.rename() method
+
+Rename a configuration property from inside a plugin's configuration path. Will log a deprecation warning if the oldKey was found and deprecation applied.
+
+<b>Signature:</b>
+
+```typescript
+rename(oldKey: string, newKey: string): ConfigDeprecation;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  oldKey | <code>string</code> |  |
+|  newKey | <code>string</code> |  |
+
+<b>Returns:</b>
+
+`ConfigDeprecation`
+
+## Example
+
+Rename 'myplugin.oldKey' to 'myplugin.newKey'
+
+```typescript
+const provider: ConfigDeprecationProvider = ({ rename }) => [
+  rename('oldKey', 'newKey'),
+]
+
+```
+

docs/development/core/server/kibana-plugin-server.configdeprecationfactory.renamefromroot.md

@@ -0,0 +1,38 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [ConfigDeprecationFactory](./kibana-plugin-server.configdeprecationfactory.md) &gt; [renameFromRoot](./kibana-plugin-server.configdeprecationfactory.renamefromroot.md)
+
+## ConfigDeprecationFactory.renameFromRoot() method
+
+Rename a configuration property from the root configuration. Will log a deprecation warning if the oldKey was found and deprecation applied.
+
+This should be only used when renaming properties from different configuration's path. To rename properties from inside a plugin's configuration, use 'rename' instead.
+
+<b>Signature:</b>
+
+```typescript
+renameFromRoot(oldKey: string, newKey: string): ConfigDeprecation;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  oldKey | <code>string</code> |  |
+|  newKey | <code>string</code> |  |
+
+<b>Returns:</b>
+
+`ConfigDeprecation`
+
+## Example
+
+Rename 'oldplugin.key' to 'newplugin.key'
+
+```typescript
+const provider: ConfigDeprecationProvider = ({ renameFromRoot }) => [
+  renameFromRoot('oldplugin.key', 'newplugin.key'),
+]
+
+```
+

docs/development/core/server/kibana-plugin-server.configdeprecationfactory.unused.md

@@ -0,0 +1,35 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [ConfigDeprecationFactory](./kibana-plugin-server.configdeprecationfactory.md) &gt; [unused](./kibana-plugin-server.configdeprecationfactory.unused.md)
+
+## ConfigDeprecationFactory.unused() method
+
+Remove a configuration property from inside a plugin's configuration path. Will log a deprecation warning if the unused key was found and deprecation applied.
+
+<b>Signature:</b>
+
+```typescript
+unused(unusedKey: string): ConfigDeprecation;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  unusedKey | <code>string</code> |  |
+
+<b>Returns:</b>
+
+`ConfigDeprecation`
+
+## Example
+
+Flags 'myplugin.deprecatedKey' as unused
+
+```typescript
+const provider: ConfigDeprecationProvider = ({ unused }) => [
+  unused('deprecatedKey'),
+]
+
+```
+

docs/development/core/server/kibana-plugin-server.configdeprecationfactory.unusedfromroot.md

@@ -0,0 +1,37 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [ConfigDeprecationFactory](./kibana-plugin-server.configdeprecationfactory.md) &gt; [unusedFromRoot](./kibana-plugin-server.configdeprecationfactory.unusedfromroot.md)
+
+## ConfigDeprecationFactory.unusedFromRoot() method
+
+Remove a configuration property from the root configuration. Will log a deprecation warning if the unused key was found and deprecation applied.
+
+This should be only used when removing properties from outside of a plugin's configuration. To remove properties from inside a plugin's configuration, use 'unused' instead.
+
+<b>Signature:</b>
+
+```typescript
+unusedFromRoot(unusedKey: string): ConfigDeprecation;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  unusedKey | <code>string</code> |  |
+
+<b>Returns:</b>
+
+`ConfigDeprecation`
+
+## Example
+
+Flags 'somepath.deprecatedProperty' as unused
+
+```typescript
+const provider: ConfigDeprecationProvider = ({ unusedFromRoot }) => [
+  unusedFromRoot('somepath.deprecatedProperty'),
+]
+
+```
+

docs/development/core/server/kibana-plugin-server.configdeprecationlogger.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [ConfigDeprecationLogger](./kibana-plugin-server.configdeprecationlogger.md)
+
+## ConfigDeprecationLogger type
+
+Logger interface used when invoking a [ConfigDeprecation](./kibana-plugin-server.configdeprecation.md)
+
+<b>Signature:</b>
+
+```typescript
+export declare type ConfigDeprecationLogger = (message: string) => void;
+```

docs/development/core/server/kibana-plugin-server.configdeprecationprovider.md

@@ -0,0 +1,28 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [ConfigDeprecationProvider](./kibana-plugin-server.configdeprecationprovider.md)
+
+## ConfigDeprecationProvider type
+
+A provider that should returns a list of [ConfigDeprecation](./kibana-plugin-server.configdeprecation.md)<!-- -->.
+
+See [ConfigDeprecationFactory](./kibana-plugin-server.configdeprecationfactory.md) for more usage examples.
+
+<b>Signature:</b>
+
+```typescript
+export declare type ConfigDeprecationProvider = (factory: ConfigDeprecationFactory) => ConfigDeprecation[];
+```
+
+## Example
+
+
+```typescript
+const provider: ConfigDeprecationProvider = ({ rename, unused }) => [
+  rename('oldKey', 'newKey'),
+  unused('deprecatedKey'),
+  myCustomDeprecation,
+]
+
+```
+

docs/development/core/server/kibana-plugin-server.md

@@ -46,6 +46,7 @@ The plugin integrates with the core system via lifecycle events: `setup`<!-- -->
 |  [Capabilities](./kibana-plugin-server.capabilities.md) | The read-only set of capabilities available for the current UI session. Capabilities are simple key-value pairs of (string, boolean), where the string denotes the capability ID, and the boolean is a flag indicating if the capability is enabled or disabled. |
 |  [CapabilitiesSetup](./kibana-plugin-server.capabilitiessetup.md) | APIs to manage the [Capabilities](./kibana-plugin-server.capabilities.md) that will be used by the application.<!-- -->Plugins relying on capabilities to toggle some of their features should register them during the setup phase using the <code>registerProvider</code> method.<!-- -->Plugins having the responsibility to restrict capabilities depending on a given context should register their capabilities switcher using the <code>registerSwitcher</code> method.<!-- -->Refers to the methods documentation for complete description and examples. |
 |  [CapabilitiesStart](./kibana-plugin-server.capabilitiesstart.md) | APIs to access the application [Capabilities](./kibana-plugin-server.capabilities.md)<!-- -->. |
+|  [ConfigDeprecationFactory](./kibana-plugin-server.configdeprecationfactory.md) | Provides helpers to generates the most commonly used [ConfigDeprecation](./kibana-plugin-server.configdeprecation.md) when invoking a [ConfigDeprecationProvider](./kibana-plugin-server.configdeprecationprovider.md)<!-- -->.<!-- -->See methods documentation for more detailed examples. |
 |  [ContextSetup](./kibana-plugin-server.contextsetup.md) | An object that handles registration of context providers and configuring handlers with context. |
 |  [CoreSetup](./kibana-plugin-server.coresetup.md) | Context passed to the plugins <code>setup</code> method. |
 |  [CoreStart](./kibana-plugin-server.corestart.md) | Context passed to the plugins <code>start</code> method. |
@@ -79,7 +80,7 @@ The plugin integrates with the core system via lifecycle events: `setup`<!-- -->
 |  [OnPreAuthToolkit](./kibana-plugin-server.onpreauthtoolkit.md) | A tool set defining an outcome of OnPreAuth interceptor for incoming request. |
 |  [PackageInfo](./kibana-plugin-server.packageinfo.md) |  |
 |  [Plugin](./kibana-plugin-server.plugin.md) | The interface that should be returned by a <code>PluginInitializer</code>. |
-|  [PluginConfigDescriptor](./kibana-plugin-server.pluginconfigdescriptor.md) | Describes a plugin configuration schema and capabilities. |
+|  [PluginConfigDescriptor](./kibana-plugin-server.pluginconfigdescriptor.md) | Describes a plugin configuration properties. |
 |  [PluginInitializerContext](./kibana-plugin-server.plugininitializercontext.md) | Context that's available to plugins during initialization stage. |
 |  [PluginManifest](./kibana-plugin-server.pluginmanifest.md) | Describes the set of required and optional properties plugin can define in its mandatory JSON manifest file. |
 |  [PluginsServiceSetup](./kibana-plugin-server.pluginsservicesetup.md) |  |
@@ -149,6 +150,9 @@ The plugin integrates with the core system via lifecycle events: `setup`<!-- -->
 |  [AuthResult](./kibana-plugin-server.authresult.md) |  |
 |  [CapabilitiesProvider](./kibana-plugin-server.capabilitiesprovider.md) | See [CapabilitiesSetup](./kibana-plugin-server.capabilitiessetup.md) |
 |  [CapabilitiesSwitcher](./kibana-plugin-server.capabilitiesswitcher.md) | See [CapabilitiesSetup](./kibana-plugin-server.capabilitiessetup.md) |
+|  [ConfigDeprecation](./kibana-plugin-server.configdeprecation.md) | Configuration deprecation returned from [ConfigDeprecationProvider](./kibana-plugin-server.configdeprecationprovider.md) that handles a single deprecation from the configuration. |
+|  [ConfigDeprecationLogger](./kibana-plugin-server.configdeprecationlogger.md) | Logger interface used when invoking a [ConfigDeprecation](./kibana-plugin-server.configdeprecation.md) |
+|  [ConfigDeprecationProvider](./kibana-plugin-server.configdeprecationprovider.md) | A provider that should returns a list of [ConfigDeprecation](./kibana-plugin-server.configdeprecation.md)<!-- -->.<!-- -->See [ConfigDeprecationFactory](./kibana-plugin-server.configdeprecationfactory.md) for more usage examples. |
 |  [ConfigPath](./kibana-plugin-server.configpath.md) |  |
 |  [ElasticsearchClientConfig](./kibana-plugin-server.elasticsearchclientconfig.md) |  |
 |  [GetAuthHeaders](./kibana-plugin-server.getauthheaders.md) | Get headers to authenticate a user against Elasticsearch. |

docs/development/core/server/kibana-plugin-server.pluginconfigdescriptor.deprecations.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-server](./kibana-plugin-server.md) &gt; [PluginConfigDescriptor](./kibana-plugin-server.pluginconfigdescriptor.md) &gt; [deprecations](./kibana-plugin-server.pluginconfigdescriptor.deprecations.md)
+
+## PluginConfigDescriptor.deprecations property
+
+Provider for the [ConfigDeprecation](./kibana-plugin-server.configdeprecation.md) to apply to the plugin configuration.
+
+<b>Signature:</b>
+
+```typescript
+deprecations?: ConfigDeprecationProvider;
+```

docs/development/core/server/kibana-plugin-server.pluginconfigdescriptor.md

@@ -4,7 +4,7 @@
 
 ## PluginConfigDescriptor interface
 
-Describes a plugin configuration schema and capabilities.
+Describes a plugin configuration properties.
 
 <b>Signature:</b>
 
@@ -16,6 +16,7 @@ export interface PluginConfigDescriptor<T = any>
 
 |  Property | Type | Description |
 |  --- | --- | --- |
+|  [deprecations](./kibana-plugin-server.pluginconfigdescriptor.deprecations.md) | <code>ConfigDeprecationProvider</code> | Provider for the [ConfigDeprecation](./kibana-plugin-server.configdeprecation.md) to apply to the plugin configuration. |
 |  [exposeToBrowser](./kibana-plugin-server.pluginconfigdescriptor.exposetobrowser.md) | <code>{</code><br/><code>        [P in keyof T]?: boolean;</code><br/><code>    }</code> | List of configuration properties that will be available on the client-side plugin. |
 |  [schema](./kibana-plugin-server.pluginconfigdescriptor.schema.md) | <code>PluginConfigSchema&lt;T&gt;</code> | Schema to use to validate the plugin configuration.[PluginConfigSchema](./kibana-plugin-server.pluginconfigschema.md) |
 
@@ -39,6 +40,10 @@ export const config: PluginConfigDescriptor<ConfigType> = {
     uiProp: true,
   },
   schema: configSchema,
+  deprecations: ({ rename, unused }) => [
+    rename('securityKey', 'secret'),
+    unused('deprecatedProperty'),
+  ],
 };
 
 ```

src/core/public/public.api.md

@@ -872,7 +872,7 @@ export class SavedObjectsClient {
     bulkUpdate<T extends SavedObjectAttributes>(objects?: SavedObjectsBulkUpdateObject[]): Promise<SavedObjectsBatchResponse<SavedObjectAttributes>>;
     create: <T extends SavedObjectAttributes>(type: string, attributes: T, options?: SavedObjectsCreateOptions) => Promise<SimpleSavedObject<T>>;
     delete: (type: string, id: string) => Promise<{}>;
-    find: <T extends SavedObjectAttributes>(options: Pick<SavedObjectsFindOptions, "search" | "filter" | "type" | "page" | "fields" | "searchFields" | "defaultSearchOperator" | "hasReference" | "sortField" | "perPage">) => Promise<SavedObjectsFindResponsePublic<T>>;
+    find: <T extends SavedObjectAttributes>(options: Pick<SavedObjectsFindOptions, "search" | "filter" | "type" | "page" | "perPage" | "sortField" | "fields" | "searchFields" | "hasReference" | "defaultSearchOperator">) => Promise<SavedObjectsFindResponsePublic<T>>;
     get: <T extends SavedObjectAttributes>(type: string, id: string) => Promise<SimpleSavedObject<T>>;
     update<T extends SavedObjectAttributes>(type: string, id: string, attributes: T, { version, migrationVersion, references }?: SavedObjectsUpdateOptions): Promise<SimpleSavedObject<T>>;
 }