From 336ec9887e40cf2129325c0851931c8c113487ec Mon Sep 17 00:00:00 2001 From: Saylor Berman Date: Tue, 24 Oct 2023 13:56:29 -0600 Subject: [PATCH] Update docs for release (#1189) Updated README, CHANGELOG, and installation docs for the latest release. --- CHANGELOG.md | 41 +++++++++++++++++++++++++++++++ README.md | 10 +++----- docs/developer/release-process.md | 6 +++-- docs/installation.md | 35 ++++++++------------------ 4 files changed, 59 insertions(+), 33 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a93357a12..dd8485a7f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,47 @@ This document includes a curated changelog for each release. We also publish a c a [GitHub release](https://github.com/nginxinc/nginx-gateway-fabric/releases), which, by contrast, is auto-generated and includes links to all PRs that went into the release. +## Release 1.0.0 + +*October 24, 2023* + +This is the official v1.0.0 release of NGINX Gateway Fabric. + +BREAKING CHANGES: + +- Rename the product from NGINX Kubernetes Gateway to NGINX Gateway Fabric. [PR-1070](https://github.com/nginxinc/nginx-gateway-fabric/pull/1070) + +FEATURES: + +- Add readiness probe. [PR-1047](https://github.com/nginxinc/nginx-gateway-fabric/pull/1047) +- Support horizontal scaling. [PR-1048](https://github.com/nginxinc/nginx-gateway-fabric/pull/1048) +- Add NGINX reload metrics. [PR-1049](https://github.com/nginxinc/nginx-gateway-fabric/pull/1049) +- Retry status updater on failures. [PR-1062](https://github.com/nginxinc/nginx-gateway-fabric/pull/1062) +- Add event processing histogram metric. [PR-1134](https://github.com/nginxinc/nginx-gateway-fabric/pull/1134) +- Set Service address in Gateway Status. [PR-1141](https://github.com/nginxinc/nginx-gateway-fabric/pull/1141) + +BUG FIXES: + +- Optimize default NGINX config. [PR-1040](https://github.com/nginxinc/nginx-gateway-fabric/pull/1040) +- Ensure NGINX reload occurs. [PR-1033](https://github.com/nginxinc/nginx-gateway-fabric/pull/1033) +- Fix failure to recover if conf files are unexpectedly removed. [PR-1132](https://github.com/nginxinc/nginx-gateway-fabric/pull/1132) +- Only update a resource's status if it has changed. [PR-1151](https://github.com/nginxinc/nginx-gateway-fabric/pull/1151) + +DOCUMENTATION: + +- Non-functional testing guides and results. [Link](https://github.com/nginxinc/nginx-gateway-fabric/tree/main/tests) + +COMPATIBILITY: + +- The Gateway API version: `0.8.1` +- NGINX version: `1.25.2` +- Kubernetes version: `1.23+` + +CONTAINER IMAGES: + +- Control plane: `ghcr.io/nginxinc/nginx-gateway-fabric:1.0.0` +- Data plane: `ghcr.io/nginxinc/nginx-gateway-fabric/nginx:1.0.0` + ## Release 0.6.0 *August 31, 2023* diff --git a/README.md b/README.md index b97b43aad..e806c33e7 100644 --- a/README.md +++ b/README.md @@ -7,14 +7,11 @@ NGINX Gateway Fabric is an open-source project that provides an implementation o the [Gateway API](https://gateway-api.sigs.k8s.io/) using [NGINX](https://nginx.org/) as the data plane. The goal of this project is to implement the core Gateway APIs -- `Gateway`, `GatewayClass`, `HTTPRoute`, `TCPRoute`, `TLSRoute`, and `UDPRoute` -- to configure an HTTP or TCP/UDP load balancer, reverse-proxy, or API gateway for applications running -on Kubernetes. NGINX Gateway Fabric is currently under development and supports a subset of the Gateway API. +on Kubernetes. NGINX Gateway Fabric supports a subset of the Gateway API. For a list of supported Gateway API resources and features, see the [Gateway API Compatibility](docs/gateway-api-compatibility.md) doc. -> Warning: This project is actively in development (beta feature state) and should not be deployed in a -> production environment. All APIs, SDKs, designs, and packages are subject to change. - Learn about our [design principles](/docs/developer/design-principles.md) and [architecture](/docs/architecture.md). ## Getting Started @@ -32,7 +29,7 @@ Learn about our [design principles](/docs/developer/design-principles.md) and [a We publish NGINX Gateway Fabric releases on GitHub. See our [releases page](https://github.com/nginxinc/nginx-gateway-fabric/releases). -The latest release is [0.6.0](https://github.com/nginxinc/nginx-gateway-fabric/releases/tag/v0.6.0). +The latest release is [1.0.0](https://github.com/nginxinc/nginx-gateway-fabric/releases/tag/v1.0.0). The edge version is useful for experimenting with new features that are not yet published in a release. To use, choose the *edge* version built from the [latest commit](https://github.com/nginxinc/nginx-gateway-fabric/commits/main) @@ -43,7 +40,7 @@ to the correct versions: | Version | Description | Installation Manifests | Documentation and Examples | |----------------|------------------------------------------|---------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Latest release | For experimental use | [Manifests](https://github.com/nginxinc/nginx-gateway-fabric/tree/v0.6.0/deploy). | [Documentation](https://github.com/nginxinc/nginx-gateway-fabric/tree/v0.6.0/docs). [Examples](https://github.com/nginxinc/nginx-gateway-fabric/tree/v0.6.0/examples). | +| Latest release | For production use | [Manifests](https://github.com/nginxinc/nginx-gateway-fabric/tree/v1.0.0/deploy). | [Documentation](https://github.com/nginxinc/nginx-gateway-fabric/tree/v1.0.0/docs). [Examples](https://github.com/nginxinc/nginx-gateway-fabric/tree/v1.0.0/examples). | | Edge | For experimental use and latest features | [Manifests](https://github.com/nginxinc/nginx-gateway-fabric/tree/main/deploy). | [Documentation](https://github.com/nginxinc/nginx-gateway-fabric/tree/main/docs). [Examples](https://github.com/nginxinc/nginx-gateway-fabric/tree/main/examples). | ### Versioning @@ -66,6 +63,7 @@ The following table lists the software versions NGINX Gateway Fabric supports. | NGINX Gateway Fabric | Gateway API | Kubernetes | NGINX OSS | |--------------------------|-------------|------------|-----------| | Edge | 0.8.1 | 1.23+ | 1.25.2 | +| 1.0.0 | 0.8.1 | 1.23+ | 1.25.2 | | 0.6.0 | 0.8.0 | 1.23+ | 1.25.2 | | 0.5.0 | 0.7.1 | 1.21+ | 1.25.x * | | 0.4.0 | 0.7.1 | 1.21+ | 1.25.x * | diff --git a/docs/developer/release-process.md b/docs/developer/release-process.md index 15287b3f2..695916e83 100644 --- a/docs/developer/release-process.md +++ b/docs/developer/release-process.md @@ -57,11 +57,13 @@ To create a new release, follow these steps: 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). 9. Close the issue created in Step 1. -10. Submit the `conformance-profile.yaml` artifact from the release to the [Gateway API repo](https://github.com/kubernetes-sigs/gateway-api/tree/main/conformance/reports). +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. +12. Submit the `conformance-profile.yaml` artifact from the release to the [Gateway API repo](https://github.com/kubernetes-sigs/gateway-api/tree/main/conformance/reports). - Create a fork of the repository - Name the file `nginxinc-nginx-gateway-fabric.yaml` and set `gatewayAPIVersion` in the file to the supported version by NGF. Also update the site source if necessary (see following example). - - Open a PR. [Example](https://github.com/kubernetes-sigs/gateway-api/pull/2368) + - Open a PR. [Example](https://github.com/kubernetes-sigs/gateway-api/pull/2514) If it's your first time submitting a PR, you will need to sign a CLA using F5, Inc. as the organization. ### Patch Release diff --git a/docs/installation.md b/docs/installation.md index 9ce6a0fde..b42b6f307 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -34,21 +34,6 @@ page. > It is possible to run NGF in a different Namespace, although you'll need to make modifications to the installation > manifests. -1. Clone the repo and change into the `nginx-gateway-fabric` directory: - - ```shell - git clone https://github.com/nginxinc/nginx-gateway-fabric.git - cd nginx-gateway-fabric - ``` - -1. Check out the latest tag (unless you are installing the `edge` version from the `main` branch): - - ```shell - git fetch --tags - latestTag=$(git describe --tags `git rev-list --tags --max-count=1`) - git checkout $latestTag - ``` - 1. Install the Gateway API resources from the standard channel (the CRDs and the validating webhook): ```shell @@ -58,13 +43,13 @@ page. 1. Deploy the NGINX Gateway Fabric CRDs: ```shell - kubectl apply -f deploy/manifests/crds + kubectl apply -f https://github.com/nginxinc/nginx-gateway-fabric/releases/download/v1.0.0/crds.yaml ``` 1. Deploy the NGINX Gateway Fabric: ```shell - kubectl apply -f deploy/manifests/nginx-gateway.yaml + kubectl apply -f https://github.com/nginxinc/nginx-gateway-fabric/releases/download/v1.0.0/nginx-gateway.yaml ``` 1. Confirm the NGINX Gateway Fabric is running in `nginx-gateway` namespace: @@ -101,7 +86,7 @@ Service sets the status field to the IP address and/or Hostname. If no Service e Create a Service with type `NodePort`: ```shell -kubectl apply -f deploy/manifests/service/nodeport.yaml +kubectl apply -f https://raw.githubusercontent.com/nginxinc/nginx-gateway-fabric/v1.0.0/deploy/manifests/service/nodeport.yaml ``` A `NodePort` Service will randomly allocate one port on every Node of the cluster. To access NGINX Gateway Fabric, @@ -114,7 +99,7 @@ Create a Service with type `LoadBalancer` using the appropriate manifest for you - For GCP or Azure: ```shell - kubectl apply -f deploy/manifests/service/loadbalancer.yaml + kubectl apply -f https://raw.githubusercontent.com/nginxinc/nginx-gateway-fabric/v1.0.0/deploy/manifests/service/loadbalancer.yaml ``` Lookup the public IP of the load balancer, which is reported in the `EXTERNAL-IP` column in the output of the @@ -129,7 +114,7 @@ Create a Service with type `LoadBalancer` using the appropriate manifest for you - For AWS: ```shell - kubectl apply -f deploy/manifests/service/loadbalancer-aws-nlb.yaml + kubectl apply -f https://raw.githubusercontent.com/nginxinc/nginx-gateway-fabric/v1.0.0/deploy/manifests/service/loadbalancer-aws-nlb.yaml ``` In AWS, the NLB DNS name will be reported by Kubernetes in lieu of a public IP in the `EXTERNAL-IP` column. To get the @@ -173,7 +158,7 @@ Create a Service with type `LoadBalancer` using the appropriate manifest for you Run the following command to upgrade the NGINX Gateway Fabric CRDs: ```shell - kubectl apply -f deploy/manifests/crds + kubectl apply -f https://github.com/nginxinc/nginx-gateway-fabric/releases/download/v1.0.0/crds.yaml ``` 1. Upgrade NGINX Gateway Fabric Deployment @@ -181,7 +166,7 @@ Create a Service with type `LoadBalancer` using the appropriate manifest for you Run the following command to upgrade NGINX Gateway Fabric: ```shell - kubectl apply -f deploy/manifests/nginx-gateway.yaml + kubectl apply -f https://github.com/nginxinc/nginx-gateway-fabric/releases/download/v1.0.0/nginx-gateway.yaml ``` ### Upgrade NGINX Gateway Fabric using Helm @@ -202,7 +187,7 @@ being performed on NGF), you may need to configure delayed termination on the NG #### Configure Delayed Termination Using Manifests -Edit the `deploy/manifests/nginx-gateway.yaml` to include the following: +Edit the `nginx-gateway.yaml` to include the following: 1. Add `lifecycle` prestop hooks to both the nginx and the nginx-gateway container definitions: @@ -250,11 +235,11 @@ To configure delayed termination on the NGF Pod when the deployment method is He 1. Uninstall the NGINX Gateway Fabric: ```shell - kubectl delete -f deploy/manifests/nginx-gateway.yaml + kubectl delete -f https://github.com/nginxinc/nginx-gateway-fabric/releases/download/v1.0.0/nginx-gateway.yaml ``` ```shell - kubectl delete -f deploy/manifests/crds + kubectl delete -f https://github.com/nginxinc/nginx-gateway-fabric/releases/download/v1.0.0/crds.yaml ``` 1. Uninstall the Gateway API resources from the standard channel (the CRDs and the validating webhook):