Skip to content

Commit 55be250

Browse files
grego952dbadura
grego952
and
dbadura
authored
docs: Add ns2 docs (#3963)
* Add n2 docs * Add Related Information * Fix numbering * Fix numbering * Fix screenshot * Provide more info in description and update diagram and its steps * Add troubleshooting guide on missing resources * Move sections from README to seperate docs * Fix links, move diagram to user/Readme, and remove operator * Fix README * Fix numbering * Diagram fix * Add gerund form * add cannot connect to a cluster * Add architecture diagram * Apply suggestions and small fixes * Apply Agata's suggestion and fix link * Disable link checker * Update README * Apply suggestions from code review * Apply suggestions from code review * add namespaces, use envs, improve configurability docs * Apply suggestions from code review * Remove unnecessary link * Remove active.env link * Add status codes and move configuration and deployment to operator * Apply Damian's suggestions * update features docs --------- Co-authored-by: Damian Badura <damian.badura@sap.com>
1 parent 8a732df commit 55be250

File tree

12 files changed

+438
-366
lines changed

12 files changed

+438
-366
lines changed

‎README.md‎

Lines changed: 11 additions & 288 deletions
Large diffs are not rendered by default.

‎docs/contributor/busola-docker.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
## Busola in Docker
2+
3+
### Adding a Cluster Using Kubeconfig ID
4+
5+
1. If you run Busola in Docker, you can mount your kubeconfig as a bind mount for the Busola container. Prepare the **KUBECONFIG** shell environment variable and run the following command:
6+
7+
```bash
8+
docker run --rm -it -p 3001:3001 -v "${KUBECONFIG}":/app/core-ui/kubeconfig/$(basename "${KUBECONFIG}") --pid=host --name busola europe-docker.pkg.dev/kyma-project/prod/busola:latest
9+
```
10+
11+
2. When you open Busola in your browser, visit `http://localhost:3001?kubeconfigID={YOUR_KUBECONFIG_FILE_NAME}`. Busola tries to download that file and adds it for your Busola instance.
12+
13+
### Setting Active Environment
14+
15+
1. To use one of the built-in environments in the `busola` image (dev, stage, prod), pass the **ENVIRONMENT** env to the Docker container.
16+
17+
```bash
18+
docker run --rm -it -p 3001:3001 --env ENVIRONMENT="${ENVIRONMENT}" --pid=host --name busola europe-docker.pkg.dev/kyma-project/prod/busola:latest
19+
```
20+
21+
2. To use a custom environment configuration, mount it in Docker and pass the **ENVIRONMENT** and **CUSTOM_CONFIG_PATH** env to the Docker container.
22+
```bash
23+
docker run --rm -it -p 3001:3001 -v ${CUSTOM_CONFIG_PATH}:/app/core-ui/environments/ --env ENVIRONMENT="${ENVIRONMENT}" --pid=host --name busola europe-docker.pkg.dev/kyma-project/prod/busola:latest
24+
```

‎docs/contributor/development.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Development
2+
3+
## Starting All Views
4+
5+
Use the following command to run Busola locally:
6+
7+
```bash
8+
npm start
9+
```
10+
11+
After a while, open the [http://localhost:8080](http://localhost:8080) address in your browser, and provide your kubeconfig in the **Connect cluster** wizard.
12+
13+
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.
14+
15+
The apps you started run at the following addresses:
16+
17+
- `Busola` - [http://localhost:8080](http://localhost:8080)
18+
- `Backend` - [http://localhost:3001](http://localhost:3001)
19+
20+
### Security Countermeasures
21+
22+
When developing new features in Busola, adhere to the following rules. This will help you to mitigate any security-related threats.
23+
24+
1. Prevent cross-site request forgery (XSRF).
25+
26+
- Do not store the authentication token as a cookie. Make sure the token is sent to Busola backend as a bearer token.
27+
- Make sure that the state-changing operations (`POST`, `PUT`, `DELETE`, and `UPDATE` requests) are only triggered upon explicit user interactions, such as form submissions.
28+
- 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.
29+
30+
2. Protect against cross-site scripting (XSS).
31+
32+
- It is recommended to use JS frameworks that have built-in XSS prevention mechanisms, such as [ReactJS](https://reactjs.org/docs/introducing-jsx.html#jsx-prevents-injection-attacks), [Vue.js](https://vuejs.org/v2/guide/security.html#What-Vue-Does-to-Protect-You), or [Angular](https://angular.io/guide/security#angulars-cross-site-scripting-security-model).
33+
- 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.
34+
- Get familiar with the most common [XSS bypasses and potential dangers](https://stackoverflow.com/questions/33644499/what-does-it-mean-when-they-say-react-is-xss-protected). Keep them in mind when writing or reviewing the code. <!-- markdown-link-check-disable-line -->
35+
- Enable the `Content-security-policy` header for all new micro frontends to ensure in-depth XSS prevention. Do not allow for `unsafe-eval` policy.
36+
37+
### Running Tests
38+
39+
For information on how to run and configure tests, go to the [`tests`](../../tests) directory.

‎docs/contributor/troubleshooting.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Troubleshooting
2+
3+
> [!TIP]
4+
> To solve most of the problems with Busola development, clear the browser cache or do a hard refresh of the website.
5+
6+
## HTTP Status Codes
7+
8+
All HTTP response codes are forwarded directly from the [Kubernetes API](https://kubernetes.io/docs/concepts/overview/kubernetes-api/).
9+
The only exceptions are:
10+
11+
- `400` when the request is invalid. The response contains a reason
12+
- `502` when the backend gets the `503` response code from the Kubernetes API
13+
- `502` when something unexpected happened when forwarding the request. The response contains the request ID, which can help you find the root cause in the backend logs
14+
15+
## Connectivity Issues with Busola Against a k3d Cluster
16+
17+
### Symptom
18+
19+
You are experiencing connectivity problems with Busola in Docker against a k3d cluster.
20+
21+
### Cause
22+
23+
When the k3d cluster's API Server is exposed on the `0.0.0.0` address on your machine, Busola in Docker interprets `0.0.0.0` as its internal Docker address, routing the requests to the wrong endpoint.
24+
25+
### Solution
26+
27+
- 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`, which is resolved to a "routable" IP address of a Docker Desktop virtual machine.
28+
29+
```bash
30+
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
31+
```
32+
33+
- For Linux, run Busola with `--net=host` (omitting the `-p` parameter).
34+
35+
```bash
36+
docker run --rm -it --net=host --pid=host --name busola europe-docker.pkg.dev/kyma-project/prod/busola:latest
37+
```
38+
39+
## SSL Certificate Issue While Connecting to the API Server
40+
41+
### Symptom
42+
43+
When you run Busola in Docker on macOS, it can't connect to the k3d cluster. The container log contains the following errors:
44+
45+
```
46+
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
47+
```
48+
49+
### Cause
50+
51+
Busola run in a Docker container with the environment variable `DOCKER_DESKTOP_CLUSTER=true` replaces the IP `0.0.0.0` in the API Server URL with `host.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.
52+
53+
Furthermore, this behavior has changed in the recent k3d versions, which is a result of [this fix](https://github.com/k3s-io/k3s/commit/aa76942d0fcb23dd02c25aa7a0dfb96b6b915fa5) for [this security issue](https://github.com/k3s-io/k3s/security/advisories/GHSA-m4hf-6vgr-75r2).
54+
55+
Clusters created by [k3d](https://k3d.io/) use a [listener](https://github.com/rancher/dynamiclistener) that extracts [SNI](https://en.wikipedia.org/wiki/Server_Name_Indication) 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 the `host.docker.internal` case.
56+
57+
### Solution
58+
59+
Provide the `host.docker.internal` host name upfront during [k3d](https://k3d.io/) cluster creation:
60+
61+
```
62+
k3d cluster create kyma --k3s-arg '--tls-san=host.docker.internal@server:*'
63+
```
64+
65+
A cluster created in such a way has the `host.docker.internal` set as Subject Alternative Name in the SSL Certificate of the API Server since the very beginning.

‎docs/features.md‎

Lines changed: 79 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,24 @@
1-
---
2-
title: Feature flags
3-
---
1+
# Feature Flags
42

5-
The document explains the usage of feature flags in Busola, lists and describes all the available feature flags, and provides their configuration examples:
3+
The document explains the usage of feature flags in Busola, lists and describes all the available feature flags, and provides their configuration examples.
64

7-
#### Features priority
5+
## Features priority
86

97
Initialisation of the Busola features is based on the `stage` property, which can take one of the following values:
108

119
- `PRIMARY` - the feature is resolved while the application bootstraps. Features that should be immediately visible must be set as `PRIMARY` (for example, main navigation structure).
1210
- `SECONDARY` - the feature is resolved after the application is ready, it must be used for non-critical features (for example, additional navigation nodes).
1311

14-
If the stage is not set, the feature is loaded only on-demand, most often by the iframe. Use the `useFeature` hook to request usage of such feature.
12+
If the stage is not set, the feature is loaded only on demand, most often by the iframe. Use the `useFeature` hook to request usage of such a feature.
1513

16-
Note that some features must be run before the application starts the bootstrap process, so they are out of the normal feature flow.
14+
> [!NOTE]
15+
> Some features must be run before the application starts the bootstrap process, so they are out of the normal feature flow.
1716
18-
#### Features list
17+
## Features List for Frontend
1918

2019
> **TIP:** The list is ordered alphabetically.
2120
22-
- **API_GATEWAY** – is used to show or hide the **API Gateway** view and to define which APIs are required for the view to be shown properly.
23-
It is also used to determine if the **API Gateway** list should be displayed in the **Function** and **Service** details.
24-
For the view to be shown, you must enable the feature. Moreover, all the APIs listed in the selectors array must be available in a cluster.
25-
26-
Default settings:
27-
28-
```yaml
29-
API_GATEWAY:
30-
isEnabled: true
31-
selectors:
32-
- type: apiGroup
33-
apiGroup: gateway.kyma-project.io
34-
```
35-
36-
- **EVENTING** – is used to show or hide the **Eventing** view and to define which APIs are required for the view to be shown properly.
37-
It is also used to determine if the **EventSubscriptions** should be displayed in **Function** and **Service** details.
38-
For the view to be shown, you must enable the feature. Moreover, all the APIs listed in the selectors array must be available in a cluster.
39-
40-
Default settings:
41-
42-
```yaml
43-
EVENTING:
44-
isEnabled: true
45-
selectors:
46-
- type: apiGroup
47-
apiGroup: eventing.kyma-project.io
48-
```
49-
50-
- **EXTENSIBILITY** - is used to indicate whether the Busola [extensibility](extensibility/README.md) feature should be enabled.
21+
- **EXTENSIBILITY** - is used to indicate whether the Busola [extensibility](extensibility/README.md) feature is enabled.
5122

5223
Default settings:
5324

@@ -56,7 +27,7 @@ EXTENSIBILITY:
5627
isEnabled: true
5728
```
5829
59-
- **EXTENSIBILITY_CUSTOM_COMPONENTS** - is used to indicate whether entirely custom extensions can be added to Busola. See [this example](../examples/custom-extension/README.md).
30+
- **EXTENSIBILITY_CUSTOM_COMPONENTS** - is used to indicate whether entire custom extensions can be added to Busola. See [this example](../examples/custom-extension/README.md).
6031
6132
Default settings:
6233
@@ -65,6 +36,15 @@ EXTENSIBILITY_CUSTOM_COMPONENTS:
6536
isEnabled: false
6637
```
6738
39+
- **EXTENSIBILITY_INJECTIONS** - is used to indicate whether extensibility injections can be added to Busola. For more information, see [Widget Injection](https://github.com/kyma-project/busola/blob/main/docs/extensibility/70-widget-injection.md).
40+
41+
Default settings:
42+
43+
```yaml
44+
EXTENSIBILITY_INJECTIONS:
45+
isEnabled: true
46+
```
47+
6848
- **EXTERNAL_NODES** - a list of links to external websites. `category`: a category name, `icon`: an optional icon, `scope`: either `namespace` or `cluster` (defaults to `cluster`), `children`: a list of pairs (label and link).
6949

7050
Default settings:
@@ -82,15 +62,15 @@ EXTENSIBILITY_CUSTOM_COMPONENTS:
8262
link: https://github.com/kyma-project/busola
8363
```
8464

85-
- **GARDENER_LOGIN** - is used to enable or disable the option of logging in with the Gardener kubeconfig. If enabled, you must set the **kubeconfig** parameter to a valid kubeconfig object.
65+
- **FEEDBACK** - determines if the feedback icon with the link redirecting the user to the survey should be rendered at the top bar.
8666

87-
Default settings:
67+
Default settings:
8868

89-
```yaml
90-
GARDENER_LOGIN:
91-
isEnabled: false
92-
kubeconfig: null
93-
```
69+
```yaml
70+
FEEDBACK:
71+
isEnabled: true
72+
link: https://www.youtube.com/watch?v=dQw4w9WgXcQ
73+
```
9474

9575
- **GET_HELP_LINKS** – is used to show or hide helper links. You can find all the available links in the following example.
9676
In **config**, you can find the unchangeable keys (for example, you cannot use **helpSapCom** instead of **help-sap-com**). The keys include the default link, which takes you to the default address.
@@ -106,17 +86,6 @@ GARDENER_LOGIN:
10686
default: https://help.sap.com
10787
```
10888

109-
* **GZIP** – is used to indicate whether a response from the backend server should be compressed or not.
110-
111-
> **NOTE:** It's a backend feature, so it cannot be modified at the cluster's ConfigMap level.
112-
113-
Default settings:
114-
115-
```yaml
116-
GZIP:
117-
isEnabled: true
118-
```
119-
12089
- **HIDDEN_NAMESPACES** – is used to define a list of Namespaces that are considered system, and are hidden by default.
12190

12291
Default settings:
@@ -142,7 +111,16 @@ HIDDEN_NAMESPACES:
142111
apiGroup: networking.istio.io
143112
```
144113

145-
* **KUBECONFIG_ID** – is used to configure the URL to which Busola sends a request to download a kubeconfig file. If you add `?kubeconfigID={your ID}` to the Busola URL, Busola tries to download the kubeconfig from `{kubeconfigUrl}/{yourID}`. If the operation succeeds, Busola adds the kubeconfing file to the cluster.
114+
- **KYMA_COMPANION** - determines if the Kyma Companion chat window is available in Busola.
115+
116+
Default settings:
117+
118+
```yaml
119+
KYMA_COMPANION:
120+
isEnabled: false
121+
```
122+
123+
- **KUBECONFIG_ID** – is used to configure the URL to which Busola sends a request to download a kubeconfig file. If you add `?kubeconfigID={your ID}` to the Busola URL, Busola tries to download the kubeconfig from `{kubeconfigUrl}/{yourID}`. If the operation succeeds, Busola adds the kubeconfing file to the cluster.
146124
If you use a full address in the **kubeconfigUrl** field, Busola also reads it.
147125

148126
- **showClustersOverview** - optional configuration to instruct Busola to show **Clusters Overview** rather than the current context cluster, after the clusters are loaded.
@@ -160,7 +138,7 @@ HIDDEN_NAMESPACES:
160138
defaultKubeconfig: AAAAA-BBBBB
161139
```
162140

163-
* **LEGAL_LINKS** – is used to show or hide legal links. You can find the all available links in the following example.
141+
- **LEGAL_LINKS** – is used to show or hide legal links. You can find all the available links in the following example.
164142
In **config** you can find the unchangeable keys (you cannot use **legalDisclosure** instead of **legal-disclosure**). The keys include both the default link, which takes you to the default address, and a link that depends on your chosen language.
165143

166144
Example:
@@ -219,14 +197,25 @@ HIDDEN_NAMESPACES:
219197

220198
The **match** keys and **messageSrc** must use the format described in the [`jsonpath` repository](https://github.com/dchester/jsonpath).
221199

200+
- **RESOURCE_VALIDATION** - determines the selected policies for [resource validation](resource-validation/README.md). They can be overwritten in the user preferences.
201+
202+
Default settings:
203+
204+
```yaml
205+
RESOURCE_VALIDATION:
206+
isEnabled: true
207+
config:
208+
policies:
209+
- Default
210+
```
211+
222212
- **SENTRY** – is used to enable monitoring of uncaught exceptions, which then are analyzed and repaired. The address to which you send the information is located under the **dsn** key.
223213

224214
Default settings:
225215

226216
```yaml
227217
SENTRY:
228218
isEnabled: false
229-
selectors: []
230219
config:
231220
dsn: ''
232221
```
@@ -245,14 +234,24 @@ The **match** keys and **messageSrc** must use the format described in the [`jso
245234
isEnabled: true
246235
```
247236

237+
- **SNOW** - determines if the snow animation is enabled in Busola.
238+
239+
Default settings:
240+
241+
```yaml
242+
SNOW:
243+
isEnabled: false
244+
```
245+
248246
- **TRACKING** - determines if simple application usage tracking is enabled.
249247

250248
```yaml
251249
TRACKING:
252250
isEnabled: false
253251
```
254252

255-
> NOTE: Enable this feature on the frontend and backend.
253+
> [!NOTE]
254+
> This feature is enabled on the frontend and backend.
256255

257256
* **VISUAL_RESOURCES** – determines if the resource graphs should be rendered at the resource details view.
258257

@@ -261,33 +260,35 @@ The **match** keys and **messageSrc** must use the format described in the [`jso
261260
isEnabled: true
262261
```
263262

264-
- **RESOURCE_VALIDATION** - determines the selected policies for [resource validation](resource-validation/README.md). They can be overwritten in the user preferences.
263+
## Features List for Backend
265264

266-
Default settings:
265+
> [!NOTE]
266+
> Backend features cannot be modified at the cluster's ConfigMap level.
267267

268-
```yaml
269-
RESOURCE_VALIDATION:
270-
isEnabled: true
271-
config:
272-
policies:
273-
- Default
274-
```
268+
- **GZIP** – is used to indicate whether a response from the backend server should be compressed or not.
269+
270+
Default settings:
271+
272+
```yaml
273+
GZIP:
274+
isEnabled: true
275+
```
275276

276-
- **CLUSTER_VALIDATION** - determines whether the Cluster Validation panel for scanning the cluster should be enabled in the Cluster Overview page. The scan uses the [resource validation](resource-validation/README.md) rules.
277+
- **KYMA_COMPANION** - is used to configure the location of the Kyma companion API.
277278

278279
Default settings:
279280

280281
```yaml
281-
CLUSTER_VALIDATION:
282-
isEnabled: false
282+
KYMA_COMPANION:
283+
link: ''
283284
```
284285

285-
- **FEEDBACK** - determines if the feedback icon with the link redirecting the user to the survey should be rendered at the top bar
286-
287-
Default settings:
286+
- **TRACKING** - determines if simple application usage tracking is enabled.
288287

289288
```yaml
290-
FEEDBACK:
291-
isEnabled: true
292-
link: https://www.youtube.com/watch?v=dQw4w9WgXcQ
289+
TRACKING:
290+
isEnabled: false
293291
```
292+
293+
> [!NOTE]
294+
> This feature is enabled on the frontend and backend.

‎docs/operator/assets/busola_kubernetes_3.svg‎

Lines changed: 4 additions & 0 deletions
Loading

0 commit comments

Comments
 (0)