Busola

Overview

Busola is a web-based UI for managing resources within Kyma or any Kubernetes cluster. It consists of separate frontend applications.

Components

Busola project consists of the following UI projects:

• Core - The main frame
• Service-Catalog-UI - The UI layer for Service Catalog, Instances and Brokers
• Backend - A kind of a proxy between Busola and the Kubernetes cluster
• Tests - Acceptance and end-to-end tests

Prerequisites

• npm: >= 6.14.12
• node: >= 14.16.1

Installation

To install dependencies for the root and all UI projects, and to prepare symlinks for local libraries within this repository, run the following command:

npm run bootstrap:ci

NOTE: The npm run bootstrap:ci command:

• Installs root dependencies provided in the package.json file.
• Installs dependencies for the libraries.
• Builds all the libraries.

Configuration

Learn about the default configuration in Busola and how to change it.

Default Configuration

Busola is delivered with the following default settings:

Parameter	Comment	Default Value
kubeconfig	The kubeconfig as JSON	null
hiddenNamespaces	A list of Namespace names that are considered system, and are hidden by default.	default list: istio-system, kube-public, kube-system, kyma-backup, kyma-installer, kyma-integration, kyma-system, natss, kube-node-lease, kubernetes-dashboard, serverless-system
features	Switches a set of Busola features on and off. Use selectors to configure conditions for the features. To switch them off, set isEnabled=false.	isEnabled=true
navigation.disabledNodes	Array of IDs of navigation nodes that are hidden from navigation. Format: <category>.<nodeName> or <namespace>.<category>.<nodeName>)	empty
navigation.externalNodes	A nested list of links to external websites. category, icon: a category name and optional icon / children: a list of pairs (label and link)	category: Learn more / children: Kyma Documentation, Our Slack, Github
version	Configuration version. Don’t edit this. Can be empty.	the most recent release

Change the Configuration

If you have the required authorizations and access to the kubeconfig, you can change the settings for the Busola cluster configuration and the target cluster configuration.

With the feature toggles, you can switch each Busola feature on or off and configure them to fit your needs. Features comprise the following elements:

• FEATURE_ID: Unique identifier, as defined in the Busola source code
• selector: The k8s resources that can activate the feature
• isActive: Activates or deactivates the feature, overwriting the status set by selector
• config: Provides additional configuration options as needed for each feature. For details, see the README in the specific component or feature.

Usage

See the Development section.

Development

Start all views

Use the following command to run Busola with the core and all other views locally:

npm run start

After a while, open the http://localhost:8080 address in your browser, and add your init params to the address to make it look like http://localhost:8080?init=yourInitParams. You can generate the params with this generator.

Once you started Busola locally, you can begin the development. All modules have the hot-reload feature enabled, therefore, you can edit the code in real-time and see the changes in your browser.

The apps you started run at the following addresses:

• Core - http://localhost:8080
• Core-UI - http://localhost:8889
• Service-Catalog-UI - http://localhost:8000
• Backend - http://localhost:3001

Security countermeasures

When developing new features in Busola UI, adhere to the following rules. This will help you to mitigate any security-related threats.

1. Prevent cross-site request forgery (XSRF).

   • Do not store the authentication token as a cookie. Make sure the token is sent to Busola backend as a bearer token.
   • Make sure that the state-changing operations (POST, PUT, DELETE, and UPDATE requests) are only triggered upon explicit user interactions, such as form submissions.
   • Keep in mind that UI rendering in response to the user navigating between views is only allowed to trigger read-only operations (GET requests) without any data mutations.

2. Protect against cross-site scripting (XSS).

   • It is recommended to use JS frameworks that have built-in XSS prevention mechanisms, such as ReactJS, Vue.js, or Angular.
   • As a rule of thumb, you cannot perceive user input to be 100% safe. Get familiar with prevention mechanisms included in the framework of your choice. Make sure the user input is sanitized before it is embedded in the DOM tree.
   • Get familiar with the most common XSS bypasses and potential dangers. Keep them in mind when writing or reviewing the code.
   • Enable the Content-security-policy header for all new micro frontends to ensure in-depth XSS prevention. Do not allow for unsafe-eval policy.

Run tests

For the information on how to run tests and configure them, go to the tests directory.

Troubleshooting

TIP: To solve most of the problems with Busola development, clear the browser cache or do a hard refresh of the website.

Symptom

You are experiencing connectivity problems with Busola in Docker against a k3d cluster.

Cause

When the k3d cluster's API server is exposed on the 0.0.0.0 address on you machine, Busola in Docker interprets 0.0.0.0 as its internal Docker address, routing the requests to the wrong endpoint.

Remedy

• For Docker Desktop for Mac and Windows, pass DOCKER_DESKTOP_CLUSTER=true on dockerized Busola startup. This way, 0.0.0.0 is automatically replaced with host.docker.internal.

  docker run --rm -it -p 3001:3001 -e DOCKER_DESKTOP_CLUSTER=true --pid=host --name busola eu.gcr.io/kyma-project/busola:latest

• For Linux, run Busola with --net=host (omitting the -p parameter).

  docker run --rm -it --net=host --pid=host --name busola eu.gcr.io/kyma-project/busola:latest