Add Helm Chart to install NKG (nginx#840)

Add a Helm chart to install NKG

Author: miledxz

.github/workflows/ci.yml

@@ -55,6 +55,9 @@ jobs:
       - name: Check if generated files are up to date
         run: make generate && git diff --exit-code
 
+      - name: Check if njs-modules yaml is up to date
+        run: make generate-njs-yaml && git diff --exit-code
+
   unit-tests:
     name: Unit Tests
     runs-on: ubuntu-22.04
@@ -149,6 +152,71 @@ jobs:
           path: ${{ github.workspace }}/dist
           key: nginx-kubernetes-gateway-${{ github.run_id }}-${{ github.run_number }}
 
+  helm-tests:
+    name: Helm Tests
+    runs-on: ubuntu-22.04
+    needs: [vars, binary]
+    if: ${{ github.ref_type != 'tag' }}
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9 # v3.5.3
+
+      - name: Fetch Cached Artifacts
+        uses: actions/cache@88522ab9f39a2ea568f7027eddc7d8d8bc9d59c8 # v3.3.1
+        with:
+          path: ${{ github.workspace }}/dist
+          key: nginx-kubernetes-gateway-${{ github.run_id }}-${{ github.run_number }}
+
+      - name: Docker Buildx
+        uses: docker/setup-buildx-action@16c0bc4a6e6ada2cfd8afd41d22d95379cf7c32a # v2.8.0
+
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@818d4b7b91585d195f67373fd9cb0332e31a7175 # v4.6.0
+        with:
+          images: |
+            name=ghcr.io/nginxinc/nginx-kubernetes-gateway
+          tags: |
+            type=semver,pattern={{version}}
+            type=edge
+            type=ref,event=pr
+            type=ref,event=branch,suffix=-rc,enable=${{ startsWith(github.ref, 'refs/heads/release') }}
+
+      - name: Build Docker Image
+        uses: docker/build-push-action@2eb1c1961a95fc15694676618e422e8ba1d63825 # v4.1.1
+        with:
+          file: build/Dockerfile
+          tags: ${{ steps.meta.outputs.tags }}
+          context: "."
+          target: goreleaser
+          load: true
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          pull: true
+
+      - name: Deploy Kubernetes
+        id: k8s
+        run: |
+          kube_config=${{ github.workspace }}/deploy/helm-chart/kube-${{ github.run_id }}-helm
+          make create-kind-cluster KIND_KUBE_CONFIG=${kube_config}
+          echo "KUBECONFIG=${kube_config}" >> "$GITHUB_ENV"
+          kind load docker-image ${{ steps.meta.outputs.tags }}
+          kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v0.7.1/standard-install.yaml
+          kubectl wait --for=condition=complete job/gateway-api-admission-patch job/gateway-api-admission -n gateway-system
+
+      - name: Install Chart
+        run: >
+          helm install
+          helm-$(echo ${{ steps.meta.outputs.tags }} | cut -d ":" -f 2)
+          .
+          --wait
+          --create-namespace
+          --set controller.image.repository=$(echo ${{ steps.meta.outputs.tags }} | cut -d ":" -f 1)
+          --set controller.image.tag=$(echo ${{ steps.meta.outputs.tags }} | cut -d ":" -f 2)
+          --set service.type=NodePort
+          -n nginx-gateway
+        working-directory: ${{ github.workspace }}/deploy/helm-chart
+
   build:
     name: Build Image
     runs-on: ubuntu-22.04
@@ -235,3 +303,31 @@ jobs:
           name: "trivy-results-nginx-kubernetes-gateway.sarif"
           path: "trivy-results-nginx-kubernetes-gateway.sarif"
         if: always()
+
+  publish-helm:
+    name: Package and Publish Helm Chart
+    runs-on: ubuntu-22.04
+    needs: [vars, helm-tests]
+    if: ${{ github.event_name == 'push' && ! startsWith(github.ref, 'refs/heads/release-') }}
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9 # v3.5.3
+        with:
+          path: nkg
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@465a07811f14bebb1938fbed4728c6a1ff8901fc # v2.2.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Package
+        id: package
+        run: |
+          output=$(helm package ${{ ! startsWith(github.ref, 'refs/tags/') && '--app-version edge --version 0.0.0-edge' || '' }} nkg/deploy/helm-chart)
+          echo "path=$(basename -- $(echo $output | cut -d: -f2))" >> $GITHUB_OUTPUT
+
+      - name: Push to GitHub Container Registry
+        run: |
+          helm push ${{ steps.package.outputs.path }} oci://ghcr.io/nginxinc/charts

.github/workflows/lint.yml

@@ -88,3 +88,12 @@ jobs:
       with:
         config: ${{ github.workspace }}/.markdownlint-cli2.yaml
         globs: '**/*.md'
+
+  chart-lint:
+    name: Chart Lint
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9 # v3.5.3
+      - name: Lint chart
+        run: make lint-helm

.pre-commit-config.yaml

@@ -8,6 +8,7 @@ repos:
       - id: end-of-file-fixer
       - id: check-yaml
         args: [--allow-multiple-documents]
+        exclude: (^deploy/helm-chart/templates)
       - id: check-added-large-files
       - id: check-merge-conflict
       - id: check-case-conflict

Makefile

@@ -2,12 +2,15 @@
 VERSION = edge
 GIT_COMMIT = $(shell git rev-parse HEAD || echo "unknown")
 DATE = $(shell date -u +"%Y-%m-%dT%H:%M:%SZ")
+MANIFEST_DIR = $(shell pwd)/deploy/manifests
+NJS_DIR = $(shell pwd)/internal/mode/static/nginx/modules/src
+CHART_DIR = $(shell pwd)/deploy/helm-chart
 
 # variables that can be overridden by the user
 PREFIX ?= nginx-kubernetes-gateway## The name of the image. For example, nginx-kubernetes-gateway
 TAG ?= $(VERSION:v%=%)## The tag of the image. For example, 0.3.0
 TARGET ?= local## The target of the build. Possible values: local and container
-KIND_KUBE_CONFIG_FOLDER = $${HOME}/.kube/kind## The folder where the kind kubeconfig is stored
+KIND_KUBE_CONFIG=$${HOME}/.kube/kind/config## The location of the kind kubeconfig
 OUT_DIR ?= $(shell pwd)/build/out## The folder where the binary will be stored
 ARCH ?= amd64## The architecture of the image and/or binary. For example: amd64 or arm64
 override DOCKER_BUILD_OPTIONS += --build-arg VERSION=$(VERSION) --build-arg GIT_COMMIT=$(GIT_COMMIT) --build-arg DATE=$(DATE)## The options for the docker build command. For example, --pull
@@ -56,7 +59,7 @@ deps: ## Add missing and remove unused modules, verify deps and download them to
 create-kind-cluster: ## Create a kind cluster
 	$(eval KIND_IMAGE=$(shell grep -m1 'FROM kindest/node' <conformance/tests/Dockerfile | awk -F'[ ]' '{print $$2}'))
 	kind create cluster --image $(KIND_IMAGE)
-	kind export kubeconfig --kubeconfig $(KIND_KUBE_CONFIG_FOLDER)/config
+	kind export kubeconfig --kubeconfig $(KIND_KUBE_CONFIG)
 
 .PHONY: delete-kind-cluster
 delete-kind-cluster: ## Delete kind cluster
@@ -92,5 +95,13 @@ njs-unit-test: ## Run unit tests for the njs httpmatches module
 		node:18 \
 		/bin/bash -c "npm install && npm test && npm run clean"
 
+.PHONY: generate-njs-yaml
+generate-njs-yaml: ## Generate the njs-modules ConfigMap
+	kubectl create configmap njs-modules --from-file=$(NJS_DIR)/httpmatches.js --dry-run=client --output=yaml > $(strip $(MANIFEST_DIR))/njs-modules.yaml
+
+.PHONY: lint-helm
+lint-helm: ## Run the helm chart linter
+	helm lint $(CHART_DIR)
+
 .PHONY: dev-all
 dev-all: deps fmt njs-fmt vet lint unit-test njs-unit-test ## Run all the development checks

conformance/Makefile

@@ -51,7 +51,8 @@ prepare-nkg-dependencies: ## Install NKG dependencies on configured kind cluster
 	./scripts/install-gateway.sh $(GW_API_VERSION)
 	kubectl wait --for=condition=available --timeout=60s deployment gateway-api-admission-server -n gateway-system
 	kubectl apply -f ../deploy/manifests/namespace.yaml
-	kubectl create configmap njs-modules --from-file=../internal/mode/static/nginx/modules/src/httpmatches.js -n nginx-gateway
+	cd .. && make generate-njs-yaml && cd -
+	kubectl apply -f ../deploy/manifests/njs-modules.yaml -n nginx-gateway
 	kubectl apply -f ../deploy/manifests/nginx-conf.yaml
 	kubectl apply -f ../deploy/manifests/rbac.yaml
 	kubectl apply -f ../deploy/manifests/gatewayclass.yaml

deploy/helm-chart/.helmignore

@@ -0,0 +1,2 @@
+# Patterns to ignore when building packages.
+*.png

deploy/helm-chart/Chart.yaml

@@ -0,0 +1,17 @@
+apiVersion: v2
+name: nginx-kubernetes-gateway
+description: NGINX Kubernetes Gateway
+type: application
+version: 0.1.0
+appVersion: "0.4.0"
+home: https://github.com/nginxinc/nginx-kubernetes-gateway
+icon: https://raw.githubusercontent.com/nginxinc/nginx-kubernetes-gateway/tree/main/deploy/helm-chart/chart-icon.png
+sources:
+  - https://github.com/nginxinc/nginx-kubernetes-gateway/tree/main/deploy/helm-chart
+keywords:
+  - kubernetes
+  - gateway
+  - nginx
+maintainers:
+  - name: nginxinc
+    email: [email protected]

deploy/helm-chart/README.md

@@ -0,0 +1,128 @@
+# NGINX Kubernetes Gateway Helm Chart
+
+## Introduction
+
+This chart deploys the NGINX Kubernetes Gateway in your Kubernetes cluster.
+
+## Prerequisites
+
+- [Helm 3.0+](https://helm.sh/docs/intro/install/)
+- [kubectl](https://kubernetes.io/docs/tasks/tools/)
+
+> Note: NGINX Kubernetes Gateway can only run in the `nginx-gateway` namespace. This limitation will be addressed in
+the future releases.
+
+### Installing the Gateway API resources
+
+> Note: The Gateway API resources from the standard channel (the CRDs and the validating webhook) must be installed
+before deploying NGINX Kubernetes Gateway. If they are already installed in your cluster, please ensure they are the
+correct version as supported by the NGINX Kubernetes Gateway -
+[see the Technical Specifications](../../README.md#technical-specifications).
+
+To install the Gateway resources from [the Gateway API repo](https://github.com/kubernetes-sigs/gateway-api), run:
+
+```shell
+kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v0.7.1/standard-install.yaml
+```
+
+## Installing the Chart
+
+### Installing the Chart from the OCI Registry
+
+To install the chart with the release name `my-release` (`my-release` is the name that you choose) into the
+nginx-gateway namespace (with optional `--create-namespace` flag - you can omit if the namespace already exists):
+
+```shell
+helm install my-release oci://ghcr.io/nginxinc/charts/nginx-kubernetes-gateway --version 0.0.0-edge --create-namespace --wait -n nginx-gateway
+```
+
+### Installing the Chart via Sources
+
+#### Pulling the Chart
+
+```shell
+helm pull oci://ghcr.io/nginxinc/charts/nginx-kubernetes-gateway --untar --version 0.0.0-edge
+cd nginx-gateway
+```
+
+#### Installing the Chart
+
+To install the chart with the release name `my-release` (`my-release` is the name that you choose) into the
+nginx-gateway namespace (with optional `--create-namespace` flag - you can omit if the namespace already exists):
+
+```shell
+helm install my-release . --create-namespace --wait -n nginx-gateway
+```
+
+## Upgrading the Chart
+### Upgrading the Gateway Resources
+Before you upgrade a release, ensure the Gateway API resources are the correct version as supported by the NGINX
+Kubernetes Gateway - [see the Technical Specifications](../../README.md#technical-specifications).:
+
+To upgrade the Gateway resources from [the Gateway API repo](https://github.com/kubernetes-sigs/gateway-api), run:
+
+```shell
+kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v0.7.1/standard-install.yaml
+```
+
+### Upgrading the Chart from the OCI Registry
+To upgrade the release `my-release`, run:
+
+```shell
+helm upgrade my-release oci://ghcr.io/nginxinc/charts/nginx-kubernetes-gateway --version 0.0.0-edge -n nginx-gateway
+```
+
+### 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 `my-release`, run:
+
+```shell
+helm upgrade my-release . -n nginx-gateway
+```
+
+## Uninstalling the Chart
+
+To uninstall/delete the release `my-release`:
+
+```shell
+helm uninstall my-release -n nginx-gateway
+```
+
+The command removes 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 resources using [the Gateway API repo](https://github.com/kubernetes-sigs/gateway-api), run:
+
+```shell
+kubectl delete -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v0.7.1/standard-install.yaml
+```
+
+## Configuration
+
+The following tables lists the configurable parameters of the NGINX Kubernetes Gateway chart and their default values.
+
+|Parameter | Description | Default Value |
+| --- | --- | --- |
+|`nginxGateway.image.repository` | The repository for the NGINX Kubernetes Gateway image. | ghcr.io/nginxinc/nginx-kubernetes-gateway |
+|`nginxGateway.image.tag` | The tag for the NGINX Kubernetes Gateway image. | edge |
+|`nginxGateway.image.pullPolicy` | The `imagePullPolicy` for the NGINX Kubernetes Gateway image. | Always |
+|`nginxGateway.gatewayClassName` | The name of the GatewayClass for the NGINX Kubernetes Gateway deployment. | nginx |
+|`nginxGateway.gatewayControllerName` | The name of the Gateway controller. The controller name must be of the form: DOMAIN/PATH. The controller's domain is k8s-gateway.nginx.org. | k8s-gateway.nginx.org/nginx-gateway-controller |
+|`nginx.image.repository` | The repository for the NGINX image. | nginx |
+|`nginx.image.tag` | The tag for the NGINX image. | 1.25 |
+|`nginx.image.pullPolicy` | The `imagePullPolicy` for the NGINX image. | Always |
+|`initContainer.image.repository` | The repository for the `initContainer` image. | busybox |
+|`initContainer.image.tag` | The tag for the `initContainer` image. | 1.36 |
+|`serviceAccount.annotations` | The `annotations` for the ServiceAccount used by the NGINX Kubernetes Gateway deployment. | {} |
+|`serviceAccount.name` | Name of the ServiceAccount used by the NGINX Kubernetes Gateway deployment. | Autogenerated |
+|`service.create` | Creates a service to expose the NGINX Kubernetes Gateway pods. | true |
+|`service.type` | The type of service to create for the NGINX Kubernetes Gateway. | Loadbalancer |
+|`service.externalTrafficPolicy` | The `externalTrafficPolicy` of the service. The value `Local` preserves the client source IP. | Local |
+|`service.annotations` | The `annotations` of the NGINX Kubernetes Gateway service. | {} |
+|`service.ports` | A list of ports to expose through the NGINX Kubernetes Gateway 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 ] |