From 78be712ad863c16e577c8fe23e774b5cc7707d34 Mon Sep 17 00:00:00 2001 From: Saylor Berman Date: Mon, 4 Dec 2023 10:42:39 -0700 Subject: [PATCH] Add more detail to helm install commands (#1299) Problem: Some environments may not want to have a Service installed by default. Our instructions for installing via helm are not clear about this. Solution: Update helm installation docs to be clear about how to alter the installation commands. Also cleaned up the commands/docs a bit. --- deploy/helm-chart/README.md | 63 ++++++++++++++----- .../installation/installing-ngf/helm.md | 54 +++++++++++++--- 2 files changed, 93 insertions(+), 24 deletions(-) diff --git a/deploy/helm-chart/README.md b/deploy/helm-chart/README.md index 2801de2a9..d20d60313 100644 --- a/deploy/helm-chart/README.md +++ b/deploy/helm-chart/README.md @@ -66,15 +66,22 @@ If you are installing the edge version of NGINX Gateway Fabric: ### 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): +To install the latest stable release of NGINX Gateway Fabric in the `nginx-gateway` namespace, run the following command: ```shell -helm install my-release oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --create-namespace --wait -n nginx-gateway +helm install ngf oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway ``` -This will install the latest stable release. To install the latest version from the `main` branch, specify the -`--version 0.0.0-edge` flag when installing. +`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 @@ -90,11 +97,39 @@ This will pull the latest stable release. To pull the latest version from the `m #### 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): +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 my-release . --create-namespace --wait -n nginx-gateway +helm install ngf oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway --set service.create=false ``` ## Upgrading the Chart @@ -145,10 +180,10 @@ Warning: kubectl apply should be used on resource created by either kubectl crea ### Upgrading the Chart from the OCI Registry -To upgrade the release `my-release`, run: +To upgrade the release `ngf`, run: ```shell -helm upgrade my-release oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric -n nginx-gateway +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 @@ -157,10 +192,10 @@ 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 `my-release`, run: +the release `ngf`, run: ```shell -helm upgrade my-release . -n nginx-gateway +helm upgrade ngf . -n nginx-gateway ``` ### Configure Delayed Termination for Zero Downtime Upgrades @@ -216,10 +251,10 @@ being performed on NGF), you may need to configure delayed termination on the NG ## Uninstalling the Chart -To uninstall/delete the release `my-release`: +To uninstall/delete the release `ngf`: ```shell -helm uninstall my-release -n nginx-gateway +helm uninstall ngf -n nginx-gateway kubectl delete ns nginx-gateway kubectl delete crd nginxgateways.gateway.nginx.org ``` diff --git a/site/content/installation/installing-ngf/helm.md b/site/content/installation/installing-ngf/helm.md index 33ebb0162..f79f474ca 100644 --- a/site/content/installation/installing-ngf/helm.md +++ b/site/content/installation/installing-ngf/helm.md @@ -27,10 +27,18 @@ To complete this guide, you'll need to install: - To install the latest stable release of NGINX Gateway Fabric in the **nginx-gateway** namespace, run the following command: ```shell - helm install oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --create-namespace --wait -n nginx-gateway + helm install ngf oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway ``` - Change `` to the name you want for your release. 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. + `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 + ``` ### Install from sources {#install-from-sources} @@ -39,10 +47,36 @@ To complete this guide, you'll need to install: 2. To install the chart into the **nginx-gateway** namespace, run the following command. ```shell - helm install . --create-namespace --wait -n nginx-gateway + helm install ngf . --create-namespace -n nginx-gateway ``` - Change `` to the name you want for your release. If the namespace already exists, you can omit the optional `--create-namespace` flag. + `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 +``` ## Upgrade NGINX Gateway Fabric @@ -89,10 +123,10 @@ To upgrade the CRDs, take the following steps: - To upgrade to the latest stable release of NGINX Gateway Fabric, run: ```shell - helm upgrade oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric -n nginx-gateway + helm upgrade ngf oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric -n nginx-gateway ``` - Replace `` with your chosen release name. + If needed, replace `ngf` with your chosen release name. #### Upgrade from sources @@ -101,10 +135,10 @@ To upgrade the CRDs, take the following steps: 1. To upgrade, run: the following command: ```shell - helm upgrade . -n nginx-gateway + helm upgrade ngf . -n nginx-gateway ``` - Replace `` with your chosen release name. + If needed, replace `ngf` with your chosen release name. ## Delay pod termination for zero downtime upgrades {#configure-delayed-pod-termination-for-zero-downtime-upgrades} @@ -163,10 +197,10 @@ Follow these steps to uninstall NGINX Gateway Fabric and Gateway API from your K - To uninstall NGINX Gateway Fabric, run: ```shell - helm uninstall -n nginx-gateway + helm uninstall ngf -n nginx-gateway ``` - Replace `` with your chosen release name. + If needed, replace `ngf` with your chosen release name. 2. **Remove namespace and CRDs:**