Skip to content

Commit 542691d

Browse files
miledxzmiledxz
committed
Use helm-docs to automatically generate Helm docs (nginx#2058)
Problem: It's hard to keep the README up-to-date and it's a manual process Solution: Use norwoodj/helm-docs to automatically generate the docs from the values.yaml file
1 parent 65d4023 commit 542691d

File tree

7 files changed

+430
-118
lines changed

7 files changed

+430
-118
lines changed

‎.github/workflows/ci.yml

+3
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,9 @@ jobs:
7575
- name: Check if generated manifests are up to date
7676
run: make generate-manifests && git diff --exit-code
7777

78+
- name: Check if helm docs are up to date
79+
run: make helm-docs && git diff --exit-code
80+
7881
unit-tests:
7982
name: Unit Tests
8083
runs-on: ubuntu-22.04

‎Makefile

+4
Original file line numberDiff line numberDiff line change
@@ -199,6 +199,10 @@ njs-unit-test: ## Run unit tests for the njs httpmatches module
199199
lint-helm: ## Run the helm chart linter
200200
docker run --pull always --rm -v $(CURDIR):/nginx-gateway-fabric -w /nginx-gateway-fabric quay.io/helmpack/chart-testing:latest ct lint --config .ct.yaml
201201

202+
.PHONY: helm-docs
203+
helm-docs: ## Generate the Helm chart documentation
204+
docker run --pull always --rm -v $(CURDIR):/nginx-gateway-fabric -w /nginx-gateway-fabric jnorwood/helm-docs:latest --chart-search-root=charts --template-files _templates.gotmpl --template-files README.md.gotmpl
205+
202206
.PHONY: load-images
203207
load-images: ## Load NGF and NGINX images on configured kind cluster.
204208
kind load docker-image $(PREFIX):$(TAG) $(NGINX_PREFIX):$(TAG)

‎charts/nginx-gateway-fabric/.helmignore

+1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
# Patterns to ignore when building packages.
22
*.png
3+
*.gotmpl

‎charts/nginx-gateway-fabric/README.md

+67-54
Large diffs are not rendered by default.

‎charts/nginx-gateway-fabric/README.md.gotmpl

+257
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,257 @@
1+
# NGINX Gateway Fabric Helm Chart
2+
3+
{{ template "chart.versionBadge" . }}{{ template "chart.appVersionBadge" . }}
4+
5+
- [NGINX Gateway Fabric Helm Chart](#nginx-gateway-fabric-helm-chart)
6+
- [Introduction](#introduction)
7+
- [Prerequisites](#prerequisites)
8+
- [Installing the Gateway API resources](#installing-the-gateway-api-resources)
9+
- [Requirements](#requirements)
10+
- [Installing the Chart](#installing-the-chart)
11+
- [Installing the Chart from the OCI Registry](#installing-the-chart-from-the-oci-registry)
12+
- [Installing the Chart via Sources](#installing-the-chart-via-sources)
13+
- [Pulling the Chart](#pulling-the-chart)
14+
- [Installing the Chart](#installing-the-chart-1)
15+
- [Custom installation options](#custom-installation-options)
16+
- [Service type](#service-type)
17+
- [Upgrading the Chart](#upgrading-the-chart)
18+
- [Upgrading the Gateway Resources](#upgrading-the-gateway-resources)
19+
- [Upgrading the CRDs](#upgrading-the-crds)
20+
- [Upgrading the Chart from the OCI Registry](#upgrading-the-chart-from-the-oci-registry)
21+
- [Upgrading the Chart from the Sources](#upgrading-the-chart-from-the-sources)
22+
- [Configure Delayed Termination for Zero Downtime Upgrades](#configure-delayed-termination-for-zero-downtime-upgrades)
23+
- [Uninstalling the Chart](#uninstalling-the-chart)
24+
- [Uninstalling the Gateway Resources](#uninstalling-the-gateway-resources)
25+
- [Configuration](#configuration)
26+
27+
28+
## Introduction
29+
30+
This chart deploys the NGINX Gateway Fabric in your Kubernetes cluster.
31+
32+
## Prerequisites
33+
34+
- [Helm 3.0+](https://helm.sh/docs/intro/install/)
35+
- [kubectl](https://kubernetes.io/docs/tasks/tools/)
36+
37+
### Installing the Gateway API resources
38+
39+
> [!NOTE]
40+
>
41+
> The [Gateway API resources](https://github.com/kubernetes-sigs/gateway-api) from the standard channel must be
42+
> installed before deploying NGINX Gateway Fabric. If they are already installed in your cluster, please ensure
43+
> they are the correct version as supported by the NGINX Gateway Fabric -
44+
> [see the Technical Specifications](https://github.com/nginxinc/nginx-gateway-fabric/blob/main/README.md#technical-specifications).
45+
46+
```shell
47+
kubectl kustomize https://github.com/nginxinc/nginx-gateway-fabric/config/crd/gateway-api/standard | kubectl apply -f -
48+
```
49+
50+
{{ template "chart.requirementsSection" . }}
51+
52+
## Installing the Chart
53+
54+
### Installing the Chart from the OCI Registry
55+
56+
To install the latest stable release of NGINX Gateway Fabric in the `nginx-gateway` namespace, run the following command:
57+
58+
```shell
59+
helm install ngf oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway
60+
```
61+
62+
`ngf` is the name of the release, and can be changed to any name you want. This name is added as a prefix to the Deployment name.
63+
64+
If the namespace already exists, you can omit the optional `--create-namespace` flag. If you want the latest version from the `main` branch, add `--version 0.0.0-edge` to your install command.
65+
66+
To wait for the Deployment to be ready, you can either add the `--wait` flag to the `helm install` command, or run
67+
the following after installing:
68+
69+
```shell
70+
kubectl wait --timeout=5m -n nginx-gateway deployment/ngf-nginx-gateway-fabric --for=condition=Available
71+
```
72+
73+
### Installing the Chart via Sources
74+
75+
#### Pulling the Chart
76+
77+
```shell
78+
helm pull oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --untar
79+
cd nginx-gateway-fabric
80+
```
81+
82+
This will pull the latest stable release. To pull the latest version from the `main` branch, specify the
83+
`--version 0.0.0-edge` flag when pulling.
84+
85+
#### Installing the Chart
86+
87+
To install the chart into the `nginx-gateway` namespace, run the following command.
88+
89+
```shell
90+
helm install ngf . --create-namespace -n nginx-gateway
91+
```
92+
93+
`ngf` is the name of the release, and can be changed to any name you want. This name is added as a prefix to the Deployment name.
94+
95+
If the namespace already exists, you can omit the optional `--create-namespace` flag.
96+
97+
To wait for the Deployment to be ready, you can either add the `--wait` flag to the `helm install` command, or run
98+
the following after installing:
99+
100+
```shell
101+
kubectl wait --timeout=5m -n nginx-gateway deployment/ngf-nginx-gateway-fabric --for=condition=Available
102+
```
103+
104+
### Custom installation options
105+
106+
#### Service type
107+
108+
By default, the NGINX Gateway Fabric helm chart deploys a LoadBalancer Service.
109+
110+
To use a NodePort Service instead:
111+
112+
```shell
113+
helm install ngf oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway --set service.type=NodePort
114+
```
115+
116+
To disable the creation of a Service:
117+
118+
```shell
119+
helm install ngf oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway --set service.create=false
120+
```
121+
122+
## Upgrading the Chart
123+
124+
> [!NOTE]
125+
>
126+
> See [below](#configure-delayed-termination-for-zero-downtime-upgrades) for instructions on how to configure delayed
127+
> termination if required for zero downtime upgrades in your environment.
128+
129+
### Upgrading the Gateway Resources
130+
131+
Before you upgrade a release, ensure the Gateway API resources are the correct version as supported by the NGINX
132+
Gateway Fabric - [see the Technical Specifications](../../README.md#technical-specifications).:
133+
134+
To upgrade the Gateway CRDs from [the Gateway API repo](https://github.com/kubernetes-sigs/gateway-api), run:
135+
136+
```shell
137+
kubectl kustomize https://github.com/nginxinc/nginx-gateway-fabric/config/crd/gateway-api/standard | kubectl apply -f -
138+
```
139+
140+
### Upgrading the CRDs
141+
142+
Helm does not upgrade the NGINX Gateway Fabric CRDs during a release upgrade. Before you upgrade a release, you
143+
must [pull the chart](#pulling-the-chart) from GitHub and run the following command to upgrade the CRDs:
144+
145+
```shell
146+
kubectl apply -f crds/
147+
```
148+
149+
The following warning is expected and can be ignored:
150+
151+
```text
152+
Warning: kubectl apply should be used on resource created by either kubectl create --save-config or kubectl apply.
153+
```
154+
155+
### Upgrading the Chart from the OCI Registry
156+
157+
To upgrade the release `ngf`, run:
158+
159+
```shell
160+
helm upgrade ngf oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric -n nginx-gateway
161+
```
162+
163+
This will upgrade to the latest stable release. To upgrade to the latest version from the `main` branch, specify
164+
the `--version 0.0.0-edge` flag when upgrading.
165+
166+
### Upgrading the Chart from the Sources
167+
168+
Pull the chart sources as described in [Pulling the Chart](#pulling-the-chart), if not already present. Then, to upgrade
169+
the release `ngf`, run:
170+
171+
```shell
172+
helm upgrade ngf . -n nginx-gateway
173+
```
174+
175+
### Configure Delayed Termination for Zero Downtime Upgrades
176+
177+
To achieve zero downtime upgrades (meaning clients will not see any interruption in traffic while a rolling upgrade is
178+
being performed on NGF), you may need to configure delayed termination on the NGF Pod, depending on your environment.
179+
180+
> [!NOTE]
181+
>
182+
> When proxying Websocket or any long-lived connections, NGINX will not terminate until that connection is closed
183+
> by either the client or the backend. This means that unless all those connections are closed by clients/backends
184+
> before or during an upgrade, NGINX will not terminate, which means Kubernetes will kill NGINX. As a result, the
185+
> clients will see the connections abruptly closed and thus experience downtime.
186+
187+
1. Add `lifecycle` to both the nginx and the nginx-gateway container definition. To do so, update your `values.yaml`
188+
file to include the following (update the `sleep` values to what is required in your environment):
189+
190+
```yaml
191+
nginxGateway:
192+
<...>
193+
lifecycle:
194+
preStop:
195+
exec:
196+
command:
197+
- /usr/bin/gateway
198+
- sleep
199+
- --duration=40s # This flag is optional, the default is 30s
200+
201+
nginx:
202+
<...>
203+
lifecycle:
204+
preStop:
205+
exec:
206+
command:
207+
- /bin/sleep
208+
- "40"
209+
```
210+
211+
2. Ensure the `terminationGracePeriodSeconds` matches or exceeds the `sleep` value from the `preStopHook` (the default
212+
is 30). This is to ensure Kubernetes does not terminate the Pod before the `preStopHook` is complete. To do so,
213+
update your `values.yaml` file to include the following (update the value to what is required in your environment):
214+
215+
```yaml
216+
terminationGracePeriodSeconds: 50
217+
```
218+
219+
> [!NOTE]
220+
>
221+
> More information on container lifecycle hooks can be found
222+
> [here](https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks) and a detailed
223+
> description of Pod termination behavior can be found in
224+
> [Termination of Pods](https://kubernetes.io/docs/concepts/workloads/Pods/Pod-lifecycle/#Pod-termination).
225+
226+
## Uninstalling the Chart
227+
228+
To uninstall/delete the release `ngf`:
229+
230+
```shell
231+
helm uninstall ngf -n nginx-gateway
232+
kubectl delete ns nginx-gateway
233+
kubectl delete -f https://raw.githubusercontent.com/nginxinc/nginx-gateway-fabric/main/deploy/crds.yaml
234+
```
235+
236+
These commands remove all the Kubernetes components associated with the release and deletes the release.
237+
238+
### Uninstalling the Gateway Resources
239+
240+
> **Warning: This command will delete all the corresponding custom resources in your cluster across all namespaces!
241+
> Please ensure there are no custom resources that you want to keep and there are no other Gateway API implementations
242+
> running in the cluster!**
243+
244+
To delete the Gateway API CRDs from [the Gateway API repo](https://github.com/kubernetes-sigs/gateway-api), run:
245+
246+
```shell
247+
kubectl kustomize https://github.com/nginxinc/nginx-gateway-fabric/config/crd/gateway-api/standard | kubectl delete -f -
248+
```
249+
250+
## Configuration
251+
252+
The following table lists the configurable parameters of the NGINX Gateway Fabric chart and their default values.
253+
254+
{{ template "chart.valuesTable" . }}
255+
256+
----------------------------------------------
257+
Autogenerated from chart metadata using [helm-docs](https://github.com/norwoodj/helm-docs)

‎charts/nginx-gateway-fabric/_templates.gotmpl

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
{{ define "chart.valuesTable" }}
2+
{{ if .Sections.Sections }}
3+
{{ range .Sections.Sections }}
4+
5+
### {{ .SectionName }}
6+
7+
| Key | Description | Type | Default |
8+
|-----|-------------|------|---------|
9+
{{- range .SectionItems }}
10+
| `{{ .Key }}` | {{ if .Description }}{{ .Description }}{{ else }}{{ .AutoDescription }}{{ end }} | {{ .Type }} | {{ if .Default }}{{ .Default }}{{ else }}{{ .AutoDefault }}{{ end }} |
11+
{{- end }}
12+
{{- end }}
13+
{{ if .Sections.DefaultSection.SectionItems}}
14+
15+
### {{ .Sections.DefaultSection.SectionName }}
16+
17+
| Key | Description | Type | Default |
18+
|-----|-------------|------|---------|
19+
{{- range .Sections.DefaultSection.SectionItems }}
20+
| `{{ .Key }}` | {{ if .Description }}{{ .Description }}{{ else }}{{ .AutoDescription }}{{ end }} | {{ .Type }} | {{ if .Default }}{{ .Default }}{{ else }}{{ .AutoDefault }}{{ end }} |
21+
{{- end }}
22+
{{ end }}
23+
{{ else }}
24+
| Key | Description | Type | Default |
25+
|-----|-------------|------|---------|
26+
{{- range .Values }}
27+
| `{{ .Key }}` | {{ if .Description }}{{ .Description }}{{ else }}{{ .AutoDescription }}{{ end }} | {{ .Type }} | {{ if .Default }}{{ .Default }}{{ else }}{{ .AutoDefault }}{{ end }} |
28+
{{- end }}
29+
{{ end }}
30+
{{ end }}

0 commit comments

Comments
 (0)