Repository files navigation

Busola is a web-based UI for managing resources within a Kubernetes cluster. It's based on theReactJS library.

Busola project contains additional sub-projects:

• Backend - A kind of a proxy between Busola and the Kubernetes cluster
• Tests - Acceptance, regression and integration tests
• Kyma - Kyma specific configuration for Busola

• npm in version 10.x
• node in version 22.x

Busola supports:

• Kyma in version 2.4.2 or higher
• Istio in versionv1beta1

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

npm install

ReadInstall Kyma Dashboard manually to learn how to install the Dashboard with Istio Ingress and how to install it on a Kyma cluster.

Run thenpm start command.

Learn about thedefault configuration in Busola andhow to change it.

Busola is delivered with the following default settings:

Busola configuration is the product of gathering and merging the configurations from several individual sources. The following list presents the sources in the order of precedence:

Backend:

• Busola backend default cluster configuration, acquired from thedefaultConfig.yaml file.
• Busola cluster configuration, available on the Busola cluster in the ConfigMap "busola/busola-config" under the key "config".This data is mounted to the Busolaweb andbackend Pods, and during the local development,thedefaultConfig.yaml file is used.

Frontend:

• Built-in, hardcoded defaults.
• Busola frontend default cluster configuration, acquired from thedefaultConfig.yaml file.
• Busola cluster configuration, available on the Busola cluster in the ConfigMap "busola/busola-config" under the key "config".This data is mounted to the Busolaweb andbackend Pods, and during the local development,thedefaultConfig.yaml file is used.
• Target cluster configuration, available on the target cluster in ConfigMap "kube-public/busola-config" under the key "config". Busola performs a request for that resource during the bootstrap process.
• Custom configuration withextensibility andconfig located inpublic/environments,read more.

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 thefeature 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
• isEnabled: Activates or deactivates the feature, overwriting the status set byselector
• config: Provides additional configuration options as needed for each feature. For details, see the README in the specific component or feature.

See the available Busolafeature flags for more information.

You can provide an override to the default configuration with your own environment-specific settings.Follow this pattern to structure your custom environment directory and place it inpublic/environments.

custom-env/├── config│   └── config.yaml└── extensions    ├── extensions.yaml    └── wizards.yaml

To activate your environment configuration, create or edit theactive.env file in thepublic directory.Follow this example of theactive.env file:

ENVIRONMENT=your-environment-name

WhenENVIRONMENT is set tomy-env, Busola looks for your custom configuration inpublic/environemnt/my-env.IfENVIRONMENT is not set, Busola fetches the default configuration with the same structure as the custom configuration located in thepublic directory.

In the case of the Docker image, theactive.env file is created at the startup of the image from the environment specified in theENVIRONMENT variable.

Use the following command to run Busola locally:

npm start

After a while, open thehttp://localhost:8080 address in your browser, and provide your kubeconfig in theConnect cluster wizard.

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:

• Busola -http://localhost:8080
• Backend -http://localhost:3001

When developing new features in Busola, 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, andUPDATE 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 asReactJS,Vue.js, orAngular.
   • 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 commonXSS bypasses and potential dangers. Keep them in mind when writing or reviewing the code.
   • Enable theContent-security-policy header for all new micro frontends to ensure in-depth XSS prevention. Do not allow forunsafe-eval policy.

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

1. If you run Busola in Docker, you can mount your kubeconfig as a bind mount for Busola container. Execute the following command:

   docker run --rm -it -p 3001:3001 -v<path to your kubeconfig>:/app/core-ui/kubeconfig/<your kubeconfig file name> --pid=host --name busola europe-docker.pkg.dev/kyma-project/prod/busola:latest

2. When you open Busola in your browser, visithttp://localhost:3001?kubeconfigID={YOUR_KUBECONFIG_FILE_NAME}. Busola will try to download that file and add it for your Busola instance.

1. To use one of the built-in environments in thebusola image (dev, stage, prod), pass envENVIRONMENT to the Docker container.

   docker run --rm -it -p 3001:3001 --env ENVIRONMENT={your-env} --pid=host --name busola europe-docker.pkg.dev/kyma-project/prod/busola:latest

2. To use a custom environment configuration, mount it in Docker and pass theENVIRONMENT env to the Docker container.

   docker run --rm -it -p 3001:3001 -v<path to your custom config>:/app/core-ui/environments/ --env ENVIRONMENT={your-env} --pid=host --name busola europe-docker.pkg.dev/kyma-project/prod/busola:latest

To install Busola from release in the Kubernetes cluster setVERSION shell environment variable with desired release and run:

kubectl apply -f https://github.com/kyma-project/busola/releases/download/${VERSION}/busola.yaml

To install Busola from main branch in the Kubernetes cluster, run:

(cd resources&& kustomize build base/| kubectl apply -f- )

To install Busola using a specific environment configuration, set theENVIRONMENT shell environment variable and run:

(cd resources&& kustomize build environments/${ENVIRONMENT}| kubectl apply -f- )

The simplest method that always works is to use the capabilities of kubectl.

kubectl port-forward services/busola 3001:3001

Prerequisites:

• K3d with exposed loadbalancer on port 80.

  TIP: To create K3d with exposed load balancer run:k3d cluster create -p "80:80@loadbalancer".SeeExposing Services for more details.

1. Install Ingress resources:

(cd resources&& kubectl apply -f ingress/ingress.yaml)

2. Visitlocalhost

To connect to the same k3d cluster with Busola installed, download kubeconfig and change the cluster server address tohttps://kubernetes.default.svc:443.

Use shell to quickly process the file.

Prerequisites:

• yq

Set theK3D_CLUSTER_NAME shell environment variable to the name of your cluster and run:

k3d kubeconfig get${K3D_CLUSTER_NAME}> k3d-kubeconfig.yamlyq --inplace'.clusters[].cluster.server = "https://kubernetes.default.svc:443"' k3d-kubeconfig.yaml

Prerequisites:

• Sidecar Proxy injection enabled, seeEnable Istio Sidecar Proxy Injection.
• The API Gateway module installed, seeQuick Install

1. Install the Istio required resources:

(cd resources&& kubectl apply -k istio)

2. To get the Busola address, run:

kubectl get virtualservices.networking.istio.io

and find thebusola-*** virtual service. UnderHOSTS, there is an address where you can access the Busola page.

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

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

When the k3d cluster's API Server is exposed on the0.0.0.0 address on your machine, Busola in Docker interprets0.0.0.0 as its internal Docker address, routing the requests to the wrong endpoint.

• For Docker Desktop for Mac and Windows, passDOCKER_DESKTOP_CLUSTER=true on dockerized Busola startup. This way,0.0.0.0 is automatically replaced withhost.docker.internal, which is resolved to 'routable' IP address of a Docker Desktop virtual machine.

  docker run --rm -it -p 3001:3001 -e DOCKER_DESKTOP_CLUSTER=true --pid=host --name busola europe-docker.pkg.dev/kyma-project/prod/busola:latest

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

  docker run --rm -it --net=host --pid=host --name busola europe-docker.pkg.dev/kyma-project/prod/busola:latest

When you run Busola in Docker on macOS, it can't connect to the k3d cluster. The container log contains the following errors:

Error [ERR_TLS_CERT_ALTNAME_INVALID]: Hostname/IP does not match certificate's altnames: Host: host.docker.internal. is not in the cert's altnames: DNS:k3d-k3s-default-server-0, DNS:k3d-k3s-default-serverlb, DNS:kubernetes, DNS:kubernetes.default, DNS:kubernetes.default.svc, DNS:kubernetes.default.svc.cluster.local, DNS:localhost, IP Address:0.0.0.0, IP Address:10.43.0.1, IP Address:127.0.0.1, IP Address:172.28.0.3, IP Address:0:0:0:0:0:0:0:1

Busola run in a Docker container with the environment variableDOCKER_DESKTOP_CLUSTER=true replaces the IP0.0.0.0 in the API Server URL withhost.docker.internal. Kubernetes is not aware of that host name, so its API Server doesn't have it in the SSL certificate, which results in the above error.

Furthermore, this behavior has changed in the recent k3d versions, which is a result ofthis fix forthis security issue.

Clusters created byk3d use alistener that extractsSNI host names from requests sent to the API server. If a new host name is requested, then the SSL certificate is regenerated, and the new host name is added to the list of Subject Alternative Names. Unfortunately, the security fix limits this mechanism only to the expected host names, like those related to Kubernetes nodes. This makes it useless for thehost.docker.internal case.

Provide thehost.docker.internal host name upfront duringk3d cluster creation:

k3d cluster create kyma --k3s-arg '--tls-san=host.docker.internal@server:*'

A cluster created in such a way has thehost.docker.internal set as Subject Alternative Name in the SSL Certificate of the API Server since the very beginning.

See theContributing Rules.

See theCode of Conduct document.

See thelicense file.