luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

Merge pull request #12863 from hashicorp/api-gateway-v0.2-docs 

Update product docs for release of Consul API Gateway v0.2
This commit is contained in:
Jeff Apple 2022-04-27 12:01:23 -07:00 committed by GitHub
parent e4008124bd 498b80b284
commit 1f8f4e5d27
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 372 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
website/content/docs/api-gateway/consul-api-gateway-install.mdx
View File

@ -32,14 +32,13 @@ 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:
enabled: true
apiGateway:
enabled: true
image: hashicorp/consul-api-gateway:0.1.0
image: hashicorp/consul-api-gateway:0.2.0
```
</CodeBlockConfig>
@ -305,6 +304,48 @@ spec:
</CodeBlockConfig>
To create a route for a `backendRef` in a different namespace, you must also
create a [ReferencePolicy](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferencePolicy).
The following example creates a route named `example-route` in namespace `gateway-namespace`. This route has a `backendRef` in namespace `service-namespace`. Traffic is allowed because the `ReferencePolicy`, named `reference-policy` in namespace `service-namespace`, allows traffic from `HTTPRoutes` in `gateway-namespace` to `Services` in `service-namespace`.
<CodeBlockConfig filename="route_with_referencepolicy.yaml">
```yaml
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: HTTPRoute
metadata:
name: example-route
namespace: gateway-namespace
spec:
parentRefs:
- name: example-gateway
rules:
- backendRefs:
- kind: Service
name: echo
namespace: service-namespace
port: 8080
---
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: ReferencePolicy
metadata:
name: reference-policy
namespace: service-namespace
spec:
from:
- group: gateway.networking.k8s.io
kind: HTTPRoute
namespace: gateway-namespace
to:
- group: ""
kind: Service
name: echo
```
</CodeBlockConfig>
### MeshService
The `MeshService` configuration holds a reference to an externally-managed Consul service mesh service and can be used as a `backendRef` for a [`Route`](#route).

6
website/content/docs/api-gateway/index.mdx
View File

@ -7,7 +7,7 @@ description: >-
# Consul API Gateway Overview
This topic provides an overview of the Consul API Gateway.
This topic provides an overview of the Consul API Gateway.
## What is Consul API Gateway?
@ -24,7 +24,7 @@ Consul API Gateway can be deployed on Kubernetes-based runtime environments and
API Gateway routes traffic to services connected to the same service mesh. Those services can be running on the same Kubernetes cluster as the API Gateway, a different Kubernetes cluster, or another runtime, as long as they are connected to the same service mesh deployment and reachable over the network.
Consul API Gateway implements, and is configured through, the Kubernetes [Gateway API Specification](https://gateway-api.sigs.k8s.io/). This specification defines a set of custom resource definitions (CRD) that can create logical gateways and routes based on the path or protocol of a client request.
Consul API Gateway implements and is configured through the Kubernetes [Gateway API Specification](https://gateway-api.sigs.k8s.io/). This specification defines a set of custom resource definitions (CRD) that can create logical gateways which route traffic based on a client request's path or protocol.
### Supported Kubernetes Gateway Specification Features
@ -38,8 +38,8 @@ are used, see the [documentation in our GitHub repo](https://github.com/hashicor
| [`Gateway`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Gateway) | <ul><li>Supported protocols: `HTTP`, `HTTPS`, `TCP`</li><li>Header-based hostname matching (no SNI support)</li><li>Supported filters: header addition, removal, and setting</li><li>TLS modes supported: `terminate`</li><li>Certificate types supported: `core/v1/Secret`</li><li>Extended options: TLS version and cipher constraints</li></ul> |
| [`HTTPRoute`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRoute) | <ul><li>Weight-based load balancing</li><li>Supported rules: path, header, query, and method-based matching</li><li>Supported filters: header addition, removal, and setting</li><li>Supported backend types: <ol><li>`core/v1/Service` (must map to a registered Consul service)</li><li>`api-gateway.consul.hashicorp.com/v1alpha1/MeshService`</li></ol></li></ul> |
| [`TCPRoute`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.TCPRoute) | <ul><li>Supported backend types: <ol><li>`core/v1/Service` (must map to a registered Consul service)</li><li>`api-gateway.consul.hashicorp.com/v1alpha1/MeshService`</li></ol></li></ul> |
| [`ReferencePolicy`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferencePolicy) | <ul><li>Required to allow any reference from an `HTTPRoute` or `TCPRoute` to a Kubernetes `core/v1/Service` in a different namespace.</li><li>A route with an unpermitted BackendRef caused by the lack of a ReferencePolicy sets a `ResolvedRefs` status to `False` with the reason `RefNotPermitted`. The gateway listener rejects routes with an unpermitted BackendRef.</li><li>WARNING: If a route BackendRef becomes unpermitted, the entire route is removed from the gateway listener. <ul><li>A BackendRef can become unpermitted when you delete a Reference Policy or add a new unpermitted BackendRef to an existing route.</li></ul></li></ul> |
## Additional Resources
You can learn more about using Consul API Gateway by completing the [Consul API Gateway tutorial](https://learn.hashicorp.com/tutorials/consul/kubernetes-api-gateway).

5
website/content/docs/api-gateway/tech-specs.mdx
View File

@ -19,9 +19,10 @@ Your datacenter must meet the following requirements prior to configuring the Co
- Kubernetes 1.21+
- `kubectl` 1.21+
- Consul 1.11.2+
- HashiCorp Consul Helm chart 0.41.1+
- Consul 1.12.0+
- HashiCorp Consul Helm chart 0.43.0+
- Consul Service Mesh must be deployed on the Kubernetes cluster that API Gateway is deployed on.
- Envoy: Envoy proxy support is determined by the Consul version deployed. Refer to [Envoy Integration](/docs/connect/proxies/envoy) for details.
### TCP Port Requirements

258
website/content/docs/api-gateway/upgrade-specific-versions.mdx Normal file
View File

@ -0,0 +1,258 @@
---
layout: docs
page_title: Upgrades
description: >-
This topic describes how to upgrade Consul API Gateway.
---
# Upgrades
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.
## Requirements
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 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.
## Procedure
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 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:
- 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 `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
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
```
</CodeBlockConfig>
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`.
```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:
<CodeBlockConfig hideClipboard>
```log hideClipboard
{
"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
}
}
```
</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`.
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:
<CodeBlockConfig filename="referencepolicy.yaml">
```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
</div>
```
</CodeBlockConfig>
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. Issue the following command to apply it to your cluster:
```shell-session
$ kubectl apply --filename referencepolicy.yaml
```
Repeat this step as needed until each of your cross-namespace routes have a corresponding `ReferencePolicy`.
<a name="step-8"/>
1. Issue the following command to install the v.0.2.0 CRDs into your cluster:
``` shell-session
$ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=0.2.0"
```
1. Update `apiGateway.image` in `values.yaml`:
<CodeBlockConfig hideClipboard filename="values.yaml">
```yaml
...
apiGateway:
image: hashicorp/consul-api-gateway:0.2.0
...
```
</CodeBlockConfig>
1. Issue the following command to upgrade your Consul installation:
```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:
```shell-session
$ kubectl delete --filename <path_to_gateway_config.yaml>
$ kubectl create --filename <path_to_gateway_config.yaml>
```
<!---
remove this warning once updating a gateway triggers reconciliation on child routes
--->
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 --filename <path_to_route_config.yaml>
$ kubectl create --filename <path_to_route_config.yaml>
```
## Post-Upgrade Configuration Changes
No configuration changes are required for this upgrade.

11
website/content/docs/release-notes/consul-api-gateway/v0_1_x.mdx
View File

@ -27,13 +27,14 @@ gateway functionality. It provides additional capabilities that ingress gateway
internal CA.
## Release Highlights
This release includes the following features and capabilities:
1. Can be deployed in the following run time environments:
- Self-managed Kubernetes
- AWS EKS
- Google GKE
- Azure AKS.
- Self-managed Kubernetes
- AWS EKS
- Google GKE
- Azure AKS.
1. Install via the HashiCorp Consul Helm chart.
1. Works with self-managed Consul servers and HCP Consul servers
1. Configure via Kubernetes Gateway API - v1alpha2
@ -48,7 +49,7 @@ This release includes the following features and capabilities:
- HTTP Header
- HTTP Method
- HTTP Query parameters
1 HTTP header manipulation:
1. HTTP header manipulation:
- Set header value
- Add header and/or value
- Remove header and/or value

51
website/content/docs/release-notes/consul-api-gateway/v0_2_x.mdx Normal file
View File

@ -0,0 +1,51 @@
---
layout: docs
page_title: 0.2.x
description: >-
Consul API Gateway release notes for version 0.2.x
---
# Consul API Gateway 0.2.0
## Release Highlights
- **Cross Namespace Reference Policies:** Reference Policies are security
mechanism in the Kubernetes Gateway API that allows users to better control
how traffic is routed between Kubernetes namespaces. With the previous
releases of Consul API Gateway, users could route requests from the API
Gateway across various namespaces without providing any sort of explicit
permissions. While this meant that any service connected to the service mesh
was reachable, it didn’t allow users to set the more granular restrictions or
permissions that they may expect.
This version of API Gateway implements Cross Namespace Reference Policies
and requires them when routes are in a different namespace than the services
(as specified by the `backendRef`) they are routing traffic to.
## Supported Software
- Consul 1.11.2+
- HashiCorp Consul Helm chart 0.43.0+
- Kubernetes 1.21+
- Kubectl 1.21+
- Envoy proxy support is determined by the Consul version deployed. Refer to
[Envoy Integration](/docs/connect/proxies/envoy) for details.
## Kubernetes Gateway API Specification
Supported version of the Gateway API spec: `v1alpha2`(v0.4.1)
## Upgrading
~>**Note**: If your current deployment has routes and and services that cross namespaces, those routes will not be applied to their gateways until cross namespace reference policies are created for them.
For detailed information on upgrading, including how to create the required refeence policies, please refer to the [upgrade details page](/docs/api-gateway/upgrade-specific-versions)
## Change logs
The changelogs for this major release version and any maintenance versions are listed below.
-> **Note**: These links will take you to the changelogs on the GitHub website.
- [0.2.0](https://github.com/hashicorp/consul-api-gateway/releases/tag/v0.2.0)

8
website/data/docs-nav-data.json
View File

@ -392,6 +392,10 @@
{
"title": "Common Errors",
"path": "api-gateway/common-errors"
},
{
"title": "Upgrades",
"path": "api-gateway/upgrade-specific-versions"
}
]
},
@ -1218,6 +1222,10 @@
{
"title": "v0.1.x",
"path": "release-notes/consul-api-gateway/v0_1_x"
},
{
"title": "v0.2.x",
"path": "release-notes/consul-api-gateway/v0_2_x"
}
]
},