Skip to content

Commit

Permalink
update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@Bamieh
Bamieh committed May 3, 2021
1 parent 5db8e32 commit a14a698
Showing 1 changed file with 44 additions and 56 deletions.
100 changes: 44 additions & 56 deletions src/core/server/deprecations/README.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,10 +22,9 @@ To check your plugin deprecations go to the UA interface and click on `view depr
## 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`) now accept an optional parameter to customize the deprecation details.
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,
Expand All @@ -42,23 +41,24 @@ 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": [
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",
]
},
domainId: 'usageCollection',
}],
}
```

#### Custom deprecations for plugin configs
Custom config deprecation handling allows specifying the deprecation details via the `addDeprecation`.

##### Example:
##### Example

```ts
export const config: PluginConfigDescriptor<ConfigSchema> = {
Expand Down Expand Up @@ -94,39 +94,27 @@ export const config: PluginConfigDescriptor<ConfigSchema> = {
};
```

## How do I use this service for my deprecated plugin features?
## 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 is passed a context object `{ esClient, savedObjectsClient }`.
```ts
interface GetDeprecationsContext {
esClient: IScopedClusterClient;
savedObjectsClient: SavedObjectsClientContract;
}
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.

interface DeprecationInfo {
message: string;
level: 'warning' | 'critical';
documentationUrl?: string;
correctiveActions: {
api?: {
path: string;
method: 'POST' | 'PUT';
body?: {
[key: string]: any;
};
};
manualSteps?: string[];
};
}
```
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
Expand All @@ -138,29 +126,29 @@ async function getDeprecations({ esClient, savedObjectsClient }: GetDeprecations

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"
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
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."
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.'
]
},
});
Expand All @@ -184,7 +172,7 @@ 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.
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.

Expand Down

0 comments on commit a14a698

Please sign in to comment.