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.
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:
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:
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.
See the mf-namespaced.yaml
file for 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.
Cluster-wide micro frontend
You can define a cluster-wide micro frontend available for all Namespaces in the side navigation.
See the cmf-environment.yaml
file for 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.
See the cmf-cluster.yaml
for a sample ClusterMicroFrontend entity using the cluster
value for placement attribute to ensure the micro frontend is visible in the Administration 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 the 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 Serverless. 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.apigateway
relates to the API Gateway.authentication
relates to IDP Presets.application
relates to the Application Connector.serverless
relates to Serverless.eventing
relates to Knative Eventing.rafter
relates to Rafter.servicecatalog
relates to the Service Catalog, including ServiceClasses, ServiceInstances, and ServiceBindings.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
orallow-from ALLOWED_URL
. - Add Content Security Policies (CSPs).
Rafter in the Console
Rafter 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 under the Service Catalog view (API specifications and Service Class-related documentation).
Add a new API specification or Service Class-related documentation topic to the Console UI by creating a CR, while Rafter handles the rest. Define the location, grouping, and order of the documents through AssetGroup and ClusterAssetGroup labels that you add to the custom resource definition. You can create your own labels and follow your own naming convention, but rafter.kyma-project.io/{label-name} applies to the Console UI.
Use the rafter.kyma-project.io/view-context label to mark and filter Service Class-related assets in the Console UI. Set its value to service-catalog
to specify that these assets should be displayed under the Service Catalog view.
Configuration
To define how AssetGroup and ClusterAssetGroup are rendered in the UI, use the following parameters:
Parameter | Default Value | Description |
---|---|---|
spec.sources.metadata.disableRelativeLinks | false | Disables relative links when documentation is rendered. It only applies to the markdown type of assets included in the (Cluster)AssetGroup CR. |
Supported specifications
The Console UI supports only certain specification types, formats, and versions passed in the AssetGroups and ClusterAssetGroups:
Type | Description | Format | Version |
---|---|---|---|
OpenAPI | API-related information | json and yaml | 3.0 and lower |
OData | API-related information | xml | 4.0 and lower |
AsyncAPI | Messaging data (for Events) | json and yaml | 2.0 and lower |
Markdown | Service Class documentation | md |
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 AsyncAPI Service validates and, if required, converts to version 2.0 and thejson
format.markdown
from which the Front Matter Service extracts front matter metadata.
TIP: The default Kyma webhooks that convert and validate
asyncapi
source files and extract metadata frommarkdown
files are defined in thewebhook-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:
Parameter | Description | Default value |
---|---|---|
cluster.orgId | Defines 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.orgName | Defines the name of the organization for which the Kyma cluster is installed. It shows under General settings in the Console UI. | My Organization |
cluster.headerLogoUrl | Defines the address of the logo image that shows in the Console UI navigation header. | assets/logo.svg |
cluster.faviconUrl | Defines the icon that shows in the address bar of a browser. | favicon.ico |
cluster.headerTitle | Defines an additional title that shows next to the logo image in the Console UI navigation header. | None |
cluster.disabledNavigationNodes | Defines 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 |
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:
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/v1alpha1kind: MicroFrontendmetadata: name: sample-microfrontend namespace: productionspec: 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:
Field | Required | Description |
---|---|---|
metadata.name | Yes | Specifies the name of the CR. |
metadata.namespace | Yes | Specifies the target Namespace for the CR. |
spec.version | No | Specifies the version of the micro frontend. |
spec.category | No | Specifies the category name under which the micro frontend appears in the navigation. |
spec.viewBaseUrl | Yes | Specifies the address of the micro frontend. The address has to begin with https:// . |
spec.navigationNodes | Yes | The list of navigation nodes specified for the micro frontend. |
spec.navigationNodes.label | Yes | Specifies the name used to display the micro frontend'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 frontend. |
spec.navigationNodes.showInNavigation | No | The Boolean that specifies if the micro frontend's node is visible in the navigation or not. |
spec.navigationNodes.requiredPermissions | No | Specifies 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:
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/v1alpha1kind: ClusterMicroFrontendmetadata: name: sample-microfrontendspec: 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:
Field | Required | Description |
---|---|---|
metadata.name | Yes | Specifies the name of the CR. |
spec.version | No | Specifies the version of the cluster micro frontend. |
spec.category | No | Defines the category name under which the cluster micro frontend appears in the navigation. |
spec.viewBaseUrl | Yes | Specifies the address of the cluster micro frontend. The address has to begin with https:// . |
spec.placement | No | Specifies if the cluster micro frontend should be visible in the Namespace navigation or settings navigation. The placement value has to be either namespace or cluster . |
spec.navigationNodes | Yes | The list of navigation nodes specified for the cluster micro frontend. |
spec.navigationNodes.label | Yes | Specifies the name used to display the cluster micro frontend'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 frontend. |
spec.navigationNodes.externalLink | No | Specifies the URL used to display the content of the cluster micro frontend in a new browser tab. |
spec.navigationNodes.showInNavigation | No | The Boolean that specifies if the cluster micro frontend's node is visible in the navigation or not. |
spec.navigationNodes.requiredPermissions | No | Specifies 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:
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:
apiVersion: ui.kyma-project.io/v1alpha1kind: BackendModulemetadata: name: servicecatalog
Custom resource parameters
This table lists all the possible parameters of a given resource together with their descriptions:
Parameter | Required | Description |
---|---|---|
metadata.name | Yes | Specifies the name of the CR. It must be the same as the name of a given Console Backend Service module. |
Related resources and components
These components use this CR:
Component | Description |
---|---|
Console Backend Service | The component reacts to every action of adding or deleting the BackendModule custom resource and enables or disables a given Console Backend Service module accordingly. |