mirror of https://github.com/status-im/consul.git
website(consul-api-gateway): fixup stray div tag and step 8 link rendering (#12873)
This commit is contained in:
Mike Morris
GitHub
parent
3bf17020d9
commit
80417f02dc
|
|
@ -11,20 +11,20 @@ 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.
|
||||
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.
|
||||
|
||||
## Requirements
|
||||
|
||||
Ensure that the following requirements are met prior to upgrading:
|
||||
|
||||
- Consul API Gateway should be running version v0.1.0.
|
||||
- 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 permission 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.
|
||||
* `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
|
||||
|
||||
|
|
@ -40,15 +40,15 @@ Ensure that the following requirements are met prior to upgrading:
|
|||
"hashicorp/consul-api-gateway:0.1.0"
|
||||
```
|
||||
|
||||
1. Retrieve all routes that have a backend in a different namespace. If you have installed the [`jq`](https://stedolan.github.io/jq/) utility, you can skip to [step 4](#jq-command). Otherwise, issue the following command to get all `HTTPRoutes` and `TCPRoutes` across all namespaces:
|
||||
1. Retrieve all routes that have a backend in a different namespace. If you have installed the [`jq`](https://stedolan.github.io/jq/) utility, you can skip to [step 4](#jq-command). Otherwise, issue the following command to get all `HTTPRoutes` and `TCPRoutes` across all namespaces:
|
||||
|
||||
```shell-session
|
||||
$ kubectl get HTTPRoute,TCPRoute --output json --all-namespaces
|
||||
```
|
||||
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:
|
||||
|
|
@ -93,12 +93,12 @@ 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)).
|
||||
|
||||
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:
|
||||
|
||||
|
||||
<CodeBlockConfig hideClipboard>
|
||||
|
||||
```yaml hideClipboard
|
||||
|
|
@ -122,7 +122,7 @@ Ensure that the following requirements are met prior to upgrading:
|
|||
```
|
||||
</CodeBlockConfig>
|
||||
|
||||
Skip to [step 8](#step-8) if your list is empty.
|
||||
Skip to [step 8](#step-8) if your list is empty.
|
||||
<a name="jq-command"/>
|
||||
|
||||
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`.
|
||||
|
|
@ -130,7 +130,7 @@ Ensure that the following requirements are met prior to upgrading:
|
|||
```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:
|
||||
|
|
@ -166,18 +166,18 @@ Ensure that the following requirements are met prior to upgrading:
|
|||
}
|
||||
```
|
||||
</CodeBlockConfig>
|
||||
|
||||
|
||||
If your output is empty, skip to [step 8](#step-8).
|
||||
<a name="create-reference-policy"/>
|
||||
|
||||
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 [`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`.
|
||||
Skip to the next step if you've already created a `ReferencePolicy`.
|
||||
<!---
|
||||
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.
|
||||
--->
|
||||
The following example `ReferencePolicy` enables `HTTPRoute` traffic from the `example-namespace` to Kubernetes Services in the `web-backend` namespace:
|
||||
The following example `ReferencePolicy` enables `HTTPRoute` traffic from the `example-namespace` to Kubernetes Services in the `web-backend` namespace:
|
||||
|
||||
<CodeBlockConfig filename="referencepolicy.yaml">
|
||||
|
||||
|
|
@ -196,7 +196,6 @@ Ensure that the following requirements are met prior to upgrading:
|
|||
- group: ""
|
||||
kind: Service
|
||||
name: web-backend
|
||||
</div>
|
||||
```
|
||||
</CodeBlockConfig>
|
||||
|
||||
|
|
@ -234,10 +233,10 @@ Ensure that the following requirements are met prior to upgrading:
|
|||
```shell-session
|
||||
$ helm upgrade --values values.yaml --namespace consul --version <NEW_VERSION> hashicorp/consul <DEPLOYMENT_NAME>
|
||||
```
|
||||
|
||||
|
||||
Note that the upgrade will cause the Consul API Gateway controller shut down and restart with the new version.
|
||||
|
||||
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:
|
||||
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 --filename <path_to_gateway_config.yaml>
|
||||
|
|
|
|||
Loading…
Reference in New Issue