Extensions
1. What is a Kiali Extension ?
The Istio ecosystem is expanding and there are an increasing number of components providing additional functionality to enrich Service Mesh technology.
Additionally, Kiali project is adding features in the areas of Observability, Analysis, Validation and Management of Istio.
An Extension is a mechanism and guideline to integrate third party components inside Kiali.
2. Examples of Kiali Extensions
Imagine that you develop a new project to provide extra capabilities on top of Istio. Your project deploys extra components into the Istio Control Plane and the typical way to interact with your project is via the CLI.
A Kiali Extension could be used to:
-
Manage specific configuration of your project in a separate section.
-
Enrich Kiali Actions adding new operations for your project.
-
Augment Kiali views to include specific results on graph, metrics or details.
-
Integrate your project in the Istio ecosystem using Kiali as first class User Interface dashboard.
Kiali currently offers integration for 3scale API Management. In the following sections we will illustrate the guidelines using Kiali 3scale extension as an example.
3. Kiali Back-End Guideline
An Extension will typically require changes in the Kiali back-end and front-end.
3.1. Update Kiali Configuration
An Extension should always be enabled/disabled via Kiali configuration.
Add your new Extension config in Kiali:
Document the config in the operator:
Don’t forget to add the default values:
Add the Extension to the Public Config that will be read by the Kiali front-end:
Kiali config is private to the back-end process, only a few values are needed in the front-end project.
An Extension will implement a "feature flag" pattern, so an "enabled" field is needed to implement a conditional render.
3.2. Add Extension logic
Implement the extension logic under the business package (including tests).
Existing extensions can be good templates for naming examples and code organization.
Also under the business package you will find examples about how to interact with the Kubernetes API and other external services.
Expose the business package with handlers to wrap HTTP requests/responses.
Update new routes for the Extension handlers.
Update swagger doc for the new routes. Otherwise Kiali CI prevents merging code without proper documentation.
4. Kiali Front-End Guideline
An Extension may add a new section to Kiali or augment an existing feature. We use the 3scale extension as an example of both use cases.
4.1. Map Back-End Services into Front-End
To make them available to the front-end code, add the Extension’s endpoints into the API mapping.
Map the models returned by the back-end into UI types:
4.2. Add Extension Pages
Extension Pages should be added under the pages/extensions folder:
A list/detail pattern is being implemented with the 3scale example extension. It can be used as template for other extensions.
List pattern:
Details pattern:
4.3. Enable Extension in Navigation
Add Extension Menu Items and Routes:
And add logic to enable the Extension in Kiali Menu and RenderPage component:
4.4. Augment Kiali Features
Actions or Tabs on existing features should always be rendered conditionally based on the configuration. Backend calls should be made only if the extension is enabled.
5. Refactoring
Kiali is an active project and is constantly evolving. Adding a new Extension may trigger the need to refactor existing code in order to accommodate new use cases, or provide a more robust abstraction. Do not hesitate to contact a Kiali maintainer with your proposal! It will help to understand the scenario and how we can coordinate best to include your work.