[Deprecation service] Using i18n for deprecation messages (#103422)
This commit is contained in:
Ahmad Bamieh
GitHub
parent
4b54ccecd3
commit
23621e663c
210
src/core/server/deprecations/README.mdx
Normal file
210
src/core/server/deprecations/README.mdx
Normal file
|
|
@ -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<ConfigType> = {
|
||||
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<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 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).
|
||||
Loading…
Reference in a new issue