From f98f77281e588762986b35be20479b199523981e Mon Sep 17 00:00:00 2001 From: spwoodcock Date: Mon, 2 Feb 2026 21:22:21 +0000 Subject: [PATCH] docs: restructure helm chart usage notes + examples --- chart/README.md | 102 ++++++++++++++++---------------------- chart/templates/NOTES.txt | 26 +++++++--- 2 files changed, 63 insertions(+), 65 deletions(-) diff --git a/chart/README.md b/chart/README.md index 5199ab9..9897258 100644 --- a/chart/README.md +++ b/chart/README.md @@ -2,49 +2,17 @@ Deploys **BentoPDF** as a **single NGINX container** serving the static frontend. -## Prereqs +## Quickstart -- Kubernetes cluster -- Helm v3 with OCI support -- An image that serves BentoPDF via nginx (default chart expects the repo image, which listens on **8080** inside the container) - -## Quickstart (ClusterIP + port-forward) +### Option 1: Port-forward (testing) ```bash helm install bentopdf ./chart - kubectl port-forward deploy/bentopdf 8080:8080 # open http://127.0.0.1:8080 ``` -## Configuration - -### Image - -- **`image.repository`**: container image repo (default `bentopdf/bentopdf`) -- **`image.tag`**: image tag (default: `Chart.appVersion`) -- **`image.pullPolicy`**: default `IfNotPresent` - -### Ports - -- **`containerPort`**: container listen port (**8080** for the BentoPDF nginx image) -- **`service.port`**: Service port exposed in-cluster (default **80**) - -### Environment variables - -Use **`env`** for the container. - -Example (IPv4-only environments): - -```yaml -env: - - name: DISABLE_IPV6 - value: "true" -``` - -### Ingress (optional) - -Enable the built-in Kubernetes Ingress: +### Option 2: Ingress ```yaml ingress: @@ -57,38 +25,56 @@ ingress: pathType: Prefix ``` -### Gateway API: Gateway + HTTPRoute (optional) - -This chart can optionally: - -- Create a **Gateway** (`gateway.enabled=true`) -- Create an **HTTPRoute** (`httpRoute.enabled=true`) that points at the chart Service - -If your cluster uses a shared Gateway created elsewhere, set `gateway.enabled=false` and point `httpRoute.parentRefs` to that Gateway. - -Example (create both Gateway + HTTPRoute): +### Option 3: Gateway API (Gateway + HTTPRoute) ```yaml gateway: enabled: true - gatewayClassName: cloudflare # or nginx, istio, etc (controller-specific) - listeners: - - name: http - protocol: HTTP - port: 80 + gatewayClassName: "cloudflare" # or your gateway class httpRoute: enabled: true hostnames: - - bentopdf.example.com + - pdfs.example.com +``` + +**Note:** Both Gateway and HTTPRoute default to the release namespace. Omit `namespace` fields to use the release namespace automatically. + +If you have an existing Gateway, set `gateway.enabled=false` and configure `httpRoute.parentRefs`: + +```yaml +gateway: + enabled: false + +httpRoute: + enabled: true parentRefs: - - name: "" # default: release fullname (or gateway.name if set) + - name: existing-gateway + namespace: gateway-namespace sectionName: http - rules: - - matches: - - path: - type: PathPrefix - value: / + hostnames: + - pdfs.example.com +``` + +## Configuration + +### Image + +- **`image.repository`**: container image repo (default: `ghcr.io/alam00000/bentopdf-simple`) +- **`image.tag`**: image tag (default: `Chart.appVersion`) +- **`image.pullPolicy`**: default `IfNotPresent` + +### Ports + +- **`containerPort`**: container listen port (**8080** for the BentoPDF nginx image) +- **`service.port`**: Service port exposed in-cluster (default **80**) + +### Environment Variables + +```yaml +env: + - name: DISABLE_IPV6 + value: "true" ``` ## Publish this chart to GHCR (OCI) for testing/deploying @@ -110,5 +96,5 @@ This could be automated as part of a Github workflow. ### Deploy ```bash -helm upgrade --install bentopdf oci://ghcr.io/$GHCR_USERNAME/charts/bentopdf --version 0.1.0 +helm upgrade --install bentopdf oci://ghcr.io/$GHCR_USERNAME/charts/bentopdf --version 1.0.0 ``` diff --git a/chart/templates/NOTES.txt b/chart/templates/NOTES.txt index 137f4f1..c99d3b0 100644 --- a/chart/templates/NOTES.txt +++ b/chart/templates/NOTES.txt @@ -1,17 +1,29 @@ 1. Get the application URL by running these commands: {{- if .Values.httpRoute.enabled }} +{{- $defaultGatewayName := .Values.gateway.name -}} +{{- if not $defaultGatewayName -}} +{{- $defaultGatewayName = printf "%s-gateway" (include "chart.fullname" .) -}} +{{- end -}} +{{- $defaultGatewayNs := .Release.Namespace -}} +{{- if .Values.gateway.enabled -}} +{{- $defaultGatewayNs = default .Release.Namespace .Values.gateway.namespace -}} +{{- end -}} +{{- $gatewayName := $defaultGatewayName -}} +{{- $gatewayNs := $defaultGatewayNs -}} +{{- if and .Values.httpRoute.parentRefs (first .Values.httpRoute.parentRefs) -}} +{{- $firstRef := first .Values.httpRoute.parentRefs -}} +{{- $gatewayName = default $defaultGatewayName $firstRef.name -}} +{{- $gatewayNs = default $defaultGatewayNs $firstRef.namespace -}} +{{- end -}} {{- if .Values.httpRoute.hostnames }} export APP_HOSTNAME={{ .Values.httpRoute.hostnames | first }} + echo "Visit http://$APP_HOSTNAME to use your application" {{- else }} - export APP_HOSTNAME=$(kubectl get --namespace {{(first .Values.httpRoute.parentRefs).namespace | default .Release.Namespace }} gateway/{{ (first .Values.httpRoute.parentRefs).name }} -o jsonpath="{.spec.listeners[0].hostname}") - {{- end }} -{{- if and .Values.httpRoute.rules (first .Values.httpRoute.rules).matches (first (first .Values.httpRoute.rules).matches).path.value }} - echo "Visit http://$APP_HOSTNAME{{ (first (first .Values.httpRoute.rules).matches).path.value }} to use your application" - + echo "HTTPRoute is enabled. Configure httpRoute.hostnames to see your URL here." +{{- end }} NOTE: Your HTTPRoute depends on the listener configuration of your gateway and your HTTPRoute rules. The rules can be set for path, method, header and query parameters. - You can check the gateway configuration with 'kubectl get --namespace {{(first .Values.httpRoute.parentRefs).namespace | default .Release.Namespace }} gateway/{{ (first .Values.httpRoute.parentRefs).name }} -o yaml' -{{- end }} + You can check the gateway configuration with 'kubectl get --namespace {{ $gatewayNs }} gateway/{{ $gatewayName }} -o yaml' {{- else if .Values.ingress.enabled }} {{- range $host := .Values.ingress.hosts }} {{- range .paths }}