Skip to content

Commit 56d846b

Browse files
joaquimrochajoaquimrocha
authored
Merge pull request #2705 from headlamp-k8s/helm-docs-refactor
charts: Reorganize and Enhance the Structure
2 parents 1888f9f + bd59781 commit 56d846b

File tree

1 file changed

+210
-62
lines changed

1 file changed

+210
-62
lines changed

‎charts/headlamp/README.md‎

Lines changed: 210 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -1,83 +1,231 @@
1-
# headlamp
1+
# Headlamp Helm Chart
22

3-
Headlamp is an easy-to-use and extensible Kubernetes web UI.
3+
Headlamp is an easy-to-use and extensible Kubernetes web UI that provides:
4+
- 🚀 Modern, fast, and responsive interface
5+
- 🔒 OIDC authentication support
6+
- 🔌 Plugin system for extensibility
7+
- 🎯 Real-time cluster state updates
48

5-
**Homepage:** <https://github.com/headlamp-k8s/headlamp/tree/main/charts/headlamp>
9+
## Prerequisites
610

7-
## TL;DR
11+
- Kubernetes 1.21+
12+
- Helm 3.x
13+
- Cluster admin access for initial setup
14+
15+
## Quick Start
16+
17+
Add the Headlamp repository and install the chart:
818

919
```console
1020
$ helm repo add headlamp https://headlamp-k8s.github.io/headlamp/
21+
$ helm repo update
1122
$ helm install my-headlamp headlamp/headlamp --namespace kube-system
1223
```
1324

25+
Access Headlamp:
26+
```console
27+
$ kubectl port-forward -n kube-system svc/my-headlamp 8080:80
28+
```
29+
Then open http://localhost:8080 in your browser.
30+
31+
## Installation
32+
33+
### Basic Installation
34+
```console
35+
$ helm install my-headlamp headlamp/headlamp --namespace kube-system
36+
```
37+
38+
### Installation with OIDC
39+
```console
40+
$ helm install my-headlamp headlamp/headlamp \
41+
--namespace kube-system \
42+
--set config.oidc.clientID=your-client-id \
43+
--set config.oidc.clientSecret=your-client-secret \
44+
--set config.oidc.issuerURL=https://your-issuer-url
45+
```
46+
47+
### Installation with Ingress
48+
```console
49+
$ helm install my-headlamp headlamp/headlamp \
50+
--namespace kube-system \
51+
--set ingress.enabled=true \
52+
--set ingress.hosts[0].host=headlamp.example.com \
53+
--set ingress.hosts[0].paths[0].path=/
54+
```
55+
56+
## Configuration
57+
58+
### Core Parameters
59+
60+
| Key | Type | Default | Description |
61+
|-----|------|---------|-------------|
62+
| replicaCount | int | `1` | Number of desired pods |
63+
| image.registry | string | `"ghcr.io"` | Container image registry |
64+
| image.repository | string | `"headlamp-k8s/headlamp"` | Container image name |
65+
| image.tag | string | `""` | Container image tag (defaults to Chart appVersion) |
66+
| image.pullPolicy | string | `"IfNotPresent"` | Image pull policy |
67+
68+
### Application Configuration
69+
70+
| Key | Type | Default | Description |
71+
|-----|------|---------|-------------|
72+
| config.baseURL | string | `""` | Base URL path for Headlamp UI |
73+
| config.pluginsDir | string | `"/headlamp/plugins"` | Directory to load Headlamp plugins from |
74+
| config.extraArgs | array | `[]` | Additional arguments for Headlamp server |
75+
76+
### OIDC Configuration
77+
78+
| Key | Type | Default | Description |
79+
|-----|------|---------|-------------|
80+
| config.oidc.clientID | string | `""` | OIDC client ID |
81+
| config.oidc.clientSecret | string | `""` | OIDC client secret |
82+
| config.oidc.issuerURL | string | `""` | OIDC issuer URL |
83+
| config.oidc.scopes | string | `""` | OIDC scopes to be used |
84+
| config.oidc.secret.create | bool | `true` | Create OIDC secret using provided values |
85+
| config.oidc.secret.name | string | `"oidc"` | Name of the OIDC secret |
86+
| config.oidc.externalSecret.enabled | bool | `false` | Enable using external secret for OIDC |
87+
| config.oidc.externalSecret.name | string | `""` | Name of external OIDC secret |
1488

15-
## Maintainers
89+
There are three ways to configure OIDC:
1690

17-
See [MAINTAINERS.md](https://github.com/headlamp-k8s/headlamp/blob/main/MAINTAINERS.md) in the headlamp github repo.
91+
1. Using direct configuration:
92+
```yaml
93+
config:
94+
oidc:
95+
clientID: "your-client-id"
96+
clientSecret: "your-client-secret"
97+
issuerURL: "https://your-issuer"
98+
scopes: "openid profile email"
99+
```
18100
19-
## Source Code
101+
2. Using automatic secret creation:
102+
```yaml
103+
config:
104+
oidc:
105+
secret:
106+
create: true
107+
name: oidc
108+
```
20109
21-
* <https://github.com/headlamp-k8s/headlamp>
22-
* <https://headlamp.dev/>
110+
3. Using external secret:
111+
```yaml
112+
config:
113+
oidc:
114+
secret:
115+
create: false
116+
externalSecret:
117+
enabled: true
118+
name: your-oidc-secret
119+
```
23120
24-
### Headlamp parameters
121+
### Deployment Configuration
25122
26123
| Key | Type | Default | Description |
27124
|-----|------|---------|-------------|
28-
| affinity | object | `{}` | Affinity settings for pod assignment |
29-
| clusterRoleBinding.annotations | object | `{}` | Annotations to add to the cluster role binding |
30-
| clusterRoleBinding.create | bool | `true` | Specified whether a cluster role binding should be created |
31-
| clusterRoleBinding.clusterRoleName| string | `cluster-admin` | Kubernetes ClusterRole name |
32-
| env | list | `[]` | An optional list of environment variables |
33-
| fullnameOverride | string | `""` | Overrides the full name of the chart |
34-
| image.pullPolicy | string | `"IfNotPresent"` | Image pull policy. One of Always, Never, IfNotPresent |
125+
| replicaCount | int | `1` | Number of desired pods |
35126
| image.registry | string | `"ghcr.io"` | Container image registry |
36127
| image.repository | string | `"headlamp-k8s/headlamp"` | Container image name |
37-
| image.tag | string | `""` | Container image tag, If "" uses appVersion in Chart.yaml |
38-
| imagePullSecrets | list | `[]` | An optional list of references to secrets in the same namespace to use for pulling any of the images used |
39-
| ingress.annotations | object | `{}` | Annotations for Ingress resource |
40-
| ingress.enabled | bool | `false` | Enable ingress controller resource |
41-
| ingress.ingressClassName | string | `""` | The ingress class name. Replacement for the deprecated "kubernetes.io/ingress.class" annotation |
42-
| ingress.hosts | list | `[]` | Hostname(s) for the Ingress resource |
128+
| image.tag | string | `""` | Container image tag (defaults to Chart appVersion) |
129+
| image.pullPolicy | string | `"IfNotPresent"` | Image pull policy |
130+
| imagePullSecrets | list | `[]` | Image pull secrets references |
131+
| nameOverride | string | `""` | Override the name of the chart |
132+
| fullnameOverride | string | `""` | Override the full name of the chart |
133+
| initContainers | list | `[]` | Init containers to run before main container |
134+
135+
### Security Configuration
136+
137+
| Key | Type | Default | Description |
138+
|-----|------|---------|-------------|
139+
| serviceAccount.create | bool | `true` | Create service account |
140+
| serviceAccount.name | string | `""` | Service account name |
141+
| serviceAccount.annotations | object | `{}` | Service account annotations |
142+
| clusterRoleBinding.create | bool | `true` | Create cluster role binding |
143+
| clusterRoleBinding.clusterRoleName | string | `"cluster-admin"` | Kubernetes ClusterRole name |
144+
| clusterRoleBinding.annotations | object | `{}` | Cluster role binding annotations |
145+
| podSecurityContext | object | `{}` | Pod security context (e.g., fsGroup: 2000) |
146+
| securityContext.runAsNonRoot | bool | `true` | Run container as non-root |
147+
| securityContext.privileged | bool | `false` | Run container in privileged mode |
148+
| securityContext.runAsUser | int | `100` | User ID to run container |
149+
| securityContext.runAsGroup | int | `101` | Group ID to run container |
150+
| securityContext.capabilities | object | `{}` | Container capabilities (e.g., drop: [ALL]) |
151+
| securityContext.readOnlyRootFilesystem | bool | `false` | Mount root filesystem as read-only |
152+
153+
### Storage Configuration
154+
155+
| Key | Type | Default | Description |
156+
|-----|------|---------|-------------|
157+
| persistentVolumeClaim.enabled | bool | `false` | Enable PVC |
158+
| persistentVolumeClaim.annotations | object | `{}` | PVC annotations |
159+
| persistentVolumeClaim.size | string | `""` | PVC size (required if enabled) |
160+
| persistentVolumeClaim.storageClassName | string | `""` | Storage class name |
161+
| persistentVolumeClaim.accessModes | list | `[]` | PVC access modes |
162+
| persistentVolumeClaim.selector | object | `{}` | PVC selector |
163+
| persistentVolumeClaim.volumeMode | string | `""` | PVC volume mode |
164+
| volumeMounts | list | `[]` | Container volume mounts |
165+
| volumes | list | `[]` | Pod volumes |
166+
167+
### Network Configuration
168+
169+
| Key | Type | Default | Description |
170+
|-----|------|---------|-------------|
171+
| service.type | string | `"ClusterIP"` | Kubernetes service type |
172+
| service.port | int | `80` | Kubernetes service port |
173+
| ingress.enabled | bool | `false` | Enable ingress |
174+
| ingress.className | string | `""` | Ingress class name |
175+
| ingress.annotations | object | `{}` | Ingress annotations (e.g., kubernetes.io/tls-acme: "true") |
176+
| ingress.hosts | list | `[]` | Ingress hosts configuration |
43177
| ingress.tls | list | `[]` | Ingress TLS configuration |
44-
| initContainers | list | `[]` | An optional list of init containers to be run before the main containers. |
45-
| nameOverride | string | `""` | Overrides the name of the chart |
178+
179+
Example ingress configuration:
180+
```yaml
181+
ingress:
182+
enabled: true
183+
annotations:
184+
kubernetes.io/tls-acme: "true"
185+
hosts:
186+
- host: headlamp.example.com
187+
paths:
188+
- path: /
189+
type: ImplementationSpecific
190+
tls:
191+
- secretName: headlamp-tls
192+
hosts:
193+
- headlamp.example.com
194+
```
195+
196+
### Resource Management
197+
198+
| Key | Type | Default | Description |
199+
|-----|------|---------|-------------|
200+
| resources | object | `{}` | Container resource requests/limits |
46201
| nodeSelector | object | `{}` | Node labels for pod assignment |
47-
| persistentVolumeClaim.accessModes | list | `[]` | accessModes for the persistent volume claim, eg: ReadWriteOnce, ReadOnlyMany, ReadWriteMany etc. |
48-
| persistentVolumeClaim.annotations | object | `{}` | Annotations to add to the persistent volume claim (if enabled) |
49-
| persistentVolumeClaim.enabled | bool | `false` | Enable Persistent Volume Claim |
50-
| persistentVolumeClaim.selector | object | `{}` | selector for the persistent volume claim. |
51-
| persistentVolumeClaim.size | string | `""` | size of the persistent volume claim, eg: 10Gi. Required if enabled is true. |
52-
| persistentVolumeClaim.storageClassName | string | `""` | storageClassName for the persistent volume claim. |
53-
| persistentVolumeClaim.volumeMode | string | `""` | volumeMode for the persistent volume claim, eg: Filesystem, Block. |
54-
| podAnnotations | object | `{}` | Annotations to add to the pod |
55-
| podSecurityContext | object | `{}` | Headlamp pod's Security Context |
56-
| replicaCount | int | `1` | Number of desired pods |
57-
| resources | object | `{}` | CPU/Memory resource requests/limits |
58-
| securityContext | object | `{}` | Headlamp containers Security Context |
59-
| service.port | int | `80` | Kubernetes Service port |
60-
| service.type | string | `"ClusterIP"` | Kubernetes Service type |
61-
| serviceAccount.annotations | object | `{}` | Annotations to add to the service account |
62-
| serviceAccount.create | bool | `true` | Specifies whether a service account should be created |
63-
| serviceAccount.name | string | `""` | The name of the service account to use.(If not set and create is true, a name is generated using the fullname template) |
64-
| tolerations | list | `[]` | Toleration labels for pod assignment |
65-
| volumeMounts | list | `[]` | Headlamp containers volume mounts |
66-
| volumes | list | `[]` | Headlamp pod's volumes |
67-
68-
69-
### Headlamp Configuration
70-
71-
| Key | Type | Default | Description |
72-
|------------------------------------|--------|-----------------------|-------------------------------------------------------------------------------------------------------|
73-
| config.baseURL | string | `""` | base url path at which headlamp should run |
74-
| config.oidc.clientID | string | `""` | OIDC client ID |
75-
| config.oidc.clientSecret | string | `""` | OIDC client secret |
76-
| config.oidc.issuerURL | string | `""` | OIDC issuer URL |
77-
| config.oidc.scopes | string | `""` | OIDC scopes to be used |
78-
| config.oidc.secret.create | bool | `true` | Enable this option to have the chart automatically create the OIDC secret using the specified values. |
79-
| config.oidc.secret.name | string | `oidc` | Name of the OIDC secret used by headlamp |
80-
| config.oidc.externalSecret.enabled | bool | `false` | Enable this option if you want to use an external secret for OIDC configuration. |
81-
| config.oidc.externalSecret.name | string | `""` | Name of the external OIDC secret to be used by headlamp. |
82-
| config.pluginsDir | string | `"/headlamp/plugins"` | directory to look for plugins |
83-
| config.extraArgs | array | `[]` | Extra arguments that can be given to the container |
202+
| tolerations | list | `[]` | Pod tolerations |
203+
| affinity | object | `{}` | Pod affinity settings |
204+
| podAnnotations | object | `{}` | Pod annotations |
205+
| env | list | `[]` | Additional environment variables |
206+
207+
Example resource configuration:
208+
```yaml
209+
resources:
210+
limits:
211+
cpu: 100m
212+
memory: 128Mi
213+
requests:
214+
cpu: 100m
215+
memory: 128Mi
216+
```
217+
218+
Example environment variables:
219+
```yaml
220+
env:
221+
- name: KUBERNETES_SERVICE_HOST
222+
value: "localhost"
223+
- name: KUBERNETES_SERVICE_PORT
224+
value: "6443"
225+
```
226+
227+
## Links
228+
229+
- [GitHub Repository](https://github.com/headlamp-k8s/headlamp)
230+
- [Documentation](https://headlamp.dev/)
231+
- [Maintainers](https://github.com/headlamp-k8s/headlamp/blob/main/MAINTAINERS.md)

0 commit comments

Comments
 (0)