From 195ec096bbc094a25613dcf1500d934db997a37d Mon Sep 17 00:00:00 2001 From: Mike Morris Date: Wed, 27 Apr 2022 14:25:42 -0400 Subject: [PATCH] website(consul-api-gateway): add ReferencePolicy to overview docs (#12861) * website(consul-api-gateway): add ReferencePolicy to overview docs * website(consul-api-gateway): bump required Consul Helm chart version For allowing Consul API Gateway controller to read ReferencePolicy resources and UX improvement re-using connectInject.consulNamespaces config for Consul API Gateway config. * added referencepolicy documentation to route section * Update website/content/docs/api-gateway/consul-api-gateway-install.mdx Co-authored-by: Mike Morris * Update website/content/docs/api-gateway/consul-api-gateway-install.mdx Co-authored-by: Mike Morris * Update website/content/docs/api-gateway/consul-api-gateway-install.mdx Co-authored-by: Mike Morris * Update website/content/docs/api-gateway/consul-api-gateway-install.mdx Co-authored-by: Mike Morris * Update website/content/docs/api-gateway/consul-api-gateway-install.mdx Co-authored-by: Mike Morris * Update consul-api-gateway-install.mdx * Update consul-api-gateway-install.mdx * Update website/content/docs/api-gateway/consul-api-gateway-install.mdx Co-authored-by: Nathan Coleman * Update website/content/docs/api-gateway/consul-api-gateway-install.mdx Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> * Update website/content/docs/api-gateway/consul-api-gateway-install.mdx * Update website/content/docs/api-gateway/consul-api-gateway-install.mdx * Update website/content/docs/api-gateway/index.mdx Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> * Update website/content/docs/api-gateway/index.mdx * Update website/content/docs/api-gateway/index.mdx Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Co-authored-by: Sarah Alsmiller Co-authored-by: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com> Co-authored-by: Nathan Coleman Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> --- .../consul-api-gateway-install.mdx | 42 +++++++++++++++++++ website/content/docs/api-gateway/index.mdx | 6 +-- .../content/docs/api-gateway/tech-specs.mdx | 2 +- 3 files changed, 46 insertions(+), 4 deletions(-) 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 dff99915e5..137072ef1e 100644 --- a/website/content/docs/api-gateway/consul-api-gateway-install.mdx +++ b/website/content/docs/api-gateway/consul-api-gateway-install.mdx @@ -304,6 +304,48 @@ spec: +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`. + + + +```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 +``` + + + ### 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). diff --git a/website/content/docs/api-gateway/index.mdx b/website/content/docs/api-gateway/index.mdx index 817aa823ec..5234eac604 100644 --- a/website/content/docs/api-gateway/index.mdx +++ b/website/content/docs/api-gateway/index.mdx @@ -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) |
  • Supported protocols: `HTTP`, `HTTPS`, `TCP`
  • Header-based hostname matching (no SNI support)
  • Supported filters: header addition, removal, and setting
  • TLS modes supported: `terminate`
  • Certificate types supported: `core/v1/Secret`
  • Extended options: TLS version and cipher constraints
| | [`HTTPRoute`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRoute) |
  • Weight-based load balancing
  • Supported rules: path, header, query, and method-based matching
  • Supported filters: header addition, removal, and setting
  • Supported backend types:
    1. `core/v1/Service` (must map to a registered Consul service)
    2. `api-gateway.consul.hashicorp.com/v1alpha1/MeshService`
| | [`TCPRoute`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.TCPRoute) |
  • Supported backend types:
    1. `core/v1/Service` (must map to a registered Consul service)
    2. `api-gateway.consul.hashicorp.com/v1alpha1/MeshService`
| +| [`ReferencePolicy`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferencePolicy) |
  • Required to allow any reference from an `HTTPRoute` or `TCPRoute` to a Kubernetes `core/v1/Service` in a different namespace.
  • 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.
  • WARNING: If a route BackendRef becomes unpermitted, the entire route is removed from the gateway listener.
    • A BackendRef can become unpermitted when you delete a Reference Policy or add a new unpermitted BackendRef to an existing route.
| ## 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). - diff --git a/website/content/docs/api-gateway/tech-specs.mdx b/website/content/docs/api-gateway/tech-specs.mdx index 3414460db1..c92d5d3e8a 100644 --- a/website/content/docs/api-gateway/tech-specs.mdx +++ b/website/content/docs/api-gateway/tech-specs.mdx @@ -20,7 +20,7 @@ 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+ +- HashiCorp Consul Helm chart 0.43.0+ - Consul Service Mesh must be deployed on the Kubernetes cluster that API Gateway is deployed on. ### TCP Port Requirements