From ba7115a1df52ebb08bfe38acc84d9b7c4550a209 Mon Sep 17 00:00:00 2001 From: Sarah Alsmiller Date: Mon, 13 Jun 2022 16:05:21 -0500 Subject: [PATCH] updated referencepolicy to referencegrant, added v0.3.0 upgrade instructions --- .../api-gateway/upgrade-specific-versions.mdx | 221 ++++++++++++++++-- 1 file changed, 201 insertions(+), 20 deletions(-) diff --git a/website/content/docs/api-gateway/upgrade-specific-versions.mdx b/website/content/docs/api-gateway/upgrade-specific-versions.mdx index fa38c15bd8..86363f5c23 100644 --- a/website/content/docs/api-gateway/upgrade-specific-versions.mdx +++ b/website/content/docs/api-gateway/upgrade-specific-versions.mdx @@ -9,9 +9,185 @@ description: >- This topic describes how to upgrade Consul API Gateway. -## 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. +## v0.3.0 + +Consul API Gateway v0.3.0 introduces a breaking change for people upgrading from lower versions. Gateways with a `secret` defined in a different namespace now require a [`ReferenceGrant`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferenceGrant) that explicitly allows traffic from the route's namespace to the `backendRef`'s namespace. + +## Requirements + +Ensure that the following requirements are met prior to upgrading: + +- Consul API Gateway should be running version v0.2.1 or lower. +- 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 permission rights on your Kubernetes cluster: + - `Gateway.read` + - `ReferenceGrant.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 + +-> **NOTE** When you see `VERSION` in examples of commands or configuration settings, replace `VERSION` with the version number of the release you are installing, like `0.2.0`. If there is a lower case "v" in front of `VERSION` the version number needs to follow the "v" as is `v0.2.0` + +1. Verify the current version of the `consul-api-gateway-controller` `Deployment`: + + ```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" + ``` + +1. Retrieve all gateways that have a secret in a different namespace. If you have installed the [`jq`](https://stedolan.github.io/jq/) utility, you can skip to [step 4](#jq-command-secrets). Otherwise, issue the following command to get all `Gateways` across all namespaces: + + ```shell-session + $ kubectl get Gateway --output json --all-namespaces + ``` + + + If you have any active `Gateways`, 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 + ... + ... + ``` + +1. Inspect the `secret` entries for each of the routes. + + If a `namespace` field is not defined in the `secret` or if the namespace matches the namespace of the parent `Gateway`, then no additional action is required for the `secret`. Otherwise, note the `namespace` field values for `secret` configurations that have a `namespace` defined that do not match the namespace of the parent `Gateway`. You must also note the `namespace` of the parent gateway. You will need these to create a `ReferenceGrant` that explicitly allows each cross-namespace secret-to-gateway pair to prevent the route from breaking (see [step 5](#create-secret-reference-grant)). + + After completing this step, you will have a list of all secrets similar to the following: + + + + ```yaml hideClipboard + example-secret: + - namespace: secret-namespace + parentNamespace: gateway-namespace + + ``` + + + Proceed with the [standard-upgrade](#standard-upgrade) if your list is empty. + + +1. If you have installed [`jq`](https://stedolan.github.io/jq/), issue the following command to get all `Gateways` and filter for secrets that require a `ReferenceGrant`. + + ```shell-session + $ kubectl get Gateway -o json -A | jq -r '.items[] | {gateway_name: .metadata.name, gateway_namespace: .metadata.namespace, kind: .kind, crossNamespaceSecrets: ( .metadata.namespace as $parentnamespace | .spec.listeners[] .tls.certificateRefs[] | select(.namespace != null and .namespace != $parentnamespace ) )} ' + ``` + + + The output will resemble the following response if gateways that require a new `ReferenceGrant` are returned: + + + + ```log hideClipboard + { + "gateway_name": "example-gateway", + "gateway_namespace": "gateway-namespace", + "kind": "Gateway", + "crossNamespaceSecrets": { + "group": "", + "kind": "Secret", + "name": "secret-name", + "namespace": "secret-namespace" + } + } + ``` + + + + If your output is empty, proceed with the [standard-upgrade](#standard-upgrade). + + +1. Using the list of secrets you created earlier as a guide, create a [`ReferenceGrant`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferenceGrant) to allow cross namespace traffic for each route service pair. + The `ReferenceGrant` explicitly allows each cross-namespace gateway to secret pair. The `ReferenceGrant` must be created in the same `namespace` as the `Secret`. + + Skip to the next step if you've already created a `ReferenceGrant`. + + The following example `ReferenceGrant` enables `example-gateway` in `gateway-namespace` to utilize secrets in the `secret-namespace` namespace: + + + + ```yaml + apiVersion: gateway.networking.k8s.io/v1alpha2 + kind: ReferenceGrant + metadata: + name: reference-grant + namespace: secret-namespace + spec: + from: + - group: gateway.networking.k8s.io + kind: Gateway + namespace: gateway-namespace + to: + - group: "" + kind: Secret + ``` + + + +1. If you have already created a `ReferenceGrant`, modify it to allow your route and save it as `referencegrant.yaml`. Note that each `ReferenceGrant` only supports one `to` field and one `from` field (refer the [`ReferenceGrant`](https://gateway-api.sigs.k8s.io/v1alpha2/api-types/referencegrant/#api-design-decisions) documentation). As a result, you may need to create multiple `ReferenceGrant`s. + +1. Issue the following command to apply it to your cluster: + + ```shell-session + $ kubectl apply --filename referencegrant.yaml + ``` + + Repeat this step as needed until each of your cross-namespace secrets have a corresponding `ReferenceGrant`. + + +## v0.2.0 + +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 [`ReferenceGrant`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferenceGrant) that explicitly allows traffic from the route's namespace to the `backendRef`'s namespace. ## Requirements @@ -23,7 +199,7 @@ Ensure that the following requirements are met prior to upgrading: - You should have the following permission rights on your Kubernetes cluster: - `HTTPRoute.read` - `TCPRoute.read` - - `ReferencePolicy.create` + - `ReferenceGrant.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 @@ -99,7 +275,7 @@ Ensure that the following requirements are met prior to upgrading: 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)). + 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 `ReferenceGrant` that explicitly allows each cross-namespace route-to-service pair to prevent the route from breaking (see [step 5](#create-reference-grant)). After completing this step, you will have a list of all routes similar to the following: @@ -127,10 +303,10 @@ Ensure that the following requirements are met prior to upgrading: - Skip to [step 8](#step-8) if your list is empty. + Proceed with [standard-upgrade](#standard-upgrade) 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`. +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 `ReferenceGrant`. ```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 ) )} ' @@ -138,7 +314,7 @@ Ensure that the following requirements are met prior to upgrading: 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: + The output will resemble the following response if routes that require a new `ReferenceGrant` are returned: @@ -173,25 +349,25 @@ Ensure that the following requirements are met prior to upgrading: - If your output is empty, skip to [step 8](#step-8). - + If your output is empty, proceed with the [standard-upgrade](#standard-upgrade). + -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`. +1. Using the list of routes you created earlier as a guide, create a [`ReferenceGrant`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferenceGrant) to allow cross namespace traffic for each route service pair. + The `ReferenceGrant` explicitly allows each cross-namespace route to service pair to prevent the route from breaking. The `ReferenceGrant` must be created in the same `namespace` as the backend `Service`. - Skip to the next step if you've already created a `ReferencePolicy`. + Skip to the next step if you've already created a `ReferenceGrant`. - The following example `ReferencePolicy` enables `HTTPRoute` traffic from the `example-namespace` to Kubernetes Services in the `web-backend` namespace: + The following example `ReferenceGrant` enables `HTTPRoute` traffic from the `example-namespace` to Kubernetes Services in the `web-backend` namespace: - + ```yaml apiVersion: gateway.networking.k8s.io/v1alpha2 - kind: ReferencePolicy + kind: ReferenceGrant metadata: - name: reference-policy + name: reference-grant namespace: gateway-namespace spec: from: @@ -206,16 +382,21 @@ Ensure that the following requirements are met prior to upgrading: -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. +1. If you have already created a `ReferenceGrant`, modify it to allow your route and save it as `referencegrant.yaml`. Note that each `ReferenceGrant` only supports one `to` field and one `from` field (refer the [`ReferenceGrant`](https://gateway-api.sigs.k8s.io/v1alpha2/api-types/referencegrant/#api-design-decisions) documentation). As a result, you may need to create multiple `ReferenceGrant`s. 1. Issue the following command to apply it to your cluster: ```shell-session - $ kubectl apply --filename referencepolicy.yaml + $ kubectl apply --filename referencegrant.yaml ``` - Repeat this step as needed until each of your cross-namespace routes have a corresponding `ReferencePolicy`. - + Repeat this step as needed until each of your cross-namespace routes have a corresponding `ReferenceGrant`. + +## Standard Upgrade + +This is the upgrade path to use when there are no version specific steps to take. + + 1. Issue the following command to install the new version of CRDs into your cluster: