Our own, Mateusz Szostok has two sessions at KubeCon around K8s Service CatalogRead more

Mateusz Szostok, Piotr Kopczynski and Pawel Kosiec have several talks at San Diego Cloud Native MeetupRead more

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 frontends and bring more functionality to the existing UI. You can define the micro frontends using dedicated CustomResourceDefinitions (CRDs).

Use the following CRs to modify the Console UI:

  • The MicroFrontend custom resource allows you to plug in micro frontends for a specific Namespace.
  • The ClusterMicroFrontend custom resource allows you to plug in micro frontends for the entire Cluster.
  • The BackendModule custom resource allows you to enable Console Backend Service modules.

Details

UI extensibility

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

Console UI interaction with micro frontends

When rendering the navigation, the Kyma Console UI calls a dedicated API endpoint to check if there are any micro frontends defined in the current context. The current context comprises the current Namespace and all global cluster micro frontends. All the defined micro frontends and cluster micro frontends 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 frontend into the content area of the Console. At the same time, the Console sends the current context data to the micro frontend to ensure it is initialized properly.

Micro frontend

A micro frontend 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 frontend, you can plug it to the Kyma Console as a UI extension using dedicated CustomResourceDefinitions.

Luigi Client

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

Click to copy
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 frontend in the UI. Use the following example to read the context data:

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

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

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

For API details, see Luigi Client API documentation.

Add a micro frontend

Use the CustomResourceDefinitions to extend the Console functionality and configure different scopes for your micro frontends.

Micro frontend for a specific Namespace

You can define a micro frontend visible only in the context of a specific Namespace.

Here you can find a sample micro frontend entity using the namespace metadata attribute to enable the micro frontend only for the production Namespace.

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

MF-one-namespace

Cluster-wide micro frontend

You can define a cluster-wide micro frontend available for all Namespaces in the side navigation.

Here you can find a sample ClusterMicroFrontend entity using the namespace value for the placement attribute to make the micro frontend available for all Namespaces in the cluster.

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

Cluster-wide micro frontend for the administration section

You can define a cluster micro frontend 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 frontend is visible in the Administration section.

CMF-admin-section

Console Backend Service

The Console Backend Service is a backend service which provides an API for all views of the Console UI. This service consumes the Kubernetes API and exposes a simplified GraphQL API to allow frontends to perform Kubernetes resource operations.

NOTE: Read this security document for more information about the Kyma GraphQL implementation.

Cache

For GraphQL queries, the Console Backend Service uses caching which is based on Informers from the Kubernetes Go client. There are separate cache stores for every Kubernetes resource. The stores are synchronized when the service starts. After cache synchronization, a single connection with the Kubernetes API server is established and any event related to one of the observed resources updates the corresponding cache store. This logic ensures that cache stores are always up-to-date without sending multiple requests to the Kubernetes API server.

Modularization

The Console Backend Service consists of the Kubernetes resource logic and cache for different domains, such as the Service Catalog, Application, or Kubeless. The Console Backend Service introduces modularization changes which are based on toggling modules while the server is running. The enabled module synchronizes cache for its resource and enables the module's logic for all server requests. If you disable a given module, every GraphQL query, mutation, and subscription related to this module returns an error.

These are the available Console Backend Service pluggable modules which contain the GraphQL resolver logic, where:

  • apicontroller relates to the API Controller.
  • authentication relates to IDP Presets.
  • application relates to the Application Connector.
  • assetstore relates to Asset Store.
  • cms relates to Headless CMS.
  • kubeless relates to Serverless.
  • servicecatalog relates to the Service Catalog, including Service Classes, Service Instances, and Service Bindings.
  • servicecatalogaddons relates to the Service Catalog add-ons, such as ServiceBindingUsage, and UsageKinds.
  • grafana relates to Grafana.
  • loki relates to Loki.

To enable a given module, install the corresponding Kyma component. It includes the BackendModule custom resource with the same name as the name of a given module.

Security guidelines for MicroFrontend and ClusterMicroFrontend CRs

For security reasons, follow the listed guidelines when you configure the web server for the MicroFrontend or ClusterMicroFrontend:

  • Make the MicroFrontend or ClusterMicroFrontend accessible only through HTTPS.
  • Make the Access-Control-Allow-Origin HTTP header as restrictive as possible.
  • Set the X-Content-Type HTTP header to nosniff.
  • Set the X-Frame-Options HTTP header to sameorigin or allow-from ALLOWED_URL.
  • Add Content Security Policies (CSPs).

Headless CMS in the Console

The Headless CMS in Kyma is a separate component and does not provide templates or a standalone UI to display content from the CMS. Still, the Console UI displays some of the assets in the Docs view (generic and component-related documentation) and the Service Catalog views (API specifications and Service Class-related documentation).

Add a new documentation topic to the Console UI by creating a CR, while the Asset Store handles the rest. Define the location, grouping, and order of the documents through DocsTopic and ClusterDocsTopic labels that you add to the custom resource definition. You can create your own labels and follow your own naming convention, but cms.kyma-project.io/{label-name} applies to the Console UI.

Use these labels to mark and filter assets in the Console UI:

  • cms.kyma-project.io/view-context specifies the location in the Console UI to render the given asset. This can be either docs-ui or service-catalog.
  • cms.kyma-project.io/group-name defines the group, such as components, under which you want to render the given asset under the docs-ui view in the Console UI. The value cannot include spaces.
  • cms.kyma-project.io/order specifies the position of the DocsTopic and ClusterDocsTopic in relation to other DocsTopics under the docs-ui view in the Console UI. For example, this can be 4.

Configuration

To define how DocsTopic and ClusterDocsTopic are rendered in the UI, use the following parameters:

ParameterDefault ValueDescription
spec.sources.metadata.disableRelativeLinksfalseDisables relative links when documentation is rendered. It only applies to the markdown type of assets included in the (Cluster)DocsTopic CR.

Supported specifications

The Console UI supports only certain specification types, formats, and versions passed in the DocsTopics and ClusterDocsTopics:

TypeDescriptionFormatVersion
OpenAPIAPI-related informationjson and yaml3.0 and lower
ODataAPI-related informationxml4.0 and lower
AsyncAPIMessaging data (for Events)json and yaml2.0 and lower
MarkdownService Class or component documentationmd

NOTE: OpenAPI, OData, and AsyncAPI specifications rendered in the Console UI follow the Fiori 3 Fundamentals styling standards.

The source files are uploaded directly to the given storage without any modifications, except for the following source types:

  • asyncapi that the CMS AsyncAPI Service validates and, if required, converts to version 2.0 and the json format.
  • markdown from which the Asset Metadata Service extracts front matter metadata.

Specification types

TIP: The default Kyma webhooks that convert and validate asyncapi source files and extract metadata from markdown files are defined in the webhook-config-map.yaml ConfigMap.

Configuration

Console chart

To configure the Console chart, override the default values of its values.yaml file. This document describes parameters that you can configure.

TIP: To learn more about how to use overrides in Kyma, see the following documents:

Configurable parameters

This table lists the configurable parameters, their descriptions, and default values:

ParameterDescriptionDefault value
cluster.orgIdDefines the ID of the organization for which the Kyma cluster is installed. It shows under General settings in the Console UI.my-org-123
cluster.orgNameDefines the name of the organization for which the Kyma cluster is installed. It shows under General settings in the Console UI.My Organization
cluster.headerLogoUrlDefines the address of the logo image that shows in the Console UI navigation header.assets/logo.svg
cluster.faviconUrlDefines the icon that shows in the address bar of a browser.favicon.ico
cluster.headerTitleDefines an additional title that shows next to the logo image in the Console UI navigation header.None
cluster.disabledNavigationNodesDefines a list of categories or specific nodes in the navigation that you want to hide in the Console UI navigation. To hide all navigation nodes from a category, make sure the list includes categoryLabel. To hide a specific navigation node, use both categoryLabel and nodeLabel separated with a period (.). For the Namespace-related views, add the namespace prefix to the list entry. For example, namespace.operation.secrets would hide the Secrets navigation node within the Operation category for all Namespaces. For all labels, use lowercase and don't use any spaces or dashes.None
cluster.systemNamespacesDefines a list of Namespaces that should be considered as system Namespaces. The Console UI gives you the possibility to toggle the visibility of system Namespaces.compass-system istio-system knative-eventing knative-serving kube-public kube-system kyma-installer kyma-integration kyma-system natss

Custom Resource

MicroFrontend

The microfrontends.ui.kyma-project.io CustomResourceDefinition (CRD) is a detailed description of the kind of data and the format used to extend the Kyma Console. It allows you to extend the Console for the specific Namespace. A micro frontend is added to the Console automatically based on the yaml file. To avoid naming conflicts with the core system, the root node receives the mf- prefix in the URL. Additionally, the navigationContext and viewGroup node configuration parameters are set to allow simple navigation. To get the up-to-date CRD and show the output in the yaml format, run this command:

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

Sample custom resource

This is a sample CR that extends the Console.

Click to copy
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: /
requiredPermissions:
- apiGroup: foo.bar.io
resource: items
verbs:
- list
- label: Details
navigationPath: items/:id
showInNavigation: false
viewUrl: /:id
requiredPermissions:
- apiGroup: foo.bar.io
resource: items
verbs:
- update
- delete

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

FieldRequiredDescription
metadata.nameYesSpecifies the name of the CR.
metadata.namespaceYesSpecifies the target Namespace for the CR.
spec.versionNoSpecifies the version of the micro frontend.
spec.categoryNoSpecifies the category name under which the micro frontend appears in the navigation.
spec.viewBaseUrlYesSpecifies the address of the micro frontend. The address has to begin with https://.
spec.navigationNodesYesThe list of navigation nodes specified for the micro frontend.
spec.navigationNodes.labelYesSpecifies the name used to display the micro frontend's node in the Console UI.
spec.navigationNodes.navigationPathNoSpecifies the path used for routing within the Console.
spec.navigationNodes.viewUrlNoSpecifies the URL used to display the content of a micro frontend.
spec.navigationNodes.showInNavigationNoThe Boolean that specifies if the micro frontend's node is visible in the navigation or not.
spec.navigationNodes.requiredPermissionsNoSpecifies the list of permissions (RBAC rules) that determine if the navigation node should be shown for the current user.

ClusterMicroFrontend

The clustermicrofrontends.ui.kyma-project.io CustomResourceDefinition (CRD) is a detailed description of the kind of data and the format used to extend the Kyma Console. It allows you to extend the Console for the entire Cluster. The cluster micro frontend is added to Console automatically based on the yaml file. To avoid naming conflicts with the core system, the root node receives the cmf- prefix in the URL. Additionally, navigationContext and viewGroup node configuration parameters are set to allow simple navigation. To get the up-to-date CRD and show the output in the yaml format, run this command:

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

Sample custom resource

This is a sample CR that extends the Console.

Click to copy
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: /
requiredPermissions:
- apiGroup: foo.bar.io
resource: items
verbs:
- list
- label: Details
navigationPath: items/:id
showInNavigation: false
viewUrl: /:id
requiredPermissions:
- apiGroup: foo.bar.io
resource: items
verbs:
- update
- delete

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

FieldRequiredDescription
metadata.nameYesSpecifies the name of the CR.
spec.versionNoSpecifies the version of the cluster micro front-end.
spec.categoryNoDefines the category name under which the cluster micro front-end appears in the navigation.
spec.viewBaseUrlYesSpecifies the address of the cluster micro front-end. The address has to begin with https://.
spec.placementNoSpecifies if the cluster micro front-end should be visible in the Namespace navigation or settings navigation. The placement value has to be either namespace or cluster.
spec.navigationNodesYesThe list of navigation nodes specified for the cluster micro front-end.
spec.navigationNodes.labelYesSpecifies the name used to display the cluster micro front-end's node in the Console UI.
spec.navigationNodes.navigationPathNoSpecifies the path that is used for routing within the Console.
spec.navigationNodes.viewUrlNoSpecifies the URL used to display the content of the cluster micro-front end.
spec.navigationNodes.externalLinkNoSpecifies the URL used to display the content of the cluster micro front-end in a new browser tab.
spec.navigationNodes.showInNavigationNoThe Boolean that specifies if the cluster micro front-end's node is visible in the navigation or not.
spec.navigationNodes.requiredPermissionsNoSpecifies the list of permissions (RBAC rules) that determine if the navigation node should be shown for the current user.

BackendModule

The backendmodules.ui.kyma-project.io CustomResourceDefinition (CRD) is a detailed description of the kind of data and the format used to enable Console Backend Service modules.

To get the up-to-date CRD and show the output in the yaml format, run this command:

Click to copy
kubectl get crd backendmodules.ui.kyma-project.io -o yaml

Sample custom resource

This is a sample CR that enables the servicecatalog module in the Console Backend Service:

Click to copy
apiVersion: ui.kyma-project.io/v1alpha1
kind: BackendModule
metadata:
name: servicecatalog

Custom resource parameters

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

ParameterRequiredDescription
metadata.nameYesSpecifies the name of the CR. It must be the same as the name of a given Console Backend Service module.

These components use this CR:

ComponentDescription
Console Backend ServiceThe component reacts to every action of adding or deleting the BackendModule custom resource and enables or disables a given Console Backend Service module accordingly.