[Core] create deprecations service

[Bamieh]

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.

Registering deprecated features for you plugin:

Each plugin will be responsible for registering any deprecations during the setup lifecycle by using the deprecations service:

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 is passed a context object { esClient, savedObjectsClient }.

interface GetDeprecationsContext {
  esClient: IScopedClusterClient;
  savedObjectsClient: SavedObjectsClientContract;
}

interface DeprecationInfo {
  message: string;
  level: 'warning' | 'critical';
  documentationUrl?: string;
  correctiveActions: {
    api?: {
      path: string;
      method: 'POST' | 'PUT';
      body?: {
        [key: string]: any;
      };
    };
    manualSteps?: string[];
  }; 
}

Example

import { DeprecationsDetails, GetDeprecationsContext, CoreSetup } from 'src/core/server';

const getDeprecations = async ({ esClient, savedObjectsClient }: GetDeprecationsContext): DeprecationsDetails[] => {
  return [
     {
       message: string;
       level: 'warning' | 'critical';
       documentationUrl?: string;
       correctiveActions: {
         api?: {
           path: string;
           method: 'POST' | 'PUT';
           body?: { [key: string]: any },
         },
         manualSteps?: string[];
       }
     }
  ]
}

export class Plugin() {
  setup: (core: CoreSetup) => {
    core.deprecations.registerDeprecations({ getDeprecations });
  }
}

Deprecated Configs

The core service automatically hooks deprecated configs with the deprecations service.

All the config deprecation functions (unused, unusedFromRoot, rename, renameFromRoot) now accept an optional parameter to customize the deprecation details.

[
  rename('config.old', 'config.new', {
     silent: true,
     documentationUrl: 'elastic.co/some-url'
  }),
]

Example

export const config: PluginConfigDescriptor<ConfigType> = {
  schema: configSchema,
  deprecations: ({ renameFromRoot }) => [
    renameFromRoot('ui_metric.debug', 'usageCollection.uiCounters.debug'),
  ],
};

If Kibana has the config ui_metric.debug in the kibana.yml file. The deprecations service will show the following config deprecation details:

{
  "deprecationsInfo":[{
    "level":"critical",
    "message": "\"ui_metric.debug\" is deprecated and has been replaced by \"usageCollection.uiCounters.debug\"",
    "correctiveActions":{
      "manualSteps": [
        "Replace \"ui_metric.debug\" in the kibana.yml file with \"usageCollection.uiCounters.debug\""
        ]
      },
    "domainId":"usageCollection"
  }]
}

Plugin config registering custom deprecations

Custom config deprecation handling allows specifying the deprecation details via the addDeprecation.

Example:

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;
    },
  ],
};

Deprecations Client

Front the public side of the plugins, core exposes a deprecations client which communicates with the kibana server and grabs the deprecations.

The start contract exposes the following methods:

interface DeprecationsService {
    getAllDeprecations: (): Promise<PluginDeprecationDetails[]>;
    getDeprecations: (pluginId: string): Promise<PluginDeprecationDetails[]>;
}

Deprecations API

This API GET /api/deprecations/ provides the user with the 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.

Sample response

{
    "deprecationsInfo": [
        {
            "message": "You have 2 Timelion worksheets. The Timelion app will be removed in 8.0. To continue using your Timelion worksheets, migrate them to a dashboard.",
            "documentationUrl": "https://www.elastic.co/guide/en/kibana/master/dashboard.html#timelion-deprecation",
            "level": "warning",
            "correctiveActions": {
                "manualSteps": [
                    "Navigate to the Kibana Dashboard and click \"Create dashboard\".",
                    "Select Timelion from the \"New Visualization\" window.",
                    "Open a new tab, open the Timelion app, select the chart you want to copy, then copy the chart expression.",
                    "Go to Timelion, paste the chart expression in the Timelion expression field, then click Update.",
                    "In the toolbar, click Save.",
                    "On the Save visualization window, enter the visualization Title, then click Save and return."
                ]
            },
            "domainId": "timelion"
        },
        {
            "message": "User 'test_dashboard_user' is using a deprecated role: 'kibana_user'",
            "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."
                ]
            },
            "documentationUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-user.html",
            "level": "critical",
            "domainId": "security"
        },
        {
            "message": "User 'test' is using a deprecated role: 'kibana_dashboard_only_user'",
            "correctiveActions": {
                "manualSteps": [
                    "Using Kibana role management, create a new custom role.",
                    "Assign read-only access to the Dashboard feature.",
                    "Assign this role in place of the dashboard_only role."
                ]
            },
            "documentationUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-user.html",
            "level": "critical",
            "domainId": "security"
        },
        {
            "message": "User 'kibana' has been deprecated.",
            "correctiveActions": {
                "manualSteps": [
                    "Using Kibana user management, set the password for the kibana_system user",
                    "Update all kibana.yml files to use this username and password for elasticsearch.username and elasticsearch.password"
                ]
            },
            "documentationUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-user.html",
            "level": "critical",
            "domainId": "security"
        }
    ]
}

Note to reviewers

Please filter by code owners and check for changes. Since the logger was swapped with addDeprecation for custom config deprecations you might just need to review those 1 line changes for your plugin.

Related work for Upgrade assitant: https://github.com/elastic/elasticsearch-team-planning/issues/135

[elasticmachine]

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

[azasypkin]

Code review only, Security and Spaces changes LGTM.

[alisonelizabeth]

This looks great @Bamieh! Thanks for working on it.

I read through the documentation and did a light code review. Overall LGTM. I left one comment in the code - let me know what you think.

[TinaHeiligers]

@elastic/kibana-core are we planning to remove the deprecated server.cors config setting that was deprecated in 7.x?