diff --git a/src/core/server/deprecations/README.mdx b/src/core/server/deprecations/README.mdx new file mode 100644 index 0000000000000..9a2ad689974e6 --- /dev/null +++ b/src/core/server/deprecations/README.mdx @@ -0,0 +1,210 @@ +--- +id: kibCoreDeprecationsService +slug: /kibana-dev-docs/services/deprecations-service +title: Core Deprecations service +summary: The Deprecations service helps surface deprecated configs and features for plugins to our users +date: 2021-06-27 +tags: ['kibana','dev', 'contributor', 'api docs'] +--- + +# Core Deprecations service +This guide is written in the format of a FAQ to help you get started using the deprecations service. +For more details on the service contract we have documented all the service apis and properties under the +deprecation service docs generated by in core. + +## What is the deprecations service? +The deprecations service provides a way for the Kibana platform to communicate deprecated features +and configs with its users. These deprecations are only communicated to the user if the deployment is using +these features, allowing for a user tailored experience for upgrading the stack version. + +The Upgrade Assistant (UA) is the main consumer of these deprecations. The UA displays them to users and signals to +Cloud that the Stack is ready for a major upgrade. + + +## Where are deprecations displayed to users? +The Upgrade Assistant (UA) in Kibana is consuming the core deprecations service in order to surface plugin +deprecations. Each deprecation is required to provide manual steps that we display in the UI. Additionally +each deprecation can provide an optional API to automatically resolve the deprecation. + +To check your plugin deprecations, go to the UA interface via **Stack Management > Stack > Upgrade Assistant** +and click on `View deprecations` under the Kibana section. + +To display deprecations in the UA set `xpack.upgrade_assistant.readonly: false` in the kibana configurations. +The UA is in read-only mode and will be enabled up until the last minor before the next major release. + +## How do I use this service for deprecated plugin configurations? +The deprecations service automatically hooks deprecated configs with the deprecations service. + +All the config deprecation functions (`unused`, `unusedFromRoot`, `rename`, `renameFromRoot`) accept an +optional parameter to customize the deprecation details. + +To read more about the deprecation functions check `/kibana-dev-docs/corePluginApi` in the new doc +system under `core.ConfigDeprecationFactory`. You can also check the `ConfigDeprecationFactory` +[interface docs](../../../../../packages/kbn-config/src/deprecation/types.ts). + +### Example +```ts +export const config: PluginConfigDescriptor = { + schema: configSchema, + deprecations: ({ renameFromRoot }) => [ + renameFromRoot('ui_metric.debug', 'usageCollection.uiCounters.debug', { + documentationUrl: 'elastic.co/some-url', + }), + ], +}; +``` + +The service will show the following deprecation details when the users set the above deprecated kibana +config `ui_metric.debug`. + +```ts +{ + deprecationsInfo:[{ + level: 'critical', + message: `"ui_metric.debug" is deprecated and has been replaced by "usageCollection.uiCounters.debug"`, + documentationUrl: 'elastic.co/some-url', + correctiveActions:{ + manualSteps: [ + `Replace "ui_metric.debug" with "usageCollection.uiCounters.debug" in the Kibana config file, CLI flag, or environment variable (in Docker only).`, + ] + }, + domainId: 'usageCollection', + }], +} +``` + +#### Custom deprecations for plugin configs +Custom config deprecation handling allows specifying the deprecation details via the `addDeprecation`. + +##### Example + +```ts +export const config: PluginConfigDescriptor = { + exposeToBrowser: { + defaultAppId: true, + }, + schema: configSchema, + deprecations: () => [ + ( + completeConfig: Record, + rootPath: string, + addDeprecation: AddConfigDeprecation + ) => { + if ( + get(completeConfig, 'kibana.defaultAppId') === undefined && + get(completeConfig, 'kibana_legacy.defaultAppId') === undefined + ) { + return completeConfig; + } + addDeprecation({ + message: `kibana.defaultAppId is deprecated and will be removed in 8.0. Please use the "defaultRoute" advanced setting instead`, + correctiveActions: { + manualSteps: [ + 'Go to Stack Management > Advanced Settings', + 'Update the "defaultRoute" setting under the General section', + 'Remove "kibana.defaultAppId" from the kibana.yml config file', + ], + }, + }); + return completeConfig; + }, + ], +}; +``` + +## How do I add deprecations for non-config plugin deprecations? +Plugins are responsible for registering any deprecations during the `setup` lifecycle by using +the deprecations service. + +Examples of non-config deprecations include things like +- timelion sheets +- kibana_user security roles + +This service is not intended to be used for non-user facing deprecations or cases where the deprecation +cannot be 'detected' by this mechanism. + +### Usage +```ts +coreSetup.deprecations.registerDeprecations({ + getDeprecations: ({ esClient, savedObjectsClient }) => [{ ...`` }], +}); +``` + +The `getDeprecations` function is invoked when the user requests to see the deprecations affecting their deployment. +The function provides a context object which contains a scoped Elasticsearch client and a saved objects client. + +To check the full TS types of the service please check the [generated core docs](../../../../docs/development/core/server/kibana-plugin-core-server.deprecationsservicesetup.md). + +### Example +```ts +import { DeprecationsDetails, GetDeprecationsContext } from 'src/core/server'; + +async function getDeprecations({ esClient, savedObjectsClient }: GetDeprecationsContext): Promise { + const deprecations: DeprecationsDetails[] = []; + const testDashboardUser = await getTestDashboardUser(savedObjectsClient); + + if (testDashboardUser) { + deprecations.push({ + message: 'User "test_dashboard_user" is using a deprecated role: "kibana_user"', + documentationUrl: 'https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-user.html', + level: 'critical', + correctiveActions: { + api: { + path: '/internal/security/users/test_dashboard_user', + method: 'POST', + body: { + username: 'test_dashboard_user', + roles: [ + 'machine_learning_user', + 'enrich_user', + 'kibana_admin' + ], + full_name: 'Alison Goryachev', + email: 'alisongoryachev@gmail.com', + metadata: {}, + enabled: true + } + }, + manualSteps: [ + 'Using Kibana user management, change all users using the kibana_user role to the kibana_admin role.', + 'Using Kibana role-mapping management, change all role-mappings which assing the kibana_user role to the kibana_admin role.' + ] + }, + }); + } + + return deprecations; +} + ``` + +## How do I implement the API corrective action? +The deprecations API allows plugins to provide an API call that can be used to automatically fix specific deprecations. +To do so create a `PUT` or `POST` route in your plugin and specify data you want to be passed in the payload for the deprecation. + +In the example above, `/internal/security/users/test_dashboard_user` will be called when users click on `Quick Resolve` in the UA. The service will automatically pass the body provided in the api corrective action to provide context to the route for fixing the deprecation. + +The deprecations service expects a `200` status code to recognize the corrective action as a success. + +## How do I test my deprecations? +We recommend testing the route for your api corrective actions via unit and plugin functional tests. +To check the deprecation in the UI please check the UA page. + +To test that your logic registering the deprecations with the deprecations service during `setup` is valid we recommend adding +unit tests to check that the `getDeprecations` is returning the expected array of deprecations at different scenarios. + +Core provides mocks for the service which should help you focus on testing only your specific requirements. + +You can also use the deprecations service API; The deprecations service exposes an api `GET /api/deprecations/` which provides +a list of deprecations and possible corrective actions required to resolve these entries. The context is scoped to the requesting +user, hence a user with limited access might not be able to see all the deprecations affecting the deployment. + +Currently we do not have test objects to run functional tests against the Upgrade Assistant directly. + +## Should I use the service for all the deprecations before 8.0? +Yes. Using this service should help users find and resolve any issues specific to their deployment before upgrading. +We recommend adding a `documentationUrl` for every deprecation you expose to further assist our users if they need extra help. + +## Note on i18n +We have decided to support i18n to the exposed deprecations for a better user experience when using the UA. +We will inject `i18n` into the deprecation function to enable teams to use it before fully documenting its usage. +For context follow [this issue](https://github.com/elastic/kibana/issues/99072).