Doc udpates for Gateway API v1.2 CRDs (#683)

erikfuller · web-flow · commit f54994c709a1 · 2024-12-13T14:08:31.000-08:00
diff --git a/docs/api-types/gateway.md b/docs/api-types/gateway.md
@@ -40,7 +40,7 @@ are assigned, please refer to our [Getting Started Guide](../guides/getstarted.m
 Here is a sample configuration that demonstrates how to set up a `Gateway`:
 
 ```yaml
-apiVersion: gateway.networking.k8s.io/v1beta1
+apiVersion: gateway.networking.k8s.io/v1
 kind: Gateway
 metadata:
   name: my-hotel
diff --git a/docs/api-types/grpc-route.md b/docs/api-types/grpc-route.md
@@ -36,7 +36,7 @@ This allows you to define and manage the routing of gRPC traffic within your Kub
 Here is a sample configuration that demonstrates how to set up a `GRPCRoute` for a HelloWorld gRPC service:
 
 ```yaml
-apiVersion: gateway.networking.k8s.io/v1alpha2
+apiVersion: gateway.networking.k8s.io/v1
 kind: GRPCRoute
 metadata:
   name: greeter-grpc-route
@@ -78,4 +78,4 @@ In this example:
 
 This `GRPCRoute` documentation provides a detailed introduction, feature set, and a basic example of how to configure
 and use the resource within AWS Gateway API Controller project. For in-depth details and specifications, you can refer to the
-official [Gateway API documentation](https://gateway-api.sigs.k8s.io/references/spec/#networking.x-k8s.io/v1alpha2.GRPCRoute).
+official [Gateway API documentation](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.GRPCRoute).
diff --git a/docs/api-types/http-route.md b/docs/api-types/http-route.md
@@ -38,7 +38,7 @@ Here is a sample configuration that demonstrates how to set up an `HTTPRoute` th
 Service and ServiceImport, using rules to determine which backendRef to route traffic to.
 
 ```yaml
-apiVersion: gateway.networking.k8s.io/v1beta1
+apiVersion: gateway.networking.k8s.io/v1
 kind: HTTPRoute
 metadata:
   name: inventory
@@ -83,7 +83,7 @@ Service and ServiceImport, using weighted rules to route more traffic to one bac
 simplify the process of creating blue/green deployments by shifting rule weight from one backendRef to another.
 
 ```yaml
-apiVersion: gateway.networking.k8s.io/v1beta1
+apiVersion: gateway.networking.k8s.io/v1
 kind: HTTPRoute
 metadata:
   name: inventory
@@ -120,4 +120,4 @@ In this example:
 
 This `HTTPRoute` documentation provides a detailed introduction, feature set, and a basic example of how to configure
 and use the resource within AWS Gateway API Controller project. For in-depth details and specifications, you can refer to the
-official [Gateway API documentation](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRoute).
+official [Gateway API documentation](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.HTTPRoute).
diff --git a/docs/api-types/service-import.md b/docs/api-types/service-import.md
@@ -39,7 +39,7 @@ spec: {}
 
 The following example HTTPRoute directs traffic to the above ServiceImport.
 ```yaml
-apiVersion: gateway.networking.k8s.io/v1beta1
+apiVersion: gateway.networking.k8s.io/v1
 kind: HTTPRoute
 metadata:
   name: my-route
diff --git a/docs/contributing/developer.md b/docs/contributing/developer.md
@@ -41,18 +41,13 @@ Before proceeding to the next sections, you need to:
 
 Once cluster is ready, we need to apply CRDs for `gateway-api` resources. First install core `gateway-api` CRDs:
 
-=== "v1 CRDs (latest, recommended)"
+=== "v1.2 CRDs"
     Install the latest `v1` CRDs:
     ```bash
-    kubectl apply -f config/crds/bases/k8s-gateway-v1.0.0.yaml
+    kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd?ref=v1.2.0" | kubectl apply -f -
     ```
     !!! Note
-        Note that v1 CRDs are **not included** in `deploy-*.yaml` and `helm` chart by default. 
-=== "v1beta1 CRDs"
-    Install `gateway-api` `v1beta1` CRDs.
-    ```bash
-    kubectl apply -f config/crds/bases/k8s-gateway-v0.6.1.yaml
-    ```
+        Note that v1 CRDs are **not included** in `deploy-*.yaml` and `helm` chart. 
 
 And install additional CRDs for the controller:
 
diff --git a/docs/guides/custom-domain-name.md b/docs/guides/custom-domain-name.md
@@ -6,7 +6,7 @@ VPC Lattice generates a unique Fully Qualified Domain Name (FQDN) for you; howev
 If you'd prefer to use a custom domain name for a HTTPRoute, you can specify them in hostname field of HTTPRoute. Here is one example:
 
 ```yaml title="custom-domain-route.yaml" hl_lines="7"
-apiVersion: gateway.networking.k8s.io/v1alpha2
+apiVersion: gateway.networking.k8s.io/v1
 kind: HTTPRoute
 metadata:
   name: review
diff --git a/docs/guides/getstarted.md b/docs/guides/getstarted.md
@@ -120,7 +120,7 @@ This example creates a single cluster in a single VPC, then configures two HTTPR
     kubectl get httproute inventory -o yaml 
     ```
     ``` hl_lines="5"
-        apiVersion: gateway.networking.k8s.io/v1beta1
+        apiVersion: gateway.networking.k8s.io/v1
         kind: HTTPRoute
         metadata:
             annotations:
@@ -132,7 +132,7 @@ This example creates a single cluster in a single VPC, then configures two HTTPR
     kubectl get httproute rates -o yaml
     ```
     ``` hl_lines="7"
-        apiVersion: gateway.networking.k8s.io/v1beta1
+        apiVersion: gateway.networking.k8s.io/v1
         kind: HTTPRoute
         metadata:
             annotations:
diff --git a/docs/guides/grpc.md b/docs/guides/grpc.md
@@ -8,7 +8,7 @@ With `GRPCRoute`, you can ensure that your gRPC traffic is directed to the appro
 Kubernetes environment.
 
 For a detailed reference on `GRPCRoute` from the Gateway API, please check the official
-[Gateway API documentation](https://gateway-api.sigs.k8s.io/references/spec/#networking.x-k8s.io/v1alpha2.GRPCRoute).
+[Gateway API documentation](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.GRPCRoute).
 
 ## Setting up a HelloWorld gRPC Server
 
diff --git a/docs/guides/https.md b/docs/guides/https.md
@@ -10,7 +10,7 @@ By adding https to the amazon-vpc-lattice gateway, you can tell the listener to
 The following modifications to the `files/examples/my-hotel-gateway.yaml` file add HTTPs communications:
 
 ```yaml title="my-hotel-gateway.yaml" hl_lines="11 12 13"
-apiVersion: gateway.networking.k8s.io/v1beta1
+apiVersion: gateway.networking.k8s.io/v1
 kind: Gateway
 metadata:
   name: my-hotel
@@ -29,7 +29,7 @@ spec:
 Next, the following modifications to the `files/examples/rate-route-path.yaml` file tell the `rates` HTTPRoute to use HTTPs for communications:
 
 ```yaml title="rate-route-path.yaml" hl_lines="10"
-apiVersion: gateway.networking.k8s.io/v1beta1
+apiVersion: gateway.networking.k8s.io/v1
 kind: HTTPRoute
 metadata:
   name: rates
@@ -55,7 +55,7 @@ If you want to use a custom domain name along with its own certificate, you can:
 The following shows modifications to `files/examples/my-hotel-gateway.yaml` to add a custom certificate:
 
 ```yaml title="my-hotel-gateway.yaml" hl_lines="16 17 18 19"
-apiVersion: gateway.networking.k8s.io/v1beta1
+apiVersion: gateway.networking.k8s.io/v1
 kind: Gateway
 metadata:
   name: my-hotel
@@ -82,7 +82,7 @@ Note that only `Terminate` mode is supported (Passthrough is not supported).
 Next, associate the HTTPRoute to the listener configuration you just configured:
 
 ```yaml title="rate-route-path.yaml" hl_lines="7"
-apiVersion: gateway.networking.k8s.io/v1beta1
+apiVersion: gateway.networking.k8s.io/v1
 kind: HTTPRoute
 metadata:
   name: rates
diff --git a/docs/guides/tls-passthrough.md b/docs/guides/tls-passthrough.md
@@ -25,7 +25,7 @@ kubectl apply -f files/examples/my-gateway-tls-passthrough.yaml
 
 ```
 # tls listener config snips:
-apiVersion: gateway.networking.k8s.io/v1beta1
+apiVersion: gateway.networking.k8s.io/v1
 kind: Gateway
 metadata:
   name: my-hotel-tls-passthrough
diff --git a/docs/guides/upgrading-v1-0-x-to-v1-1-y.md b/docs/guides/upgrading-v1-0-x-to-v1-1-y.md
@@ -0,0 +1,25 @@
+# Update the AWS Gateway API Controller from v1.0.x to v1.1.y
+
+Release `v1.1.0` of the AWS Gateway API Controller is built against `v1.2` of the Gateway API spec, but the controller is also compatible with the `v1.1` Gateway API. It is _not_ compatible the `v1.0` Gateway API.
+
+Previous `v1.0.x` builds of the controller were built against `v1.0` of the Gateway API spec. This guide outlines the controller upgrade process from `v1.0.x` to `v1.1.y`.
+
+# Basic Upgrade Process
+
+1. Back up configuration, in particular GRPCRoute objects
+2. Disable `v1.0.x` controller (e.g. scale to zero)
+3. Update Gateway API CRDs to `v1.1.0`
+4. Deploy and launch `v1.1.y` controller version
+
+With the basic upgrade process, previously created GRPCRoutes on `v1alpha2` will automatically update to `v1` once they are reconciled by the controller. Alternatively, you can manually update your GRPCRoute versions (for example export to YAML, update version number, and apply updates). Creation of new GRPCRoutes objects using `v1alpha2` will be rejected.
+
+# Upgrading to Gateway API `v1.2`
+
+Moving to GatewayAPI `v1.2` can require an additional step as `v1alpha2` GRPCRoute objects have been removed. If GRPCRoute objects are not already on `v1`, you will need to follow steps outlined in the `v1.2.0` [release notes](https://github.com/kubernetes-sigs/gateway-api/releases/tag/v1.2.0).
+
+1. Back up configuration, in particular GRPCRoute objects
+2. Disable `v1.0.x` controller (e.g. scale to zero)
+3. Update Gateway API CRDs to `v1.1.0`
+4. Deploy and launch `v1.1.Y` controller version
+5. Take upgrade steps outlined in `v1.2.0` [Gateway API release notes](https://github.com/kubernetes-sigs/gateway-api/releases/tag/v1.2.0)
+6. Update Gateway API CRDs to `v1.2.0`
diff --git a/files/examples/greeter-grpc-route.yaml b/files/examples/greeter-grpc-route.yaml
@@ -1,4 +1,4 @@
-apiVersion: gateway.networking.k8s.io/v1alpha2
+apiVersion: gateway.networking.k8s.io/v1
 kind: GRPCRoute
 metadata:
   name: greeter-grpc-route
diff --git a/files/examples/inventory-route-bluegreen.yaml b/files/examples/inventory-route-bluegreen.yaml
@@ -1,4 +1,4 @@
-apiVersion: gateway.networking.k8s.io/v1beta1
+apiVersion: gateway.networking.k8s.io/v1
 kind: HTTPRoute
 metadata:
   name: inventory
diff --git a/files/examples/inventory-route.yaml b/files/examples/inventory-route.yaml
@@ -1,4 +1,4 @@
-apiVersion: gateway.networking.k8s.io/v1beta1
+apiVersion: gateway.networking.k8s.io/v1
 kind: HTTPRoute
 metadata:
   name: inventory
diff --git a/files/examples/my-gateway-tls-passthrough.yaml b/files/examples/my-gateway-tls-passthrough.yaml
@@ -1,4 +1,4 @@
-apiVersion: gateway.networking.k8s.io/v1beta1
+apiVersion: gateway.networking.k8s.io/v1
 kind: Gateway
 metadata:
   name: my-hotel-tls-passthrough
diff --git a/files/examples/my-gateway.yaml b/files/examples/my-gateway.yaml
@@ -1,4 +1,4 @@
-apiVersion: gateway.networking.k8s.io/v1beta1
+apiVersion: gateway.networking.k8s.io/v1
 kind: Gateway
 metadata:
   name: my-gateway
diff --git a/files/examples/my-hotel-gateway-multi-listeners.yaml b/files/examples/my-hotel-gateway-multi-listeners.yaml
@@ -1,4 +1,4 @@
-apiVersion: gateway.networking.k8s.io/v1beta1
+apiVersion: gateway.networking.k8s.io/v1
 kind: Gateway
 metadata:
   name: my-hotel
diff --git a/files/examples/my-hotel-gateway.yaml b/files/examples/my-hotel-gateway.yaml
@@ -1,4 +1,4 @@
-apiVersion: gateway.networking.k8s.io/v1beta1
+apiVersion: gateway.networking.k8s.io/v1
 kind: Gateway
 metadata:
   name: my-hotel
diff --git a/files/examples/my-httproute.yaml b/files/examples/my-httproute.yaml
@@ -1,4 +1,4 @@
-apiVersion: gateway.networking.k8s.io/v1beta1
+apiVersion: gateway.networking.k8s.io/v1
 kind: HTTPRoute
 metadata:
   name: my-httproute
diff --git a/files/examples/rate-route-path.yaml b/files/examples/rate-route-path.yaml
@@ -1,4 +1,4 @@
-apiVersion: gateway.networking.k8s.io/v1beta1
+apiVersion: gateway.networking.k8s.io/v1
 kind: HTTPRoute
 metadata:
   name: rates
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -13,6 +13,7 @@ nav:
     - Concepts: concepts/overview.md
   - User Guides:
     - Controller Installation: guides/deploy.md
+    - Upgrading Controller from v1.0.x to v1.1.y: guides/upgrading-v1-0-x-to-v1-1-y.md
     - Getting Started: guides/getstarted.md
     - Cross-Account Sharing: guides/ram-sharing.md
     - Advanced Configurations: guides/advanced-configurations.md
