[Deprecations service] FAQ documentation

src/core/server/deprecations/README.mdx

@@ -0,0 +1,182 @@
+---
+id: kibUsageCollectionPlugin
+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-05-03
+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've 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 if the deployment is using these features, allowing for a user tailored experience for upgrading the stack version.
+
+## 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 should have manual steps that we display in the UI to fix the deprecation an API to automatically resolve it.
+
+To check your plugin deprecations go to the UA interface and click on `view deprecations` under the kibana section.
+
+## 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.
+
+### Example
+```ts
+export const config: PluginConfigDescriptor<ConfigType> = {
+  schema: configSchema,
+  deprecations: ({ renameFromRoot }) => [
+    renameFromRoot('ui_metric.debug', 'usageCollection.uiCounters.debug', {
+      documentationUrl: 'elastic.co/some-url',
+    }),
+  ],
+};
+```
+
+If the above deprecated kibana config `ui_metric.debug` is being used by the cluster.
+The service will show the following details about the deprecation:
+
+```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<ConfigSchema> = {
+  exposeToBrowser: {
+    defaultAppId: true,
+  },
+  schema: configSchema,
+  deprecations: () => [
+    (
+      completeConfig: Record<string, any>,
+      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 }) => [{ ...`<list of deprecations>` }],
+});
+```
+
+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<DeprecationsDetails[]> {
+  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 pleae 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.
+
+
+## Should I use the service for all the deprecations before 8.0?
+Yes. Using this service should help the 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.