Skip to content

Commit a7cd160

Browse files
TaylorMutchTaylorMutch
authored
docs(helm): add chart readme generation (#1437)
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
1 parent 3cd238a commit a7cd160

11 files changed

Lines changed: 330 additions & 59 deletions

File tree

‎.github/workflows/helm-lint.yml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,10 @@ on:
99
- "pull-request/[0-9]+"
1010
paths:
1111
- "deploy/helm/**"
12+
- "mise.toml"
13+
- "mise.lock"
14+
- "tasks/helm.toml"
15+
- ".github/workflows/helm-lint.yml"
1216
workflow_dispatch:
1317

1418
env:
@@ -56,5 +60,8 @@ jobs:
5660
- name: Lint Helm chart
5761
run: mise run helm:lint
5862

63+
- name: Check Helm chart README
64+
run: mise run helm:docs:check
65+
5966
- name: Run Helm chart unit tests
6067
run: mise run helm:test

‎CONTRIBUTING.md‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -174,15 +174,16 @@ openshell sandbox create -- codex
174174

175175
These are the primary `mise` tasks for day-to-day development:
176176

177-
| Task | Purpose |
178-
| ------------------ | ------------------------------------------------------- |
179-
| `mise run gateway` | Run a standalone gateway for local development |
180-
| `mise run sandbox` | Create or reconnect to the dev sandbox |
181-
| `mise run test` | Default test suite |
182-
| `mise run e2e` | Default end-to-end test lane |
183-
| `mise run ci` | Full local CI checks (lint, compile/type checks, tests) |
184-
| `mise run docs` | Validate Fern docs locally |
185-
| `mise run clean` | Clean build artifacts |
177+
| Task | Purpose |
178+
| -------------------- | ------------------------------------------------------- |
179+
| `mise run gateway` | Run a standalone gateway for local development |
180+
| `mise run sandbox` | Create or reconnect to the dev sandbox |
181+
| `mise run test` | Default test suite |
182+
| `mise run e2e` | Default end-to-end test lane |
183+
| `mise run ci` | Full local CI checks (lint, compile/type checks, tests) |
184+
| `mise run docs` | Validate Fern docs locally |
185+
| `mise run helm:docs` | Regenerate the Helm chart README |
186+
| `mise run clean` | Clean build artifacts |
186187

187188
## Project Structure
188189

‎deploy/docker/Dockerfile.ci‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
# SPDX-License-Identifier: Apache-2.0
55

66
# CI runner image with all development tools pre-installed
7-
# Rebuild triggered automatically when mise.toml or this file changes
7+
# Rebuild triggered automatically when mise.toml, mise.lock, tasks, or this file changes
88

99
FROM nvcr.io/nvidia/base/ubuntu:noble-20251013
1010

‎deploy/helm/openshell/.helmignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,5 +18,6 @@
1818
.vscode/
1919

2020
# Ignore development files
21+
README.md.gotmpl
2122
skaffold.yaml
2223
ci/

‎deploy/helm/openshell/README.md‎

Lines changed: 106 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,31 @@
11
# OpenShell Helm Chart
22

3-
> **Experimental** — the Kubernetes deployment path is under active development. Expect rough edges and breaking changes.
3+
<!--
4+
This file is generated by helm-docs.
5+
Edit README.md.gotmpl and values.yaml, then run `mise run helm:docs`.
6+
-->
7+
8+
> **Experimental** - the Kubernetes deployment path is under active development. Expect rough edges and breaking changes.
49
510
This chart deploys the OpenShell gateway into a Kubernetes cluster. It is published as an OCI artifact to GHCR at `oci://ghcr.io/nvidia/openshell/helm-chart`.
611

712
## Prerequisites
813

914
The Kubernetes Agent Sandbox CRDs and controller must be installed on the cluster before deploying OpenShell. Install them with:
1015

11-
```bash
16+
```shell
1217
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/latest/download/manifest.yaml
1318
```
1419

1520
## Install on Kubernetes
1621

17-
```bash
22+
```shell
1823
helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version>
1924
```
2025

2126
## Install on OpenShift
2227

23-
```bash
28+
```shell
2429
# Precreate the openshell namespace so we can create the SCC cluster role
2530
oc create ns openshell
2631

@@ -47,11 +52,11 @@ The `dev` tags are intended for testing changes ahead of a release. Production d
4752

4853
## Configuration
4954

50-
See [`values.yaml`](values.yaml) for configurable values. Selected overlays:
55+
See [`values.yaml`](values.yaml) for source defaults. Selected overlays:
5156

52-
- [`ci/values-gateway.yaml`](ci/values-gateway.yaml) — gateway-only configuration
53-
- [`ci/values-cert-manager.yaml`](ci/values-cert-manager.yaml) — cert-manager integration
54-
- [`ci/values-keycloak.yaml`](ci/values-keycloak.yaml) — Keycloak OIDC integration
57+
- [`ci/values-gateway.yaml`](ci/values-gateway.yaml) - gateway-only configuration
58+
- [`ci/values-cert-manager.yaml`](ci/values-cert-manager.yaml) - cert-manager integration
59+
- [`ci/values-keycloak.yaml`](ci/values-keycloak.yaml) - Keycloak OIDC integration
5560

5661
## PKI bootstrap
5762

@@ -62,11 +67,100 @@ openssl/alpine sidecar).
6267

6368
The Job is idempotent:
6469

65-
- Both target Secrets exist → log and exit 0.
66-
- Exactly one exists → fail with `kubectl delete secret -n <ns> <server> <client>` recovery hint.
67-
- Neither exists → generate a CA, server cert, and client cert; POST both `kubernetes.io/tls`
68-
Secrets (`tls.crt`, `tls.key`, `ca.crt`).
70+
- Both target Secrets exist: log and exit 0.
71+
- Exactly one exists: fail with `kubectl delete secret -n <ns> <server> <client>` recovery hint.
72+
- Neither exists: generate a CA, server cert, and client cert; POST both `kubernetes.io/tls` Secrets (`tls.crt`, `tls.key`, `ca.crt`).
6973

7074
Disable with `--set pkiInitJob.enabled=false` when bringing your own PKI (cert-manager,
7175
external CA, or pre-created Secrets). See `certManager.*` in `values.yaml` for the
7276
cert-manager alternative.
77+
78+
## Values
79+
80+
| Key | Type | Default | Description |
81+
|-----|------|---------|-------------|
82+
| affinity | object | `{}` | Affinity rules for the gateway pod. |
83+
| certManager.caSecretName | string | `"openshell-ca-tls"` | Secret created for the intermediate CA (Certificate with isCA: true). |
84+
| certManager.certificateDuration | string | `"8760h"` | Duration for cert-manager-issued certificates. |
85+
| certManager.certificateRenewBefore | string | `"720h"` | Renewal window for cert-manager-issued certificates. |
86+
| certManager.clientCaFromServerTlsSecret | bool | `true` | Mount gateway client CA from the server TLS secret's ca.crt (populated by cert-manager for certs issued by a CA Issuer). Avoids a separate openshell-server-client-ca Secret. |
87+
| certManager.enabled | bool | `false` | Create cert-manager Issuer and Certificate resources instead of using the PKI bootstrap Job. |
88+
| certManager.serverDnsNames | list | `["openshell","openshell.openshell.svc","openshell.openshell.svc.cluster.local","localhost","openshell.localhost","*.openshell.localhost","host.docker.internal"]` | DNS SANs on the cert-manager-issued server certificate. |
89+
| certManager.serverIpAddresses | list | `["127.0.0.1"]` | IP SANs on the cert-manager-issued server certificate. |
90+
| fullnameOverride | string | `""` | Override the full generated resource name. |
91+
| grpcRoute.enabled | bool | `false` | Create a Gateway API GRPCRoute for the gateway service. |
92+
| grpcRoute.gateway.className | string | `"eg"` | GatewayClass to reference. Envoy Gateway installs one named "eg". |
93+
| grpcRoute.gateway.create | bool | `false` | When true, a Gateway resource is created in the release namespace. Set to false and provide name/namespace to attach to a pre-existing Gateway. |
94+
| grpcRoute.gateway.listener.allowedRoutes | string | `"Same"` | "Same" restricts attached routes to the release namespace; "All" allows any namespace. |
95+
| grpcRoute.gateway.listener.port | int | `80` | Listener port for the generated Gateway resource. |
96+
| grpcRoute.gateway.listener.protocol | string | `"HTTP"` | Listener protocol for the generated Gateway resource. |
97+
| grpcRoute.gateway.name | string | `""` | Name of the Gateway resource. Defaults to the chart fullname. |
98+
| grpcRoute.gateway.namespace | string | `""` | Namespace of the Gateway referenced by the GRPCRoute parentRef. Defaults to the release namespace. |
99+
| grpcRoute.hostnames | list | `[]` | Hostnames the GRPCRoute matches on. Leave empty to match all hosts. |
100+
| image.pullPolicy | string | `"IfNotPresent"` | Gateway image pull policy. |
101+
| image.repository | string | `"ghcr.io/nvidia/openshell/gateway"` | Gateway image repository. |
102+
| image.tag | string | `""` | Gateway image tag. Defaults to the chart appVersion when empty. |
103+
| imagePullSecrets | list | `[]` | Image pull secrets attached to gateway and helper pods. |
104+
| nameOverride | string | `"openshell"` | Override the chart name used in generated resource names. |
105+
| networkPolicy.enabled | bool | `true` | Create a NetworkPolicy restricting SSH ingress on sandbox pods to the gateway. |
106+
| nodeSelector | object | `{}` | Node selector for the gateway pod. |
107+
| pkiInitJob.enabled | bool | `true` | Run a pre-install/pre-upgrade Job that creates gateway and client mTLS Secrets. |
108+
| pkiInitJob.serverDnsNames | list | `[]` | Extra DNS SANs to append to the server certificate. |
109+
| pkiInitJob.serverIpAddresses | list | `[]` | Extra IP SANs to append to the server certificate. |
110+
| podAnnotations | object | `{}` | Extra annotations to add to the gateway pod. |
111+
| podLabels | object | `{}` | Extra labels to add to the gateway pod. |
112+
| podLifecycle.terminationGracePeriodSeconds | int | `5` | Grace period, in seconds, before Kubernetes terminates the gateway pod. |
113+
| podSecurityContext.fsGroup | int | `1000` | fsGroup assigned to the gateway pod. |
114+
| probes.liveness.failureThreshold | int | `3` | Liveness probe failure threshold before the container is restarted. |
115+
| probes.liveness.initialDelaySeconds | int | `2` | Liveness probe initial delay, in seconds. |
116+
| probes.liveness.periodSeconds | int | `5` | Liveness probe period, in seconds. |
117+
| probes.liveness.timeoutSeconds | int | `1` | Liveness probe timeout, in seconds. |
118+
| probes.readiness.failureThreshold | int | `3` | Readiness probe failure threshold before the pod is marked not ready. |
119+
| probes.readiness.initialDelaySeconds | int | `1` | Readiness probe initial delay, in seconds. |
120+
| probes.readiness.periodSeconds | int | `2` | Readiness probe period, in seconds. |
121+
| probes.readiness.timeoutSeconds | int | `1` | Readiness probe timeout, in seconds. |
122+
| probes.startup.failureThreshold | int | `30` | Startup probe failure threshold before the container is killed. |
123+
| probes.startup.periodSeconds | int | `2` | Startup probe period, in seconds. |
124+
| probes.startup.timeoutSeconds | int | `1` | Startup probe timeout, in seconds. |
125+
| replicaCount | int | `1` | Number of OpenShell gateway replicas. |
126+
| resources | object | `{}` | Gateway pod resource requests and limits. |
127+
| securityContext.allowPrivilegeEscalation | bool | `false` | Whether the gateway container can gain additional privileges. |
128+
| securityContext.capabilities.drop | list | `["ALL"]` | Linux capabilities dropped from the gateway container. |
129+
| securityContext.runAsNonRoot | bool | `true` | Require the gateway container to run as a non-root user. |
130+
| securityContext.runAsUser | int | `1000` | UID assigned to the gateway container. |
131+
| server.dbUrl | string | `"sqlite:/var/openshell/openshell.db"` | Gateway database URL. |
132+
| server.disableTls | bool | `false` | Disable TLS entirely - the server listens on plaintext HTTP. Set to true when a reverse proxy / tunnel terminates TLS at the edge. |
133+
| server.enableLoopbackServiceHttp | bool | `true` | Enable plaintext HTTP routing for loopback sandbox service URLs on TLS-enabled gateways. |
134+
| server.enableUserNamespaces | bool | `false` | Enable Kubernetes user namespace isolation (hostUsers: false) for sandbox pods. Requires Kubernetes 1.33+ with user namespace support available (beta through 1.35, GA in 1.36+), plus a supporting container runtime and Linux 5.12+. When enabled, container UID 0 maps to an unprivileged host UID and capabilities become namespaced. |
135+
| server.grpcEndpoint | string | `""` | gRPC endpoint sandboxes call back into the gateway. Leave empty to derive it from the chart fullname, release namespace, service port, and disableTls flag, for example https://openshell.openshell.svc.cluster.local:8080. Override only when sandboxes must reach the gateway via a different hostname (e.g. an external ingress or a host alias). |
136+
| server.hostGatewayIP | string | `""` | Host gateway IP for sandbox pod hostAliases. When set, sandbox pods get hostAliases entries mapping host.docker.internal and host.openshell.internal to this IP, allowing them to reach services running on the Docker host. Auto-detected by the cluster entrypoint script. |
137+
| server.logLevel | string | `"info"` | Gateway log level. |
138+
| server.oidc.adminRole | string | `""` | Role name for admin access. Leave empty (with userRole also empty) for authentication-only mode. Both must be set or both empty. |
139+
| server.oidc.audience | string | `"openshell-cli"` | Expected audience claim for the API resource server. This should match the server's --oidc-audience, NOT the CLI client ID. |
140+
| server.oidc.caConfigMapName | string | `""` | Name of a ConfigMap containing a CA certificate bundle (key: ca.crt) for verifying the OIDC issuer's TLS certificate. Required when the issuer uses a non-public CA (e.g. OpenShift ingress, private PKI). |
141+
| server.oidc.issuer | string | `""` | OIDC issuer URL (e.g. https://keycloak.example.com/realms/openshell). |
142+
| server.oidc.jwksTtl | int | `3600` | JWKS key cache TTL in seconds. |
143+
| server.oidc.rolesClaim | string | `""` | Dot-separated path to the roles array in the JWT claims. Keycloak: "realm_access.roles", Entra ID: "roles", Okta: "groups". |
144+
| server.oidc.scopesClaim | string | `""` | Dot-separated path to the scopes array in the JWT claims. |
145+
| server.oidc.userRole | string | `""` | Role name for standard user access. |
146+
| server.sandboxImage | string | `"ghcr.io/nvidia/openshell-community/sandboxes/base:latest"` | Default sandbox image used when requests do not specify one. |
147+
| server.sandboxImagePullPolicy | string | `""` | Kubernetes imagePullPolicy for sandbox pods. Empty = Kubernetes default (Always for :latest, IfNotPresent otherwise). Set to "Always" for dev clusters so new images are picked up without manual eviction. |
148+
| server.sandboxNamespace | string | `""` | Namespace where sandbox pods are created. Defaults to the Helm release namespace (.Release.Namespace) when left empty. |
149+
| server.tls.certSecretName | string | `"openshell-server-tls"` | K8s secret (type kubernetes.io/tls) with tls.crt and tls.key for the server. |
150+
| server.tls.clientCaSecretName | string | `"openshell-server-client-ca"` | K8s secret with ca.crt for client certificate verification (mTLS). Set to "" to disable mTLS and run HTTPS-only (use OIDC for auth instead). |
151+
| server.tls.clientTlsSecretName | string | `"openshell-client-tls"` | K8s secret mounted into sandbox pods for mTLS to the server. |
152+
| service.healthPort | int | `8081` | Gateway health service port. |
153+
| service.metricsPort | int | `9090` | Gateway metrics service port. |
154+
| service.port | int | `8080` | Gateway gRPC/HTTP service port. |
155+
| service.type | string | `"ClusterIP"` | Kubernetes Service type for the gateway. |
156+
| serviceAccount.annotations | object | `{}` | Annotations to add to the generated service account. |
157+
| serviceAccount.create | bool | `true` | Create a service account for the gateway. |
158+
| serviceAccount.name | string | `""` | Existing service account name to use when serviceAccount.create is false. |
159+
| supervisor.image.pullPolicy | string | `""` | Supervisor image pull policy. Defaults to the gateway image pull policy when empty. |
160+
| supervisor.image.repository | string | `"ghcr.io/nvidia/openshell/supervisor"` | Supervisor image repository. |
161+
| supervisor.image.tag | string | `""` | Supervisor image tag. Defaults to the chart appVersion when empty. |
162+
| supervisor.sideloadMethod | string | `""` | How the supervisor binary is delivered into sandbox pods. Empty (default) = auto-detect from cluster version: K8s >= v1.35 -> "image-volume" (ImageVolume enabled by default; GA in v1.36) K8s < v1.35 -> "init-container" (copies via init container + emptyDir) On K8s v1.33-v1.34 with the ImageVolume feature gate manually enabled, set this to "image-volume" explicitly. |
163+
| tolerations | list | `[]` | Tolerations for the gateway pod. |
164+
165+
----------------------------------------------
166+
Autogenerated from chart metadata using [helm-docs v1.14.2](https://github.com/norwoodj/helm-docs/releases/v1.14.2)

‎deploy/helm/openshell/README.md.gotmpl‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# OpenShell Helm Chart
2+
3+
<!--
4+
This file is generated by helm-docs.
5+
Edit README.md.gotmpl and values.yaml, then run `mise run helm:docs`.
6+
-->
7+
8+
> **Experimental** - the Kubernetes deployment path is under active development. Expect rough edges and breaking changes.
9+
10+
This chart deploys the OpenShell gateway into a Kubernetes cluster. It is published as an OCI artifact to GHCR at `oci://ghcr.io/nvidia/openshell/helm-chart`.
11+
12+
## Prerequisites
13+
14+
The Kubernetes Agent Sandbox CRDs and controller must be installed on the cluster before deploying OpenShell. Install them with:
15+
16+
```shell
17+
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/latest/download/manifest.yaml
18+
```
19+
20+
## Install on Kubernetes
21+
22+
```shell
23+
helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version>
24+
```
25+
26+
## Install on OpenShift
27+
28+
```shell
29+
# Precreate the openshell namespace so we can create the SCC cluster role
30+
oc create ns openshell
31+
32+
# Sandboxes are deployed into the openshell namespace and use the default service account for now
33+
oc adm policy add-scc-to-user privileged -z default -n openshell
34+
35+
# Deploy openshell with overrides to allow SCC assignment of fsGroup and runAsUser for the gateway
36+
helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart --version <version> -n openshell \
37+
--set pkiInitJob.enabled=false \
38+
--set server.disableTls=true \
39+
--set podSecurityContext.fsGroup=null \
40+
--set securityContext.runAsUser=null
41+
```
42+
43+
## Available versions
44+
45+
| Tag | Source | Notes |
46+
| --- | --- | --- |
47+
| `<semver>` (e.g. `0.6.0`) | Tagged GitHub release | Tracks the matching gateway and supervisor image versions. Recommended for production. |
48+
| `0.0.0-dev` | Latest commit on `main` | Floating tag, overwritten on every push. `appVersion` is `dev`, so images resolve to the `:dev` tag. |
49+
| `0.0.0-dev.<commit-sha>` | A specific commit on `main` | Per-commit pin. Chart version and `appVersion` both use the full 40-character commit SHA, which matches the image tag pushed by CI. |
50+
51+
The `dev` tags are intended for testing changes ahead of a release. Production deployments should pin to a tagged release.
52+
53+
## Configuration
54+
55+
See [`values.yaml`](values.yaml) for source defaults. Selected overlays:
56+
57+
- [`ci/values-gateway.yaml`](ci/values-gateway.yaml) - gateway-only configuration
58+
- [`ci/values-cert-manager.yaml`](ci/values-cert-manager.yaml) - cert-manager integration
59+
- [`ci/values-keycloak.yaml`](ci/values-keycloak.yaml) - Keycloak OIDC integration
60+
61+
## PKI bootstrap
62+
63+
By default, a pre-install/pre-upgrade hook Job runs `openshell-gateway generate-certs`
64+
to create the gateway's server and client mTLS Secrets. The Job uses the gateway image
65+
itself, so air-gapped environments only need to mirror that one image (no separate
66+
openssl/alpine sidecar).
67+
68+
The Job is idempotent:
69+
70+
- Both target Secrets exist: log and exit 0.
71+
- Exactly one exists: fail with `kubectl delete secret -n <ns> <server> <client>` recovery hint.
72+
- Neither exists: generate a CA, server cert, and client cert; POST both `kubernetes.io/tls` Secrets (`tls.crt`, `tls.key`, `ca.crt`).
73+
74+
Disable with `--set pkiInitJob.enabled=false` when bringing your own PKI (cert-manager,
75+
external CA, or pre-created Secrets). See `certManager.*` in `values.yaml` for the
76+
cert-manager alternative.
77+
78+
{{ template "chart.valuesSection" . }}
79+
{{ template "helm-docs.versionFooter" . }}

0 commit comments

Comments
 (0)