145 lines
8.6 KiB
Plaintext
145 lines
8.6 KiB
Plaintext
---
|
||
id: kibPlatformIntro
|
||
slug: /kibana-dev-docs/platform-intro
|
||
title: Plugins and the Kibana platform
|
||
summary: An introduction to the Kibana platform and how to use it to build a plugin.
|
||
date: 2021-01-06
|
||
tags: ['kibana','onboarding', 'dev', 'architecture']
|
||
---
|
||
|
||
From an end user perspective, Kibana is a tool for interacting with Elasticsearch, providing an easy way
|
||
to visualize and analyze data.
|
||
|
||
From a developer perspective, Kibana is a platform that provides a set of tools to build not only the UI you see in Kibana today, but
|
||
a wide variety of applications that can be used to explore, visualize, and act upon data in Elasticsearch. The platform provides developers the ability
|
||
to build applications, or inject extra functionality into
|
||
already existing applications. Did you know that almost everything you see in the
|
||
Kibana UI is built inside a plugin? If you removed all plugins from Kibana, you'd be left with an empty navigation menu, and a set of
|
||
developer tools. The Kibana platform is a blank canvas, just waiting for a developer to come along and create something!
|
||
|
||
|
||
|
||
## Platform services
|
||
|
||
Plugins have access to three kinds of public services:
|
||
|
||
- Platform services provided by `core` (<DocLink id="kibPlatformIntro" section="core-services" text="Core services"/>)
|
||
- Platform services provided by plugins (<DocLink id="kibPlatformIntro" section="platform-plugins" text="Platform plugins"/>)
|
||
- Shared services provided by plugins, that are only relevant for only a few, specific plugins (e.g. "presentation utils").
|
||
|
||
The first two items are what make up "Platform services".
|
||
|
||
<DocCallOut title="What is the difference between services provided by platform plugins, and those by core?">
|
||
|
||
We try to put only the most stable and fundamental code into `Core`, while more application focused functionality goes in a plugin, but the heuristic isn't
|
||
clear, and we haven't done a great job of sticking to it. For example, notifications and toasts are core services, but data and search are plugin services.
|
||
|
||
Today it looks something like this.
|
||
|
||
|
||
|
||
<DocAccordion buttonContent="A bit of history">
|
||
When the Kibana platform and plugin infrastructure was built, we thought of two types of code: core services, and other plugin services. We planned to keep the most stable and fundamental
|
||
code needed to build plugins inside core.
|
||
|
||
In reality, we ended up with many platform-like services living outside of core, with no (short term) intention of moving them. We highly encourage plugin developers to use
|
||
them, so we consider them part of platform services.
|
||
|
||
When we built our platform system, we also thought we'd end up with only a handful of large plugins outside core. Users could turn certain plugins off, to minimize the code
|
||
footprint and speed up Kibana.
|
||
|
||
In reality, our plugin model ended up being used like micro-services. Plugins are the only form of encapsulation we provide developers, and they liked it! However, we ended
|
||
up with a ton of small plugins, that developers never intended to be uninstallable, nor tested in this manner. We are considering ways to provide developers the ability to build services
|
||
with the encapsulation
|
||
they desire, without the need to build a plugin.
|
||
|
||
Another side effect of having many small plugins is that common code often ends up extracted into another plugin. Use case specific utilities are exported,
|
||
that are not meant to be used in a general manner. This makes our definition of "platform code" a bit trickier to define. We'd like to say "The platform is made up of
|
||
every publically exposed service", but in today's world, that wouldn't be a very accurate picture.
|
||
|
||
We recognize the need to better clarify the relationship between core functionality, platform-like plugin functionality, and functionality exposed by other plugins.
|
||
It's something we will be working on!
|
||
</DocAccordion>
|
||
|
||
We will continue to focus on adding clarity around these types of services and what developers can expect from each.
|
||
|
||
|
||
</DocCallOut>
|
||
|
||
### Core services
|
||
|
||
Sometimes referred to just as <DocLink id="kibServerAndCoreComponents" text="Core, Core services"/> provide the most basic and fundamental tools neccessary for building a plugin, like creating saved objects,
|
||
routing, application registration, notifications and <DocLink id="kibCoreLogging" text="logging"/>. The Core platform is not a plugin itself, although
|
||
there are some plugins that provide platform functionality. We call these <DocLink id="kibPlatformIntro" section="platform-plugins" text="Platform plugins"/>.
|
||
|
||
### Platform plugins
|
||
|
||
Plugins that provide fundamental services and functionality to extend and customize Kibana, for example, the
|
||
<DocLink id="kibDataPlugin" text="data"/> plugin. There is no official way to tell if a plugin is a platform plugin or not.
|
||
Platform plugins are _usually_ plugins that are managed by the Platform Group, but we are starting to see some exceptions.
|
||
|
||
## Plugins
|
||
|
||
Plugins are code that is written to extend and customize Kibana. Plugin's don't have to be part of the Kibana repo, though the Kibana
|
||
repo does contain many plugins! Plugins add customizations by
|
||
using <DocLink id="kibPlatformIntro" section="extension-points" text="extension points"/> provided by <DocLink id="kibPlatformIntro" section="platform-services" text="platform services"/>.
|
||
Sometimes people confuse the term "plugin" and "application". While often there is a 1:1 relationship between a plugin and an application, it is not always the case.
|
||
A plugin may register many applications, or none.
|
||
|
||
### Applications
|
||
|
||
Applications are top level pages in the Kibana UI. Dashboard, Canvas, Maps, App Search, etc, are all examples of applications:
|
||
|
||
|
||
|
||
A plugin can register an application by
|
||
adding it to core's application <DocLink id="kibPlatformIntro" section="registry" text="registry"/>.
|
||
|
||
### Public plugin API
|
||
|
||
A plugin's public API consists of everything exported from a plugin's <DocLink id="kibPlatformIntro" section="plugin-lifecycle" text="start or setup lifecycle methods"/>,
|
||
as well as from the top level `index.ts` files that exist in the three "scope" folders:
|
||
|
||
- common/index.ts
|
||
- public/index.ts
|
||
- server/index.ts
|
||
|
||
Any plugin that exports something from those files, or from the lifecycle methods, is exposing a public service. We sometimes call these things "plugin services" or
|
||
"shared services".
|
||
|
||
## Lifecycle methods
|
||
|
||
Core, and plugins, expose different features at different parts of their lifecycle. We describe the lifecycle of core services and plugins with
|
||
specifically-named functions on the service definition.
|
||
|
||
Kibana has three lifecycles: setup, start, and stop. Each plugin’s setup function is called sequentially while Kibana is setting up
|
||
on the server or when it is being loaded in the browser. The start functions are called sequentially after setup has been completed for all plugins.
|
||
The stop functions are called sequentially while Kibana is gracefully shutting down the server or when the browser tab or window is being closed.
|
||
|
||
The table below explains how each lifecycle relates to the state of Kibana.
|
||
|
||
| lifecycle | purpose | server | browser |
|
||
| ---------- | ------ | ------- | ----- |
|
||
| setup | perform "registration" work to setup environment for runtime |configure REST API endpoint, register saved object types, etc. | configure application routes in SPA, register custom UI elements in extension points, etc. |
|
||
| start | bootstrap runtime logic | respond to an incoming request, request Elasticsearch server, etc. | start polling Kibana server, update DOM tree in response to user interactions, etc.|
|
||
| stop | cleanup runtime | dispose of active handles before the server shutdown. | store session data in the LocalStorage when the user navigates away from Kibana, etc. |
|
||
|
||
Different service interfaces can and will be passed to setup, start, and stop because certain functionality makes sense in the context of a running plugin while other types
|
||
of functionality may have restrictions or may only make sense in the context of a plugin that is stopping.
|
||
|
||
## Extension points
|
||
|
||
An extension point is a function provided by core, or a plugin's plugin API, that can be used by other
|
||
plugins to customize the Kibana experience. Examples of extension points are:
|
||
|
||
- core.application.register (The extension point talked about above)
|
||
- core.notifications.toasts.addSuccess
|
||
- core.overlays.showModal
|
||
- embeddables.registerEmbeddableFactory
|
||
- uiActions.registerAction
|
||
- core.saedObjects.registerType
|
||
|
||
## Follow up material
|
||
|
||
Learn how to build your own plugin by following <DocLink id="kibDevTutorialBuildAPlugin" />.
|