diff --git a/site-src/guides/index.md b/site-src/guides/index.md index 0c3ca7bc2a..60cbe96e7f 100644 --- a/site-src/guides/index.md +++ b/site-src/guides/index.md @@ -29,6 +29,11 @@ you. ## Installing Gateway API +!!! danger "Upgrades from earlier Experimental Channel releases" + + If you've previously installed an earlier version of experimental channel, + refer to the [v1.1 upgrade notes](#v11-upgrade-notes). + A Gateway API bundle represents the set of CRDs associated with a version of Gateway API. Each release includes two channels with different levels of stability: @@ -40,7 +45,7 @@ beta, including GatewayClass, Gateway, HTTPRoute, and ReferenceGrant. To install this channel, run the following kubectl command: ```bash -kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/standard-install.yaml +kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.1.0/standard-install.yaml ``` ### Install Experimental Channel @@ -58,9 +63,67 @@ documentation](/concepts/versioning/). To install the experimental channel, run the following kubectl command: ```bash -kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/experimental-install.yaml +kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.1.0/experimental-install.yaml ``` +### v1.1 Upgrade Notes +If you are already using previous versions of GRPCRoute or BackendTLSPolicy +experimental channel CRDs from previous Gateway API releases, you'll need to be +careful with this upgrade. If you haven't installed Gateway API before, or have +exclusively used the standard channel of the API, you can skip the rest of this +section. + +#### GRPCRoute +**Summary:** If you're already using v1alpha2 GRPCRoute, stick with the +experimental channel of GRPCRoute in v1.1 until the implementation(s) you're +relying on have been updated to support GRPCRoute v1. + +**Explanation:** With the graduation of GRPCRoute to GA, it is now included in +standard channel. Unfortunately, that can be problematic for anyone that was +already using the experimental channel version of GRPCRoute. As a rule, CRDs in +standard channel do not expose alpha API version to avoid any version +deprecations in that channel. That means that the standard channel version of +GRPCRoute excludes v1alpha2. All implementations of GRPCRoute built before the +v1.1 release of Gateway API would have exclusively relied on v1alpha2 and will +need to be updated to support GRPCRoute v1. Until implementations have been +updated to support v1, you can safely upgrade to the experimental channel +version of GRPCRoute included in v1.1 that exposes both v1 and v1alpha2. + +**Upgrade Sequence:** If you're already using v1alpha2 GRPCRoute, we'd recommend +the following upgrade sequence: + +1. Install *experimental* v1.1 GRPCRoute CRD +2. Update all your manifests to use `v1` instead of `v1alpha2` +3. Upgrade to an implementation that supports GRPCRoute `v1` API Version +4. Install *standard* channel v1.1 GRPCRoute CRD + +#### BackendTLSPolicy +**Summary:** If you've previously installed BackendTLSPolicy, wait until the +implementation(s) you're relying on have been updated to support `v1alpha3` of +the API. When upgrading to an implementation that supports `v1alpha3`, you'll +also need to uninstall the old BackendTLSPolicy CRD before installing the new +one. + +**Explanation:** BackendTLSPolicy had several significant fields renamed in +v1.1, resulting in a version bump to v1alpha3. As this is experimental channel, +we are not providing an in-place upgrade path for this change, instead you'll +need to coordinate the CRD upgrade with the implementation(s) of +BackendTLSPolicy that you're relying on. + +**Upgrade Sequence:** If you're already using v1alpha2 BackendTLSPolicy, we'd +recommend the following upgrade sequence: + +1. Wait for your implementation of choice to release support for v1alpha3 +2. Delete the older pre-v1.1 BackendTLSPolicy CRD (this will also delete all + instances of BackendTLSPolicy in your cluster) +3. Install the new v1.1 BackendTLSPolicy CRD +4. Deploy the version of your implementation that supports BackendTLSPolicy v1alpha3 + +Note that some implementations may prefer switching the order of steps 3 and 4, +it's worth checking with any relevant release notes for your implementation of +choice. + + ### Cleanup After you're done, you can clean up after yourself by uninstalling the Gateway