Explicitly set `level` for all registered deprecations #115344

pgayvallet · 2021-10-18T12:01:54Z

Required for #114197

In #114197, we're planning to no longer have the deprecation's level be optional when registering it.

For this reason, we need all deprecation owners to explicitly set the correct level for all of their existing deprecations, both config deprecations registered via the PluginConfigDescriptor, and deprecations registered via the core.deprecations API.

This will also be an occasion for all deprecation owners to check if their deprecations are defining their correct level, as most deprecations are currently using the default, which is critical, and may be wrong.

Note: having a deprecation with an incorrect level is considered a bug. Therefor, fixing your deprecation's level can be flagged as bug and merged after 7.16 FF.

How to choose the correct deprecation level?

Please follow these guidelines to decide if your deprecation should be considered as critical or warning:

Critical deprecations are ones that must be addressed before the upgrade, otherwise the deployment will be unstable, degraded, fail to start, or otherwise exhibit undesirable and unintended behavior.
Warning deprecations are everything else. They're optional or they may not apply to the user. The user has discretion to decide whether or not to act on them. If the user ignores them and upgrades the deployment, the deployment will function normally.

How to adapt my deprecation to set the correct level?

For config deprecations (registered with the plugin's config)

factory deprecations

Add the level option to the (optional) last parameter of the deprecation factory.

before

export const config: PluginConfigDescriptor<ConfigType> = {
  schema: configSchema,
  deprecations: ({ deprecate, rename, unused }) => [
    deprecate('enabled', '8.0.0'),
    rename('old', 'new'),
    unused('unused'),
  ],
};

after

export const config: PluginConfigDescriptor<ConfigType> = {
  schema: configSchema,
  deprecations: ({ deprecate, rename, unused }) => [
    deprecate('enabled', '8.0.0', { level: 'critical'}),
    rename('old', 'new', { level: 'warning'}),
    unused('unused', { level: 'warning'}),
  ],
};

non-factory deprecations

Just add the level option to the addDeprecation call:

before

export const config: PluginConfigDescriptor<MyConfigType> = {
  schema: ConfigSchema,
  deprecations: () => [
    (settings, fromPath, addDeprecation) => {
      if (someCondition) {
        addDeprecation({
          configPath: 'plugin.somePath',
          title: 'some title',
          message: `some message`,
          correctiveActions: {
            manualSteps: [`come on, do something`],
          },
        });
      }
    },
  ],
};

after

export const config: PluginConfigDescriptor<MyConfigType> = {
  schema: ConfigSchema,
  deprecations: () => [
    (settings, fromPath, addDeprecation) => {
      if (someCondition) {
        addDeprecation({
          configPath: 'plugin.somePath',
          level: ''warning, // <-- that's the only change
          title: 'some title',
          message: `some message`,
          correctiveActions: {
            manualSteps: [`come on, do something`],
          },
        });
      }
    },
  ],
};

For other deprecations (registered via `core.deprecations`)

Just specify the level option when returning your deprecations

before

core.deprecations.registerDeprecations({
   getDeprecations: async (context) => {
     return [{
       title: 'some title',
       message: 'some message',
       deprecationType: 'feature',
       correctiveActions: { /* */ }
     }];
   }
})

after

core.deprecations.registerDeprecations({
   getDeprecations: async (context) => {
     return [{
       level: 'critical', // <-- this is the only change
       title: 'some title',
       message: 'some message',
       deprecationType: 'feature',
       correctiveActions: { /* */ }
     }];
   }
})

Inventory

Note: this is the inventory from the 7.x branch, as a lot of deprecations are only present on this branch and not on master, and I don't think we have a lot of deprecations on master that are not present in 7.x. However, that's each team's responsibility to properly also reverse-backport/apply their changes on master when necessary.

I did not include the deprecate('enabled', '8.0.0') config deprecations in the per-team list to avoid pinging unnecessary teams, as we know those are all critical.

@elastic/kibana-core

done in #115501

/src/plugins/home/server/index.ts

kibana/src/plugins/home/server/index.ts

Lines 21 to 23 in 669839c

    
           deprecations: ({ renameFromRoot }) => [ 
        
             renameFromRoot('kibana.disableWelcomeScreen', 'home.disableWelcomeScreen'), 
        
           ],

/src/plugins/newsfeed/server/index.ts

kibana/src/plugins/newsfeed/server/index.ts

Line 20 in 57af846

deprecations: ({ unused }) => [unused('defaultLanguage')],

/src/plugins/telemetry/server/config/config.ts

kibana/src/plugins/telemetry/server/config/config.ts

Line 84 in cfae29a

deprecations: () => [deprecateEndpointConfigs],

/src/plugins/usage_collection/server/config.ts

kibana/src/plugins/usage_collection/server/config.ts

Lines 32 to 37 in c670302

    
           deprecations: ({ renameFromRoot }) => [ 
        
             renameFromRoot('ui_metric.enabled', 'usageCollection.uiCounters.enabled'), 
        
             renameFromRoot('ui_metric.debug', 'usageCollection.uiCounters.debug'), 
        
             renameFromRoot('usageCollection.uiMetric.enabled', 'usageCollection.uiCounters.enabled'), 
        
             renameFromRoot('usageCollection.uiMetric.debug', 'usageCollection.uiCounters.debug'), 
        
           ],

/x-pack/plugins/banners/server/config.ts

kibana/x-pack/plugins/banners/server/config.ts

Lines 42 to 46 in 26b5ef8

    
           deprecations: () => [ 
        
             (rootConfig, fromPath, addDeprecation) => { 
        
               const pluginConfig = get(rootConfig, fromPath); 
        
               if (pluginConfig?.placement === 'header') { 
        
                 addDeprecation({

/x-pack/plugins/licensing/server/licensing_config.ts

kibana/x-pack/plugins/licensing/server/licensing_config.ts

Lines 21 to 25 in 57af846

    
           deprecations: ({ renameFromRoot }) => [ 
        
             renameFromRoot( 
        
               'xpack.xpack_main.xpack_api_polling_frequency_millis', 
        
               'xpack.licensing.api_polling_frequency' 
        
             ),

@elastic/kibana-stack-management

/src/plugins/console/server/config.ts (183a1c3)

kibana/src/plugins/console/server/config.ts

Lines 69 to 74 in cef53a9

    
           deprecations: ({ deprecate, unused }) => [ 
        
             deprecate('enabled', '8.0.0'), 
        
             deprecate('proxyFilter', '8.0.0'), 
        
             deprecate('proxyConfig', '8.0.0'), 
        
             unused('ssl'), 
        
           ],

@elastic/kibana-app-services

/src/plugins/data/server/index.ts

kibana/src/plugins/data/server/index.ts

Lines 139 to 140 in 0d2fcbc

    
           export const config: PluginConfigDescriptor<ConfigSchema> = { 
        
             deprecations: autocompleteConfigDeprecationProvider,

/x-pack/plugins/reporting/server/config/index.ts ([Reporting] Add log level to config #118319)

kibana/x-pack/plugins/reporting/server/config/index.ts

Lines 19 to 23 in 26b5ef8

    
           deprecations: ({ unused }) => [ 
        
             unused('capture.browser.chromium.maxScreenshotDimension'), // unused since 7.8 
        
             unused('poll.jobCompletionNotifier.intervalErrorMultiplier'), // unused since 7.10 
        
             unused('poll.jobsRefresh.intervalErrorMultiplier'), // unused since 7.10 
        
             unused('capture.viewport'), // deprecated as unused since 7.16

@elastic/kibana-vis-editors

/src/plugins/kibana_legacy/server/index.ts

kibana/src/plugins/kibana_legacy/server/index.ts

Lines 19 to 21 in 26b5ef8

    
           deprecations: ({ renameFromRoot }) => [ 
        
             // TODO: Remove deprecation once defaultAppId is deleted 
        
             renameFromRoot('kibana.defaultAppId', 'kibana_legacy.defaultAppId', { silent: true }),

/src/plugins/vis_types/metric/server/index.ts

kibana/src/plugins/vis_types/metric/server/index.ts

Lines 15 to 17 in c13f6ad

    
           deprecations: ({ renameFromRoot }) => [ 
        
             renameFromRoot('metric_vis.enabled', 'vis_type_metric.enabled'), 
        
           ],

/src/plugins/vis_types/table/server/index.ts

kibana/src/plugins/vis_types/table/server/index.ts

Lines 17 to 21 in 10668d0

    
           deprecations: ({ renameFromRoot, unused }) => [ 
        
             renameFromRoot('table_vis.enabled', 'vis_type_table.enabled'), 
        
             // Unused property which should be removed after releasing Kibana v8.0: 
        
             unused('legacyVisEnabled'), 
        
           ],

/src/plugins/vis_types/tagcloud/server/index.ts

kibana/src/plugins/vis_types/tagcloud/server/index.ts

Lines 15 to 17 in c13f6ad

    
           deprecations: ({ renameFromRoot }) => [ 
        
             renameFromRoot('tagcloud.enabled', 'vis_type_tagcloud.enabled'), 
        
           ],

/src/plugins/vis_types/timelion/server/index.ts

kibana/src/plugins/vis_types/timelion/server/index.ts

Lines 15 to 18 in 10668d0

    
           deprecations: ({ renameFromRoot, unused }) => [ 
        
             renameFromRoot('timelion_vis.enabled', 'vis_type_timelion.enabled'), 
        
             renameFromRoot('timelion.enabled', 'vis_type_timelion.enabled'), 
        
             renameFromRoot('timelion.graphiteUrls', 'vis_type_timelion.graphiteUrls'),

/src/plugins/vis_types/timeseries/server/index.ts

kibana/src/plugins/vis_types/timeseries/server/index.ts

Lines 16 to 20 in f3a4520

    
           deprecations: ({ unused, renameFromRoot }) => [ 
        
             // In Kibana v7.8 plugin id was renamed from 'metrics' to 'vis_type_timeseries': 
        
             renameFromRoot('metrics.enabled', 'vis_type_timeseries.enabled'), 
        
             renameFromRoot('metrics.chartResolution', 'vis_type_timeseries.chartResolution', { 
        
               silent: true,

/src/plugins/vis_types/vega/server/index.ts

kibana/src/plugins/vis_types/vega/server/index.ts

Lines 19 to 21 in c13f6ad

    
           deprecations: ({ renameFromRoot }) => [ 
        
             renameFromRoot('vega.enableExternalUrls', 'vis_type_vega.enableExternalUrls'), 
        
             renameFromRoot('vega.enabled', 'vis_type_vega.enabled'),

@elastic/kibana-presentation

/src/plugins/vis_type_markdown/server/index.ts
Done Adds level to vis_markdown deprecations #118389

kibana/src/plugins/vis_type_markdown/server/index.ts

Lines 15 to 17 in 57af846

    
           deprecations: ({ renameFromRoot }) => [ 
        
             renameFromRoot('markdown_vis.enabled', 'vis_type_markdown.enabled'), 
        
           ],

@elastic/kibana-alerting-services

Done #115832

/x-pack/plugins/actions/server/index.ts

kibana/x-pack/plugins/actions/server/index.ts

Lines 59 to 61 in 26b5ef8

    
           deprecations: ({ renameFromRoot, unused }) => [ 
        
             renameFromRoot('xpack.actions.whitelistedHosts', 'xpack.actions.allowedHosts'), 
        
             (settings, fromPath, addDeprecation) => {

/x-pack/plugins/alerting/server/index.ts

kibana/x-pack/plugins/alerting/server/index.ts

Lines 51 to 56 in 26b5ef8

    
           deprecations: ({ renameFromRoot }) => [ 
        
             renameFromRoot('xpack.alerts.healthCheck', 'xpack.alerting.healthCheck'), 
        
             renameFromRoot( 
        
               'xpack.alerts.invalidateApiKeysTask.interval', 
        
               'xpack.alerting.invalidateApiKeysTask.interval' 
        
             ),

/x-pack/plugins/event_log/server/index.ts

kibana/x-pack/plugins/event_log/server/index.ts

Lines 29 to 34 in 26b5ef8

    
           deprecations: () => [ 
        
             (settings, fromPath, addDeprecation) => { 
        
               if ( 
        
                 settings?.xpack?.eventLog?.enabled === false || 
        
                 settings?.xpack?.eventLog?.enabled === true 
        
               ) {

/x-pack/plugins/stack_alerts/server/index.ts

kibana/x-pack/plugins/stack_alerts/server/index.ts

Lines 16 to 19 in 26b5ef8

    
           deprecations: () => [ 
        
             (settings, fromPath, addDeprecation) => { 
        
               const stackAlerts = get(settings, fromPath); 
        
               if (stackAlerts?.enabled === false || stackAlerts?.enabled === true) {

/x-pack/plugins/task_manager/server/index.ts

kibana/x-pack/plugins/task_manager/server/index.ts

Lines 47 to 50 in 26b5ef8

    
           deprecations: () => [ 
        
             (settings, fromPath, addDeprecation) => { 
        
               const taskManager = get(settings, fromPath); 
        
               if (taskManager?.index) {

/x-pack/plugins/triggers_actions_ui/server/index.ts

kibana/x-pack/plugins/triggers_actions_ui/server/index.ts

Lines 29 to 31 in 26b5ef8

    
           deprecations: () => [ 
        
             (settings, fromPath, addDeprecation) => { 
        
               const triggersActionsUi = get(settings, fromPath);

@elastic/apm-ui

Done in #116272

/x-pack/plugins/apm/server/index.ts

kibana/x-pack/plugins/apm/server/index.ts

Lines 68 to 73 in 2d28371

    
           }) => [ 
        
             deprecate('enabled', '8.0.0'), 
        
             renameFromRoot( 
        
               'apm_oss.transactionIndices', 
        
               'xpack.apm.indices.transaction' 
        
             ),

It already has a level

/x-pack/plugins/apm/server/deprecations/index.ts

kibana/x-pack/plugins/apm/server/deprecations/index.ts

Lines 22 to 28 in b47f88a

    
           return async ({ 
        
             savedObjectsClient, 
        
           }: GetDeprecationsContext): Promise<DeprecationsDetails[]> => { 
        
             const deprecations: DeprecationsDetails[] = []; 
        
             if (!fleet) { 
        
               return deprecations; 
        
             }

@elastic/security-threat-hunting (#118268)

/x-pack/plugins/cases/server/index.ts

kibana/x-pack/plugins/cases/server/index.ts

Lines 18 to 21 in ef8518d

    
           deprecations: ({ deprecate, renameFromRoot }) => [ 
        
             deprecate('enabled', '8.0.0'), 
        
             renameFromRoot('xpack.case.enabled', 'xpack.cases.enabled'), 
        
           ],

@elastic/kibana-security

/x-pack/plugins/security/server/config_deprecations.ts (done via Update security deprecation messages #115241/[7.x] Update security deprecation messages (#115241) #115395 in 7.x/master)

kibana/x-pack/plugins/security/server/config_deprecations.ts

Lines 11 to 17 in 26b5ef8

    
           export const securityConfigDeprecationProvider: ConfigDeprecationProvider = ({ 
        
             rename, 
        
             renameFromRoot, 
        
             unused, 
        
           }) => [ 
        
             rename('sessionTimeout', 'session.idleTimeout'), 
        
             rename('authProviders', 'authc.providers'),

/x-pack/plugins/spaces/server/config.ts (done via [7.x] Update security deprecation messages (#115241) #115395 in 7.x only, no deprecations remaining in master)

kibana/x-pack/plugins/spaces/server/config.ts

Lines 50 to 52 in 26b5ef8

    
           export const spacesConfigDeprecationProvider: ConfigDeprecationProvider = () => { 
        
             return [disabledDeprecation]; 
        
           };

@elastic/fleet

/x-pack/plugins/fleet/server/index.ts

kibana/x-pack/plugins/fleet/server/index.ts

Lines 46 to 49 in 26b5ef8

    
           deprecations: ({ deprecate, renameFromRoot, unused, unusedFromRoot }) => [ 
        
             deprecate('enabled', '8.0.0'), 
        
             // Fleet plugin was named ingestManager before 
        
             renameFromRoot('xpack.ingestManager.enabled', 'xpack.fleet.enabled'),

@elastic/kibana-gis

/x-pack/plugins/maps/server/index.ts

kibana/x-pack/plugins/maps/server/index.ts

Lines 26 to 32 in 26b5ef8

    
           deprecations: ({ deprecate }) => [ 
        
             deprecate('enabled', '8.0.0'), 
        
             ( 
        
               completeConfig: Record<string, any>, 
        
               rootPath: string, 
        
               addDeprecation: AddConfigDeprecation 
        
             ) => {

@elastic/security-solution (#118268)

/x-pack/plugins/security_solution/server/index.ts

kibana/x-pack/plugins/security_solution/server/index.ts

Lines 23 to 29 in ef8518d

    
           deprecations: ({ deprecate, renameFromRoot }) => [ 
        
             deprecate('enabled', '8.0.0'), 
        
             renameFromRoot('xpack.siem.enabled', 'xpack.securitySolution.enabled'), 
        
             renameFromRoot( 
        
               'xpack.siem.maxRuleImportExportSize', 
        
               'xpack.securitySolution.maxRuleImportExportSize' 
        
             ),

@elastic/rac

/x-pack/plugins/rule_registry/server/config.ts

kibana/x-pack/plugins/rule_registry/server/config.ts

Lines 12 to 15 in 8fe23f3

    
           deprecations: ({ deprecate, unused }) => [ 
        
             deprecate('enabled', '8.0.0'), 
        
             unused('unsafe.indexUpgrade.enabled'), 
        
           ],