From 51bf5d12dd9284f384c5d2f89ba88c3c7bc10aa6 Mon Sep 17 00:00:00 2001 From: Sarah Alsmiller Date: Fri, 22 Apr 2022 13:06:32 -0500 Subject: [PATCH 01/19] add upgrade path documentation --- .../api-gateway/upgrade-specific-versions.mdx | 180 ++++++++++++++++++ website/data/docs-nav-data.json | 4 + 2 files changed, 184 insertions(+) create mode 100644 website/content/docs/api-gateway/upgrade-specific-versions.mdx diff --git a/website/content/docs/api-gateway/upgrade-specific-versions.mdx b/website/content/docs/api-gateway/upgrade-specific-versions.mdx new file mode 100644 index 0000000000..b2ef871f32 --- /dev/null +++ b/website/content/docs/api-gateway/upgrade-specific-versions.mdx @@ -0,0 +1,180 @@ +--- +layout: docs +page_title: Upgrading Specific Versions +description: >- + Consul api gateway versions v0.2.x introduced a change to namespace backend ref + enforcement that will potentially break any routes created with a cross namespace in + v0.1.0. This documents the flow for finding and remediating any potentially + broken routes +--- + +# Upgrading Specific Versions + + +## Consul API Gateway v0.1.0 + +This guide explains how to best upgrade a Consul API Gateway deployment that is currently +running v0.1.0 to all future versions. v0.2.0 introduced a breaking change that +causes routes defined with a BackendRef defined in a different namespace to +require a [ReferencePolicy](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferencePolicy) +that explicitly allows traffic from the route's namespace to the BackendRef's namespace. + + + +## Requirements + +- The consul-api-gateway should be running version v0.1.0. If the version is different, follow the normal upgrade path. +- [jq](https://stedolan.github.io/jq/download/) is installed on the users CLI + +Note, as of writing, this is the only upgrade path documented as v0.1.0 is the only currently released version. Normal upgrade path will be documented +in future releases + +## Pre-requisites + +In order to follow this guide, the following conditions must be true: + +- You have the ability to run Kubectl CLI commands +- Your kubectl config is already configured to point at the cluster with the installation you are upgrading +- You have HTTPRoute.read, TCPRoute.read and ReferencePolicy.create rights on your Kubernetes cluster + + +## Procedures + +**1.** Optional, double check the current version of the consul-api-gateway with the following command: + +``` +$ kubectl get deployment --namespace consul consul-api-gateway-controller --output=jsonpath= "{@.spec.template.spec.containers[?(@.name=='api-gateway-controller')].image}" +``` + +If the output looks as follows + +```log +"hashicorp/consul-api-gateway:0.1.0" +``` + + continue following this upgrade path. + +**2.** Run the following command to retrieve all routes defined with a cross namespace: + +```shell-session +$ kubectl get HttpRoute,TcpRoute -o json -A | jq -r '.items[] | {name: .metadata.name, namespace: .metadata.namespace, kind: .kind, crossNamespaceBackendReferences: ( .metadata.namespace as $parentnamespace | .spec.rules[] .backendRefs[] | select(.namespace != null and .namespace != $parentnamespace ) )} ' +``` + +Note, the above command will retrieve all HTTPRoutes and TCPRoutes. TLSRoutes and UDPRoutes are not supported in v0.1.0. + +If your output is empty, you can skip to the last step; otherwise, you have existing routes that require a new ReferencePolicy. In this case, your output will appear similar to the following: + +```log +{ + "name": "example-breaking-http-route", + "namespace": "example-namespace", + "kind": "HTTPRoute", + "crossNamespaceBackendReferences": { + "group": "", + "kind": "Service", + "name": "web-backend", + "namespace": "gateway-namespace", + "port": 8080, + "weight": 1 + } +} +{ + "name": "example-breaking-tcp-route", + "namespace": "a-different-namespace", + "kind": "TCPRoute", + "crossNamespaceBackendReferences": { + "group": "", + "kind": "Service", + "name": "web-backend", + "namespace": "gateway-namespace", + "port": 8080, + "weight": 1 + } +} +``` + +**3.** Create a ReferencePolicy to allow cross namespace traffic for each route service pair. + +Using the above output as a guide, create a [ReferencePolicy](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferencePolicy) to allow cross namespace traffic. +You will need to create a reference policy that explicitly allows each cross namespace route to service pair to prevent the route from breaking. If you've already created a ReferencePolicy you can skip this step. + +For example, the above output would require a reference policy that looks as follows. + +Note, the ReferencePolicy should be created in the same namespace that it is allowing traffic to + + + + +apiVersion: gateway.networking.k8s.io/v1alpha2 +kind: ReferencePolicy +metadata: + name: reference-policy + namespace: gateway-namespace +spec: + from: + - group: gateway.networking.k8s.io + kind: HTTPRoute + namespace: example-namespace + - group: gateway.networking.k8s.io + kind: TCPRoute + namespace: a-different-namespace + to: + - group: "" + kind: Service + name: web-backend + + +Edit your ReferencePolicy so all routes are allowed and then save into a file called referencepolicy.yaml + +Run the following command to apply it to your cluster + +```shell-session +$ kubectl apply -f referencepolicy.yaml +``` + +Repeat as needed until all of your cross namespace routes have defined reference policys. + +**4.** Upgrade your deployment to v.0.2.0. + +Install the updated CRDs into your cluster + +``` shell-session +$ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=0.2.0" +``` + +**5.** Helm upgrade consul + +Upgrade your consul installation using helm. + +~> Warning: This will call the API Gateway controller to be shut down and restart with the new version + +```shell-session +$ helm upgrade --values values.yaml --namespace consul --version hashicorp/consul +``` + +**6.** Refresh gateway deployments +Because [the gateway class is immutable](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io%2fv1alpha2.GatewayClass), once you've upgraded your CRD installation, in order to see the effects on prexisting gateways, you will need to delete and recreate any gateways. + +To accomplish this you can run the following two commands + +~> Warning: This will delete and recreate your gateway. + + +```shell-session +$ kubectl delete -f +$ kubectl create -f +``` + + + +~> Warning: Optionally you might want to delete and recreate your routes following the same pattern, as when you update your +gateway, it might take a long time for it's attached routes to reconcile and start reporting bind errors. + + +## Post-Upgrade Configuration Changes + +No configuration changes are required for this upgrade. diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 52ef17c454..79dbb5f0f1 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -392,6 +392,10 @@ { "title": "Common Errors", "path": "api-gateway/common-errors" + }, + { + "title": "Upgrading Specific Versions", + "path": "api-gateway/upgrade-specific-versions" } ] }, From 81d98e4310e04eab36ac9cf811a5568c45e5f497 Mon Sep 17 00:00:00 2001 From: Sarah Alsmiller Date: Tue, 26 Apr 2022 17:56:50 -0500 Subject: [PATCH 02/19] fix upgrade path documentation --- .../api-gateway/upgrade-specific-versions.mdx | 186 ++++++++++++++---- 1 file changed, 143 insertions(+), 43 deletions(-) diff --git a/website/content/docs/api-gateway/upgrade-specific-versions.mdx b/website/content/docs/api-gateway/upgrade-specific-versions.mdx index b2ef871f32..3bce62a34b 100644 --- a/website/content/docs/api-gateway/upgrade-specific-versions.mdx +++ b/website/content/docs/api-gateway/upgrade-specific-versions.mdx @@ -2,34 +2,34 @@ layout: docs page_title: Upgrading Specific Versions description: >- - Consul api gateway versions v0.2.x introduced a change to namespace backend ref - enforcement that will potentially break any routes created with a cross namespace in - v0.1.0. This documents the flow for finding and remediating any potentially - broken routes + Guide to updating specific versions of the Consul API Gateway that differ from the standard upgrade path --- # Upgrading Specific Versions +This guide explains how to upgrade a Consul API Gateway deployment running a specific version +that requires additional steps from the standard upgrade path. + +Note: As of writing, v0.1.0 is the only previous release. A standardized upgrade path will be documented with future releases. + ## Consul API Gateway v0.1.0 -This guide explains how to best upgrade a Consul API Gateway deployment that is currently -running v0.1.0 to all future versions. v0.2.0 introduced a breaking change that -causes routes defined with a BackendRef defined in a different namespace to +Consul API Gateway v0.2.0 introduced a breaking change that causes routes with a BackendRef defined in a different namespace to require a [ReferencePolicy](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferencePolicy) -that explicitly allows traffic from the route's namespace to the BackendRef's namespace. +that explicitly allows traffic from the route's namespace to the BackendRef's namespace. This guide explains how to find all routes +that require a ReferencePolicy and create a matching ReferencePolicy. -## Requirements +### Requirements - The consul-api-gateway should be running version v0.1.0. If the version is different, follow the normal upgrade path. -- [jq](https://stedolan.github.io/jq/download/) is installed on the users CLI +- **Optional** [jq](https://stedolan.github.io/jq/download/) is installed on the users CLI -Note, as of writing, this is the only upgrade path documented as v0.1.0 is the only currently released version. Normal upgrade path will be documented -in future releases -## Pre-requisites + +### Pre-requisites In order to follow this guide, the following conditions must be true: @@ -38,26 +38,125 @@ In order to follow this guide, the following conditions must be true: - You have HTTPRoute.read, TCPRoute.read and ReferencePolicy.create rights on your Kubernetes cluster -## Procedures +### Procedures -**1.** Optional, double check the current version of the consul-api-gateway with the following command: +**1.** Double check the current version of the consul-api-gateway-controller Deployment with the following command: -``` +```shell-session $ kubectl get deployment --namespace consul consul-api-gateway-controller --output=jsonpath= "{@.spec.template.spec.containers[?(@.name=='api-gateway-controller')].image}" ``` -If the output looks as follows +If the output looks as follows: ```log "hashicorp/consul-api-gateway:0.1.0" ``` - continue following this upgrade path. + Continue following this upgrade path. -**2.** Run the following command to retrieve all routes defined with a cross namespace: +**2.** Retrieve all routes that have a backend in a different namespace + +There are two ways to retrieve cross-namespace routes: + +1. Method 1 is more manual but requires no additional dependencies +1. Method 2 is faster but requires that [jq](https://stedolan.github.io/jq/) be installed + +##### Method 1: Manual + +Get all HTTPRoutes and TCPRoutes across all namespaces with the following command: ```shell-session -$ kubectl get HttpRoute,TcpRoute -o json -A | jq -r '.items[] | {name: .metadata.name, namespace: .metadata.namespace, kind: .kind, crossNamespaceBackendReferences: ( .metadata.namespace as $parentnamespace | .spec.rules[] .backendRefs[] | select(.namespace != null and .namespace != $parentnamespace ) )} ' +$ kubectl get HTTPRoute,TCPRoute -o json -A +``` + +If you have any active HTTPRoutes or TCPRoutes, you should receive output that looks as follows. Note that the output has been truncated to show only relevant fields. + +Note that the above command will retrieve only HTTPRoutes and TCPRoutes. TLSRoutes and UDPRoutes are not supported in v0.1.0. + +```yaml +... + +apiVersion: v1 +items: +- apiVersion: gateway.networking.k8s.io/v1alpha2 + kind: HTTPRoute + metadata: + name: example-http-route, + namespace: example-namespace, + ... + spec: + parentRefs: + - group: gateway.networking.k8s.io + kind: Gateway + name: gateway + namespace: gw-ns + rules: + - backendRefs: + - group: "" + kind: Service + name: web-backend + namespace: gateway-namespace + ... + ... +- apiVersion: gateway.networking.k8s.io/v1alpha2 + kind: TCPRoute + metadata: + name: example-tcp-route, + namespace: a-different-namespace, + ... + spec: + parentRefs: + - group: gateway.networking.k8s.io + kind: Gateway + name: gateway + namespace: gateway-namespace + rules: + - backendRefs: + - group: "" + kind: Service + name: web-backend + namespace: gateway-namespace + ... +... + +``` + +For each of the above defined routes, you will need to inspect each of the backendRefs. + +If a backendRef has no namespace field defined or the namespace matches the namespace of the route itself, that backendRef requires no further action. + +If the `backendRef` does have a namespace defined and it does not match the namespace of the parent route, make a note of the backendRef's `group`, `kind`, `name`, and `namespace`, as well as the `kind` and `namespace` of the parent route. +You will need these later. Keep going until you have a list of all routes that match this criteria. The routes above would yield the following: + +```yaml + + example-http-route: + - namespace: example-namespace + kind: HTTPRoute + backendReferences: + - group : "" + kind: Service + name: web-backend + namespace: gateway-namespace + + example-tcp-route: + - namespace: a-different-namespace + kind: HTTPRoute + backendReferences: + - group : "" + kind: Service + name: web-backend + namespace: gateway-namespace +``` + +If after inspecting your routes, your list is empty, you may skip to the last step. + +##### Method 2: Using jq + +Get all HTTPRoutes and TCPRoutes, using [jq](https://stedolan.github.io/jq/) to filter for routes that require a ReferencePolicy. + +```shell-session +$ kubectl get HTTPRoute,TCPRoute -o json -A | jq -r '.items[] | {name: .metadata.name, namespace: .metadata.namespace, kind: .kind, crossNamespaceBackendReferences: ( .metadata.namespace as $parentnamespace | .spec.rules[] .backendRefs[] | select(.namespace != null and .namespace != $parentnamespace ) )} ' ``` Note, the above command will retrieve all HTTPRoutes and TCPRoutes. TLSRoutes and UDPRoutes are not supported in v0.1.0. @@ -66,7 +165,7 @@ If your output is empty, you can skip to the last step; otherwise, you have exis ```log { - "name": "example-breaking-http-route", + "name": "example-http-route", "namespace": "example-namespace", "kind": "HTTPRoute", "crossNamespaceBackendReferences": { @@ -79,7 +178,7 @@ If your output is empty, you can skip to the last step; otherwise, you have exis } } { - "name": "example-breaking-tcp-route", + "name": "example-tcp-route", "namespace": "a-different-namespace", "kind": "TCPRoute", "crossNamespaceBackendReferences": { @@ -93,20 +192,20 @@ If your output is empty, you can skip to the last step; otherwise, you have exis } ``` -**3.** Create a ReferencePolicy to allow cross namespace traffic for each route service pair. +**3.** Create a ReferencePolicy to allow cross namespace traffic for each route service pair -Using the above output as a guide, create a [ReferencePolicy](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferencePolicy) to allow cross namespace traffic. -You will need to create a reference policy that explicitly allows each cross namespace route to service pair to prevent the route from breaking. If you've already created a ReferencePolicy you can skip this step. +Using the list of routes you created earlier as a guide, create a [ReferencePolicy](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferencePolicy) to allow cross namespace traffic. +You will need to create a ReferencePolicy that explicitly allows each cross-namespace route to service pair to prevent the route from breaking. If you've already created a ReferencePolicy, you can skip this step. -For example, the above output would require a reference policy that looks as follows. +For example, the above output would require a ReferencePolicy that looks as follows. -Note, the ReferencePolicy should be created in the same namespace that it is allowing traffic to +Note: The ReferencePolicy should be created in the same namespace as the backend Service. - +```yaml apiVersion: gateway.networking.k8s.io/v1alpha2 kind: ReferencePolicy metadata: @@ -117,24 +216,25 @@ spec: - group: gateway.networking.k8s.io kind: HTTPRoute namespace: example-namespace - - group: gateway.networking.k8s.io - kind: TCPRoute - namespace: a-different-namespace to: - group: "" kind: Service name: web-backend + +``` -Edit your ReferencePolicy so all routes are allowed and then save into a file called referencepolicy.yaml +Edit your ReferencePolicy so your route is allowed and then save into a file called referencepolicy.yaml +Note, Because each ReferencePolicy [only supports one to field and one from field](https://gateway-api.sigs.k8s.io/v1alpha2/api-types/referencepolicy/#api-design-decisions) you +might need to create multiple ReferencePolicys. Run the following command to apply it to your cluster ```shell-session -$ kubectl apply -f referencepolicy.yaml +$ kubectl apply --filename referencepolicy.yaml ``` -Repeat as needed until all of your cross namespace routes have defined reference policys. +Repeat as needed until each of your cross-namespace routes have a corresponding ReferencePolicy. **4.** Upgrade your deployment to v.0.2.0. @@ -144,22 +244,22 @@ Install the updated CRDs into your cluster $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=0.2.0" ``` -**5.** Helm upgrade consul +**5.** Helm upgrade Consul -Upgrade your consul installation using helm. +Upgrade your Consul installation using Helm. -~> Warning: This will call the API Gateway controller to be shut down and restart with the new version +~> This will cause the Consul API Gateway controller to be shut down and restart with the new version ```shell-session $ helm upgrade --values values.yaml --namespace consul --version hashicorp/consul ``` **6.** Refresh gateway deployments -Because [the gateway class is immutable](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io%2fv1alpha2.GatewayClass), once you've upgraded your CRD installation, in order to see the effects on prexisting gateways, you will need to delete and recreate any gateways. +A requirement of the Kubernetes Gateway API specification is that the settings of the [Gateway Class](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io%2fv1alpha2.GatewayClass) are only applied to a gateway when the gateway is created. For that reason, in order to see the effects on preexisting gateways, once you've upgraded your CRD installation, you will need to delete and recreate any gateways. -To accomplish this you can run the following two commands +To accomplish this you can run the following two commands: -~> Warning: This will delete and recreate your gateway. +~> This will delete and recreate your gateway. ```shell-session @@ -171,10 +271,10 @@ $ kubectl create -f remove this warning once updating a gateway triggers reconciliation on child routes ---> -~> Warning: Optionally you might want to delete and recreate your routes following the same pattern, as when you update your -gateway, it might take a long time for it's attached routes to reconcile and start reporting bind errors. +~> Optionally, you might want to delete and recreate your routes following the same pattern, as when you update your +gateway, it might take a long time for its attached routes to reconcile and start reporting bind errors. -## Post-Upgrade Configuration Changes +### Post-Upgrade Configuration Changes No configuration changes are required for this upgrade. From 6782a64f6c6616e80c902519842f5c3a8a96c7ab Mon Sep 17 00:00:00 2001 From: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com> Date: Tue, 26 Apr 2022 22:07:36 -0500 Subject: [PATCH 03/19] Update website/content/docs/api-gateway/upgrade-specific-versions.mdx Co-authored-by: Jeff Apple <79924108+Jeff-Apple@users.noreply.github.com> --- website/content/docs/api-gateway/upgrade-specific-versions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/upgrade-specific-versions.mdx b/website/content/docs/api-gateway/upgrade-specific-versions.mdx index 3bce62a34b..cfe372e2b3 100644 --- a/website/content/docs/api-gateway/upgrade-specific-versions.mdx +++ b/website/content/docs/api-gateway/upgrade-specific-versions.mdx @@ -13,7 +13,7 @@ that requires additional steps from the standard upgrade path. Note: As of writing, v0.1.0 is the only previous release. A standardized upgrade path will be documented with future releases. -## Consul API Gateway v0.1.0 +## Consul API Gateway v0.2.0 Consul API Gateway v0.2.0 introduced a breaking change that causes routes with a BackendRef defined in a different namespace to require a [ReferencePolicy](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferencePolicy) From f61ff69db55f892fabdf61386cd1cdc25c1365ef Mon Sep 17 00:00:00 2001 From: Sarah Alsmiller Date: Tue, 26 Apr 2022 22:23:04 -0500 Subject: [PATCH 04/19] add inlinecode blocks to kubernetes object references --- .../api-gateway/upgrade-specific-versions.mdx | 48 +++++++++---------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/website/content/docs/api-gateway/upgrade-specific-versions.mdx b/website/content/docs/api-gateway/upgrade-specific-versions.mdx index cfe372e2b3..9e670ae38f 100644 --- a/website/content/docs/api-gateway/upgrade-specific-versions.mdx +++ b/website/content/docs/api-gateway/upgrade-specific-versions.mdx @@ -13,18 +13,18 @@ that requires additional steps from the standard upgrade path. Note: As of writing, v0.1.0 is the only previous release. A standardized upgrade path will be documented with future releases. -## Consul API Gateway v0.2.0 +## Consul API Gateway v0.1.0 -Consul API Gateway v0.2.0 introduced a breaking change that causes routes with a BackendRef defined in a different namespace to +Consul API Gateway v0.2.0 introduced a breaking change that causes routes with a `backendRef` defined in a different namespace to require a [ReferencePolicy](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferencePolicy) -that explicitly allows traffic from the route's namespace to the BackendRef's namespace. This guide explains how to find all routes -that require a ReferencePolicy and create a matching ReferencePolicy. +that explicitly allows traffic from the route's namespace to the `backendRef's` namespace. This guide explains how to find all routes +that require a `ReferencePolicy` and create a matching `ReferencePolicy`. ### Requirements -- The consul-api-gateway should be running version v0.1.0. If the version is different, follow the normal upgrade path. +- Consul API Gateway should be running version v0.1.0. If the version is different, follow the normal upgrade path. - **Optional** [jq](https://stedolan.github.io/jq/download/) is installed on the users CLI @@ -35,12 +35,12 @@ In order to follow this guide, the following conditions must be true: - You have the ability to run Kubectl CLI commands - Your kubectl config is already configured to point at the cluster with the installation you are upgrading -- You have HTTPRoute.read, TCPRoute.read and ReferencePolicy.create rights on your Kubernetes cluster +- You have `HTTPRoute.read`, `TCPRoute.read` and `ReferencePolicy.create` rights on your Kubernetes cluster ### Procedures -**1.** Double check the current version of the consul-api-gateway-controller Deployment with the following command: +**1.** Double check the current version of the `consul-api-gateway-controller` `Deployment` with the following command: ```shell-session $ kubectl get deployment --namespace consul consul-api-gateway-controller --output=jsonpath= "{@.spec.template.spec.containers[?(@.name=='api-gateway-controller')].image}" @@ -63,15 +63,15 @@ There are two ways to retrieve cross-namespace routes: ##### Method 1: Manual -Get all HTTPRoutes and TCPRoutes across all namespaces with the following command: +Get all `HTTPRoutes` and `TCPRoutes` across all namespaces with the following command: ```shell-session $ kubectl get HTTPRoute,TCPRoute -o json -A ``` -If you have any active HTTPRoutes or TCPRoutes, you should receive output that looks as follows. Note that the output has been truncated to show only relevant fields. +If you have any active `HTTPRoutes` or `TCPRoutes`, you should receive output that looks as follows. Note that the output has been truncated to show only relevant fields. -Note that the above command will retrieve only HTTPRoutes and TCPRoutes. TLSRoutes and UDPRoutes are not supported in v0.1.0. +Note that the above command will retrieve only `HTTPRoutes` and `TCPRoutes`. `TLSRoutes` and `UDPRoutes` are not supported in v0.1.0. ```yaml ... @@ -121,11 +121,11 @@ items: ``` -For each of the above defined routes, you will need to inspect each of the backendRefs. +For each of the above defined routes, you will need to inspect each of the `backendRefs`. -If a backendRef has no namespace field defined or the namespace matches the namespace of the route itself, that backendRef requires no further action. +If a `backendRef` has no `namespace` field defined or the namespace matches the namespace of the route itself, that `backendRef` requires no further action. -If the `backendRef` does have a namespace defined and it does not match the namespace of the parent route, make a note of the backendRef's `group`, `kind`, `name`, and `namespace`, as well as the `kind` and `namespace` of the parent route. +If the `backendRef` does have a `namespace` defined and it does not match the namespace of the parent route, make a note of the `backendRef`'s `group`, `kind`, `name`, and `namespace`, as well as the `kind` and `namespace` of the parent route. You will need these later. Keep going until you have a list of all routes that match this criteria. The routes above would yield the following: ```yaml @@ -153,15 +153,15 @@ If after inspecting your routes, your list is empty, you may skip to the last st ##### Method 2: Using jq -Get all HTTPRoutes and TCPRoutes, using [jq](https://stedolan.github.io/jq/) to filter for routes that require a ReferencePolicy. +Get all `HTTPRoutes` and `TCPRoutes`, using [jq](https://stedolan.github.io/jq/) to filter for routes that require a `ReferencePolicy`. ```shell-session $ kubectl get HTTPRoute,TCPRoute -o json -A | jq -r '.items[] | {name: .metadata.name, namespace: .metadata.namespace, kind: .kind, crossNamespaceBackendReferences: ( .metadata.namespace as $parentnamespace | .spec.rules[] .backendRefs[] | select(.namespace != null and .namespace != $parentnamespace ) )} ' ``` -Note, the above command will retrieve all HTTPRoutes and TCPRoutes. TLSRoutes and UDPRoutes are not supported in v0.1.0. +Note, the above command will retrieve all `HTTPRoutes` and `TCPRoutes`. `TLSRoutes` and `UDPRoutes` are not supported in v0.1.0. -If your output is empty, you can skip to the last step; otherwise, you have existing routes that require a new ReferencePolicy. In this case, your output will appear similar to the following: +If your output is empty, you can skip to the last step; otherwise, you have existing routes that require a new `ReferencePolicy`. In this case, your output will appear similar to the following: ```log { @@ -192,16 +192,16 @@ If your output is empty, you can skip to the last step; otherwise, you have exis } ``` -**3.** Create a ReferencePolicy to allow cross namespace traffic for each route service pair +**3.** Create a `ReferencePolicy` to allow cross namespace traffic for each route service pair Using the list of routes you created earlier as a guide, create a [ReferencePolicy](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferencePolicy) to allow cross namespace traffic. -You will need to create a ReferencePolicy that explicitly allows each cross-namespace route to service pair to prevent the route from breaking. If you've already created a ReferencePolicy, you can skip this step. +You will need to create a `ReferencePolicy` that explicitly allows each cross-namespace route to service pair to prevent the route from breaking. If you've already created a `ReferencePolicy`, you can skip this step. -For example, the above output would require a ReferencePolicy that looks as follows. +For example, the above output would require a `ReferencePolicy` that looks as follows. -Note: The ReferencePolicy should be created in the same namespace as the backend Service. +Note: The `ReferencePolicy` should be created in the same `namespace` as the backend `Service`. @@ -224,9 +224,9 @@ spec: ``` -Edit your ReferencePolicy so your route is allowed and then save into a file called referencepolicy.yaml -Note, Because each ReferencePolicy [only supports one to field and one from field](https://gateway-api.sigs.k8s.io/v1alpha2/api-types/referencepolicy/#api-design-decisions) you -might need to create multiple ReferencePolicys. +Edit your `ReferencePolicy` so your route is allowed and then save into a file called referencepolicy.yaml +Note, Because each `ReferencePolicy` [only supports one to field and one from field](https://gateway-api.sigs.k8s.io/v1alpha2/api-types/referencepolicy/#api-design-decisions) you +might need to create multiple `ReferencePolicys`. Run the following command to apply it to your cluster @@ -234,7 +234,7 @@ Run the following command to apply it to your cluster $ kubectl apply --filename referencepolicy.yaml ``` -Repeat as needed until each of your cross-namespace routes have a corresponding ReferencePolicy. +Repeat as needed until each of your cross-namespace routes have a corresponding `ReferencePolicy`. **4.** Upgrade your deployment to v.0.2.0. From b278ffe48f596d254064883664ba93cdbb918a28 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Wed, 27 Apr 2022 11:03:14 -0700 Subject: [PATCH 05/19] edits to draft of upgrades --- .../api-gateway/upgrade-specific-versions.mdx | 440 ++++++++---------- website/data/docs-nav-data.json | 2 +- 2 files changed, 201 insertions(+), 241 deletions(-) diff --git a/website/content/docs/api-gateway/upgrade-specific-versions.mdx b/website/content/docs/api-gateway/upgrade-specific-versions.mdx index 9e670ae38f..a2f836f6d2 100644 --- a/website/content/docs/api-gateway/upgrade-specific-versions.mdx +++ b/website/content/docs/api-gateway/upgrade-specific-versions.mdx @@ -1,280 +1,240 @@ --- layout: docs -page_title: Upgrading Specific Versions +page_title: Upgrades description: >- - Guide to updating specific versions of the Consul API Gateway that differ from the standard upgrade path + This topic describes how to upgrade Consul API Gateway. --- -# Upgrading Specific Versions +# Upgrades -This guide explains how to upgrade a Consul API Gateway deployment running a specific version -that requires additional steps from the standard upgrade path. +This topic describes how to upgrade Consul API Gateway. -Note: As of writing, v0.1.0 is the only previous release. A standardized upgrade path will be documented with future releases. +## Breaking Changes +Consul API Gateway v0.2.0 introduces a breaking change for people upgrading from Consul API Gateway v0.1.0. Routes with a `backendRef` defined in a different namespace now require a [`ReferencePolicy`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferencePolicy) that explicitly allows traffic from the route's namespace to the `backendRef`'s namespace. -## Consul API Gateway v0.1.0 +## Requirements -Consul API Gateway v0.2.0 introduced a breaking change that causes routes with a `backendRef` defined in a different namespace to -require a [ReferencePolicy](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferencePolicy) -that explicitly allows traffic from the route's namespace to the `backendRef's` namespace. This guide explains how to find all routes -that require a `ReferencePolicy` and create a matching `ReferencePolicy`. +Ensure that the following requirements are met prior to upgrading: +- Consul API Gateway should be running version v0.1.0. +- You should have the ability to run `kubectl` CLI commands. +- `kubectl` should be configured to point to the cluster containing the installation you are upgrading. +- You should have the following rights on your Kubernetes cluster: + * `HTTPRoute.read` + * `TCPRoute.read` + * `ReferencePolicy.create` +- (Optional) The [jq](https://stedolan.github.io/jq/download/) command line processor for JSON can be installed, which will ease route retrieval during the upgrade process. +## Procedure -### Requirements +1. Verify the current version of the `consul-api-gateway-controller` `Deployment`: -- Consul API Gateway should be running version v0.1.0. If the version is different, follow the normal upgrade path. -- **Optional** [jq](https://stedolan.github.io/jq/download/) is installed on the users CLI + ```shell-session + $ kubectl get deployment --namespace consul consul-api-gateway-controller --output=jsonpath= "{@.spec.template.spec.containers[?(@.name=='api-gateway-controller')].image}" + ``` + You should receive the following response: + ```log + "hashicorp/consul-api-gateway:0.1.0" + ``` -### Pre-requisites +1. Retrieve all routes that have a backend in a different namespace. If you have installed the `jq` utility, you can skip to [step 4](#jq-command). Otherwise, issue the following command to get all `HTTPRoutes` and `TCPRoutes` across all namespaces: -In order to follow this guide, the following conditions must be true: - -- You have the ability to run Kubectl CLI commands -- Your kubectl config is already configured to point at the cluster with the installation you are upgrading -- You have `HTTPRoute.read`, `TCPRoute.read` and `ReferencePolicy.create` rights on your Kubernetes cluster - - -### Procedures - -**1.** Double check the current version of the `consul-api-gateway-controller` `Deployment` with the following command: - -```shell-session -$ kubectl get deployment --namespace consul consul-api-gateway-controller --output=jsonpath= "{@.spec.template.spec.containers[?(@.name=='api-gateway-controller')].image}" -``` - -If the output looks as follows: - -```log -"hashicorp/consul-api-gateway:0.1.0" -``` - - Continue following this upgrade path. - -**2.** Retrieve all routes that have a backend in a different namespace - -There are two ways to retrieve cross-namespace routes: - -1. Method 1 is more manual but requires no additional dependencies -1. Method 2 is faster but requires that [jq](https://stedolan.github.io/jq/) be installed - -##### Method 1: Manual - -Get all `HTTPRoutes` and `TCPRoutes` across all namespaces with the following command: - -```shell-session -$ kubectl get HTTPRoute,TCPRoute -o json -A -``` - -If you have any active `HTTPRoutes` or `TCPRoutes`, you should receive output that looks as follows. Note that the output has been truncated to show only relevant fields. - -Note that the above command will retrieve only `HTTPRoutes` and `TCPRoutes`. `TLSRoutes` and `UDPRoutes` are not supported in v0.1.0. - -```yaml -... - -apiVersion: v1 -items: -- apiVersion: gateway.networking.k8s.io/v1alpha2 - kind: HTTPRoute - metadata: - name: example-http-route, - namespace: example-namespace, - ... - spec: - parentRefs: - - group: gateway.networking.k8s.io - kind: Gateway - name: gateway - namespace: gw-ns - rules: - - backendRefs: - - group: "" - kind: Service - name: web-backend - namespace: gateway-namespace + ```shell-session + $ kubectl get HTTPRoute,TCPRoute -o json -A + ``` + Note that the command only retrieves `HTTPRoutes` and `TCPRoutes`. `TLSRoutes` and `UDPRoutes` are not supported in v0.1.0. + + If you have any active `HTTPRoutes` or `TCPRoutes`, you will receive output similar to the following response. The output has been truncated to show only relevant fields: + + ```yaml + apiVersion: v1 + items: + - apiVersion: gateway.networking.k8s.io/v1alpha2 + kind: HTTPRoute + metadata: + name: example-http-route, + namespace: example-namespace, ... + spec: + parentRefs: + - group: gateway.networking.k8s.io + kind: Gateway + name: gateway + namespace: gw-ns + rules: + - backendRefs: + - group: "" + kind: Service + name: web-backend + namespace: gateway-namespace + ... + ... + - apiVersion: gateway.networking.k8s.io/v1alpha2 + kind: TCPRoute + metadata: + name: example-tcp-route, + namespace: a-different-namespace, + ... + spec: + parentRefs: + - group: gateway.networking.k8s.io + kind: Gateway + name: gateway + namespace: gateway-namespace + rules: + - backendRefs: + - group: "" + kind: Service + name: web-backend + namespace: gateway-namespace + ... ... -- apiVersion: gateway.networking.k8s.io/v1alpha2 - kind: TCPRoute + ``` +1. Inspect the `backendRefs` entries for each of the routes. + + If a `namespace` field is not defined in the `backendRef` or if the namespace matches the namespace of the route, then no additional action is required for the `backendRef`. Otherwise, note the `group`, `kind`, `name`, and `namespace` field values for `backendRef` configurations that have a `namespace` defined that do not match the namespace of the parent route. You must also note the `kind` and `namespace` of the parent route. You will need these to create a `ReferencePolicy` that explicitly allows each cross-namespace route-to-service pair to prevent the route from breaking (see [step 5](#create-reference-policy)). + + After completing this step, you will have a list of all routes similar to the following: + + ```yaml + example-http-route: + - namespace: example-namespace + kind: HTTPRoute + backendReferences: + - group : "" + kind: Service + name: web-backend + namespace: gateway-namespace + + example-tcp-route: + - namespace: a-different-namespace + kind: HTTPRoute + backendReferences: + - group : "" + kind: Service + name: web-backend + namespace: gateway-namespace + ``` + + Skip to [step 8](#step-8) if your list is empty. + + +1. If you have installed [`jq`](https://stedolan.github.io/jq/), issue the following command to get all `HTTPRoutes` and `TCPRoutes` and filter for routes that require a `ReferencePolicy`. + + ```shell-session + $ kubectl get HTTPRoute,TCPRoute -o json -A | jq -r '.items[] | {name: .metadata.name, namespace: .metadata.namespace, kind: .kind, crossNamespaceBackendReferences: ( .metadata.namespace as $parentnamespace | .spec.rules[] .backendRefs[] | select(.namespace != null and .namespace != $parentnamespace ) )} ' + ``` + + Note that the command retrieves all `HTTPRoutes` and `TCPRoutes`. `TLSRoutes` and `UDPRoutes` are not supported in v0.1.0. + + The output will resemble the following response if routes that require a new `ReferencePolicy` are returned: + + ```log + { + "name": "example-http-route", + "namespace": "example-namespace", + "kind": "HTTPRoute", + "crossNamespaceBackendReferences": { + "group": "", + "kind": "Service", + "name": "web-backend", + "namespace": "gateway-namespace", + "port": 8080, + "weight": 1 + } + } + { + "name": "example-tcp-route", + "namespace": "a-different-namespace", + "kind": "TCPRoute", + "crossNamespaceBackendReferences": { + "group": "", + "kind": "Service", + "name": "web-backend", + "namespace": "gateway-namespace", + "port": 8080, + "weight": 1 + } + } + ``` + + If your output is empty, skip to [step 8](#step-8). + + +1. Using the list of routes you created earlier as a guide, create a [`ReferencePolicy`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferencePolicy) to allow cross namespace traffic for each route service pair. + The `ReferencePolicy` explicitly allows each cross-namespace route to service pair to prevent the route from breaking. The `ReferencePolicy` must be created in the same `namespace` as the backend `Service`. + + Skip to the next step if you've already created a `ReferencePolicy`. + + The following example `ReferencePolicy` enables `HTTPRoute` traffic from the `example-namespace` to Kubernetes Services in the `web-backend` namespace: + + + + ```yaml + apiVersion: gateway.networking.k8s.io/v1alpha2 + kind: ReferencePolicy metadata: - name: example-tcp-route, - namespace: a-different-namespace, - ... + name: reference-policy + namespace: gateway-namespace spec: - parentRefs: - - group: gateway.networking.k8s.io - kind: Gateway - name: gateway - namespace: gateway-namespace - rules: - - backendRefs: + from: + - group: gateway.networking.k8s.io + kind: HTTPRoute + namespace: example-namespace + to: - group: "" kind: Service name: web-backend - namespace: gateway-namespace - ... -... + + ``` + -``` +1. If you have already created a `ReferencePolicy`, modify it to allow your route and save it as `referencepolicy.yaml`. Note that each `ReferencePolicy` only supports one `to` field and one `from` field (refer the [`ReferencePolicy`](https://gateway-api.sigs.k8s.io/v1alpha2/api-types/referencepolicy/#api-design-decisions) documentation). As a result, you may need to create multiple `ReferencePolicy`s. -For each of the above defined routes, you will need to inspect each of the `backendRefs`. +1. Issue the following command to apply it to your cluster: -If a `backendRef` has no `namespace` field defined or the namespace matches the namespace of the route itself, that `backendRef` requires no further action. + ```shell-session + $ kubectl apply --filename referencepolicy.yaml + ``` -If the `backendRef` does have a `namespace` defined and it does not match the namespace of the parent route, make a note of the `backendRef`'s `group`, `kind`, `name`, and `namespace`, as well as the `kind` and `namespace` of the parent route. -You will need these later. Keep going until you have a list of all routes that match this criteria. The routes above would yield the following: + Repeat this step as needed until each of your cross-namespace routes have a corresponding `ReferencePolicy`. + -```yaml +1. Issue the following command to install the v.0.2.0 CRDs into your cluster: - example-http-route: - - namespace: example-namespace - kind: HTTPRoute - backendReferences: - - group : "" - kind: Service - name: web-backend - namespace: gateway-namespace + ``` shell-session + $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=0.2.0" + ``` - example-tcp-route: - - namespace: a-different-namespace - kind: HTTPRoute - backendReferences: - - group : "" - kind: Service - name: web-backend - namespace: gateway-namespace -``` +1. Issue the following command to upgrade your Consul installation: -If after inspecting your routes, your list is empty, you may skip to the last step. + ```shell-session + $ helm upgrade --values values.yaml --namespace consul --version hashicorp/consul + ``` + + Note that the upgrade will cause the Consul API Gateway controller shut down and restart with the new version. -##### Method 2: Using jq +1. According to the Kubernetes Gateway API specification, [Gateway Class](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io%2fv1alpha2.GatewayClass) configurations should only be applied to a gateway upon creation. To see the effects on preexisting gateways after upgrading your CRD installation, delete and recreate any gateways by issuing the following commands: -Get all `HTTPRoutes` and `TCPRoutes`, using [jq](https://stedolan.github.io/jq/) to filter for routes that require a `ReferencePolicy`. - -```shell-session -$ kubectl get HTTPRoute,TCPRoute -o json -A | jq -r '.items[] | {name: .metadata.name, namespace: .metadata.namespace, kind: .kind, crossNamespaceBackendReferences: ( .metadata.namespace as $parentnamespace | .spec.rules[] .backendRefs[] | select(.namespace != null and .namespace != $parentnamespace ) )} ' -``` - -Note, the above command will retrieve all `HTTPRoutes` and `TCPRoutes`. `TLSRoutes` and `UDPRoutes` are not supported in v0.1.0. - -If your output is empty, you can skip to the last step; otherwise, you have existing routes that require a new `ReferencePolicy`. In this case, your output will appear similar to the following: - -```log -{ - "name": "example-http-route", - "namespace": "example-namespace", - "kind": "HTTPRoute", - "crossNamespaceBackendReferences": { - "group": "", - "kind": "Service", - "name": "web-backend", - "namespace": "gateway-namespace", - "port": 8080, - "weight": 1 - } -} -{ - "name": "example-tcp-route", - "namespace": "a-different-namespace", - "kind": "TCPRoute", - "crossNamespaceBackendReferences": { - "group": "", - "kind": "Service", - "name": "web-backend", - "namespace": "gateway-namespace", - "port": 8080, - "weight": 1 - } -} -``` - -**3.** Create a `ReferencePolicy` to allow cross namespace traffic for each route service pair - -Using the list of routes you created earlier as a guide, create a [ReferencePolicy](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferencePolicy) to allow cross namespace traffic. -You will need to create a `ReferencePolicy` that explicitly allows each cross-namespace route to service pair to prevent the route from breaking. If you've already created a `ReferencePolicy`, you can skip this step. - -For example, the above output would require a `ReferencePolicy` that looks as follows. - -Note: The `ReferencePolicy` should be created in the same `namespace` as the backend `Service`. - - - -```yaml -apiVersion: gateway.networking.k8s.io/v1alpha2 -kind: ReferencePolicy -metadata: - name: reference-policy - namespace: gateway-namespace -spec: - from: - - group: gateway.networking.k8s.io - kind: HTTPRoute - namespace: example-namespace - to: - - group: "" - kind: Service - name: web-backend - -``` - - -Edit your `ReferencePolicy` so your route is allowed and then save into a file called referencepolicy.yaml -Note, Because each `ReferencePolicy` [only supports one to field and one from field](https://gateway-api.sigs.k8s.io/v1alpha2/api-types/referencepolicy/#api-design-decisions) you -might need to create multiple `ReferencePolicys`. - -Run the following command to apply it to your cluster - -```shell-session -$ kubectl apply --filename referencepolicy.yaml -``` - -Repeat as needed until each of your cross-namespace routes have a corresponding `ReferencePolicy`. - -**4.** Upgrade your deployment to v.0.2.0. - -Install the updated CRDs into your cluster - -``` shell-session -$ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=0.2.0" -``` - -**5.** Helm upgrade Consul - -Upgrade your Consul installation using Helm. - -~> This will cause the Consul API Gateway controller to be shut down and restart with the new version - -```shell-session -$ helm upgrade --values values.yaml --namespace consul --version hashicorp/consul -``` - -**6.** Refresh gateway deployments -A requirement of the Kubernetes Gateway API specification is that the settings of the [Gateway Class](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io%2fv1alpha2.GatewayClass) are only applied to a gateway when the gateway is created. For that reason, in order to see the effects on preexisting gateways, once you've upgraded your CRD installation, you will need to delete and recreate any gateways. - -To accomplish this you can run the following two commands: - -~> This will delete and recreate your gateway. - - -```shell-session -$ kubectl delete -f -$ kubectl create -f -``` - - + ---> -~> Optionally, you might want to delete and recreate your routes following the same pattern, as when you update your -gateway, it might take a long time for its attached routes to reconcile and start reporting bind errors. +1. (Optional) Delete and recreate your routes. Note that it may take several minutes for attached routes to reconcile and start reporting bind errors. + ```shell-session + $ kubectl delete -f + $ kubectl create -f + ``` - -### Post-Upgrade Configuration Changes +## Post-Upgrade Configuration Changes No configuration changes are required for this upgrade. diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 79dbb5f0f1..7063f5a22c 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -394,7 +394,7 @@ "path": "api-gateway/common-errors" }, { - "title": "Upgrading Specific Versions", + "title": "Upgrades", "path": "api-gateway/upgrade-specific-versions" } ] From d3a23229bb36290d1e4986157ede6f47df02931f Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Wed, 27 Apr 2022 14:11:51 -0400 Subject: [PATCH 06/19] Remove Consul pin from installation instructions The consul-k8s chart has the correct version defaulted, and having it pinned here is another thing we have to include in all upgrade instructions --- website/content/docs/api-gateway/consul-api-gateway-install.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/website/content/docs/api-gateway/consul-api-gateway-install.mdx b/website/content/docs/api-gateway/consul-api-gateway-install.mdx index 814959a1f5..724ff89791 100644 --- a/website/content/docs/api-gateway/consul-api-gateway-install.mdx +++ b/website/content/docs/api-gateway/consul-api-gateway-install.mdx @@ -32,7 +32,6 @@ Ensure that the environment you are deploying Consul API Gateway in meets the re ```yaml global: name: consul - image: 'hashicorp/consul:1.11.3' connectInject: enabled: true controller: From 1c17b2c9c3db7816be1da7028e1adb6ae04d061e Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Wed, 27 Apr 2022 14:12:19 -0400 Subject: [PATCH 07/19] Update consul-api-gateway pin in installation instructions --- website/content/docs/api-gateway/consul-api-gateway-install.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/consul-api-gateway-install.mdx b/website/content/docs/api-gateway/consul-api-gateway-install.mdx index 724ff89791..dff99915e5 100644 --- a/website/content/docs/api-gateway/consul-api-gateway-install.mdx +++ b/website/content/docs/api-gateway/consul-api-gateway-install.mdx @@ -38,7 +38,7 @@ Ensure that the environment you are deploying Consul API Gateway in meets the re enabled: true apiGateway: enabled: true - image: hashicorp/consul-api-gateway:0.1.0 + image: hashicorp/consul-api-gateway:0.2.0 ``` From 45be1d370fc342e1b3694f95b9235824df8184ad Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Wed, 27 Apr 2022 14:14:27 -0400 Subject: [PATCH 08/19] Update website/content/docs/api-gateway/upgrade-specific-versions.mdx Co-authored-by: Karl Cardenas --- .../content/docs/api-gateway/upgrade-specific-versions.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/content/docs/api-gateway/upgrade-specific-versions.mdx b/website/content/docs/api-gateway/upgrade-specific-versions.mdx index a2f836f6d2..aac9b77fb0 100644 --- a/website/content/docs/api-gateway/upgrade-specific-versions.mdx +++ b/website/content/docs/api-gateway/upgrade-specific-versions.mdx @@ -231,8 +231,8 @@ Ensure that the following requirements are met prior to upgrading: 1. (Optional) Delete and recreate your routes. Note that it may take several minutes for attached routes to reconcile and start reporting bind errors. ```shell-session - $ kubectl delete -f - $ kubectl create -f + $ kubectl delete --filename + $ kubectl create --filename ``` ## Post-Upgrade Configuration Changes From d2234fc6f78cc518085b6f6e8473a3c35a5836d5 Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Wed, 27 Apr 2022 14:14:36 -0400 Subject: [PATCH 09/19] Update website/content/docs/api-gateway/upgrade-specific-versions.mdx Co-authored-by: Karl Cardenas --- .../content/docs/api-gateway/upgrade-specific-versions.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/content/docs/api-gateway/upgrade-specific-versions.mdx b/website/content/docs/api-gateway/upgrade-specific-versions.mdx index aac9b77fb0..7d4ee60f05 100644 --- a/website/content/docs/api-gateway/upgrade-specific-versions.mdx +++ b/website/content/docs/api-gateway/upgrade-specific-versions.mdx @@ -222,8 +222,8 @@ Ensure that the following requirements are met prior to upgrading: 1. According to the Kubernetes Gateway API specification, [Gateway Class](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io%2fv1alpha2.GatewayClass) configurations should only be applied to a gateway upon creation. To see the effects on preexisting gateways after upgrading your CRD installation, delete and recreate any gateways by issuing the following commands: ```shell-session - $ kubectl delete -f - $ kubectl create -f + $ kubectl delete --filename + $ kubectl create --filename ```