mirror of
https://github.com/elastic/kibana.git
synced 2025-04-24 01:38:56 -04:00
Polish migration.md (#52764)
* Polish migration.md - Added saved objects legacy vs NP docs - Moved some data plugin docs into the right table - added table for server-side plugin services and added the features plugin * Missing backticks
This commit is contained in:
Rudolf Meijering
GitHub
parent
ba2e2588a3
commit
45563b2574
1 changed files with 50 additions and 76 deletions
|
|
@ -9,22 +9,21 @@
|
|||
- [Challenges on the server](#challenges-on-the-server)
|
||||
- [Challenges in the browser](#challenges-in-the-browser)
|
||||
- [Plan of action](#plan-of-action)
|
||||
- [Shared application plugins](#shared-application-plugins)
|
||||
- [Server-side plan of action](#server-side-plan-of-action)
|
||||
- [De-couple from hapi.js server and request objects](#de-couple-from-hapijs-server-and-request-objects)
|
||||
- [Introduce new plugin definition shim](#introduce-new-plugin-definition-shim)
|
||||
- [Switch to new platform services](#switch-to-new-platform-services)
|
||||
- [Migrate to the new plugin system](#migrate-to-the-new-plugin-system)
|
||||
- [Browser-side plan of action](#browser-side-plan-of-action)
|
||||
- [1. Create a plugin definition file](#1-create-a-plugin-definition-file)
|
||||
- [2. Export all static code and types from `public/index.ts`](#2-export-all-static-code-and-types-from-publicindexts)
|
||||
- [3. Export your runtime contract](#3-export-your-runtime-contract)
|
||||
- [4. Move "owned" UI modules into your plugin and expose them from your public contract](#4-move-owned-ui-modules-into-your-plugin-and-expose-them-from-your-public-contract)
|
||||
- [5. Provide plugin extension points decoupled from angular.js](#5-provide-plugin-extension-points-decoupled-from-angularjs)
|
||||
- [6. Move all webpack alias imports into uiExport entry files](#6-move-all-webpack-alias-imports-into-uiexport-entry-files)
|
||||
- [7. Switch to new platform services](#7-switch-to-new-platform-services)
|
||||
- [8. Migrate to the new plugin system](#8-migrate-to-the-new-plugin-system)
|
||||
- [Bonus: Tips for complex migration scenarios](#bonus-tips-for-complex-migration-scenarios)
|
||||
- [1. Create a plugin definition file](#1-create-a-plugin-definition-file)
|
||||
- [2. Export all static code and types from `public/index.ts`](#2-export-all-static-code-and-types-from-publicindexts)
|
||||
- [3. Export your runtime contract](#3-export-your-runtime-contract)
|
||||
- [4. Move "owned" UI modules into your plugin and expose them from your public contract](#4-move-owned-ui-modules-into-your-plugin-and-expose-them-from-your-public-contract)
|
||||
- [5. Provide plugin extension points decoupled from angular.js](#5-provide-plugin-extension-points-decoupled-from-angularjs)
|
||||
- [6. Move all webpack alias imports into uiExport entry files](#6-move-all-webpack-alias-imports-into-uiexport-entry-files)
|
||||
- [7. Switch to new platform services](#7-switch-to-new-platform-services)
|
||||
- [8. Migrate to the new plugin system](#8-migrate-to-the-new-plugin-system)
|
||||
- [Bonus: Tips for complex migration scenarios](#bonus-tips-for-complex-migration-scenarios)
|
||||
- [Frequently asked questions](#frequently-asked-questions)
|
||||
- [Is migrating a plugin an all-or-nothing thing?](#is-migrating-a-plugin-an-all-or-nothing-thing)
|
||||
- [Do plugins need to be converted to TypeScript?](#do-plugins-need-to-be-converted-to-typescript)
|
||||
|
|
@ -42,6 +41,7 @@
|
|||
- [Plugins for shared application services](#plugins-for-shared-application-services)
|
||||
- [Server-side](#server-side)
|
||||
- [Core services](#core-services-1)
|
||||
- [Plugin services](#plugin-services)
|
||||
- [UI Exports](#ui-exports)
|
||||
- [How to](#how-to)
|
||||
- [Configure plugin](#configure-plugin)
|
||||
|
|
@ -325,43 +325,6 @@ First, decouple your plugin's business logic from the dependencies that are not
|
|||
|
||||
Once those things are finished for any given plugin, it can officially be switched to the new plugin system.
|
||||
|
||||
### Shared application plugins
|
||||
|
||||
Some services have been already moved to the new platform.
|
||||
|
||||
Below you can find their new locations:
|
||||
|
||||
| Service | Old place | New place in the NP |
|
||||
| --------------- | ----------------------------------------- | --------------------------------------------------- |
|
||||
| *FieldFormats* | ui/registry/field_formats | plugins/data/public |
|
||||
|
||||
The `FieldFormats` service has been moved to the `data` plugin in the New Platform. If your plugin has any imports from `ui/registry/field_formats`, you'll need to update your imports as follows:
|
||||
|
||||
Use it in your New Platform plugin:
|
||||
|
||||
```ts
|
||||
class MyPlugin {
|
||||
setup (core, { data }) {
|
||||
data.fieldFormats.register(myFieldFormat);
|
||||
// ...
|
||||
}
|
||||
start (core, { data }) {
|
||||
data.fieldFormats.getType(myFieldFormatId);
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Or, in your legacy platform plugin, consume it through the `ui/new_platform` module:
|
||||
|
||||
```ts
|
||||
import { npSetup, npStart } from 'ui/new_platform';
|
||||
|
||||
npSetup.plugins.data.fieldFormats.register(myFieldFormat);
|
||||
npStart.plugins.data.fieldFormats.getType(myFieldFormatId);
|
||||
// ...
|
||||
```
|
||||
|
||||
## Server-side plan of action
|
||||
|
||||
Legacy server-side plugins access functionality from core and other plugins at runtime via function arguments, which is similar to how they must be architected to use the new plugin system. This greatly simplifies the plan of action for migrating server-side plugins.
|
||||
|
|
@ -1191,25 +1154,26 @@ import { setup, start } from '../core_plugins/embeddables/public/legacy';
|
|||
import { setup, start } from '../core_plugins/visualizations/public/legacy';
|
||||
```
|
||||
|
||||
| Legacy Platform | New Platform | Notes |
|
||||
| ------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `import 'ui/apply_filters'` | N/A. Replaced by triggering an APPLY_FILTER_TRIGGER trigger. | Directive is deprecated. |
|
||||
| `import 'ui/filter_bar'` | `import { FilterBar } from '../data/public'` | Directive is deprecated. |
|
||||
| `import 'ui/query_bar'` | `import { QueryStringInput } from '../data/public'` | Directives are deprecated. |
|
||||
| `import 'ui/search_bar'` | `import { SearchBar } from '../data/public'` | Directive is deprecated. |
|
||||
| `import 'ui/kbn_top_nav'` | `import { TopNavMenu } from '../navigation/public'` | Directive is still available in `ui/kbn_top_nav`. |
|
||||
| `ui/saved_objects/components/saved_object_finder` | `import { SavedObjectFinder } from '../kibana_react/public'` | |
|
||||
| `core_plugins/interpreter` | `data.expressions` | still in progress |
|
||||
| `ui/courier` | `data.search` | still in progress |
|
||||
| `ui/embeddable` | `embeddables` | still in progress |
|
||||
| `ui/filter_manager` | `data.filter` | -- |
|
||||
| `ui/index_patterns` | `data.indexPatterns` | still in progress |
|
||||
| `ui/registry/feature_catalogue` | `home.featureCatalogue.register` | Must add `home` as a dependency in your kibana.json. |
|
||||
| `ui/registry/vis_types` | `visualizations.types` | -- |
|
||||
| `ui/vis` | `visualizations.types` | -- |
|
||||
| `ui/share` | `share` | `showShareContextMenu` is now called `toggleShareContextMenu`, `ShareContextMenuExtensionsRegistryProvider` is now called `register` |
|
||||
| `ui/vis/vis_factory` | `visualizations.types` | -- |
|
||||
| `ui/vis/vis_filters` | `visualizations.filters` | -- |
|
||||
| Legacy Platform | New Platform | Notes |
|
||||
| ------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `import 'ui/apply_filters'` | N/A. Replaced by triggering an APPLY_FILTER_TRIGGER trigger. | Directive is deprecated. |
|
||||
| `import 'ui/filter_bar'` | `import { FilterBar } from '../data/public'` | Directive is deprecated. |
|
||||
| `import 'ui/query_bar'` | `import { QueryStringInput } from '../data/public'` | Directives are deprecated. |
|
||||
| `import 'ui/search_bar'` | `import { SearchBar } from '../data/public'` | Directive is deprecated. |
|
||||
| `import 'ui/kbn_top_nav'` | `import { TopNavMenu } from '../navigation/public'` | Directive is still available in `ui/kbn_top_nav`. |
|
||||
| `ui/saved_objects/components/saved_object_finder` | `import { SavedObjectFinder } from '../kibana_react/public'` | |
|
||||
| `core_plugins/interpreter` | `data.expressions` | still in progress |
|
||||
| `ui/courier` | `data.search` | still in progress |
|
||||
| `ui/embeddable` | `embeddables` | still in progress |
|
||||
| `ui/filter_manager` | `data.filter` | -- |
|
||||
| `ui/index_patterns` | `data.indexPatterns` | still in progress |
|
||||
| `ui/registry/field_formats` | `data.fieldFormats` | |
|
||||
| `ui/registry/feature_catalogue` | `home.featureCatalogue.register` | Must add `home` as a dependency in your kibana.json. |
|
||||
| `ui/registry/vis_types` | `visualizations.types` | -- |
|
||||
| `ui/vis` | `visualizations.types` | -- |
|
||||
| `ui/share` | `share` | `showShareContextMenu` is now called `toggleShareContextMenu`, `ShareContextMenuExtensionsRegistryProvider` is now called `register` |
|
||||
| `ui/vis/vis_factory` | `visualizations.types` | -- |
|
||||
| `ui/vis/vis_filters` | `visualizations.filters` | -- |
|
||||
| `ui/utils/parse_es_interval` | `import { parseEsInterval } from '../data/public'` | `parseEsInterval`, `ParsedInterval`, `InvalidEsCalendarIntervalError`, `InvalidEsIntervalFormatError` items were moved to the `Data Plugin` as a static code |
|
||||
|
||||
#### Server-side
|
||||
|
|
@ -1218,17 +1182,27 @@ import { setup, start } from '../core_plugins/visualizations/public/legacy';
|
|||
|
||||
In server code, `core` can be accessed from either `server.newPlatform` or `kbnServer.newPlatform`. There are not currently very many services available on the server-side:
|
||||
|
||||
| Legacy Platform | New Platform | Notes |
|
||||
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
|
||||
| `server.config()` | [`initializerContext.config.create()`](/docs/development/core/server/kibana-plugin-server.plugininitializercontext.config.md) | Must also define schema. See _[how to configure plugin](#configure-plugin)_ |
|
||||
| `server.route` | [`core.http.createRouter`](/docs/development/core/server/kibana-plugin-server.httpservicesetup.createrouter.md) | [Examples](./MIGRATION_EXAMPLES.md#route-registration) |
|
||||
| `request.getBasePath()` | [`core.http.basePath.get`](/docs/development/core/server/kibana-plugin-server.httpservicesetup.basepath.md) | |
|
||||
| `server.plugins.elasticsearch.getCluster('data')` | [`core.elasticsearch.dataClient$`](/docs/development/core/server/kibana-plugin-server.elasticsearchservicesetup.dataclient_.md) | Handlers will also include a pre-configured client |
|
||||
| `server.plugins.elasticsearch.getCluster('admin')` | [`core.elasticsearch.adminClient$`](/docs/development/core/server/kibana-plugin-server.elasticsearchservicesetup.adminclient_.md) | Handlers will also include a pre-configured client |
|
||||
| `xpackMainPlugin.info.feature(pluginID).registerLicenseCheckResultsGenerator` | [`x-pack licensing plugin`](/x-pack/plugins/licensing/README.md) | |
|
||||
| Legacy Platform | New Platform | Notes |
|
||||
| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
|
||||
| `server.config()` | [`initializerContext.config.create()`](/docs/development/core/server/kibana-plugin-server.plugininitializercontext.config.md) | Must also define schema. See _[how to configure plugin](#configure-plugin)_ |
|
||||
| `server.route` | [`core.http.createRouter`](/docs/development/core/server/kibana-plugin-server.httpservicesetup.createrouter.md) | [Examples](./MIGRATION_EXAMPLES.md#route-registration) |
|
||||
| `request.getBasePath()` | [`core.http.basePath.get`](/docs/development/core/server/kibana-plugin-server.httpservicesetup.basepath.md) | |
|
||||
| `server.plugins.elasticsearch.getCluster('data')` | [`core.elasticsearch.dataClient$`](/docs/development/core/server/kibana-plugin-server.elasticsearchservicesetup.dataclient_.md) | Handlers will also include a pre-configured client |
|
||||
| `server.plugins.elasticsearch.getCluster('admin')` | [`core.elasticsearch.adminClient$`](/docs/development/core/server/kibana-plugin-server.elasticsearchservicesetup.adminclient_.md) | Handlers will also include a pre-configured client |
|
||||
| `xpackMainPlugin.info.feature(pluginID).registerLicenseCheckResultsGenerator` | [`x-pack licensing plugin`](/x-pack/plugins/licensing/README.md) | |
|
||||
| `server.savedObjects.setScopedSavedObjectsClientFactory` | [`core.savedObjects.setClientFactory`](/docs/development/core/server/kibana-plugin-server.savedobjectsservicesetup.setclientfactory.md) | |
|
||||
| `server.savedObjects.addScopedSavedObjectsClientWrapperFactory` | [`core.savedObjects.addClientWrapper`](/docs/development/core/server/kibana-plugin-server.savedobjectsservicesetup.addclientwrapper.md) | |
|
||||
| `server.savedObjects.getSavedObjectsRepository` | [`core.savedObjects.createInternalRepository`](/docs/development/core/server/kibana-plugin-server.savedobjectsservicesetup.createinternalrepository.md) [`core.savedObjects.createScopedRepository`](/docs/development/core/server/kibana-plugin-server.savedobjectsservicesetup.createscopedrepository.md) | |
|
||||
| `server.savedObjects.getScopedSavedObjectsClient` | [`core.savedObjects.getScopedClient`](/docs/development/core/server/kibana-plugin-server.savedobjectsservicestart.getscopedclient.md) | |
|
||||
| `request.getSavedObjectsClient` | [`context.core.savedObjects.client`](/docs/development/core/server/kibana-plugin-server.requesthandlercontext.core.md) | |
|
||||
|
||||
_See also: [Server's CoreSetup API Docs](/docs/development/core/server/kibana-plugin-server.coresetup.md)_
|
||||
|
||||
##### Plugin services
|
||||
| Legacy Platform | New Platform | Notes |
|
||||
| ------------------------------------------- | ------------------------------------------------------------------------------ | ----- |
|
||||
| `server.plugins.xpack_main.registerFeature` | [`plugins.features.registerFeature`](x-pack/plugins/features/server/plugin.ts) | |
|
||||
|
||||
#### UI Exports
|
||||
|
||||
The legacy platform uses a set of "uiExports" to inject modules from one plugin into other plugins. This mechansim is not necessary in the New Platform because all plugins are executed on the page at once (though only one application) is rendered at a time.
|
||||
|
|
@ -1249,7 +1223,7 @@ This table shows where these uiExports have moved to in the New Platform. In mos
|
|||
| `fieldFormatEditors` | | |
|
||||
| `fieldFormats` | | |
|
||||
| `hacks` | n/a | Just run the code in your plugin's `start` method. |
|
||||
| `home` | [`plugins.home.featureCatalogue.register`](./src/plugins/home/public/feature_catalogue) | Must add `home` as a dependency in your kibana.json. |
|
||||
| `home` | [`plugins.home.featureCatalogue.register`](./src/plugins/home/public/feature_catalogue) | Must add `home` as a dependency in your kibana.json. |
|
||||
| `indexManagement` | | Should be an API on the indexManagement plugin. |
|
||||
| `injectDefaultVars` | n/a | Plugins will only be able to "whitelist" config values for the frontend. See [#41990](https://github.com/elastic/kibana/issues/41990) |
|
||||
| `inspectorViews` | | Should be an API on the data (?) plugin. |
|
||||
|
|
@ -1267,7 +1241,7 @@ This table shows where these uiExports have moved to in the New Platform. In mos
|
|||
| `styleSheetPaths` | | |
|
||||
| `taskDefinitions` | | Should be an API on the taskManager plugin. |
|
||||
| `uiCapabilities` | [`core.application.register`](/docs/development/core/public/kibana-plugin-public.applicationsetup.register.md) | |
|
||||
| `uiSettingDefaults` | [`core.uiSettings.register`](/docs/development/core/server/kibana-plugin-server.uisettingsservicesetup.md) | |
|
||||
| `uiSettingDefaults` | [`core.uiSettings.register`](/docs/development/core/server/kibana-plugin-server.uisettingsservicesetup.md) | |
|
||||
| `validations` | | Part of SavedObjects, see [#33587](https://github.com/elastic/kibana/issues/33587) |
|
||||
| `visEditorTypes` | | |
|
||||
| `visTypeEnhancers` | | |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue