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.** 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
...
...
- 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.
**2.** Run the following command to retrieve all routes defined with a cross namespace:
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 ) )} '
$ 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.
<!---
TODO: add link to our docs on Cross Namespace Reference Policies, once we have written then, and tell the user to see them for more details on how to create these policies.
--->
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.
<CodeBlockConfig filename="referencepolicy.yaml">
```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
</div>
```
</CodeBlockConfig>
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
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.
Sarah Alsmiller
3 years ago
committed by