Skip to content

Commit 9e1be01

Browse files
kvapskvaps
authored
docs(storage): add LINSTOR GUI documentation (#521)
## Summary - New page `linstor-gui.md` in both `v1.3/storage/` and `next/storage/` - Covers: what linstor-gui is (LINBIT's web UI proxying the LINSTOR controller REST API over mTLS), how to enable it, and two access methods: - Ingress (requires OIDC enabled; restricted to `cozystack-cluster-admin` group) - Port-forward fallback (`kubectl -n cozy-linstor port-forward svc/linstor-gui 3373:80`) ## Test plan - [ ] Netlify deploy preview renders linstor-gui.md correctly for both `/docs/v1.3/` and `/docs/next/` - [ ] Page appears in storage section nav with correct weight (40) 🤖 Generated with [Claude Code](https://claude.com/claude-code)
2 parents 5c30552 + 60deb84 commit 9e1be01

2 files changed

Lines changed: 124 additions & 0 deletions

File tree

‎content/en/docs/next/storage/linstor-gui.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
title: "LINSTOR GUI"
3+
linkTitle: "LINSTOR GUI"
4+
description: "Enable and access the optional LINSTOR web console for managing storage nodes, resources, and volumes."
5+
weight: 40
6+
aliases:
7+
- /docs/next/operations/storage/linstor-gui
8+
---
9+
10+
The `linstor-gui` package deploys [LINBIT's LINSTOR GUI](https://github.com/LINBIT/linstor-gui) — a web console
11+
for browsing and managing LINSTOR nodes, resource definitions, volumes, storage pools, and snapshots.
12+
The UI proxies the LINSTOR controller REST API in-cluster using mTLS, so no credentials are ever exposed in the browser.
13+
14+
The package is **opt-in**. The CLI workflow is unchanged — enabling the GUI does not affect any LINSTOR behaviour.
15+
16+
## Enable the package
17+
18+
Add `cozystack.linstor-gui` to `bundles.enabledPackages` in the [Platform Package]({{% ref "/docs/next/operations/configuration/platform-package" %}}):
19+
20+
```bash
21+
kubectl patch packages.cozystack.io cozystack.cozystack-platform --type=json \
22+
-p '[{"op": "add", "path": "/spec/components/platform/values/bundles/enabledPackages/-", "value": "cozystack.linstor-gui"}]'
23+
```
24+
25+
Wait a minute for the platform chart to reconcile, then verify the HelmRelease has been created:
26+
27+
```bash
28+
kubectl get helmrelease --namespace cozy-linstor linstor-gui
29+
```
30+
31+
## Access the UI
32+
33+
### Option 1 — Keycloak-protected Ingress (recommended)
34+
35+
When [OIDC authentication]({{% ref "/docs/next/operations/oidc" %}}) is enabled, you can publish the UI at
36+
`https://linstor-gui.<root-host>` behind the cluster Keycloak realm.
37+
Add `linstor-gui` to `publishing.exposedServices` in the Platform Package:
38+
39+
```bash
40+
kubectl patch packages.cozystack.io cozystack.cozystack-platform --type=json \
41+
-p '[{"op": "add", "path": "/spec/components/platform/values/publishing/exposedServices/-", "value": "linstor-gui"}]'
42+
```
43+
44+
{{% alert color="info" %}}
45+
The Ingress is only created when both conditions are met: `linstor-gui` is listed in `publishing.exposedServices`
46+
**and** OIDC is enabled (`authentication.oidc.enabled: true`). Without Keycloak there is no authentication
47+
layer in front of the LINSTOR REST API proxy, so the chart deliberately skips the Ingress.
48+
{{% /alert %}}
49+
50+
Access is restricted to members of the `cozystack-cluster-admin` Keycloak group — the same group that grants
51+
cluster-admin RBAC on the host cluster. Once enabled, open `https://linstor-gui.<root-host>` in your browser
52+
and log in with your Keycloak credentials.
53+
54+
### Option 2 — Port-forward
55+
56+
For ad-hoc access without Keycloak, forward the `ClusterIP` service:
57+
58+
```bash
59+
kubectl -n cozy-linstor port-forward svc/linstor-gui 3373:80
60+
```
61+
62+
Then open <http://localhost:3373>.

‎content/en/docs/v1.3/storage/linstor-gui.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
title: "LINSTOR GUI"
3+
linkTitle: "LINSTOR GUI"
4+
description: "Enable and access the optional LINSTOR web console for managing storage nodes, resources, and volumes."
5+
weight: 40
6+
aliases:
7+
- /docs/v1.3/operations/storage/linstor-gui
8+
---
9+
10+
The `linstor-gui` package deploys [LINBIT's LINSTOR GUI](https://github.com/LINBIT/linstor-gui) — a web console
11+
for browsing and managing LINSTOR nodes, resource definitions, volumes, storage pools, and snapshots.
12+
The UI proxies the LINSTOR controller REST API in-cluster using mTLS, so no credentials are ever exposed in the browser.
13+
14+
The package is **opt-in**. The CLI workflow is unchanged — enabling the GUI does not affect any LINSTOR behaviour.
15+
16+
## Enable the package
17+
18+
Add `cozystack.linstor-gui` to `bundles.enabledPackages` in the [Platform Package]({{% ref "/docs/v1.3/operations/configuration/platform-package" %}}):
19+
20+
```bash
21+
kubectl patch packages.cozystack.io cozystack.cozystack-platform --type=json \
22+
-p '[{"op": "add", "path": "/spec/components/platform/values/bundles/enabledPackages/-", "value": "cozystack.linstor-gui"}]'
23+
```
24+
25+
Wait a minute for the platform chart to reconcile, then verify the HelmRelease has been created:
26+
27+
```bash
28+
kubectl get helmrelease --namespace cozy-linstor linstor-gui
29+
```
30+
31+
## Access the UI
32+
33+
### Option 1 — Keycloak-protected Ingress (recommended)
34+
35+
When [OIDC authentication]({{% ref "/docs/v1.3/operations/oidc" %}}) is enabled, you can publish the UI at
36+
`https://linstor-gui.<root-host>` behind the cluster Keycloak realm.
37+
Add `linstor-gui` to `publishing.exposedServices` in the Platform Package:
38+
39+
```bash
40+
kubectl patch packages.cozystack.io cozystack.cozystack-platform --type=json \
41+
-p '[{"op": "add", "path": "/spec/components/platform/values/publishing/exposedServices/-", "value": "linstor-gui"}]'
42+
```
43+
44+
{{% alert color="info" %}}
45+
The Ingress is only created when both conditions are met: `linstor-gui` is listed in `publishing.exposedServices`
46+
**and** OIDC is enabled (`authentication.oidc.enabled: true`). Without Keycloak there is no authentication
47+
layer in front of the LINSTOR REST API proxy, so the chart deliberately skips the Ingress.
48+
{{% /alert %}}
49+
50+
Access is restricted to members of the `cozystack-cluster-admin` Keycloak group — the same group that grants
51+
cluster-admin RBAC on the host cluster. Once enabled, open `https://linstor-gui.<root-host>` in your browser
52+
and log in with your Keycloak credentials.
53+
54+
### Option 2 — Port-forward
55+
56+
For ad-hoc access without Keycloak, forward the `ClusterIP` service:
57+
58+
```bash
59+
kubectl -n cozy-linstor port-forward svc/linstor-gui 3373:80
60+
```
61+
62+
Then open <http://localhost:3373>.

0 commit comments

Comments
 (0)