Console

Overview

The Console is a web-based administrative UI for Kyma. It allows you to administer the Kyma functionality and manage the basic Kubernetes resources.

The Console uses the Luigi framework to extend the UI functionality with custom micro front-ends and bring more functionality to the existing UI. You can define the micro front-ends using dedicated Custom Resource Definitions (CRDs).

Use the following CRs to extend the Console UI:

  • The MicroFrontend custom resource allows you to plug in micro front-ends for a specific Environment.
  • The ClusterMicroFrontend custom resource allows you to plug in micro front-ends for the entire Cluster.

UI extensibility

The Kyma Console UI uses the Luigi framework to allow you to seamlessly extend the UI content with custom micro front-ends.

Console UI interaction with micro front-ends

When rendering the navigation, the Kyma Console UI calls a dedicated API endpoint to check if there are any micro front-ends defined in the current context. The current context comprises the current Environment and all global cluster micro front-ends. All the defined micro front-ends and cluster micro front-ends are mapped to the navigation model as navigation nodes with remote viewUrls. When you click the navigation node, the system loads the content of the micro front-end into the content area of the Console. At the same time, the Console sends the current context data to the micro front-end to ensure it is initialized properly.

Micro front-end

A micro front-end is a standalone web application which is developed, tested and deployed independently from the Kyma Console application. It uses the Luigi Client library to ensure proper communication with the Console application. When you implement and deploy a micro front-end, you can plug it to the Kyma Console as a UI extension using dedicated Custom Resource Definitions.

Luigi Client

The Luigi Client enables communication between the micro front-end and the Console application. Include Luigi Client in the micro front-end's codebase as an npm dependency.

npm i @kyma-project/luigi-client

It helps to read the context data that is sent by the Console when the user activates the micro front-end in the UI. Use the following example to read the context data:

LuigiClient.addInitListener((data)=>{
    // do stuff with the context data
});

The Luigi Client facilitates communication between the micro front-end and the Console. Use the Luigi Client API to request the Console to navigate from the micro front-end to any other route available in the application:

LuigiClient.linkManager().navigate('/targetRoute', null, true)

For API details, see Luigi Client API documentation.

Add a micro front-end

Use the Custom Resource Definitions to extend the Console functionality and configure different scopes for your micro front-ends.

Micro front-end for a specific Environment

You can define a micro front-end visible only in the context of a specific Environment (Namespace).

Here you can find a sample micro front-end entity using the namespace metadata attribute to enable the micro front-end only for the production Environment.

Using this yaml file in your Kyma cluster results in a Tractors Overview micro front-end navigation node displayed under the Hardware category. It is available only in the production Environment.

MF-one-environment

Cluster-wide micro front-end

You can define a cluster-wide micro front-end available for all Environments in the side navigation.

Here you can find a sample ClusterMicroFrontend entity using the environment value for the placement attribute to make the micro front-end available for all Environments in the cluster.

Using this yaml file in your Kyma cluster results in a Tractors Overview micro front-end navigation node displayed under the Hardware category. It is available for every Environment in your cluster.

Cluster-wide micro front-end for the administration section

You can define a cluster micro front-end visible in the Administration section of the Console.

Here you can find a sample of such ClusterMicroFrontend entity using the cluster value for placement attribute to ensure the micro front-end is visible in the Administration section.

CMF-admin-section

MicroFrontend

The microfrontend.ui.kyma-project.io custom resource definition (CRD) is a detailed description of the kind of data and the format used to extend the Kyma Console. It allows to extend the Console for the specific Namespace. To get the up-to-date CRD and show the output in the yaml format, run this command:

kubectl get crd microfrontends.ui.kyma-project.io -o yaml

Sample custom resource

This is a sample CR that extends the Console.

apiVersion: ui.kyma-project.io/v1alpha1
kind: MicroFrontend
metadata:
  name: sample-microfrontend
  namespace: production
spec:
  version: 0.0.1
  category: Sample Category
  viewBaseUrl: https://sample-microfrontend-url.com
  navigationNodes:
    - label: Sample List
      navigationPath: items
      viewUrl: /
    - label: Details
      navigationPath: items/:id
      showInNavigation: false
      viewUrl: /:id

This table lists all the possible parameters of a given resource together with their descriptions:

Field Mandatory? Description
metadata.name YES Specifies the name of the CR.
metadata.namespace YES Specifies the target Namespace (Environment) for the CR.
spec.version NO Specifies the version of the micro front-end.
spec.category NO Specifies the category name under which the micro front-end appears in the navigation.
spec.viewBaseUrl YES Specifies the address of the micro front-end. The address has to begin with https://.
spec.navigationNodes YES The list of navigation nodes specified for the micro front-end.
spec.navigationNodes.label YES Specifies the name used to display the micro front-end's node in the Console UI.
spec.navigationNodes.navigationPath NO Specifies the path used for routing within the Console.
spec.navigationNodes.viewUrl NO Specifies the URL used to display the content of a micro front-end.
spec.navigationNodes.showInNavigation NO The Boolean that specifies if the micro front-end's node is visible in the navigation or not.

ClusterMicroFrontend

The clustermicrofrontend.ui.kyma-project.io custom resource definition (CRD) is a detailed description of the kind of data and the format used to extend the Kyma Console. It allows to extend the Console for the entire Cluster. To get the up-to-date CRD and show the output in the yaml format, run this command:

kubectl get crd clustermicrofrontends.ui.kyma-project.io -o yaml

Sample custom resource

This is a sample CR that extends the Console.

apiVersion: ui.kyma-project.io/v1alpha1
kind: ClusterMicroFrontend
metadata:
  name: sample-microfrontend
spec:
  version: 0.0.1
  category: category-name
  viewBaseUrl: https://sample-microfrontend-url.com
  placement: cluster
  navigationNodes:
    - label: Sample List
      navigationPath: items
      viewUrl: /
    - label: Details
      navigationPath: items/:id
      showInNavigation: false
      viewUrl: /:id

This table lists all the possible parameters of a given resource together with their descriptions:

Field Mandatory? Description
metadata.name YES Specifies the name of the CR.
spec.version NO Specifies the version of the cluster micro front-end.
spec.category NO Defines the category name under which the cluster micro front-end appears in the navigation.
spec.viewBaseUrl YES Specifies the address of the cluster micro front-end. The address has to begin with https://.
spec.placement NO Specifies if the cluster micro front-end should be visible in the Environment navigation or settings navigation. The placement value has to be either environment or cluster.
spec.navigationNodes YES The list of navigation nodes specified for the cluster micro front-end.
spec.navigationNodes.label YES Specifies the name used to display the cluster micro front-end's node in the Console UI.
spec.navigationNodes.navigationPath NO Specifies the path that is used for routing within the Console.
spec.navigationNodes.viewUrl NO Specifies the URL used to display the content of the cluster micro-front end.
spec.navigationNodes.showInNavigation NO The Boolean that specifies if the cluster micro front-end's node is visible in the navigation or not.