Fix installation docs for mismatched versions

Problem: Our installation docs suggested installing Gateway API v1 and NGF v1, which are not compatible. Solution: Fix the docs to mention both stable and edge versions, with proper versioning. Also updated the release process doc to ensure these are updated at release time as needed.
nginx · Nov 30, 2023 · c2f5de8 · c2f5de8
1 parent a5ae669
commit c2f5de8
Show file tree

Hide file tree

Showing 6 changed files with 129 additions and 67 deletions.
diff --git a/deploy/helm-chart/README.md b/deploy/helm-chart/README.md
@@ -32,22 +32,29 @@ This chart deploys the NGINX Gateway Fabric in your Kubernetes cluster.
 
 > **Note**
 >
-> The Gateway API resources 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 -
+> 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).
 
-To install the Gateway API CRDs from [the Gateway API repo](https://github.com/kubernetes-sigs/gateway-api), run:
+If installing the latest stable release of NGINX Gateway Fabric, ensure you are deploying its supported version of
+the Gateway API resources:
 
-```shell
-kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/standard-install.yaml
-```
+  ```shell
+  kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v0.8.1/standard-install.yaml
+  ```
 
-If you are running on Kubernetes 1.23 or 1.24, you also need to install the validating webhook. To do so, run:
+If you are installing the edge version of NGINX Gateway Fabric:
 
-```shell
-kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/webhook-install.yaml
-```
+  ```shell
+  kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/standard-install.yaml
+  ```
+
+  If you are running on Kubernetes 1.23 or 1.24, you also need to install the validating webhook. To do so, run:
+
+  ```shell
+  kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/webhook-install.yaml
+  ```
 
 > **Important**
 >

diff --git a/docs/developer/release-process.md b/docs/developer/release-process.md
@@ -36,26 +36,29 @@ To create a new release, follow these steps:
        URLs to point at `vX.Y.Z`, and bump the `version`.
     2. Adjust the `VERSION` variable in the [Makefile](/Makefile) and the `TAG` in the
        [conformance tests Makefile](/conformance/Makefile) to `X.Y.Z`.
-    3. Update the tag of NGF container images used in the Helm [values.yaml](/deploy/helm-chart/values.yaml) file, the
-       [provisioner manifest](/conformance/provisioner/provisioner.yaml), and all docs to `X.Y.Z`.
+    3. Update the tag of NGF container images used in the Helm [values.yaml](/deploy/helm-chart/values.yaml) file,
+       the [provisioner manifest](/conformance/provisioner/provisioner.yaml), and all docs to `X.Y.Z`.
     4. Ensure that the `imagePullPolicy` is `IfNotPresent` in the Helm [values.yaml](/deploy/helm-chart/values.yaml)
        file.
     5. Generate the installation manifests by running `make generate-manifests`.
     6. Modify any `git clone` instructions to use `vX.Y.Z` tag.
     7. Modify any docs links that refer to `main` to instead refer to `vX.Y.Z`.
-    8. Update the [README](/README.md) to include information about the release.
-    9. Update the [changelog](/CHANGELOG.md). The changelog includes only important (from the user perspective)
-       changes to NGF. This is in contrast with the autogenerated full changelog, which is created in the next step. As
-       a starting point, copy the important features, bug fixes, and dependencies from the autogenerated draft of the
-       full changelog. This draft can be found under
-       the [GitHub releases](https://github.com/nginxinc/nginx-gateway-fabric/releases) after the release branch is
-       created. Use the previous changelog entries for formatting and content guidance.
+    8. Update any installation instructions to ensure that the supported Gateway API and NGF versions are correct.
+       Specifically, helm README and `site/content/includes/installation/install-gateway-api-resources.md`.
+    9. Update the [README](/README.md) to include information about the release.
+    10. Update the [changelog](/CHANGELOG.md). The changelog includes only important (from the user perspective)
+        changes to NGF. This is in contrast with the autogenerated full changelog, which is created in the next
+        step. As a starting point, copy the important features, bug fixes, and dependencies from the autogenerated
+        draft of the full changelog. This draft can be found under
+        the [GitHub releases](https://github.com/nginxinc/nginx-gateway-fabric/releases) after the release branch is
+        created. Use the previous changelog entries for formatting and content guidance.
 7. Create and push the release tag in the format `vX.Y.Z`. As a result, the CI/CD pipeline will:
     - Build NGF container images with the release tag `X.Y.Z` and push it to the registry.
     - Package and publish the Helm chart to the registry.
     - Create a GitHub release with an autogenerated changelog and attached release artifacts.
-8. Prepare and merge a PR into the main branch to update the [README](/README.md) to include the information about the
-   latest release and also the [changelog](/CHANGELOG.md).
+8. Prepare and merge a PR into the main branch to update the [README](/README.md) to include the information about
+   the latest release and also the [changelog](/CHANGELOG.md). Also update any installation instructions to ensure
+   that the supported Gateway API and NGF versions are correct. Specifically, helm README and `site/content/includes/installation/install-gateway-api-resources.md`.
 9. Close the issue created in Step 1.
 10. Ensure that the [associated milestone](https://github.com/nginxinc/nginx-gateway-fabric/milestones) is closed.
 11. Verify that published artifacts in the release can be installed properly.

diff --git a/site/content/includes/installation/install-gateway-api-resources.md b/site/content/includes/installation/install-gateway-api-resources.md
@@ -0,0 +1,30 @@
+---
+docs:
+---
+
+{{<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).{{</note>}}
+
+**Stable release**
+
+If installing the latest stable release of NGINX Gateway Fabric, ensure you are deploying its supported version of
+the Gateway API resources:
+
+```shell
+kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v0.8.1/standard-install.yaml
+```
+
+**Edge version**
+
+If installing the edge version of NGINX Gateway Fabric from the **main** branch:
+
+```shell
+kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/standard-install.yaml
+```
+
+If you are running on Kubernetes 1.23 or 1.24, you also need to install the validating webhook. To do so, run:
+
+```shell
+kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/webhook-install.yaml
+```
+
+{{< important >}}The validating webhook is not needed if you are running Kubernetes 1.25+. Validation is done using CEL on the CRDs. See the [resource validation doc]({{< relref "/overview/resource-validation.md" >}}) for more information.{{< /important >}}
diff --git a/...n/helm/uninstall-gateway-api-resources.md → ...lation/uninstall-gateway-api-resources.md b/...n/helm/uninstall-gateway-api-resources.md → ...lation/uninstall-gateway-api-resources.md
@@ -2,16 +2,28 @@
 docs:
 ---
 
-To uninstall the Gateway API resources, including the CRDs and the validating webhook, run:
-
    {{<warning>}}This will remove all corresponding custom resources in your entire cluster, across all namespaces. Double-check to make sure you don't have any custom resources you need to keep, and confirm that there are no other Gateway API implementations active in your cluster.{{</warning>}}
 
+   To uninstall the Gateway API resources, including the CRDs and the validating webhook, run the following:
+
+   **Stable release**
+
+   If you were running the latest stable release version of NGINX Gateway Fabric:
+
+   ```shell
+   kubectl delete -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v0.8.1/standard-install.yaml
+   ```
+
+   **Edge version**
+
+   If you were running the edge version of NGINX Gateway Fabric from the **main** branch:
+
    ```shell
    kubectl delete -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/standard-install.yaml
    ```
 
 
-If you are running on Kubernetes 1.23 or 1.24, you also need to delete the validating webhook. To do so, run:
+   If you are running on Kubernetes 1.23 or 1.24, you also need to delete the validating webhook. To do so, run:
 
    ```shell
    kubectl delete -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/webhook-install.yaml

diff --git a/site/content/installation/installing-ngf/helm.md b/site/content/installation/installing-ngf/helm.md
@@ -18,6 +18,10 @@ To complete this guide, you'll need to install:
 
 ## Deploy NGINX Gateway Fabric
 
+### Installing the Gateway API resources
+
+{{<include "installation/install-gateway-api-resources.md" >}}
+
 ### Install from the OCI registry
 
 - To install the latest stable release of NGINX Gateway Fabric in the **nginx-gateway** namespace, run the following command:
@@ -175,7 +179,7 @@ Follow these steps to uninstall NGINX Gateway Fabric and Gateway API from your K
 
 3. **Remove the Gateway API resources:**
 
-   - {{<include "installation/helm/uninstall-gateway-api-resources.md" >}}
+   - {{<include "installation/uninstall-gateway-api-resources.md" >}}
 
 ## Next steps
 

diff --git a/site/content/installation/installing-ngf/manifests.md b/site/content/installation/installing-ngf/manifests.md
@@ -19,53 +19,59 @@ To complete this guide, you'll need to install:
 
 Deploying NGINX Gateway Fabric with Kubernetes manifests takes only a few steps. With manifests, you can configure your deployment exactly how you want. Manifests also make it easy to replicate deployments across environments or clusters, ensuring consistency.
 
-{{<note>}}By default, NGINX Gateway Fabric is installed in the **nginx-gateway** namespace. You can deploy in another namespace by modifying the manifest files.{{</note>}}
+### 1. Install the Gateway API resources
 
-1. **Install the Gateway API resources:**
+{{<include "installation/install-gateway-api-resources.md" >}}
 
-   - Install the Gateway API CRDs from [the Gateway API repo](https://github.com/kubernetes-sigs/gateway-api):
+### 2. Deploy the NGINX Gateway Fabric CRDs
+
+#### Stable release
 
    ```shell
-   kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/standard-install.yaml
+   kubectl apply -f https://github.com/nginxinc/nginx-gateway-fabric/releases/download/v1.0.0/crds.yaml
    ```
 
-   - If you are running on Kubernetes 1.23 or 1.24, you also need to install the validating webhook. To do so, run:
+#### Edge version
 
    ```shell
-   kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/webhook-install.yaml
+   git clone https://github.com/nginxinc/nginx-gateway-fabric.git
+   cd nginx-gateway-fabric
    ```
 
-   {{< important >}}The validating webhook is not needed if you are running Kubernetes 1.25+. Validation is done using CEL on the CRDs. See the [resource validation doc]({{< relref "/overview/resource-validation.md" >}}) for more information. {{< /important >}}
+   ```shell
+   kubectl apply -f deploy/manifests/crds
+   ```
 
-1. **Deploy the NGINX Gateway Fabric CRDs:**
+### 3. Deploy NGINX Gateway Fabric
 
-   - Next, deploy the NGINX Gateway Fabric CRDs:
+   {{<note>}}By default, NGINX Gateway Fabric is installed in the **nginx-gateway** namespace. You can deploy in another namespace by modifying the manifest files.{{</note>}}
 
-     ```shell
-     kubectl apply -f https://github.com/nginxinc/nginx-gateway-fabric/releases/download/v1.0.0/crds.yaml
-     ```
+#### Stable release
 
-1. **Deploy NGINX Gateway Fabric:**
+   ```shell
+   kubectl apply -f https://github.com/nginxinc/nginx-gateway-fabric/releases/download/v1.0.0/nginx-gateway.yaml
+   ```
 
-   - Then, deploy NGINX Gateway Fabric:
+#### Edge version
 
-     ```shell
-     kubectl apply -f https://github.com/nginxinc/nginx-gateway-fabric/releases/download/v1.0.0/nginx-gateway.yaml
-     ```
+   ```shell
+   kubectl apply -f deploy/manifests/nginx-gateway.yaml
+   ```
 
-1. **Verify the Deployment:**
-   - To confirm that NGINX Gateway Fabric is running, check the pods in the `nginx-gateway` namespace:
+### 4. Verify the Deployment
 
-     ```shell
-     kubectl get pods -n nginx-gateway
-     ```
+To confirm that NGINX Gateway Fabric is running, check the pods in the `nginx-gateway` namespace:
 
-     The output should look similar to this (note that the pod name will include a unique string):
+   ```shell
+   kubectl get pods -n nginx-gateway
+   ```
 
-     ```text
-     NAME                             READY   STATUS    RESTARTS   AGE
-     nginx-gateway-5d4f4c7db7-xk2kq   2/2     Running   0          112s
-     ```
+   The output should look similar to this (note that the pod name will include a unique string):
+
+   ```text
+   NAME                             READY   STATUS    RESTARTS   AGE
+   nginx-gateway-5d4f4c7db7-xk2kq   2/2     Running   0          112s
+   ```
 
 
 ## Upgrade NGINX Gateway Fabric
@@ -77,7 +83,7 @@ To upgrade NGINX Gateway Fabric and get the latest features and improvements, ta
 1. **Upgrade Gateway API resources:**
 
    - Verify that your NGINX Gateway Fabric version is compatible with the Gateway API resources. Refer to the [Technical Specifications]({{< relref "reference/technical-specifications.md" >}}) for details.
-   - Review the [release notes](https://github.com/kubernetes-sigs/gateway-api/releases/tag/v1.0.0) for any important upgrade-specific information.
+   - Review the [release notes](https://github.com/kubernetes-sigs/gateway-api/releases) for any important upgrade-specific information.
    - To upgrade the Gateway API resources, run:
 
       ```shell
@@ -86,30 +92,30 @@ To upgrade NGINX Gateway Fabric and get the latest features and improvements, ta
 
    - If you are running on Kubernetes 1.23 or 1.24, you also need to update the validating webhook:
 
-   ```shell
-    kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/webhook-install.yaml
-   ```
+      ```shell
+      kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/webhook-install.yaml
+      ```
 
    - If you are running on Kubernetes 1.25 or newer and have the validating webhook installed, you should remove the
    webhook:
 
-   ```shell
-    kubectl delete -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/webhook-install.yaml
-   ```
+      ```shell
+      kubectl delete -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/webhook-install.yaml
+      ```
 
 1. **Upgrade NGINX Gateway Fabric CRDs:**
    - To upgrade the Custom Resource Definitions (CRDs), run:
 
-     ```shell
-     kubectl apply -f https://github.com/nginxinc/nginx-gateway-fabric/releases/download/v1.0.0/crds.yaml
-     ```
+      ```shell
+      kubectl apply -f https://github.com/nginxinc/nginx-gateway-fabric/releases/download/v1.0.0/crds.yaml
+      ```
 
 1. **Upgrade NGINX Gateway Fabric deployment:**
    - To upgrade the deployment, run:
 
-     ```shell
-     kubectl apply -f https://github.com/nginxinc/nginx-gateway-fabric/releases/download/v1.0.0/nginx-gateway.yaml
-     ```
+      ```shell
+      kubectl apply -f https://github.com/nginxinc/nginx-gateway-fabric/releases/download/v1.0.0/nginx-gateway.yaml
+      ```
 
 ## Delay pod termination for zero downtime upgrades {#configure-delayed-pod-termination-for-zero-downtime-upgrades}
 
@@ -179,7 +185,7 @@ Follow these steps to uninstall NGINX Gateway Fabric and Gateway API from your K
 
 1. **Remove the Gateway API resources:**
 
-   - {{<include "installation/helm/uninstall-gateway-api-resources.md" >}}
+   - {{<include "installation/uninstall-gateway-api-resources.md" >}}
 
 ## Next steps