From eec598439c26cb5e0154629932f1a666a1217e9d Mon Sep 17 00:00:00 2001 From: Luca Comellini Date: Wed, 29 May 2024 15:11:50 -0700 Subject: [PATCH] Use helm-docs to automatically generate Helm docs 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 --- .github/workflows/ci.yml | 3 + Makefile | 4 + charts/nginx-gateway-fabric/.helmignore | 1 + charts/nginx-gateway-fabric/README.md | 121 +++++---- charts/nginx-gateway-fabric/README.md.gotmpl | 257 ++++++++++++++++++ charts/nginx-gateway-fabric/_templates.gotmpl | 30 ++ charts/nginx-gateway-fabric/values.yaml | 132 ++++----- 7 files changed, 430 insertions(+), 118 deletions(-) create mode 100644 charts/nginx-gateway-fabric/README.md.gotmpl create mode 100644 charts/nginx-gateway-fabric/_templates.gotmpl diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index accef7c249..3775f9bce5 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -75,6 +75,9 @@ jobs: - name: Check if generated manifests are up to date run: make generate-manifests && git diff --exit-code + - name: Check if helm docs are up to date + run: make helm-docs && git diff --exit-code + unit-tests: name: Unit Tests runs-on: ubuntu-22.04 diff --git a/Makefile b/Makefile index 047dd875db..fdb17fd17e 100644 --- a/Makefile +++ b/Makefile @@ -199,6 +199,10 @@ njs-unit-test: ## Run unit tests for the njs httpmatches module lint-helm: ## Run the helm chart linter 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 +.PHONY: helm-docs +helm-docs: ## Generate the Helm chart documentation + 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 + .PHONY: load-images load-images: ## Load NGF and NGINX images on configured kind cluster. kind load docker-image $(PREFIX):$(TAG) $(NGINX_PREFIX):$(TAG) diff --git a/charts/nginx-gateway-fabric/.helmignore b/charts/nginx-gateway-fabric/.helmignore index c1347c2c27..8612fd290e 100644 --- a/charts/nginx-gateway-fabric/.helmignore +++ b/charts/nginx-gateway-fabric/.helmignore @@ -1,2 +1,3 @@ # Patterns to ignore when building packages. *.png +*.gotmpl diff --git a/charts/nginx-gateway-fabric/README.md b/charts/nginx-gateway-fabric/README.md index 45efa1ff67..fca37162ca 100644 --- a/charts/nginx-gateway-fabric/README.md +++ b/charts/nginx-gateway-fabric/README.md @@ -1,9 +1,13 @@ + # NGINX Gateway Fabric Helm Chart +![Version: 1.2.0](https://img.shields.io/badge/Version-1.2.0-informational?style=flat-square) ![AppVersion: edge](https://img.shields.io/badge/AppVersion-edge-informational?style=flat-square) + - [NGINX Gateway Fabric Helm Chart](#nginx-gateway-fabric-helm-chart) - [Introduction](#introduction) - [Prerequisites](#prerequisites) - [Installing the Gateway API resources](#installing-the-gateway-api-resources) + - [Requirements](#requirements) - [Installing the Chart](#installing-the-chart) - [Installing the Chart from the OCI Registry](#installing-the-chart-from-the-oci-registry) - [Installing the Chart via Sources](#installing-the-chart-via-sources) @@ -32,7 +36,7 @@ This chart deploys the NGINX Gateway Fabric in your Kubernetes cluster. ### Installing the Gateway API resources -> **Note** +> [!NOTE] > > The [Gateway API resources](https://github.com/kubernetes-sigs/gateway-api) from the standard channel must be > installed before deploying NGINX Gateway Fabric. If they are already installed in your cluster, please ensure @@ -43,6 +47,10 @@ This chart deploys the NGINX Gateway Fabric in your Kubernetes cluster. kubectl kustomize https://github.com/nginxinc/nginx-gateway-fabric/config/crd/gateway-api/standard | kubectl apply -f - ``` +## Requirements + +Kubernetes: `>= 1.25.0-0` + ## Installing the Chart ### Installing the Chart from the OCI Registry @@ -115,7 +123,7 @@ helm install ngf oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --create-nam ## Upgrading the Chart -> **Note** +> [!NOTE] > > See [below](#configure-delayed-termination-for-zero-downtime-upgrades) for instructions on how to configure delayed > termination if required for zero downtime upgrades in your environment. @@ -171,7 +179,7 @@ helm upgrade ngf . -n nginx-gateway To achieve zero downtime upgrades (meaning clients will not see any interruption in traffic while a rolling upgrade is being performed on NGF), you may need to configure delayed termination on the NGF Pod, depending on your environment. -> **Note** +> [!NOTE] > > When proxying Websocket or any long-lived connections, NGINX will not terminate until that connection is closed > by either the client or the backend. This means that unless all those connections are closed by clients/backends @@ -210,7 +218,7 @@ being performed on NGF), you may need to configure delayed termination on the NG terminationGracePeriodSeconds: 50 ``` -> **Note** +> [!NOTE] > > More information on container lifecycle hooks can be found > [here](https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks) and a detailed @@ -243,53 +251,58 @@ kubectl kustomize https://github.com/nginxinc/nginx-gateway-fabric/config/crd/ga ## Configuration -The following tables lists the configurable parameters of the NGINX Gateway Fabric chart and their default values. - -| Parameter | Description | Default Value | -| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -| `nginxGateway.image.repository` | The repository for the NGINX Gateway Fabric image. | ghcr.io/nginxinc/nginx-gateway-fabric | -| `nginxGateway.image.tag` | The tag for the NGINX Gateway Fabric image. | edge | -| `nginxGateway.image.pullPolicy` | The `imagePullPolicy` for the NGINX Gateway Fabric image. | Always | -| `nginxGateway.lifecycle` | The `lifecycle` of the nginx-gateway container. | {} | -| `nginxGateway.extraVolumeMounts` | Extra `volumeMounts` for the nginxGateway container. | {} | -| `nginxGateway.gatewayClassName` | The name of the GatewayClass for the NGINX Gateway Fabric deployment. | nginx | -| `nginxGateway.gatewayClassAnnotations` | Set of custom annotations for GatewayClass objects. | {} | -| `nginxGateway.gatewayControllerName` | The name of the Gateway controller. The controller name must be of the form: DOMAIN/PATH. The controller's domain is gateway.nginx.org. | gateway.nginx.org/nginx-gateway-controller | -| `nginxGateway.kind` | The kind of the NGINX Gateway Fabric installation - currently, only Deployment is supported. | deployment | -| `nginxGateway.config` | The dynamic configuration for the control plane that is contained in the NginxGateway resource | [See nginxGateway.config section](values.yaml) | -| `nginxGateway.configAnnotations` | Set of custom annotations for NginxGateway objects. | {} | -| `nginxGateway.readinessProbe.enable` | Enable the /readyz endpoint on the control plane. | true | -| `nginxGateway.readinessProbe.port` | Port in which the readiness endpoint is exposed. | 8081 | -| `nginxGateway.readinessProbe.initialDelaySeconds` | The number of seconds after the Pod has started before the readiness probes are initiated. | 3 | -| `nginxGateway.replicaCount` | The number of replicas of the NGINX Gateway Fabric Deployment. | 1 | -| `nginxGateway.leaderElection.enable` | Enable leader election. Leader election is used to avoid multiple replicas of the NGINX Gateway Fabric reporting the status of the Gateway API resources. | true | -| `nginxGateway.leaderElection.lockName` | The name of the leader election lock. A Lease object with this name will be created in the same Namespace as the controller. | Autogenerated | -| `nginxGateway.securityContext.allowPrivilegeEscalation` | Some environments may need this set to true in order for the control plane to successfully reload NGINX. | false | -| `nginxGateway.productTelemetry.enable` | Enable the collection of product telemetry. | true | -| `nginxGateway.gwAPIExperimentalFeatures.enable` | Enable the experimental features of Gateway API which are supported by NGINX Gateway Fabric. Requires the Gateway APIs installed from the experimental channel. | false | -| `nginx.image.repository` | The repository for the NGINX image. | ghcr.io/nginxinc/nginx-gateway-fabric/nginx | -| `nginx.image.tag` | The tag for the NGINX image. | edge | -| `nginx.image.pullPolicy` | The `imagePullPolicy` for the NGINX image. | Always | -| `nginx.plus` | Is NGINX Plus image being used | false | -| `nginx.config` | The configuration for the data plane that is contained in the NginxProxy resource. | [See nginx.config section](values.yaml) | -| `nginx.usage.secretName` | The namespace/name of the Secret containing the credentials for NGINX Plus usage reporting. | | -| `nginx.usage.serverURL` | The base server URL of the NGINX Plus usage reporting server. | | -| `nginx.usage.clusterName` | The display name of the Kubernetes cluster in the NGINX Plus usage reporting server. | | -| `nginx.usage.insecureSkipVerify` | Disable client verification of the NGINX Plus usage reporting server certificate. | false | -| `nginx.lifecycle` | The `lifecycle` of the nginx container. | {} | -| `nginx.extraVolumeMounts` | Extra `volumeMounts` for the nginx container. | {} | -| `terminationGracePeriodSeconds` | The termination grace period of the NGINX Gateway Fabric pod. | 30 | -| `tolerations` | The `tolerations` of the NGINX Gateway Fabric pod. | [] | -| `nodeSelector` | The `nodeSelector` of the NGINX Gateway Fabric pod. | {} | -| `affinity` | The `affinity` of the NGINX Gateway Fabric pod. | {} | -| `serviceAccount.annotations` | The `annotations` for the ServiceAccount used by the NGINX Gateway Fabric deployment. | {} | -| `serviceAccount.name` | Name of the ServiceAccount used by the NGINX Gateway Fabric deployment. | Autogenerated | -| `service.create` | Creates a service to expose the NGINX Gateway Fabric pods. | true | -| `service.type` | The type of service to create for the NGINX Gateway Fabric. | Loadbalancer | -| `service.externalTrafficPolicy` | The `externalTrafficPolicy` of the service. The value `Local` preserves the client source IP. | Local | -| `service.annotations` | The `annotations` of the NGINX Gateway Fabric service. | {} | -| `service.ports` | A list of ports to expose through the NGINX Gateway Fabric service. Update it to match the listener ports from your Gateway resource. Follows the conventional Kubernetes yaml syntax for service ports. | [ port: 80, targetPort: 80, protocol: TCP, name: http; port: 443, targetPort: 443, protocol: TCP, name: https ] | -| `metrics.disable` | Disable exposing metrics in the Prometheus format. | false | -| `metrics.port` | Set the port where the Prometheus metrics are exposed. Format: [1024 - 65535] | 9113 | -| `metrics.secure` | Enable serving metrics via https. By default metrics are served via http. Please note that this endpoint will be secured with a self-signed certificate. | false | -| `extraVolumes` | Extra `volumes` for the NGINX Gateway Fabric pod. | [] | +The following table lists the configurable parameters of the NGINX Gateway Fabric chart and their default values. + +| Key | Description | Type | Default | +|-----|-------------|------|---------| +| `affinity` | The affinity of the NGINX Gateway Fabric pod. | object | `{}` | +| `extraVolumes` | extraVolumes for the NGINX Gateway Fabric pod. Use in conjunction with nginxGateway.extraVolumeMounts and nginx.extraVolumeMounts to mount additional volumes to the containers. | list | `[]` | +| `metrics.enable` | Enable exposing metrics in the Prometheus format. | bool | `true` | +| `metrics.port` | Set the port where the Prometheus metrics are exposed. Format: [1024 - 65535] | int | `9113` | +| `metrics.secure` | Enable serving metrics via https. By default metrics are served via http. Please note that this endpoint will be secured with a self-signed certificate. | bool | `false` | +| `nginx.config` | The configuration for the data plane that is contained in the NginxProxy resource. | object | `{}` | +| `nginx.extraVolumeMounts` | extraVolumeMounts are the additional volume mounts for the nginx container. | list | `[]` | +| `nginx.image.pullPolicy` | | string | `"Always"` | +| `nginx.image.repository` | The NGINX image to use. | string | `"ghcr.io/nginxinc/nginx-gateway-fabric/nginx"` | +| `nginx.image.tag` | | string | `"edge"` | +| `nginx.lifecycle` | The lifecycle of the nginx container. | object | `{}` | +| `nginx.plus` | Is NGINX Plus image being used | bool | `false` | +| `nginx.usage.clusterName` | The display name of the Kubernetes cluster in the NGINX Plus usage reporting server. | string | `""` | +| `nginx.usage.insecureSkipVerify` | Disable client verification of the NGINX Plus usage reporting server certificate. | bool | `false` | +| `nginx.usage.secretName` | The namespace/name of the Secret containing the credentials for NGINX Plus usage reporting. | string | `""` | +| `nginx.usage.serverURL` | The base server URL of the NGINX Plus usage reporting server. | string | `""` | +| `nginxGateway.config.logging.level` | Log level. Supported values "info", "debug", "error". | string | `"info"` | +| `nginxGateway.configAnnotations` | Set of custom annotations for NginxGateway objects. | object | `{}` | +| `nginxGateway.extraVolumeMounts` | extraVolumeMounts are the additional volume mounts for the nginx-gateway container. | list | `[]` | +| `nginxGateway.gatewayClassAnnotations` | Set of custom annotations for GatewayClass objects. | object | `{}` | +| `nginxGateway.gatewayClassName` | The name of the GatewayClass that will be created as part of this release. Every NGINX Gateway Fabric must have a unique corresponding GatewayClass resource. NGINX Gateway Fabric only processes resources that belong to its class - i.e. have the "gatewayClassName" field resource equal to the class. | string | `"nginx"` | +| `nginxGateway.gatewayControllerName` | The name of the Gateway controller. The controller name must be of the form: DOMAIN/PATH. The controller's domain is gateway.nginx.org. | string | `"gateway.nginx.org/nginx-gateway-controller"` | +| `nginxGateway.gwAPIExperimentalFeatures.enable` | Enable the experimental features of Gateway API which are supported by NGINX Gateway Fabric. Requires the Gateway APIs installed from the experimental channel. | bool | `false` | +| `nginxGateway.image.pullPolicy` | | string | `"Always"` | +| `nginxGateway.image.repository` | The NGINX Gateway Fabric image to use | string | `"ghcr.io/nginxinc/nginx-gateway-fabric"` | +| `nginxGateway.image.tag` | | string | `"edge"` | +| `nginxGateway.kind` | The kind of the NGINX Gateway Fabric installation - currently, only deployment is supported. | string | `"deployment"` | +| `nginxGateway.leaderElection.enable` | Enable leader election. Leader election is used to avoid multiple replicas of the NGINX Gateway Fabric reporting the status of the Gateway API resources. If not enabled, all replicas of NGINX Gateway Fabric will update the statuses of the Gateway API resources. | bool | `true` | +| `nginxGateway.leaderElection.lockName` | The name of the leader election lock. A Lease object with this name will be created in the same Namespace as the controller. | string | Autogenerated if not set or set to "". | +| `nginxGateway.lifecycle` | The lifecycle of the nginx-gateway container. | object | `{}` | +| `nginxGateway.productTelemetry.enable` | Enable the collection of product telemetry. | bool | `true` | +| `nginxGateway.readinessProbe.enable` | Enable the /readyz endpoint on the control plane. | bool | `true` | +| `nginxGateway.readinessProbe.initialDelaySeconds` | The number of seconds after the Pod has started before the readiness probes are initiated. | int | `3` | +| `nginxGateway.readinessProbe.port` | Port in which the readiness endpoint is exposed. | int | `8081` | +| `nginxGateway.replicaCount` | The number of replicas of the NGINX Gateway Fabric Deployment. | int | `1` | +| `nginxGateway.securityContext.allowPrivilegeEscalation` | Some environments may need this set to true in order for the control plane to successfully reload NGINX. | bool | `false` | +| `nodeSelector` | The nodeSelector of the NGINX Gateway Fabric pod. | object | `{}` | +| `service.annotations` | The annotations of the NGINX Gateway Fabric service. | object | `{}` | +| `service.create` | Creates a service to expose the NGINX Gateway Fabric pods. | bool | `true` | +| `service.externalTrafficPolicy` | The externalTrafficPolicy of the service. The value Local preserves the client source IP. | string | `"Local"` | +| `service.ports` | A list of ports to expose through the NGINX Gateway Fabric service. Update it to match the listener ports from your Gateway resource. Follows the conventional Kubernetes yaml syntax for service ports. | list | `[{"name":"http","port":80,"protocol":"TCP","targetPort":80},{"name":"https","port":443,"protocol":"TCP","targetPort":443}]` | +| `service.type` | The type of service to create for the NGINX Gateway Fabric. | string | `"LoadBalancer"` | +| `serviceAccount.annotations` | | object | `{}` | +| `serviceAccount.imagePullSecret` | The name of the secret containing docker registry credentials. Secret must exist in the same namespace as the helm release. | string | `""` | +| `serviceAccount.imagePullSecrets` | A list of secret names containing docker registry credentials. Secrets must exist in the same namespace as the helm release. | list | `[]` | +| `serviceAccount.name` | The name of the service account of the NGINX Gateway Fabric pods. Used for RBAC. | string | Autogenerated if not set or set to "" | +| `terminationGracePeriodSeconds` | The termination grace period of the NGINX Gateway Fabric pod. | int | `30` | +| `tolerations` | Tolerations for the NGINX Gateway Fabric pod. | list | `[]` | + +---------------------------------------------- +Autogenerated from chart metadata using [helm-docs](https://github.com/norwoodj/helm-docs) diff --git a/charts/nginx-gateway-fabric/README.md.gotmpl b/charts/nginx-gateway-fabric/README.md.gotmpl new file mode 100644 index 0000000000..438fa67db6 --- /dev/null +++ b/charts/nginx-gateway-fabric/README.md.gotmpl @@ -0,0 +1,257 @@ +# NGINX Gateway Fabric Helm Chart + +{{ template "chart.versionBadge" . }}{{ template "chart.appVersionBadge" . }} + +- [NGINX Gateway Fabric Helm Chart](#nginx-gateway-fabric-helm-chart) + - [Introduction](#introduction) + - [Prerequisites](#prerequisites) + - [Installing the Gateway API resources](#installing-the-gateway-api-resources) + - [Requirements](#requirements) + - [Installing the Chart](#installing-the-chart) + - [Installing the Chart from the OCI Registry](#installing-the-chart-from-the-oci-registry) + - [Installing the Chart via Sources](#installing-the-chart-via-sources) + - [Pulling the Chart](#pulling-the-chart) + - [Installing the Chart](#installing-the-chart-1) + - [Custom installation options](#custom-installation-options) + - [Service type](#service-type) + - [Upgrading the Chart](#upgrading-the-chart) + - [Upgrading the Gateway Resources](#upgrading-the-gateway-resources) + - [Upgrading the CRDs](#upgrading-the-crds) + - [Upgrading the Chart from the OCI Registry](#upgrading-the-chart-from-the-oci-registry) + - [Upgrading the Chart from the Sources](#upgrading-the-chart-from-the-sources) + - [Configure Delayed Termination for Zero Downtime Upgrades](#configure-delayed-termination-for-zero-downtime-upgrades) + - [Uninstalling the Chart](#uninstalling-the-chart) + - [Uninstalling the Gateway Resources](#uninstalling-the-gateway-resources) + - [Configuration](#configuration) + + +## Introduction + +This chart deploys the NGINX Gateway Fabric in your Kubernetes cluster. + +## Prerequisites + +- [Helm 3.0+](https://helm.sh/docs/intro/install/) +- [kubectl](https://kubernetes.io/docs/tasks/tools/) + +### Installing the Gateway API resources + +> [!NOTE] +> +> The [Gateway API resources](https://github.com/kubernetes-sigs/gateway-api) from the standard channel must be +> installed before deploying NGINX Gateway Fabric. If they are already installed in your cluster, please ensure +> they are the correct version as supported by the NGINX Gateway Fabric - +> [see the Technical Specifications](https://github.com/nginxinc/nginx-gateway-fabric/blob/main/README.md#technical-specifications). + +```shell +kubectl kustomize https://github.com/nginxinc/nginx-gateway-fabric/config/crd/gateway-api/standard | kubectl apply -f - +``` + +{{ template "chart.requirementsSection" . }} + +## Installing the Chart + +### Installing the Chart from the OCI Registry + +To install the latest stable release of NGINX Gateway Fabric in the `nginx-gateway` namespace, run the following command: + +```shell +helm install ngf oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway +``` + +`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. + +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. + +To wait for the Deployment to be ready, you can either add the `--wait` flag to the `helm install` command, or run +the following after installing: + +```shell +kubectl wait --timeout=5m -n nginx-gateway deployment/ngf-nginx-gateway-fabric --for=condition=Available +``` + +### Installing the Chart via Sources + +#### Pulling the Chart + +```shell +helm pull oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --untar +cd nginx-gateway-fabric +``` + +This will pull the latest stable release. To pull the latest version from the `main` branch, specify the +`--version 0.0.0-edge` flag when pulling. + +#### Installing the Chart + +To install the chart into the `nginx-gateway` namespace, run the following command. + +```shell +helm install ngf . --create-namespace -n nginx-gateway +``` + +`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. + +If the namespace already exists, you can omit the optional `--create-namespace` flag. + +To wait for the Deployment to be ready, you can either add the `--wait` flag to the `helm install` command, or run +the following after installing: + +```shell +kubectl wait --timeout=5m -n nginx-gateway deployment/ngf-nginx-gateway-fabric --for=condition=Available +``` + +### Custom installation options + +#### Service type + +By default, the NGINX Gateway Fabric helm chart deploys a LoadBalancer Service. + +To use a NodePort Service instead: + +```shell +helm install ngf oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway --set service.type=NodePort +``` + +To disable the creation of a Service: + +```shell +helm install ngf oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway --set service.create=false +``` + +## Upgrading the Chart + +> [!NOTE] +> +> See [below](#configure-delayed-termination-for-zero-downtime-upgrades) for instructions on how to configure delayed +> termination if required for zero downtime upgrades in your environment. + +### Upgrading the Gateway Resources + +Before you upgrade a release, ensure the Gateway API resources are the correct version as supported by the NGINX +Gateway Fabric - [see the Technical Specifications](../../README.md#technical-specifications).: + +To upgrade the Gateway CRDs from [the Gateway API repo](https://github.com/kubernetes-sigs/gateway-api), run: + +```shell +kubectl kustomize https://github.com/nginxinc/nginx-gateway-fabric/config/crd/gateway-api/standard | kubectl apply -f - +``` + +### Upgrading the CRDs + +Helm does not upgrade the NGINX Gateway Fabric CRDs during a release upgrade. Before you upgrade a release, you +must [pull the chart](#pulling-the-chart) from GitHub and run the following command to upgrade the CRDs: + +```shell +kubectl apply -f crds/ +``` + +The following warning is expected and can be ignored: + +```text +Warning: kubectl apply should be used on resource created by either kubectl create --save-config or kubectl apply. +``` + +### Upgrading the Chart from the OCI Registry + +To upgrade the release `ngf`, run: + +```shell +helm upgrade ngf oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric -n nginx-gateway +``` + +This will upgrade to the latest stable release. To upgrade to the latest version from the `main` branch, specify +the `--version 0.0.0-edge` flag when upgrading. + +### Upgrading the Chart from the Sources + +Pull the chart sources as described in [Pulling the Chart](#pulling-the-chart), if not already present. Then, to upgrade +the release `ngf`, run: + +```shell +helm upgrade ngf . -n nginx-gateway +``` + +### Configure Delayed Termination for Zero Downtime Upgrades + +To achieve zero downtime upgrades (meaning clients will not see any interruption in traffic while a rolling upgrade is +being performed on NGF), you may need to configure delayed termination on the NGF Pod, depending on your environment. + +> [!NOTE] +> +> When proxying Websocket or any long-lived connections, NGINX will not terminate until that connection is closed +> by either the client or the backend. This means that unless all those connections are closed by clients/backends +> before or during an upgrade, NGINX will not terminate, which means Kubernetes will kill NGINX. As a result, the +> clients will see the connections abruptly closed and thus experience downtime. + +1. Add `lifecycle` to both the nginx and the nginx-gateway container definition. To do so, update your `values.yaml` + file to include the following (update the `sleep` values to what is required in your environment): + + ```yaml + nginxGateway: + <...> + lifecycle: + preStop: + exec: + command: + - /usr/bin/gateway + - sleep + - --duration=40s # This flag is optional, the default is 30s + + nginx: + <...> + lifecycle: + preStop: + exec: + command: + - /bin/sleep + - "40" + ``` + +2. Ensure the `terminationGracePeriodSeconds` matches or exceeds the `sleep` value from the `preStopHook` (the default + is 30). This is to ensure Kubernetes does not terminate the Pod before the `preStopHook` is complete. To do so, + update your `values.yaml` file to include the following (update the value to what is required in your environment): + + ```yaml + terminationGracePeriodSeconds: 50 + ``` + +> [!NOTE] +> +> More information on container lifecycle hooks can be found +> [here](https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks) and a detailed +> description of Pod termination behavior can be found in +> [Termination of Pods](https://kubernetes.io/docs/concepts/workloads/Pods/Pod-lifecycle/#Pod-termination). + +## Uninstalling the Chart + +To uninstall/delete the release `ngf`: + +```shell +helm uninstall ngf -n nginx-gateway +kubectl delete ns nginx-gateway +kubectl delete -f https://raw.githubusercontent.com/nginxinc/nginx-gateway-fabric/main/deploy/crds.yaml +``` + +These commands remove all the Kubernetes components associated with the release and deletes the release. + +### Uninstalling the Gateway Resources + +> **Warning: This command will delete all the corresponding custom resources in your cluster across all namespaces! +> Please ensure there are no custom resources that you want to keep and there are no other Gateway API implementations +> running in the cluster!** + +To delete the Gateway API CRDs from [the Gateway API repo](https://github.com/kubernetes-sigs/gateway-api), run: + +```shell +kubectl kustomize https://github.com/nginxinc/nginx-gateway-fabric/config/crd/gateway-api/standard | kubectl delete -f - +``` + +## Configuration + +The following table lists the configurable parameters of the NGINX Gateway Fabric chart and their default values. + +{{ template "chart.valuesTable" . }} + +---------------------------------------------- +Autogenerated from chart metadata using [helm-docs](https://github.com/norwoodj/helm-docs) diff --git a/charts/nginx-gateway-fabric/_templates.gotmpl b/charts/nginx-gateway-fabric/_templates.gotmpl new file mode 100644 index 0000000000..9b8101dfcf --- /dev/null +++ b/charts/nginx-gateway-fabric/_templates.gotmpl @@ -0,0 +1,30 @@ +{{ define "chart.valuesTable" }} +{{ if .Sections.Sections }} +{{ range .Sections.Sections }} + +### {{ .SectionName }} + +| Key | Description | Type | Default | +|-----|-------------|------|---------| + {{- range .SectionItems }} +| `{{ .Key }}` | {{ if .Description }}{{ .Description }}{{ else }}{{ .AutoDescription }}{{ end }} | {{ .Type }} | {{ if .Default }}{{ .Default }}{{ else }}{{ .AutoDefault }}{{ end }} | + {{- end }} +{{- end }} +{{ if .Sections.DefaultSection.SectionItems}} + +### {{ .Sections.DefaultSection.SectionName }} + +| Key | Description | Type | Default | +|-----|-------------|------|---------| + {{- range .Sections.DefaultSection.SectionItems }} +| `{{ .Key }}` | {{ if .Description }}{{ .Description }}{{ else }}{{ .AutoDescription }}{{ end }} | {{ .Type }} | {{ if .Default }}{{ .Default }}{{ else }}{{ .AutoDefault }}{{ end }} | + {{- end }} +{{ end }} +{{ else }} +| Key | Description | Type | Default | +|-----|-------------|------|---------| + {{- range .Values }} +| `{{ .Key }}` | {{ if .Description }}{{ .Description }}{{ else }}{{ .AutoDescription }}{{ end }} | {{ .Type }} | {{ if .Default }}{{ .Default }}{{ else }}{{ .AutoDefault }}{{ end }} | + {{- end }} +{{ end }} +{{ end }} diff --git a/charts/nginx-gateway-fabric/values.yaml b/charts/nginx-gateway-fabric/values.yaml index 10e0cdd04a..e0a4854bb8 100644 --- a/charts/nginx-gateway-fabric/values.yaml +++ b/charts/nginx-gateway-fabric/values.yaml @@ -1,84 +1,88 @@ nginxGateway: - ## The kind of the NGINX Gateway Fabric installation - currently, only deployment is supported. + # -- The kind of the NGINX Gateway Fabric installation - currently, only deployment is supported. kind: deployment - ## gatewayClassName is the name of the GatewayClass that will be created as part of this release. Every NGINX Gateway - ## Fabric must have a unique corresponding GatewayClass resource. NGINX Gateway Fabric only processes resources that - ## belong to its class - i.e. have the "gatewayClassName" field resource equal to the class. + + # -- The name of the GatewayClass that will be created as part of this release. Every NGINX Gateway + # Fabric must have a unique corresponding GatewayClass resource. NGINX Gateway Fabric only processes resources that + # belong to its class - i.e. have the "gatewayClassName" field resource equal to the class. gatewayClassName: nginx - ## Set of custom annotations for GatewayClass objects, e.g: - ## gatewayClassAnnotations: - ## someKey: someValue + + # -- Set of custom annotations for GatewayClass objects. gatewayClassAnnotations: {} - ## The name of the Gateway controller. The controller name must be of the form: DOMAIN/PATH. The controller's domain - ## is gateway.nginx.org. + + # -- The name of the Gateway controller. The controller name must be of the form: DOMAIN/PATH. The controller's domain + # is gateway.nginx.org. gatewayControllerName: gateway.nginx.org/nginx-gateway-controller - ## The dynamic configuration for the control plane that is contained in the NginxGateway resource. + + # The dynamic configuration for the control plane that is contained in the NginxGateway resource. config: logging: - ## Log level. Supported values "info", "debug", "error". + # -- Log level. Supported values "info", "debug", "error". level: info - ## Set of custom annotations for NginxGateway objects, e.g: - ## configAnnotations: - ## someKey: someValue + + # -- Set of custom annotations for NginxGateway objects. configAnnotations: {} - ## The number of replicas of the NGINX Gateway Fabric Deployment. + + # -- The number of replicas of the NGINX Gateway Fabric Deployment. replicaCount: 1 - ## The configuration for leader election. + + # The configuration for leader election. leaderElection: - ## Enable leader election. Leader election is used to avoid multiple replicas of the NGINX Gateway Fabric - ## reporting the status of the Gateway API resources. If not enabled, all replicas of NGINX Gateway Fabric - ## will update the statuses of the Gateway API resources. + # -- Enable leader election. Leader election is used to avoid multiple replicas of the NGINX Gateway Fabric + # reporting the status of the Gateway API resources. If not enabled, all replicas of NGINX Gateway Fabric + # will update the statuses of the Gateway API resources. enable: true - ## The name of the leader election lock. A Lease object with this name will be created in the same Namespace as - ## the controller. Autogenerated if not set or set to "". + # -- The name of the leader election lock. A Lease object with this name will be created in the same Namespace as + # the controller. + # @default -- Autogenerated if not set or set to "". lockName: "" ## Defines the settings for the control plane readiness probe. This probe returns Ready when the controller ## has started and configured NGINX to serve traffic. readinessProbe: - ## Enable the /readyz endpoint on the control plane. + # -- Enable the /readyz endpoint on the control plane. enable: true - ## Port in which the readiness endpoint is exposed. + # -- Port in which the readiness endpoint is exposed. port: 8081 - ## The number of seconds after the Pod has started before the readiness probes are initiated. + # -- The number of seconds after the Pod has started before the readiness probes are initiated. initialDelaySeconds: 3 image: - ## The NGINX Gateway Fabric image to use + # -- The NGINX Gateway Fabric image to use repository: ghcr.io/nginxinc/nginx-gateway-fabric tag: edge pullPolicy: Always securityContext: - ## Some environments may need this set to true in order for the control plane to successfully reload NGINX. + # -- Some environments may need this set to true in order for the control plane to successfully reload NGINX. allowPrivilegeEscalation: false productTelemetry: - ## Enable the collection of product telemetry. + # -- Enable the collection of product telemetry. enable: true - ## The lifecycle of the nginx-gateway container. + # -- The lifecycle of the nginx-gateway container. lifecycle: {} - ## extraVolumeMounts are the additional volume mounts for the nginx-gateway container. + # -- extraVolumeMounts are the additional volume mounts for the nginx-gateway container. extraVolumeMounts: [] gwAPIExperimentalFeatures: - ## Enable the experimental features of Gateway API which are supported by NGINX Gateway Fabric. Requires the Gateway - ## APIs installed from the experimental channel. + # -- Enable the experimental features of Gateway API which are supported by NGINX Gateway Fabric. Requires the Gateway + # APIs installed from the experimental channel. enable: false nginx: - ## The NGINX image to use image: + # -- The NGINX image to use. repository: ghcr.io/nginxinc/nginx-gateway-fabric/nginx tag: edge pullPolicy: Always - ## Is NGINX Plus image being used + # -- Is NGINX Plus image being used plus: false - ## The configuration for the data plane that is contained in the NginxProxy resource. + # -- The configuration for the data plane that is contained in the NginxProxy resource. config: {} # disableHTTP2: false @@ -91,61 +95,61 @@ nginx: # serviceName: "" # spanAttributes: [] - ## Configuration for NGINX Plus usage reporting. + # Configuration for NGINX Plus usage reporting. usage: - ## The namespace/name of the Secret containing the credentials for NGINX Plus usage reporting. + # -- The namespace/name of the Secret containing the credentials for NGINX Plus usage reporting. secretName: "" - ## The base server URL of the NGINX Plus usage reporting server. + # -- The base server URL of the NGINX Plus usage reporting server. serverURL: "" - ## The display name of the Kubernetes cluster in the NGINX Plus usage reporting server. + # -- The display name of the Kubernetes cluster in the NGINX Plus usage reporting server. clusterName: "" - ## Disable client verification of the NGINX Plus usage reporting server certificate. + # -- Disable client verification of the NGINX Plus usage reporting server certificate. insecureSkipVerify: false - ## The lifecycle of the nginx container. + # -- The lifecycle of the nginx container. lifecycle: {} - ## extraVolumeMounts are the additional volume mounts for the nginx container. + # -- extraVolumeMounts are the additional volume mounts for the nginx container. extraVolumeMounts: [] -## The termination grace period of the NGINX Gateway Fabric pod. +# -- The termination grace period of the NGINX Gateway Fabric pod. terminationGracePeriodSeconds: 30 -## Tolerations for the NGINX Gateway Fabric pod. +# -- Tolerations for the NGINX Gateway Fabric pod. tolerations: [] -## The nodeSelector of the NGINX Gateway Fabric pod. +# -- The nodeSelector of the NGINX Gateway Fabric pod. nodeSelector: {} -## The affinity of the NGINX Gateway Fabric pod. +# -- The affinity of the NGINX Gateway Fabric pod. affinity: {} serviceAccount: annotations: {} - ## The name of the service account of the NGINX Gateway Fabric pods. Used for RBAC. - ## Autogenerated if not set or set to "". - # name: nginx-gateway + # -- The name of the service account of the NGINX Gateway Fabric pods. Used for RBAC. + # @default -- Autogenerated if not set or set to "" + name: "" - ## The name of the secret containing docker registry credentials. - ## Secret must exist in the same namespace as the helm release. + # -- The name of the secret containing docker registry credentials. + # Secret must exist in the same namespace as the helm release. imagePullSecret: "" - ## A list of secret names containing docker registry credentials. - ## Secrets must exist in the same namespace as the helm release. + # -- A list of secret names containing docker registry credentials. + # Secrets must exist in the same namespace as the helm release. imagePullSecrets: [] service: - ## Creates a service to expose the NGINX Gateway Fabric pods. + # -- Creates a service to expose the NGINX Gateway Fabric pods. create: true - ## The type of service to create for the NGINX Gateway Fabric. + # -- The type of service to create for the NGINX Gateway Fabric. type: LoadBalancer - ## The externalTrafficPolicy of the service. The value Local preserves the client source IP. + # -- The externalTrafficPolicy of the service. The value Local preserves the client source IP. externalTrafficPolicy: Local - ## The annotations of the NGINX Gateway Fabric service. + # -- The annotations of the NGINX Gateway Fabric service. annotations: {} - ## A list of ports to expose through the NGINX Gateway Fabric service. Update it to match the listener ports from - ## your Gateway resource. Follows the conventional Kubernetes yaml syntax for service ports. + # -- A list of ports to expose through the NGINX Gateway Fabric service. Update it to match the listener ports from + # your Gateway resource. Follows the conventional Kubernetes yaml syntax for service ports. ports: - port: 80 targetPort: 80 @@ -157,14 +161,14 @@ service: name: https metrics: - ## Enable exposing metrics in the Prometheus format. + # -- Enable exposing metrics in the Prometheus format. enable: true - ## Set the port where the Prometheus metrics are exposed. Format: [1024 - 65535] + # -- Set the port where the Prometheus metrics are exposed. Format: [1024 - 65535] port: 9113 - ## Enable serving metrics via https. By default metrics are served via http. - ## Please note that this endpoint will be secured with a self-signed certificate. + # -- Enable serving metrics via https. By default metrics are served via http. + # Please note that this endpoint will be secured with a self-signed certificate. secure: false -## extraVolumes for the NGINX Gateway Fabric pod. Use in conjunction with -## nginxGateway.extraVolumeMounts and nginx.extraVolumeMounts to mount additional volumes to the containers. +# -- extraVolumes for the NGINX Gateway Fabric pod. Use in conjunction with +# nginxGateway.extraVolumeMounts and nginx.extraVolumeMounts to mount additional volumes to the containers. extraVolumes: []