Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Providing more detailed upgrade notes for v1.1 #3084

Merged
merged 1 commit into from
May 16, 2024
Merged

Providing more detailed upgrade notes for v1.1 #3084

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 65 additions & 2 deletions site-src/guides/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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
Expand All @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you here is the user, but most users today dont install Gateway API CRDs, they rely on implementations to install Gateway API CRDs and in some cases like GKE where the cloud provider installs it

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you have any examples of implementations bundling CRDs? So far we've recommended that CRD management is owned by users or cluster providers (https://gateway-api.sigs.k8s.io/guides/crd-management/#who-should-manage-crds).

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.
Comment on lines +86 to +90
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This basically means that the upgrade path we recommend is to first upgrade the GWAPI CRD to v1.1, and then update the specific implementation, right?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point, pushed a more detailed set of recommended steps that should make this clearer. PTAL.


**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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we mention as point 5 to re-apply all the manifests that were updated in step 2?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need a step to clean up CRDs that are not included in the standard channel?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good questions, re-applying isn't necessary in this case because although the standard channel version of GRPCRoute does not expose v1alpha2 for reads or writes, it does include the schema so it can auto-convert as needed.

I also don't think we need to cover cleaning up old experimental CRDs since this is entirely focused on GRPCRoute, and the experimental version would be cleaned up when upgrading to standard channel. I think it's still valid to have other resources like BackendTLSPolicy that are only in standard channel, though we admittedly have not been very clear about our policy of mixing and matching resources from different channels...

Open to follow ups on either front, but I think this PR is overall a good enough improvement to get in now and then just iterate as needed from here.


#### 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
Expand Down