From 3e755ccf1fb4ee6f93d78ce0c141233a8f39d1fb Mon Sep 17 00:00:00 2001 From: Ahmad Bamieh Date: Wed, 2 Jun 2021 18:28:22 +0300 Subject: [PATCH] [7.x] [Deprecations service] make `correctiveActions.manualSteps` required (#100997) (#101156) * merge conflicts * update deprecation message --- ...r.deprecationsdetails.correctiveactions.md | 2 +- ...-plugin-core-server.deprecationsdetails.md | 2 +- .../kbn-config/src/config_service.test.ts | 38 +++++- packages/kbn-config/src/deprecation/types.ts | 4 +- .../deprecations/deprecations_client.test.ts | 11 +- .../deprecation/core_deprecations.test.ts | 6 +- .../config/deprecation/core_deprecations.ts | 121 +++++++++++++++++- .../deprecations/deprecations_service.ts | 4 +- src/core/server/deprecations/types.ts | 8 +- .../elasticsearch/elasticsearch_config.ts | 22 ++++ src/core/server/kibana_config.ts | 6 + .../saved_objects/saved_objects_config.ts | 3 + src/core/server/server.api.md | 2 +- .../core_plugin_deprecations/server/config.ts | 5 + .../core_plugin_deprecations/server/plugin.ts | 4 +- .../test_suites/core/deprecations.ts | 13 +- x-pack/plugins/actions/server/index.ts | 37 +++++- x-pack/plugins/banners/server/config.ts | 6 + .../plugins/monitoring/server/deprecations.ts | 21 +++ .../reporting/server/config/index.test.ts | 2 +- .../plugins/reporting/server/config/index.ts | 15 ++- .../server/config_deprecations.test.ts | 4 +- .../security/server/config_deprecations.ts | 24 +++- x-pack/plugins/spaces/server/config.ts | 3 + x-pack/plugins/task_manager/server/index.ts | 12 ++ .../client_integration/overview.test.ts | 2 +- 26 files changed, 340 insertions(+), 37 deletions(-) diff --git a/docs/development/core/server/kibana-plugin-core-server.deprecationsdetails.correctiveactions.md b/docs/development/core/server/kibana-plugin-core-server.deprecationsdetails.correctiveactions.md index e362bc4e0329c4..447823a5c34910 100644 --- a/docs/development/core/server/kibana-plugin-core-server.deprecationsdetails.correctiveactions.md +++ b/docs/development/core/server/kibana-plugin-core-server.deprecationsdetails.correctiveactions.md @@ -15,6 +15,6 @@ correctiveActions: { [key: string]: any; }; }; - manualSteps?: string[]; + manualSteps: string[]; }; ``` diff --git a/docs/development/core/server/kibana-plugin-core-server.deprecationsdetails.md b/docs/development/core/server/kibana-plugin-core-server.deprecationsdetails.md index 6e46ce0b8611f7..7592b8486d950f 100644 --- a/docs/development/core/server/kibana-plugin-core-server.deprecationsdetails.md +++ b/docs/development/core/server/kibana-plugin-core-server.deprecationsdetails.md @@ -14,7 +14,7 @@ export interface DeprecationsDetails | Property | Type | Description | | --- | --- | --- | -| [correctiveActions](./kibana-plugin-core-server.deprecationsdetails.correctiveactions.md) | {
api?: {
path: string;
method: 'POST' | 'PUT';
body?: {
[key: string]: any;
};
};
manualSteps?: string[];
} | | +| [correctiveActions](./kibana-plugin-core-server.deprecationsdetails.correctiveactions.md) | {
api?: {
path: string;
method: 'POST' | 'PUT';
body?: {
[key: string]: any;
};
};
manualSteps: string[];
} | | | [deprecationType](./kibana-plugin-core-server.deprecationsdetails.deprecationtype.md) | 'config' | 'feature' | (optional) Used to identify between different deprecation types. Example use case: in Upgrade Assistant, we may want to allow the user to sort by deprecation type or show each type in a separate tab.Feel free to add new types if necessary. Predefined types are necessary to reduce having similar definitions with different keywords across kibana deprecations. | | [documentationUrl](./kibana-plugin-core-server.deprecationsdetails.documentationurl.md) | string | | | [level](./kibana-plugin-core-server.deprecationsdetails.level.md) | 'warning' | 'critical' | 'fetch_error' | levels: - warning: will not break deployment upon upgrade - critical: needs to be addressed before upgrade. - fetch\_error: Deprecations service failed to grab the deprecation details for the domain. | diff --git a/packages/kbn-config/src/config_service.test.ts b/packages/kbn-config/src/config_service.test.ts index c2d4f15b6d9153..b1b622381abb1c 100644 --- a/packages/kbn-config/src/config_service.test.ts +++ b/packages/kbn-config/src/config_service.test.ts @@ -418,8 +418,14 @@ test('logs deprecation warning during validation', async () => { const configService = new ConfigService(rawConfig, defaultEnv, logger); mockApplyDeprecations.mockImplementationOnce((config, deprecations, createAddDeprecation) => { const addDeprecation = createAddDeprecation!(''); - addDeprecation({ message: 'some deprecation message' }); - addDeprecation({ message: 'another deprecation message' }); + addDeprecation({ + message: 'some deprecation message', + correctiveActions: { manualSteps: ['do X'] }, + }); + addDeprecation({ + message: 'another deprecation message', + correctiveActions: { manualSteps: ['do Y'] }, + }); return { config, changedPaths: mockedChangedPaths }; }); @@ -444,13 +450,24 @@ test('does not log warnings for silent deprecations during validation', async () mockApplyDeprecations .mockImplementationOnce((config, deprecations, createAddDeprecation) => { const addDeprecation = createAddDeprecation!(''); - addDeprecation({ message: 'some deprecation message', silent: true }); - addDeprecation({ message: 'another deprecation message' }); + addDeprecation({ + message: 'some deprecation message', + correctiveActions: { manualSteps: ['do X'] }, + silent: true, + }); + addDeprecation({ + message: 'another deprecation message', + correctiveActions: { manualSteps: ['do Y'] }, + }); return { config, changedPaths: mockedChangedPaths }; }) .mockImplementationOnce((config, deprecations, createAddDeprecation) => { const addDeprecation = createAddDeprecation!(''); - addDeprecation({ message: 'I am silent', silent: true }); + addDeprecation({ + message: 'I am silent', + silent: true, + correctiveActions: { manualSteps: ['do Z'] }, + }); return { config, changedPaths: mockedChangedPaths }; }); @@ -519,7 +536,11 @@ describe('getHandledDeprecatedConfigs', () => { mockApplyDeprecations.mockImplementationOnce((config, deprecations, createAddDeprecation) => { deprecations.forEach((deprecation) => { const addDeprecation = createAddDeprecation!(deprecation.path); - addDeprecation({ message: `some deprecation message`, documentationUrl: 'some-url' }); + addDeprecation({ + message: `some deprecation message`, + documentationUrl: 'some-url', + correctiveActions: { manualSteps: ['do X'] }, + }); }); return { config, changedPaths: mockedChangedPaths }; }); @@ -532,6 +553,11 @@ describe('getHandledDeprecatedConfigs', () => { "base", Array [ Object { + "correctiveActions": Object { + "manualSteps": Array [ + "do X", + ], + }, "documentationUrl": "some-url", "message": "some deprecation message", }, diff --git a/packages/kbn-config/src/deprecation/types.ts b/packages/kbn-config/src/deprecation/types.ts index 0522365ad76c11..1791dac060e2bf 100644 --- a/packages/kbn-config/src/deprecation/types.ts +++ b/packages/kbn-config/src/deprecation/types.ts @@ -25,8 +25,8 @@ export interface DeprecatedConfigDetails { silent?: boolean; /* (optional) link to the documentation for more details on the deprecation. */ documentationUrl?: string; - /* (optional) corrective action needed to fix this deprecation. */ - correctiveActions?: { + /* corrective action needed to fix this deprecation. */ + correctiveActions: { /** * Specify a list of manual steps our users need to follow * to fix the deprecation before upgrade. diff --git a/src/core/public/deprecations/deprecations_client.test.ts b/src/core/public/deprecations/deprecations_client.test.ts index 2f52f7b4af195b..a998a03772cca8 100644 --- a/src/core/public/deprecations/deprecations_client.test.ts +++ b/src/core/public/deprecations/deprecations_client.test.ts @@ -90,6 +90,7 @@ describe('DeprecationsClient', () => { path: 'some-path', method: 'POST', }, + manualSteps: ['manual-step'], }, }; @@ -104,7 +105,9 @@ describe('DeprecationsClient', () => { domainId: 'testPluginId-1', message: 'some-message', level: 'warning', - correctiveActions: {}, + correctiveActions: { + manualSteps: ['manual-step'], + }, }; const isResolvable = deprecationsClient.isDeprecationResolvable(mockDeprecationDetails); @@ -120,7 +123,9 @@ describe('DeprecationsClient', () => { domainId: 'testPluginId-1', message: 'some-message', level: 'warning', - correctiveActions: {}, + correctiveActions: { + manualSteps: ['manual-step'], + }, }; const result = await deprecationsClient.resolveDeprecation(mockDeprecationDetails); @@ -144,6 +149,7 @@ describe('DeprecationsClient', () => { extra_param: 123, }, }, + manualSteps: ['manual-step'], }, }; const result = await deprecationsClient.resolveDeprecation(mockDeprecationDetails); @@ -176,6 +182,7 @@ describe('DeprecationsClient', () => { extra_param: 123, }, }, + manualSteps: ['manual-step'], }, }; http.fetch.mockRejectedValue({ body: { message: mockResponse } }); diff --git a/src/core/server/config/deprecation/core_deprecations.test.ts b/src/core/server/config/deprecation/core_deprecations.test.ts index 26fb96154223cd..5abe7da721ed2b 100644 --- a/src/core/server/config/deprecation/core_deprecations.test.ts +++ b/src/core/server/config/deprecation/core_deprecations.test.ts @@ -24,7 +24,7 @@ describe('core deprecations', () => { const { messages } = applyCoreDeprecations(); expect(messages).toMatchInlineSnapshot(` Array [ - "Environment variable CONFIG_PATH is deprecated. It has been replaced with KBN_PATH_CONF pointing to a config folder", + "Environment variable \\"CONFIG_PATH\\" is deprecated. It has been replaced with \\"KBN_PATH_CONF\\" pointing to a config folder", ] `); }); @@ -425,7 +425,7 @@ describe('core deprecations', () => { }); expect(messages).toMatchInlineSnapshot(` Array [ - "\\"logging.events.log\\" has been deprecated and will be removed in 8.0. Moving forward, log levels can be customized on a per-logger basis using the new logging configuration. ", + "\\"logging.events.log\\" has been deprecated and will be removed in 8.0. Moving forward, log levels can be customized on a per-logger basis using the new logging configuration.", ] `); }); @@ -438,7 +438,7 @@ describe('core deprecations', () => { }); expect(messages).toMatchInlineSnapshot(` Array [ - "\\"logging.events.error\\" has been deprecated and will be removed in 8.0. Moving forward, you can use \\"logging.root.level: error\\" in your logging configuration. ", + "\\"logging.events.error\\" has been deprecated and will be removed in 8.0. Moving forward, you can use \\"logging.root.level: error\\" in your logging configuration.", ] `); }); diff --git a/src/core/server/config/deprecation/core_deprecations.ts b/src/core/server/config/deprecation/core_deprecations.ts index e270a5c67aa1c6..04889f20956b50 100644 --- a/src/core/server/config/deprecation/core_deprecations.ts +++ b/src/core/server/config/deprecation/core_deprecations.ts @@ -11,7 +11,10 @@ import { ConfigDeprecationProvider, ConfigDeprecation } from '@kbn/config'; const configPathDeprecation: ConfigDeprecation = (settings, fromPath, addDeprecation) => { if (process.env?.CONFIG_PATH) { addDeprecation({ - message: `Environment variable CONFIG_PATH is deprecated. It has been replaced with KBN_PATH_CONF pointing to a config folder`, + message: `Environment variable "CONFIG_PATH" is deprecated. It has been replaced with "KBN_PATH_CONF" pointing to a config folder`, + correctiveActions: { + manualSteps: ['Use "KBN_PATH_CONF" instead of "CONFIG_PATH" to point to a config folder.'], + }, }); } }; @@ -20,6 +23,11 @@ const dataPathDeprecation: ConfigDeprecation = (settings, fromPath, addDeprecati if (process.env?.DATA_PATH) { addDeprecation({ message: `Environment variable "DATA_PATH" will be removed. It has been replaced with kibana.yml setting "path.data"`, + correctiveActions: { + manualSteps: [ + `Set 'path.data' in the config file or CLI flag with the value of the environment variable "DATA_PATH".`, + ], + }, }); } }; @@ -32,6 +40,12 @@ const rewriteBasePathDeprecation: ConfigDeprecation = (settings, fromPath, addDe 'will expect that all requests start with server.basePath rather than expecting you to rewrite ' + 'the requests in your reverse proxy. Set server.rewriteBasePath to false to preserve the ' + 'current behavior and silence this warning.', + correctiveActions: { + manualSteps: [ + `Set 'server.rewriteBasePath' in the config file, CLI flag, or environment variable (in Docker only).`, + `Set to false to preserve the current behavior and silence this warning.`, + ], + }, }); } }; @@ -41,6 +55,11 @@ const rewriteCorsSettings: ConfigDeprecation = (settings, fromPath, addDeprecati if (typeof corsSettings === 'boolean') { addDeprecation({ message: '"server.cors" is deprecated and has been replaced by "server.cors.enabled"', + correctiveActions: { + manualSteps: [ + `Replace "server.cors: ${corsSettings}" with "server.cors.enabled: ${corsSettings}"`, + ], + }, }); return { @@ -72,6 +91,9 @@ const cspRulesDeprecation: ConfigDeprecation = (settings, fromPath, addDeprecati if (sourceList.find((source) => source.includes(NONCE_STRING))) { addDeprecation({ message: `csp.rules no longer supports the {nonce} syntax. Replacing with 'self' in ${policy}`, + correctiveActions: { + manualSteps: [`Replace {nonce} syntax with 'self' in ${policy}`], + }, }); sourceList = sourceList.filter((source) => !source.includes(NONCE_STRING)); @@ -87,6 +109,9 @@ const cspRulesDeprecation: ConfigDeprecation = (settings, fromPath, addDeprecati ) { addDeprecation({ message: `csp.rules must contain the 'self' source. Automatically adding to ${policy}.`, + correctiveActions: { + manualSteps: [`Add 'self' source to ${policy}.`], + }, }); sourceList.push(SELF_STRING); } @@ -111,6 +136,12 @@ const mapManifestServiceUrlDeprecation: ConfigDeprecation = ( 'of the Elastic Maps Service settings. These settings have moved to the "map.emsTileApiUrl" and ' + '"map.emsFileApiUrl" settings instead. These settings are for development use only and should not be ' + 'modified for use in production environments.', + correctiveActions: { + manualSteps: [ + `Use "map.emsTileApiUrl" and "map.emsFileApiUrl" config instead of "map.manifestServiceUrl".`, + `These settings are for development use only and should not be modified for use in production environments.`, + ], + }, }); } }; @@ -121,6 +152,11 @@ const serverHostZeroDeprecation: ConfigDeprecation = (settings, fromPath, addDep message: 'Support for setting server.host to "0" in kibana.yml is deprecated and will be removed in Kibana version 8.0.0. ' + 'Instead use "0.0.0.0" to bind to all interfaces.', + correctiveActions: { + manualSteps: [ + `Replace "server.host: 0" to "server.host: 0.0.0.0" in your kibana configurations.`, + ], + }, }); } return settings; @@ -136,12 +172,28 @@ const opsLoggingEventDeprecation: ConfigDeprecation = (settings, fromPath, addDe 'in 8.0. To access ops data moving forward, please enable debug logs for the ' + '"metrics.ops" context in your logging configuration. For more details, see ' + 'https://github.com/elastic/kibana/blob/master/src/core/server/logging/README.mdx', + correctiveActions: { + manualSteps: [ + `Remove "logging.events.ops" from your kibana settings.`, + `Enable debug logs for the "metrics.ops" context in your logging configuration`, + ], + }, }); } }; const requestLoggingEventDeprecation: ConfigDeprecation = (settings, fromPath, addDeprecation) => { if (settings.logging?.events?.request || settings.logging?.events?.response) { + const removeConfigsSteps = []; + + if (settings.logging?.events?.request) { + removeConfigsSteps.push(`Remove "logging.events.request" from your kibana configs.`); + } + + if (settings.logging?.events?.response) { + removeConfigsSteps.push(`Remove "logging.events.response" from your kibana configs.`); + } + addDeprecation({ documentationUrl: 'https://github.com/elastic/kibana/blob/master/src/core/server/logging/README.mdx#loggingevents', @@ -150,6 +202,12 @@ const requestLoggingEventDeprecation: ConfigDeprecation = (settings, fromPath, a 'in 8.0. To access request and/or response data moving forward, please enable debug logs for the ' + '"http.server.response" context in your logging configuration. For more details, see ' + 'https://github.com/elastic/kibana/blob/master/src/core/server/logging/README.mdx', + correctiveActions: { + manualSteps: [ + ...removeConfigsSteps, + `enable debug logs for the "http.server.response" context in your logging configuration.`, + ], + }, }); } }; @@ -164,6 +222,12 @@ const timezoneLoggingDeprecation: ConfigDeprecation = (settings, fromPath, addDe 'in 8.0. To set the timezone moving forward, please add a timezone date modifier to the log pattern ' + 'in your logging configuration. For more details, see ' + 'https://github.com/elastic/kibana/blob/master/src/core/server/logging/README.mdx', + correctiveActions: { + manualSteps: [ + `Remove "logging.timezone" from your kibana configs.`, + `To set the timezone add a timezone date modifier to the log pattern in your logging configuration.`, + ], + }, }); } }; @@ -178,6 +242,12 @@ const destLoggingDeprecation: ConfigDeprecation = (settings, fromPath, addDeprec 'in 8.0. To set the destination moving forward, you can use the "console" appender ' + 'in your logging configuration or define a custom one. For more details, see ' + 'https://github.com/elastic/kibana/blob/master/src/core/server/logging/README.mdx', + correctiveActions: { + manualSteps: [ + `Remove "logging.dest" from your kibana configs.`, + `To set the destination use the "console" appender in your logging configuration or define a custom one.`, + ], + }, }); } }; @@ -190,6 +260,12 @@ const quietLoggingDeprecation: ConfigDeprecation = (settings, fromPath, addDepre message: '"logging.quiet" has been deprecated and will be removed ' + 'in 8.0. Moving forward, you can use "logging.root.level:error" in your logging configuration. ', + correctiveActions: { + manualSteps: [ + `Remove "logging.quiet" from your kibana configs.`, + `Use "logging.root.level:error" in your logging configuration.`, + ], + }, }); } }; @@ -202,6 +278,12 @@ const silentLoggingDeprecation: ConfigDeprecation = (settings, fromPath, addDepr message: '"logging.silent" has been deprecated and will be removed ' + 'in 8.0. Moving forward, you can use "logging.root.level:off" in your logging configuration. ', + correctiveActions: { + manualSteps: [ + `Remove "logging.silent" from your kibana configs.`, + `Use "logging.root.level:off" in your logging configuration.`, + ], + }, }); } }; @@ -214,6 +296,12 @@ const verboseLoggingDeprecation: ConfigDeprecation = (settings, fromPath, addDep message: '"logging.verbose" has been deprecated and will be removed ' + 'in 8.0. Moving forward, you can use "logging.root.level:all" in your logging configuration. ', + correctiveActions: { + manualSteps: [ + `Remove "logging.verbose" from your kibana configs.`, + `Use "logging.root.level:all" in your logging configuration.`, + ], + }, }); } }; @@ -234,6 +322,12 @@ const jsonLoggingDeprecation: ConfigDeprecation = (settings, fromPath, addDeprec 'There is currently no default layout for custom appenders and each one must be declared explicitly. ' + 'For more details, see ' + 'https://github.com/elastic/kibana/blob/master/src/core/server/logging/README.mdx', + correctiveActions: { + manualSteps: [ + `Remove "logging.json" from your kibana configs.`, + `Configure the "appender.layout" property for every custom appender in your logging configuration.`, + ], + }, }); } }; @@ -248,6 +342,12 @@ const logRotateDeprecation: ConfigDeprecation = (settings, fromPath, addDeprecat 'Moving forward, you can enable log rotation using the "rolling-file" appender for a logger ' + 'in your logging configuration. For more details, see ' + 'https://github.com/elastic/kibana/blob/master/src/core/server/logging/README.mdx#rolling-file-appender', + correctiveActions: { + manualSteps: [ + `Remove "logging.rotate" from your kibana configs.`, + `Enable log rotation using the "rolling-file" appender for a logger in your logging configuration.`, + ], + }, }); } }; @@ -259,7 +359,13 @@ const logEventsLogDeprecation: ConfigDeprecation = (settings, fromPath, addDepre 'https://github.com/elastic/kibana/blob/master/src/core/server/logging/README.mdx#loggingevents', message: '"logging.events.log" has been deprecated and will be removed ' + - 'in 8.0. Moving forward, log levels can be customized on a per-logger basis using the new logging configuration. ', + 'in 8.0. Moving forward, log levels can be customized on a per-logger basis using the new logging configuration.', + correctiveActions: { + manualSteps: [ + `Remove "logging.events.log" from your kibana configs.`, + `Customize log levels can be per-logger using the new logging configuration.`, + ], + }, }); } }; @@ -271,7 +377,13 @@ const logEventsErrorDeprecation: ConfigDeprecation = (settings, fromPath, addDep 'https://github.com/elastic/kibana/blob/master/src/core/server/logging/README.mdx#loggingevents', message: '"logging.events.error" has been deprecated and will be removed ' + - 'in 8.0. Moving forward, you can use "logging.root.level: error" in your logging configuration. ', + 'in 8.0. Moving forward, you can use "logging.root.level: error" in your logging configuration.', + correctiveActions: { + manualSteps: [ + `Remove "logging.events.error" from your kibana configs.`, + `Use "logging.root.level: error" in your logging configuration.`, + ], + }, }); } }; @@ -282,6 +394,9 @@ const logFilterDeprecation: ConfigDeprecation = (settings, fromPath, addDeprecat documentationUrl: 'https://github.com/elastic/kibana/blob/master/src/core/server/logging/README.mdx#loggingfilter', message: '"logging.filter" has been deprecated and will be removed in 8.0.', + correctiveActions: { + manualSteps: [`Remove "logging.filter" from your kibana configs.`], + }, }); } }; diff --git a/src/core/server/deprecations/deprecations_service.ts b/src/core/server/deprecations/deprecations_service.ts index 205dd964468c1a..ede7f859ffd0d4 100644 --- a/src/core/server/deprecations/deprecations_service.ts +++ b/src/core/server/deprecations/deprecations_service.ts @@ -116,7 +116,7 @@ export interface DeprecationsSetupDeps { export class DeprecationsService implements CoreService { private readonly logger: Logger; - constructor(private readonly coreContext: CoreContext) { + constructor(private readonly coreContext: Pick) { this.logger = coreContext.logger.get('deprecations-service'); } @@ -154,7 +154,7 @@ export class DeprecationsService implements CoreService [ if (es.username === 'elastic') { addDeprecation({ message: `Setting [${fromPath}.username] to "elastic" is deprecated. You should use the "kibana_system" user instead.`, + correctiveActions: { + manualSteps: [`Replace [${fromPath}.username] from "elastic" to "kibana_system".`], + }, }); } else if (es.username === 'kibana') { addDeprecation({ message: `Setting [${fromPath}.username] to "kibana" is deprecated. You should use the "kibana_system" user instead.`, + correctiveActions: { + manualSteps: [`Replace [${fromPath}.username] from "kibana" to "kibana_system".`], + }, }); } if (es.ssl?.key !== undefined && es.ssl?.certificate === undefined) { addDeprecation({ message: `Setting [${fromPath}.ssl.key] without [${fromPath}.ssl.certificate] is deprecated. This has no effect, you should use both settings to enable TLS client authentication to Elasticsearch.`, + correctiveActions: { + manualSteps: [ + `Set [${fromPath}.ssl.certificate] in your kibana configs to enable TLS client authentication to Elasticsearch.`, + ], + }, }); } else if (es.ssl?.certificate !== undefined && es.ssl?.key === undefined) { addDeprecation({ message: `Setting [${fromPath}.ssl.certificate] without [${fromPath}.ssl.key] is deprecated. This has no effect, you should use both settings to enable TLS client authentication to Elasticsearch.`, + correctiveActions: { + manualSteps: [ + `Set [${fromPath}.ssl.key] in your kibana configs to enable TLS client authentication to Elasticsearch.`, + ], + }, }); } else if (es.logQueries === true) { addDeprecation({ message: `Setting [${fromPath}.logQueries] is deprecated and no longer used. You should set the log level to "debug" for the "elasticsearch.queries" context in "logging.loggers" or use "logging.verbose: true".`, + correctiveActions: { + manualSteps: [ + `Remove Setting [${fromPath}.logQueries] from your kibana configs`, + `Set the log level to "debug" for the "elasticsearch.queries" context in "logging.loggers".`, + ], + }, }); } return; diff --git a/src/core/server/kibana_config.ts b/src/core/server/kibana_config.ts index 623ffa86c0e8d9..77ee3197b988db 100644 --- a/src/core/server/kibana_config.ts +++ b/src/core/server/kibana_config.ts @@ -18,6 +18,12 @@ const deprecations: ConfigDeprecationProvider = () => [ addDeprecation({ message: `"kibana.index" is deprecated. Multitenancy by changing "kibana.index" will not be supported starting in 8.0. See https://ela.st/kbn-remove-legacy-multitenancy for more details`, documentationUrl: 'https://ela.st/kbn-remove-legacy-multitenancy', + correctiveActions: { + manualSteps: [ + `If you rely on this setting to achieve multitenancy you should use Spaces, cross-cluster replication, or cross-cluster search instead.`, + `To migrate to Spaces, we encourage using saved object management to export your saved objects from a tenant into the default tenant in a space.`, + ], + }, }); } return settings; diff --git a/src/core/server/saved_objects/saved_objects_config.ts b/src/core/server/saved_objects/saved_objects_config.ts index 7182df74c597fa..c62d322f0bf8d9 100644 --- a/src/core/server/saved_objects/saved_objects_config.ts +++ b/src/core/server/saved_objects/saved_objects_config.ts @@ -29,6 +29,9 @@ const migrationDeprecations: ConfigDeprecationProvider = () => [ message: '"migrations.enableV2" is deprecated and will be removed in an upcoming release without any further notice.', documentationUrl: 'https://ela.st/kbn-so-migration-v2', + correctiveActions: { + manualSteps: [`Remove "migrations.enableV2" from your kibana configs.`], + }, }); } return settings; diff --git a/src/core/server/server.api.md b/src/core/server/server.api.md index 0c35177f51f996..379e4147ae024c 100644 --- a/src/core/server/server.api.md +++ b/src/core/server/server.api.md @@ -872,7 +872,7 @@ export interface DeprecationsDetails { [key: string]: any; }; }; - manualSteps?: string[]; + manualSteps: string[]; }; deprecationType?: 'config' | 'feature'; // (undocumented) diff --git a/test/plugin_functional/plugins/core_plugin_deprecations/server/config.ts b/test/plugin_functional/plugins/core_plugin_deprecations/server/config.ts index e051c39f681504..650567f761aa3c 100644 --- a/test/plugin_functional/plugins/core_plugin_deprecations/server/config.ts +++ b/test/plugin_functional/plugins/core_plugin_deprecations/server/config.ts @@ -26,6 +26,11 @@ const configSecretDeprecation: ConfigDeprecation = (settings, fromPath, addDepre message: 'Kibana plugin functional tests will no longer allow corePluginDeprecations.secret ' + 'config to be set to anything except 42.', + correctiveActions: { + manualSteps: [ + `This is an intentional deprecation for testing with no intention for having it fixed!`, + ], + }, }); } return settings; diff --git a/test/plugin_functional/plugins/core_plugin_deprecations/server/plugin.ts b/test/plugin_functional/plugins/core_plugin_deprecations/server/plugin.ts index 65a2ce02aa0a45..9922e56f44bd9a 100644 --- a/test/plugin_functional/plugins/core_plugin_deprecations/server/plugin.ts +++ b/test/plugin_functional/plugins/core_plugin_deprecations/server/plugin.ts @@ -29,7 +29,9 @@ async function getDeprecations({ message: `SavedObject test-deprecations-plugin is still being used.`, documentationUrl: 'another-test-url', level: 'critical', - correctiveActions: {}, + correctiveActions: { + manualSteps: ['Step a', 'Step b'], + }, }); } diff --git a/test/plugin_functional/test_suites/core/deprecations.ts b/test/plugin_functional/test_suites/core/deprecations.ts index 99b1a79fb51e34..38a8b835b118c3 100644 --- a/test/plugin_functional/test_suites/core/deprecations.ts +++ b/test/plugin_functional/test_suites/core/deprecations.ts @@ -45,7 +45,11 @@ export default function ({ getService, getPageObjects }: PluginFunctionalProvide level: 'critical', message: 'Kibana plugin functional tests will no longer allow corePluginDeprecations.secret config to be set to anything except 42.', - correctiveActions: {}, + correctiveActions: { + manualSteps: [ + 'This is an intentional deprecation for testing with no intention for having it fixed!', + ], + }, documentationUrl: 'config-secret-doc-url', deprecationType: 'config', domainId: 'corePluginDeprecations', @@ -64,7 +68,9 @@ export default function ({ getService, getPageObjects }: PluginFunctionalProvide message: 'SavedObject test-deprecations-plugin is still being used.', documentationUrl: 'another-test-url', level: 'critical', - correctiveActions: {}, + correctiveActions: { + manualSteps: ['Step a', 'Step b'], + }, domainId: 'corePluginDeprecations', }, ]; @@ -151,6 +157,7 @@ export default function ({ getService, getPageObjects }: PluginFunctionalProvide mockFail: true, }, }, + manualSteps: ['Step a', 'Step b'], }, domainId: 'corePluginDeprecations', }) @@ -178,6 +185,7 @@ export default function ({ getService, getPageObjects }: PluginFunctionalProvide mockFail: true, }, }, + manualSteps: ['Step a', 'Step b'], }, domainId: 'corePluginDeprecations', }) @@ -213,6 +221,7 @@ export default function ({ getService, getPageObjects }: PluginFunctionalProvide path: '/api/core_deprecations_resolve/', body: { keyId }, }, + manualSteps: ['Step a', 'Step b'], }, domainId: 'corePluginDeprecations', }) diff --git a/x-pack/plugins/actions/server/index.ts b/x-pack/plugins/actions/server/index.ts index 6a0f06b34d670e..692ff6fa0a5084 100644 --- a/x-pack/plugins/actions/server/index.ts +++ b/x-pack/plugins/actions/server/index.ts @@ -69,7 +69,18 @@ export const config: PluginConfigDescriptor = { ) { addDeprecation({ message: - '`xpack.actions.customHostSettings[].tls.rejectUnauthorized` is deprecated. Use `xpack.actions.customHostSettings[].tls.verificationMode` instead, with the setting `verificationMode:full` eql to `rejectUnauthorized:true`, and `verificationMode:none` eql to `rejectUnauthorized:false`.', + `"xpack.actions.customHostSettings[].tls.rejectUnauthorized" is deprecated.` + + `Use "xpack.actions.customHostSettings[].tls.verificationMode" instead, ` + + `with the setting "verificationMode:full" eql to "rejectUnauthorized:true", ` + + `and "verificationMode:none" eql to "rejectUnauthorized:false".`, + correctiveActions: { + manualSteps: [ + `Remove "xpack.actions.customHostSettings[].tls.rejectUnauthorized" from your kibana configs.`, + `Use "xpack.actions.customHostSettings[].tls.verificationMode" ` + + `with the setting "verificationMode:full" eql to "rejectUnauthorized:true", ` + + `and "verificationMode:none" eql to "rejectUnauthorized:false".`, + ], + }, }); } }, @@ -77,7 +88,17 @@ export const config: PluginConfigDescriptor = { if (!!settings?.xpack?.actions?.rejectUnauthorized) { addDeprecation({ message: - '`xpack.actions.rejectUnauthorized` is deprecated. Use `xpack.actions.verificationMode` instead, with the setting `verificationMode:full` eql to `rejectUnauthorized:true`, and `verificationMode:none` eql to `rejectUnauthorized:false`.', + `"xpack.actions.rejectUnauthorized" is deprecated. Use "xpack.actions.verificationMode" instead, ` + + `with the setting "verificationMode:full" eql to "rejectUnauthorized:true", ` + + `and "verificationMode:none" eql to "rejectUnauthorized:false".`, + correctiveActions: { + manualSteps: [ + `Remove "xpack.actions.rejectUnauthorized" from your kibana configs.`, + `Use "xpack.actions.verificationMode" ` + + `with the setting "verificationMode:full" eql to "rejectUnauthorized:true", ` + + `and "verificationMode:none" eql to "rejectUnauthorized:false".`, + ], + }, }); } }, @@ -85,7 +106,17 @@ export const config: PluginConfigDescriptor = { if (!!settings?.xpack?.actions?.proxyRejectUnauthorizedCertificates) { addDeprecation({ message: - '`xpack.actions.proxyRejectUnauthorizedCertificates` is deprecated. Use `xpack.actions.proxyVerificationMode` instead, with the setting `proxyVerificationMode:full` eql to `rejectUnauthorized:true`, and `proxyVerificationMode:none` eql to `rejectUnauthorized:false`.', + `"xpack.actions.proxyRejectUnauthorizedCertificates" is deprecated. Use "xpack.actions.proxyVerificationMode" instead, ` + + `with the setting "proxyVerificationMode:full" eql to "rejectUnauthorized:true",` + + `and "proxyVerificationMode:none" eql to "rejectUnauthorized:false".`, + correctiveActions: { + manualSteps: [ + `Remove "xpack.actions.proxyRejectUnauthorizedCertificates" from your kibana configs.`, + `Use "xpack.actions.proxyVerificationMode" ` + + `with the setting "proxyVerificationMode:full" eql to "rejectUnauthorized:true",` + + `and "proxyVerificationMode:none" eql to "rejectUnauthorized:false".`, + ], + }, }); } }, diff --git a/x-pack/plugins/banners/server/config.ts b/x-pack/plugins/banners/server/config.ts index 5ee01ec2b0b19e..37b4c57fc2ce1f 100644 --- a/x-pack/plugins/banners/server/config.ts +++ b/x-pack/plugins/banners/server/config.ts @@ -45,6 +45,12 @@ export const config: PluginConfigDescriptor = { if (pluginConfig?.placement === 'header') { addDeprecation({ message: 'The `header` value for xpack.banners.placement has been replaced by `top`', + correctiveActions: { + manualSteps: [ + `Remove "xpack.banners.placement: header" from your kibana configs.`, + `Add "xpack.banners.placement: to" to your kibana configs instead.`, + ], + }, }); return { set: [{ path: `${fromPath}.placement`, value: 'top' }], diff --git a/x-pack/plugins/monitoring/server/deprecations.ts b/x-pack/plugins/monitoring/server/deprecations.ts index a38f81d72b78f3..ac1c2a0d7ac101 100644 --- a/x-pack/plugins/monitoring/server/deprecations.ts +++ b/x-pack/plugins/monitoring/server/deprecations.ts @@ -54,6 +54,11 @@ export const deprecations = ({ if (emailNotificationsEnabled && !updatedKey && !legacyKey) { addDeprecation({ message: `Config key [${fromPath}.${CLUSTER_ALERTS_ADDRESS_CONFIG_KEY}] will be required for email notifications to work in 8.0."`, + correctiveActions: { + manualSteps: [ + `Add [${fromPath}.${CLUSTER_ALERTS_ADDRESS_CONFIG_KEY}] to your kibana configs."`, + ], + }, }); } return config; @@ -64,10 +69,16 @@ export const deprecations = ({ if (es.username === 'elastic') { addDeprecation({ message: `Setting [${fromPath}.username] to "elastic" is deprecated. You should use the "kibana_system" user instead.`, + correctiveActions: { + manualSteps: [`Replace [${fromPath}.username] from "elastic" to "kibana_system".`], + }, }); } else if (es.username === 'kibana') { addDeprecation({ message: `Setting [${fromPath}.username] to "kibana" is deprecated. You should use the "kibana_system" user instead.`, + correctiveActions: { + manualSteps: [`Replace [${fromPath}.username] from "kibana" to "kibana_system".`], + }, }); } } @@ -79,10 +90,20 @@ export const deprecations = ({ if (ssl.key !== undefined && ssl.certificate === undefined) { addDeprecation({ message: `Setting [${fromPath}.key] without [${fromPath}.certificate] is deprecated. This has no effect, you should use both settings to enable TLS client authentication to Elasticsearch.`, + correctiveActions: { + manualSteps: [ + `Set [${fromPath}.ssl.certificate] in your kibana configs to enable TLS client authentication to Elasticsearch.`, + ], + }, }); } else if (ssl.certificate !== undefined && ssl.key === undefined) { addDeprecation({ message: `Setting [${fromPath}.certificate] without [${fromPath}.key] is deprecated. This has no effect, you should use both settings to enable TLS client authentication to Elasticsearch.`, + correctiveActions: { + manualSteps: [ + `Set [${fromPath}.ssl.key] in your kibana configs to enable TLS client authentication to Elasticsearch.`, + ], + }, }); } } diff --git a/x-pack/plugins/reporting/server/config/index.test.ts b/x-pack/plugins/reporting/server/config/index.test.ts index 327b03d679caed..b9665759f9f52b 100644 --- a/x-pack/plugins/reporting/server/config/index.test.ts +++ b/x-pack/plugins/reporting/server/config/index.test.ts @@ -45,7 +45,7 @@ describe('deprecations', () => { const { messages } = applyReportingDeprecations({ roles: { enabled: true } }); expect(messages).toMatchInlineSnapshot(` Array [ - "\\"xpack.reporting.roles\\" is deprecated. Granting reporting privilege through a \\"reporting_user\\" role will not be supported starting in 8.0. Please set 'xpack.reporting.roles.enabled' to 'false' and grant reporting privileges to users using Kibana application privileges **Management > Security > Roles**.", + "\\"xpack.reporting.roles\\" is deprecated. Granting reporting privilege through a \\"reporting_user\\" role will not be supported starting in 8.0. Please set \\"xpack.reporting.roles.enabled\\" to \\"false\\" and grant reporting privileges to users using Kibana application privileges **Management > Security > Roles**.", ] `); }); diff --git a/x-pack/plugins/reporting/server/config/index.ts b/x-pack/plugins/reporting/server/config/index.ts index 8927bd8ee94d50..d0c743f859b3c5 100644 --- a/x-pack/plugins/reporting/server/config/index.ts +++ b/x-pack/plugins/reporting/server/config/index.ts @@ -28,6 +28,12 @@ export const config: PluginConfigDescriptor = { if (reporting?.index) { addDeprecation({ message: `"${fromPath}.index" is deprecated. Multitenancy by changing "kibana.index" will not be supported starting in 8.0. See https://ela.st/kbn-remove-legacy-multitenancy for more details`, + correctiveActions: { + manualSteps: [ + `If you rely on this setting to achieve multitenancy you should use Spaces, cross-cluster replication, or cross-cluster search instead.`, + `To migrate to Spaces, we encourage using saved object management to export your saved objects from a tenant into the default tenant in a space.`, + ], + }, }); } @@ -35,8 +41,15 @@ export const config: PluginConfigDescriptor = { addDeprecation({ message: `"${fromPath}.roles" is deprecated. Granting reporting privilege through a "reporting_user" role will not be supported ` + - `starting in 8.0. Please set 'xpack.reporting.roles.enabled' to 'false' and grant reporting privileges to users ` + + `starting in 8.0. Please set "xpack.reporting.roles.enabled" to "false" and grant reporting privileges to users ` + `using Kibana application privileges **Management > Security > Roles**.`, + correctiveActions: { + manualSteps: [ + `Set 'xpack.reporting.roles.enabled' to 'false' in your kibana configs.`, + `Grant reporting privileges to users using Kibana application privileges` + + `under **Management > Security > Roles**.`, + ], + }, }); } }, diff --git a/x-pack/plugins/security/server/config_deprecations.test.ts b/x-pack/plugins/security/server/config_deprecations.test.ts index a233d760359e5b..d2c75fd2331b99 100644 --- a/x-pack/plugins/security/server/config_deprecations.test.ts +++ b/x-pack/plugins/security/server/config_deprecations.test.ts @@ -243,7 +243,7 @@ describe('Config Deprecations', () => { expect(migrated).toEqual(config); expect(messages).toMatchInlineSnapshot(` Array [ - "Defining \`xpack.security.authc.providers\` as an array of provider types is deprecated. Use extended \`object\` format instead.", + "Defining \\"xpack.security.authc.providers\\" as an array of provider types is deprecated. Use extended \\"object\\" format instead.", ] `); }); @@ -262,7 +262,7 @@ describe('Config Deprecations', () => { expect(migrated).toEqual(config); expect(messages).toMatchInlineSnapshot(` Array [ - "Defining \`xpack.security.authc.providers\` as an array of provider types is deprecated. Use extended \`object\` format instead.", + "Defining \\"xpack.security.authc.providers\\" as an array of provider types is deprecated. Use extended \\"object\\" format instead.", "Enabling both \`basic\` and \`token\` authentication providers in \`xpack.security.authc.providers\` is deprecated. Login page will only use \`token\` provider.", ] `); diff --git a/x-pack/plugins/security/server/config_deprecations.ts b/x-pack/plugins/security/server/config_deprecations.ts index f99f3450417f2f..a12f2f738f14c0 100644 --- a/x-pack/plugins/security/server/config_deprecations.ts +++ b/x-pack/plugins/security/server/config_deprecations.ts @@ -27,7 +27,13 @@ export const securityConfigDeprecationProvider: ConfigDeprecationProvider = ({ if (Array.isArray(settings?.xpack?.security?.authc?.providers)) { addDeprecation({ message: - 'Defining `xpack.security.authc.providers` as an array of provider types is deprecated. Use extended `object` format instead.', + `Defining "xpack.security.authc.providers" as an array of provider types is deprecated. ` + + `Use extended "object" format instead.`, + correctiveActions: { + manualSteps: [ + `Use the extended object format for "xpack.security.authc.providers" in your Kibana configuration.`, + ], + }, }); } }, @@ -47,6 +53,11 @@ export const securityConfigDeprecationProvider: ConfigDeprecationProvider = ({ addDeprecation({ message: 'Enabling both `basic` and `token` authentication providers in `xpack.security.authc.providers` is deprecated. Login page will only use `token` provider.', + correctiveActions: { + manualSteps: [ + 'Remove either the `basic` or `token` auth provider in "xpack.security.authc.providers" from your Kibana configuration.', + ], + }, }); } }, @@ -59,6 +70,11 @@ export const securityConfigDeprecationProvider: ConfigDeprecationProvider = ({ addDeprecation({ message: '`xpack.security.authc.providers.saml..maxRedirectURLSize` is deprecated and is no longer used', + correctiveActions: { + manualSteps: [ + `Remove "xpack.security.authc.providers.saml..maxRedirectURLSize" from your Kibana configuration.`, + ], + }, }); } }, @@ -68,6 +84,12 @@ export const securityConfigDeprecationProvider: ConfigDeprecationProvider = ({ message: 'Disabling the security plugin (`xpack.security.enabled`) will not be supported in the next major version (8.0). ' + 'To turn off security features, disable them in Elasticsearch instead.', + correctiveActions: { + manualSteps: [ + `Remove "xpack.security.enabled" from your Kibana configuration.`, + `To turn off security features, disable them in Elasticsearch instead.`, + ], + }, }); } }, diff --git a/x-pack/plugins/spaces/server/config.ts b/x-pack/plugins/spaces/server/config.ts index 2ad8ed654ebb60..2a2f363d769f7f 100644 --- a/x-pack/plugins/spaces/server/config.ts +++ b/x-pack/plugins/spaces/server/config.ts @@ -28,6 +28,9 @@ const disabledDeprecation: ConfigDeprecation = (config, fromPath, addDeprecation if (config.xpack?.spaces?.enabled === false) { addDeprecation({ message: `Disabling the Spaces plugin (xpack.spaces.enabled) will not be supported in the next major version (8.0)`, + correctiveActions: { + manualSteps: [`Remove "xpack.spaces.enabled: false" from your Kibana configuration`], + }, }); } }; diff --git a/x-pack/plugins/task_manager/server/index.ts b/x-pack/plugins/task_manager/server/index.ts index 155b8246905d1e..80f0e298a8ac38 100644 --- a/x-pack/plugins/task_manager/server/index.ts +++ b/x-pack/plugins/task_manager/server/index.ts @@ -38,11 +38,23 @@ export const config: PluginConfigDescriptor = { addDeprecation({ documentationUrl: 'https://ela.st/kbn-remove-legacy-multitenancy', message: `"${fromPath}.index" is deprecated. Multitenancy by changing "kibana.index" will not be supported starting in 8.0. See https://ela.st/kbn-remove-legacy-multitenancy for more details`, + correctiveActions: { + manualSteps: [ + `If you rely on this setting to achieve multitenancy you should use Spaces, cross-cluster replication, or cross-cluster search instead.`, + `To migrate to Spaces, we encourage using saved object management to export your saved objects from a tenant into the default tenant in a space.`, + ], + }, }); } if (taskManager?.max_workers > MAX_WORKERS_LIMIT) { addDeprecation({ message: `setting "${fromPath}.max_workers" (${taskManager?.max_workers}) greater than ${MAX_WORKERS_LIMIT} is deprecated. Values greater than ${MAX_WORKERS_LIMIT} will not be supported starting in 8.0.`, + correctiveActions: { + manualSteps: [ + `Maximum allowed value of "${fromPath}.max_workers" is ${MAX_WORKERS_LIMIT}.` + + `Replace "${fromPath}.max_workers: ${taskManager?.max_workers}" with (${MAX_WORKERS_LIMIT}).`, + ], + }, }); } }, diff --git a/x-pack/plugins/upgrade_assistant/__jest__/client_integration/overview.test.ts b/x-pack/plugins/upgrade_assistant/__jest__/client_integration/overview.test.ts index f3f76c3a6688ed..85efaf38f32a73 100644 --- a/x-pack/plugins/upgrade_assistant/__jest__/client_integration/overview.test.ts +++ b/x-pack/plugins/upgrade_assistant/__jest__/client_integration/overview.test.ts @@ -45,7 +45,7 @@ describe('Overview page', () => { const kibanaDeprecationsMockResponse: DomainDeprecationDetails[] = [ { - correctiveActions: {}, + correctiveActions: { manualSteps: ['test-step'] }, domainId: 'xpack.spaces', level: 'critical', message: