From 68ee017adfdf7cac37e1bc8fde5ae5e7caf1bddd Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Mon, 17 Oct 2022 11:42:24 -0700 Subject: [PATCH 01/25] added usage folder to organize use case docs for CAPIgw --- .../content/docs/api-gateway/usage/errors.mdx | 60 ++++++++++ .../usage/reroute-http-requests.mdx | 58 ++++++++++ .../usage/route-to-peered-services.mdx | 18 +++ .../docs/api-gateway/{ => usage}/usage.mdx | 108 ++---------------- website/data/docs-nav-data.json | 20 +++- 5 files changed, 164 insertions(+), 100 deletions(-) create mode 100644 website/content/docs/api-gateway/usage/errors.mdx create mode 100644 website/content/docs/api-gateway/usage/reroute-http-requests.mdx create mode 100644 website/content/docs/api-gateway/usage/route-to-peered-services.mdx rename website/content/docs/api-gateway/{ => usage}/usage.mdx (55%) diff --git a/website/content/docs/api-gateway/usage/errors.mdx b/website/content/docs/api-gateway/usage/errors.mdx new file mode 100644 index 000000000000..40f1d4011e7c --- /dev/null +++ b/website/content/docs/api-gateway/usage/errors.mdx @@ -0,0 +1,60 @@ +--- +layout: docs +page_title: Use Consul API Gateway +description: >- + Learn how to apply a configured Consul API Gateway to your Kubernetes cluster, review the required fields for rerouting HTTP requests, and troubleshoot an error message. +--- + +# Error Messages + +This topic provides information about potential error messages associated with Consul API Gateway. If you receive an error message that does not appear in this section, refer to the following resources: + +* [Common Consul errors](/docs/troubleshoot/common-errors#common-errors-on-kubernetes) +* [Consul troubleshooting guide](/docs/troubleshoot/common-errors) +* [Consul Discuss forum](https://discuss.hashicorp.com/) + + + +## Helm installation failed: "no matches for kind" + +```log +Error: INSTALLATION FAILED: unable to build kubernetes objects from release manifest: [unable to recognize "": no matches for kind "GatewayClass" in version "gateway.networking.k8s.io/v1alpha2", unable to recognize "": no matches for kind "GatewayClassConfig" in version "api-gateway.consul.hashicorp.com/v1alpha1"] +``` +**Conditions:** +Consul API Gateway generates this error when the required CRD files have not been installed in Kubernetes prior to installing Consul API Gateway. + +**Impact:** +The installation process typically fails after this error message is generated. + +**Resolution:** +Install the required CRDs. Refer to the [Consul API Gateway installation instructions](/docs/api-gateway/install#installation) for instructions. \ No newline at end of file diff --git a/website/content/docs/api-gateway/usage/reroute-http-requests.mdx b/website/content/docs/api-gateway/usage/reroute-http-requests.mdx new file mode 100644 index 000000000000..8f457e934f17 --- /dev/null +++ b/website/content/docs/api-gateway/usage/reroute-http-requests.mdx @@ -0,0 +1,58 @@ +--- +layout: docs +page_title: Reroute HTTP Requests +description: >- + Learn how to configure Consul API Gateway to reroute HTTP requests to a specific path. +--- + +# Reroute HTTP Requests + +This topic describes how to configure Consul API Gateway to reroute HTTP requests. + +## Requirements + +1. Verify that the [requirements](/docs/api-gateway/tech-specs) have been met. +1. Verify that the Consul API Gateway CRDs and controller have been installed and applied. Refer to [Installation](/docs/api-gateway/install) for details. + +## Configuration + +Configure the following fields in your `Route` configuration to use this feature. Refer to the [Route configuration reference](/docs/api-gateway/configuration/routes) for details about the parameters. + +* [`rules.filters.type`](/docs/api-gateway/configuration/routes#rules-filters-type): Set this parameter to `URLRewrite` to instruct Consul API Gateway to rewrite the URL when specific conditions are met. +* [`rules.filters.urlRewrite`](/docs/api-gateway/configuration/routes#rules-filters-urlrewrite): Specify the `path` configuration. +* [`rules.filters.urlRewrite.path`](/docs/api-gateway/configuration/routes#rules-filters-urlrewrite-path): Contains the paths that incoming requests should be rewritten to based on the match conditions. + +Note that if the route is configured to accept paths with and without a trailing slash, you must make two separate routes to handle each case. + +### Example + +In the following example, requests to` /incoming-request-prefix/` are forwarded to the `backendRef` as `/prefix-backend-receives/`. A request to `/incoming-request-prefix/request-path`, for instance, is received by the `backendRef` as `/prefix-backend-receives/request-path`. + + + +```yaml hideClipboard +apiVersion: gateway.networking.k8s.io/v1beta1 +kind: HTTPRoute +metadata: + name: example-route + ##... +spec: + parentRefs: + - group: gateway.networking.k8s.io + kind: Gateway + name: api-gateway + rules: + - backendRefs: + . . . + filters: + - type: URLRewrite + urlRewrite: + path: + replacePrefixMatch: /prefix-backend-receives/ + type: ReplacePrefixMatch + matches: + - path: + type: PathPrefix + value: /incoming–request-prefix/ +``` + \ No newline at end of file diff --git a/website/content/docs/api-gateway/usage/route-to-peered-services.mdx b/website/content/docs/api-gateway/usage/route-to-peered-services.mdx new file mode 100644 index 000000000000..e00c80e98aff --- /dev/null +++ b/website/content/docs/api-gateway/usage/route-to-peered-services.mdx @@ -0,0 +1,18 @@ +--- +Page_title: Route Traffic to Peered Services +Description: Learn how to configure Consul API Gateway to route traffic to services connected to the mesh through a peering connection. +--- + +# Route Traffic to Peered Services + +This topic describes how to configure Consul API Gateway to route traffic to services connected to the mesh through a peering connection + +## Requirements + +1. Verify that the [requirements](/docs/api-gateway/tech-specs) have been met. +1. Verify that the Consul API Gateway CRDs and controller have been installed and applied. Refer to [Installation](/docs/api-gateway/install) for details. + +## Configuration + + +## Example diff --git a/website/content/docs/api-gateway/usage.mdx b/website/content/docs/api-gateway/usage/usage.mdx similarity index 55% rename from website/content/docs/api-gateway/usage.mdx rename to website/content/docs/api-gateway/usage/usage.mdx index f5199d0c8f5b..31b6e78b4b96 100644 --- a/website/content/docs/api-gateway/usage.mdx +++ b/website/content/docs/api-gateway/usage/usage.mdx @@ -5,17 +5,20 @@ description: >- Learn how to apply a configured Consul API Gateway to your Kubernetes cluster, review the required fields for rerouting HTTP requests, and troubleshoot an error message. --- -# Use Consul API Gateway +# Basic Consul API Gateway Usage This topic describes how to use Consul API Gateway. -## Basic usage +## Requirements Complete the following steps to use Consul API Gateway in your network. 1. Verify that the [requirements](/docs/api-gateway/tech-specs) have been met. 1. Verify that the Consul API Gateway CRDs and controller have been installed and applied. Refer to [Installation](/docs/api-gateway/install) for details. -1. Configure your [`Gateway`](/docs/api-gateway/configuration/gateway) and [`Routes`](/docs/api-gateway/configuration/routes) as describe in the [Configuration](/docs/api-gateway/configuration) section. + +## Configuration + +Configure your [`Gateway`](/docs/api-gateway/configuration/gateway) and [`Routes`](/docs/api-gateway/configuration/routes) as describe in the [Configuration](/docs/api-gateway/configuration) section. @@ -27,55 +30,14 @@ Complete the following steps to use Consul API Gateway in your network. -1. Issue the `kubectl apply` command to implement the configurations: +## Apply configurations + +Issue the `kubectl apply` command to implement the configurations: ```shell-session $ kubectl apply -f gateway.yaml routes.yaml ``` -## Reroute HTTP requests - -Configure the following fields in your `Route` configuration to use this feature. Refer to the [Route configuration reference](/docs/api-gateway/configuration/routes) for details about the parameters. - -* [`rules.filters.type`](/docs/api-gateway/configuration/routes#rules-filters-type): Set this parameter to `URLRewrite` to instruct Consul API Gateway to rewrite the URL when specific conditions are met. -* [`rules.filters.urlRewrite`](/docs/api-gateway/configuration/routes#rules-filters-urlrewrite): Specify the `path` configuration. -* [`rules.filters.urlRewrite.path`](/docs/api-gateway/configuration/routes#rules-filters-urlrewrite-path): Contains the paths that incoming requests should be rewritten to based on the match conditions. - -Note that if the route is configured to accept paths with and without a trailing slash, you must make two separate routes to handle each case. - -### Example - -In the following example, requests to` /incoming-request-prefix/` are forwarded to the `backendRef` as `/prefix-backend-receives/`. A request to `/incoming-request-prefix/request-path`, for instance, is received by the `backendRef` as `/prefix-backend-receives/request-path`. - - - -```yaml hideClipboard -apiVersion: gateway.networking.k8s.io/v1beta1 -kind: HTTPRoute -metadata: - name: example-route - ##... -spec: - parentRefs: - - group: gateway.networking.k8s.io - kind: Gateway - name: api-gateway - rules: - - backendRefs: - . . . - filters: - - type: URLRewrite - urlRewrite: - path: - replacePrefixMatch: /prefix-backend-receives/ - type: ReplacePrefixMatch - matches: - - path: - type: PathPrefix - value: /incoming–request-prefix/ -``` - - -## Error Messages - -This topic provides information about potential error messages associated with Consul API Gateway. If you receive an error message that does not appear in this section, refer to the following resources: - -* [Common Consul errors](/docs/troubleshoot/common-errors#common-errors-on-kubernetes) -* [Consul troubleshooting guide](/docs/troubleshoot/common-errors) -* [Consul Discuss forum](https://discuss.hashicorp.com/) - - - -### Helm installation failed: "no matches for kind" - -```log -Error: INSTALLATION FAILED: unable to build kubernetes objects from release manifest: [unable to recognize "": no matches for kind "GatewayClass" in version "gateway.networking.k8s.io/v1alpha2", unable to recognize "": no matches for kind "GatewayClassConfig" in version "api-gateway.consul.hashicorp.com/v1alpha1"] -``` -**Conditions:** -Consul API Gateway generates this error when the required CRD files have not been installed in Kubernetes prior to installing Consul API Gateway. - -**Impact:** -The installation process typically fails after this error message is generated. -**Recommended Action:** -Install the required CRDs by using the command in Step 1 of the [Consul API Gateway installation instructions](/docs/api-gateway/install#installation) and then retry installing Consul API Gateway. diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 1a06f9cd9615..16cdb531dcd0 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -1276,7 +1276,25 @@ }, { "title": "Usage", - "path": "api-gateway/usage" + "routes": [ + { + "title": "Basic Usage", + "path": "api-gateway/usage/usage" + }, + { + "title": "Reroute HTTP Requests", + "path": "api-gateway/usage/reroute-http-requests" + }, + { + "title": "Route Traffic to Peered Services", + "path": "api-gateway/usage/route-to-peered-services" + }, + { + "title": "Error Messages", + "path": "api-gateway/usage/errors" + } + + ] }, { "title": "Configuration", From f23b3662d89054fbf7b25298e023c3e8db779270 Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Mon, 17 Oct 2022 15:58:04 -0400 Subject: [PATCH 02/25] Add peer field to MeshService configuration page --- .../docs/api-gateway/configuration/meshservice.mdx | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/configuration/meshservice.mdx b/website/content/docs/api-gateway/configuration/meshservice.mdx index 2dd377fb68d8..5e24d90779a3 100644 --- a/website/content/docs/api-gateway/configuration/meshservice.mdx +++ b/website/content/docs/api-gateway/configuration/meshservice.mdx @@ -11,7 +11,7 @@ This topic provides full details about the `MeshService` resource. ## Introduction -A `MeshService` is a resource in the Kubernetes cluster that enables Kubernetes configuration models, such as `HTTPRoute` and `TCPRoute`, to reference services that only exist in Consul. A `MeshService` represents a service in the Consul service mesh outside the Kubernetes cluster where Consul API Gateway is deployed. The service represented by the `MeshService` resource must be in the same Consul datacenter as the Kubernetes cluster. +A `MeshService` is a resource in the Kubernetes cluster that enables Kubernetes configuration models, such as `HTTPRoute` and `TCPRoute`, to reference services that only exist in Consul. A `MeshService` represents a service in the Consul service mesh outside the Kubernetes cluster where Consul API Gateway is deployed. The service represented by the `MeshService` resource must be in the same Consul datacenter as the Kubernetes cluster. ## Configuration Model @@ -19,6 +19,7 @@ A `MeshService` is a resource in the Kubernetes cluster that enables Kubernetes The following outline shows how to format the configurations in the `MeshService` object. Click on a property name to view details about the configuration. * [`name`](#name): string | required +* [`peer`](#peer): string | optional ## Specification @@ -29,3 +30,8 @@ This topic provides details about the configuration parameters. Specifies the name of the service in the Consul service mesh to send traffic to. * Type: string * Required: required + +### peer +Specifies the name of the Consul peer exporting the service. If not specified, the service is assumed to be in the local datacenter. +* Type: string +* Required: optional From deaba3ef155f176cf17cc318c2b39355cba932fc Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Mon, 17 Oct 2022 16:08:22 -0400 Subject: [PATCH 03/25] Add first pass at guide for routing to peered services --- .../usage/route-to-peered-services.mdx | 23 ++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/usage/route-to-peered-services.mdx b/website/content/docs/api-gateway/usage/route-to-peered-services.mdx index e00c80e98aff..fbd979adc870 100644 --- a/website/content/docs/api-gateway/usage/route-to-peered-services.mdx +++ b/website/content/docs/api-gateway/usage/route-to-peered-services.mdx @@ -5,14 +5,35 @@ Description: Learn how to configure Consul API Gateway to route traffic to servi # Route Traffic to Peered Services -This topic describes how to configure Consul API Gateway to route traffic to services connected to the mesh through a peering connection +This topic describes how to configure Consul API Gateway to route traffic to services connected to the mesh through a peering connection. ## Requirements 1. Verify that the [requirements](/docs/api-gateway/tech-specs) have been met. 1. Verify that the Consul API Gateway CRDs and controller have been installed and applied. Refer to [Installation](/docs/api-gateway/install) for details. +1. Verify that a peering connection has been established between Consul clusters and that at least one service has been exported to the cluster containing your `Gateway`. Refer to [Cluster Peering on Kubernetes](https://developer.hashicorp.com/consul/docs/connect/cluster-peering/k8s) for details. ## Configuration +Configure the following fields in your `MeshService` configuration to use this feature. Refer to the [MeshService configuration reference](/docs/api-gateway/configuration/mesh) for details about the parameters. + +* [`name`](/docs/api-gateway/configuration/meshservice#name) +* [`peer`](/docs/api-gateway/configuration/meshservice#peer) ## Example + +In the following example, routes using the example-mesh-service as a backend will send requests to the `echo` service exported by the peered Consul cluster, `dc2`. + + + +```yaml hideClipboard +apiVersion: api-gateway.consul.hashicorp.com/v1alpha1 +kind: MeshService +metadata: + name: example-mesh-service + ##... +spec: + name: echo + peer: dc2 +``` + From d1f1ff50f8b3f295fcd1058dabcf8465b7268df0 Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Mon, 17 Oct 2022 16:19:06 -0400 Subject: [PATCH 04/25] Add exception to same-datacenter restriction for referenced Consul service --- .../content/docs/api-gateway/configuration/meshservice.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/configuration/meshservice.mdx b/website/content/docs/api-gateway/configuration/meshservice.mdx index 5e24d90779a3..c1e6f01d27a1 100644 --- a/website/content/docs/api-gateway/configuration/meshservice.mdx +++ b/website/content/docs/api-gateway/configuration/meshservice.mdx @@ -11,7 +11,9 @@ This topic provides full details about the `MeshService` resource. ## Introduction -A `MeshService` is a resource in the Kubernetes cluster that enables Kubernetes configuration models, such as `HTTPRoute` and `TCPRoute`, to reference services that only exist in Consul. A `MeshService` represents a service in the Consul service mesh outside the Kubernetes cluster where Consul API Gateway is deployed. The service represented by the `MeshService` resource must be in the same Consul datacenter as the Kubernetes cluster. +A `MeshService` is a resource in the Kubernetes cluster that enables Kubernetes configuration models, such as `HTTPRoute` and `TCPRoute`, to reference services that only exist in Consul. +A `MeshService` represents a service in the Consul service mesh outside the Kubernetes cluster where Consul API Gateway is deployed. +The service represented by the `MeshService` resource must either be in the same Consul datacenter as the Kubernetes cluster or imported from a peered Consul cluster. ## Configuration Model From e41ec340d8037ea8b7cd6e27577bb2e07d928363 Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Mon, 17 Oct 2022 16:25:46 -0400 Subject: [PATCH 05/25] Add example HTTPRoute referencing the MeshService as backendRef --- .../usage/route-to-peered-services.mdx | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/website/content/docs/api-gateway/usage/route-to-peered-services.mdx b/website/content/docs/api-gateway/usage/route-to-peered-services.mdx index fbd979adc870..bc5e0a9d56a3 100644 --- a/website/content/docs/api-gateway/usage/route-to-peered-services.mdx +++ b/website/content/docs/api-gateway/usage/route-to-peered-services.mdx @@ -37,3 +37,25 @@ spec: peer: dc2 ``` + +A `HTTPRoute` may then reference this `example-mesh-service` as its `backendRef`. + + + +```yaml hideClipboard +apiVersion: gateway.networking.k8s.io/v1beta1 +kind: HTTPRoute +metadata: + name: example-route + ##... +spec: + ... + rules: + - backendRefs: + - group: api-gateway.consul.hashicorp.com + kind: MeshService + name: example-mesh-service + port: 3000 + ... +``` + From 72a3bf2296f9a0453458d2f368421e705bdf9c52 Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Mon, 17 Oct 2022 16:35:45 -0400 Subject: [PATCH 06/25] Add example ServiceResolver --- .../usage/route-to-peered-services.mdx | 23 +++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/website/content/docs/api-gateway/usage/route-to-peered-services.mdx b/website/content/docs/api-gateway/usage/route-to-peered-services.mdx index bc5e0a9d56a3..e89c9487ce15 100644 --- a/website/content/docs/api-gateway/usage/route-to-peered-services.mdx +++ b/website/content/docs/api-gateway/usage/route-to-peered-services.mdx @@ -11,7 +11,8 @@ This topic describes how to configure Consul API Gateway to route traffic to ser 1. Verify that the [requirements](/docs/api-gateway/tech-specs) have been met. 1. Verify that the Consul API Gateway CRDs and controller have been installed and applied. Refer to [Installation](/docs/api-gateway/install) for details. -1. Verify that a peering connection has been established between Consul clusters and that at least one service has been exported to the cluster containing your `Gateway`. Refer to [Cluster Peering on Kubernetes](https://developer.hashicorp.com/consul/docs/connect/cluster-peering/k8s) for details. +1. Verify that a peering connection has been established between Consul clusters and that the Consul service you want to route to has been exported to the cluster containing your `Gateway`. Refer to [Cluster Peering on Kubernetes](https://developer.hashicorp.com/consul/docs/connect/cluster-peering/k8s) for details. +1. Verify that a `ServiceResolver` has been created in the cluster containing your `Gateway` for the Consul service you want to route to ## Configuration @@ -22,7 +23,21 @@ Configure the following fields in your `MeshService` configuration to use this f ## Example -In the following example, routes using the example-mesh-service as a backend will send requests to the `echo` service exported by the peered Consul cluster, `dc2`. +In the following example, routes using `example-mesh-service` as a backend will send requests to the `echo` service exported by the peered Consul cluster, `cluster-02`. + + + +```yaml hideClipboard +apiVersion: consul.hashicorp.com/v1alpha1 +kind: ServiceResolver +metadata: + name: echo +spec: + redirect: + peer: cluster-02 + service: echo +``` + @@ -34,11 +49,11 @@ metadata: ##... spec: name: echo - peer: dc2 + peer: cluster-02 ``` -A `HTTPRoute` may then reference this `example-mesh-service` as its `backendRef`. +A `HTTPRoute` may then reference `example-mesh-service` as its `backendRef`. From 41dfa896534756bb74cb8c35d7291e7f3b6b77dd Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Mon, 17 Oct 2022 16:45:18 -0400 Subject: [PATCH 07/25] Add note about current ServiceResolver requirement ServiceResolver may eventually be created implicitly by the API gateway controller, but that decision is pending. --- website/content/docs/api-gateway/configuration/meshservice.mdx | 3 +++ 1 file changed, 3 insertions(+) diff --git a/website/content/docs/api-gateway/configuration/meshservice.mdx b/website/content/docs/api-gateway/configuration/meshservice.mdx index c1e6f01d27a1..dcb1e6f9f86d 100644 --- a/website/content/docs/api-gateway/configuration/meshservice.mdx +++ b/website/content/docs/api-gateway/configuration/meshservice.mdx @@ -35,5 +35,8 @@ Specifies the name of the service in the Consul service mesh to send traffic to. ### peer Specifies the name of the Consul peer exporting the service. If not specified, the service is assumed to be in the local datacenter. + +Note that a [ServiceResolver](/docs/connect/config-entries/service-resolver) is also required for the referenced Consul service indicating what peer the service is exported by. + * Type: string * Required: optional From 9d4c77a51f7a602f22be272714d027fe8832316f Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 21 Oct 2022 13:18:24 -0700 Subject: [PATCH 08/25] tweaks to the usage page for routing to peered services --- .../api-gateway/usage/route-to-peered-services.mdx | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/website/content/docs/api-gateway/usage/route-to-peered-services.mdx b/website/content/docs/api-gateway/usage/route-to-peered-services.mdx index e89c9487ce15..0ce8c4cbb637 100644 --- a/website/content/docs/api-gateway/usage/route-to-peered-services.mdx +++ b/website/content/docs/api-gateway/usage/route-to-peered-services.mdx @@ -1,6 +1,6 @@ --- -Page_title: Route Traffic to Peered Services -Description: Learn how to configure Consul API Gateway to route traffic to services connected to the mesh through a peering connection. +page_title: Route Traffic to Peered Services +description: Learn how to configure Consul API Gateway to route traffic to services connected to the mesh through a peering connection. --- # Route Traffic to Peered Services @@ -11,8 +11,9 @@ This topic describes how to configure Consul API Gateway to route traffic to ser 1. Verify that the [requirements](/docs/api-gateway/tech-specs) have been met. 1. Verify that the Consul API Gateway CRDs and controller have been installed and applied. Refer to [Installation](/docs/api-gateway/install) for details. -1. Verify that a peering connection has been established between Consul clusters and that the Consul service you want to route to has been exported to the cluster containing your `Gateway`. Refer to [Cluster Peering on Kubernetes](https://developer.hashicorp.com/consul/docs/connect/cluster-peering/k8s) for details. -1. Verify that a `ServiceResolver` has been created in the cluster containing your `Gateway` for the Consul service you want to route to +1. A peering connection must already be established between Consul clusters. Refer to [Cluster Peering on Kubernetes](/docs/connect/cluster-peering/k8s) for instructions. +1. The Consul service you want to route traffic to must be exported to the cluster containing your `Gateway`. Refer to [Cluster Peering on Kubernetes](/docs/connect/cluster-peering/k8s) for instructions. +1. A `ServiceResolver` for the Consul service you want to route traffic to must be created in the cluster that contains your `Gateway`. Refer to [Service Resolver Configuration Entry](/docs/connect/config-entries/service-resolver) for instructions. ## Configuration @@ -23,7 +24,7 @@ Configure the following fields in your `MeshService` configuration to use this f ## Example -In the following example, routes using `example-mesh-service` as a backend will send requests to the `echo` service exported by the peered Consul cluster, `cluster-02`. +In the following example, routes that use `example-mesh-service` as a backend are configured to send requests to the `echo` service exported by the peered Consul cluster `cluster-02`. @@ -53,7 +54,7 @@ spec: ``` -A `HTTPRoute` may then reference `example-mesh-service` as its `backendRef`. +After applying the configuration, an `HTTPRoute` may then reference `example-mesh-service` as its `backendRef`. From 0d8bad1d020a0f02eccc83b1e2bea0e5782716a7 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 21 Oct 2022 13:32:47 -0700 Subject: [PATCH 09/25] tweaks to the description in the configuration reference --- .../content/docs/api-gateway/configuration/meshservice.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/content/docs/api-gateway/configuration/meshservice.mdx b/website/content/docs/api-gateway/configuration/meshservice.mdx index dcb1e6f9f86d..8847495874fb 100644 --- a/website/content/docs/api-gateway/configuration/meshservice.mdx +++ b/website/content/docs/api-gateway/configuration/meshservice.mdx @@ -34,9 +34,9 @@ Specifies the name of the service in the Consul service mesh to send traffic to. * Required: required ### peer -Specifies the name of the Consul peer exporting the service. If not specified, the service is assumed to be in the local datacenter. +Specifies the name of the peered Consul cluster from where the service is exported. If not specified, Consul defaults to the local datacenter. -Note that a [ServiceResolver](/docs/connect/config-entries/service-resolver) is also required for the referenced Consul service indicating what peer the service is exported by. +You must apply a [`ServiceResolver`](/docs/connect/config-entries/service-resolver) for the referenced service. The `ServiceResolver` configuration entry enables Consul to resolve routes to upstream service instances. * Type: string * Required: optional From a2a2d60a1f25e130c1eecd774fea0435d9d560ee Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 4 Nov 2022 12:18:07 -0700 Subject: [PATCH 10/25] resolved TO-DOs from previous iteration --- website/content/docs/api-gateway/tech-specs.mdx | 4 ++-- .../docs/api-gateway/usage/route-to-peered-services.mdx | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/website/content/docs/api-gateway/tech-specs.mdx b/website/content/docs/api-gateway/tech-specs.mdx index b0a0e4fadafb..0af53675d046 100644 --- a/website/content/docs/api-gateway/tech-specs.mdx +++ b/website/content/docs/api-gateway/tech-specs.mdx @@ -48,9 +48,9 @@ The following table lists API Gateway limitations related to specific Consul fea | Consul Feature | Limitation | | -------------- | ---------- | -| [Admin partitions](/docs/enterprise/admin-partitions) | You can only deploy Consul API Gateway into the `default` admin partition and it can only route to other services within that partition, i.e. you cannot route to services in other admin partitions. | +| [Admin partitions](/docs/enterprise/admin-partitions) | You can only deploy Consul API Gateway into the `default` admin partition. You can route to services in other admin partitions through peered connections. Refer to [Route Traffic to Peered Services](/consul/docs/api-gateway/usage/route-to-peered-services) for additional information. | | Datacenter federation | If you are connecting multiple Consul datacenters to create a federated network, you can only deploy Consul API Gateway in the `primary` datacenter. | -| Routing between datacenters | If you are connecting multiple Consul datacenters to create a federated network, API Gateway can only route traffic to Services in the local datacenter. However, API Gateway can route to Services in other Kubernetes clusters when they are in the same Consul datacenter. Refer to [Single Consul Datacenter in Multiple Kubernetes Clusters](/docs/k8s/deployment-configurations/single-dc-multi-k8s) for more details. | +| Routing between datacenters | If you are connecting multiple Consul datacenters to create a federated network, you can route to services in other datacenters through peered connections. Refer to [Route Traffic to Peered Services](/consul/docs/api-gateway/usage/route-to-peered-services) for additional information. | ## Deployment Environments diff --git a/website/content/docs/api-gateway/usage/route-to-peered-services.mdx b/website/content/docs/api-gateway/usage/route-to-peered-services.mdx index 0ce8c4cbb637..93dceb3f0bed 100644 --- a/website/content/docs/api-gateway/usage/route-to-peered-services.mdx +++ b/website/content/docs/api-gateway/usage/route-to-peered-services.mdx @@ -9,6 +9,7 @@ This topic describes how to configure Consul API Gateway to route traffic to ser ## Requirements +1. Consul 1.14 or later 1. Verify that the [requirements](/docs/api-gateway/tech-specs) have been met. 1. Verify that the Consul API Gateway CRDs and controller have been installed and applied. Refer to [Installation](/docs/api-gateway/install) for details. 1. A peering connection must already be established between Consul clusters. Refer to [Cluster Peering on Kubernetes](/docs/connect/cluster-peering/k8s) for instructions. From 5728d69fdc99f3c34be10d772cc089cdbe88116c Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Mon, 7 Nov 2022 10:52:56 -0500 Subject: [PATCH 11/25] Remove datacenter federation from limited support matrix --- website/content/docs/api-gateway/tech-specs.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/website/content/docs/api-gateway/tech-specs.mdx b/website/content/docs/api-gateway/tech-specs.mdx index 0af53675d046..f9b7bee11259 100644 --- a/website/content/docs/api-gateway/tech-specs.mdx +++ b/website/content/docs/api-gateway/tech-specs.mdx @@ -49,7 +49,6 @@ The following table lists API Gateway limitations related to specific Consul fea | Consul Feature | Limitation | | -------------- | ---------- | | [Admin partitions](/docs/enterprise/admin-partitions) | You can only deploy Consul API Gateway into the `default` admin partition. You can route to services in other admin partitions through peered connections. Refer to [Route Traffic to Peered Services](/consul/docs/api-gateway/usage/route-to-peered-services) for additional information. | -| Datacenter federation | If you are connecting multiple Consul datacenters to create a federated network, you can only deploy Consul API Gateway in the `primary` datacenter. | | Routing between datacenters | If you are connecting multiple Consul datacenters to create a federated network, you can route to services in other datacenters through peered connections. Refer to [Route Traffic to Peered Services](/consul/docs/api-gateway/usage/route-to-peered-services) for additional information. | ## Deployment Environments From caea307e8b65d043ec605fe744d0db5da1ebba35 Mon Sep 17 00:00:00 2001 From: Sarah Alsmiller Date: Mon, 7 Nov 2022 17:21:15 -0600 Subject: [PATCH 12/25] added tolerations doc --- .../configuration/gatewayclassconfig.mdx | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx index 2aba347737e5..e93f193a500c 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx @@ -39,6 +39,7 @@ The following outline shows how to format the configurations in the `GatewayClas * [`envoy`](#image-envoy): string | optional * [`logLevel`](#loglevel): string | optional * [`nodeSelector`](#nodeselector): string | optional +* [`tolerations`](#tolerations): array of objects | optional * [`serviceType`](#servicetype): string | optional * [`useHostPorts`](#usehostports): boolean | optional @@ -158,6 +159,46 @@ Pods normally run on multiple nodes. You can specify a set of parameters in the * Type: string * Required: optional +### tolerations +When opperating Kubernetes, it is possible to apply a taint to a node running pods. Tolerations allow you to specify which pods are allowed to run on those tained nodes. Refer to the [Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) for additional information. + +* Type: Array of Objects +* Required: optional + +You can create an array of the following object to specify a toleration +#### toleration.key +The key value of the taint being described + +* Type: string +* Required: yes + +#### toleration.operator +The operation being applied to the taints being allowed. + +* Type: string +* Required: yes +* Default: Equal + +You can specify the following strings +* `Equal` +* `Exists` +#### toleration.value +If the operator is "Equal", the value being matched + +* Type: string +* Required: If operator is set to "Equal" + +#### toleration.effect +The effect the taint should cause the pod + +* Type: string +* Required: no + +You can specify the following strings: +* `NoExecute` +* `NoSchedule` +* `PreferNoSchedule` + ### serviceType Specifies the ingress methods for the gateway's Kubernetes service. * Type: string From 1934711667da2ed0bec15e1bdd61d5f7aedb1cbd Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Mon, 7 Nov 2022 18:33:12 -0500 Subject: [PATCH 13/25] Remove note excluding k8s 1.24 since we now support it --- website/content/docs/api-gateway/tech-specs.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/website/content/docs/api-gateway/tech-specs.mdx b/website/content/docs/api-gateway/tech-specs.mdx index f9b7bee11259..5bfec5fc1699 100644 --- a/website/content/docs/api-gateway/tech-specs.mdx +++ b/website/content/docs/api-gateway/tech-specs.mdx @@ -18,7 +18,6 @@ Verify that your environment meets the following requirements prior to using Con Your datacenter must meet the following requirements prior to configuring the Consul API Gateway: - Kubernetes 1.21+ - - Kubernetes 1.24 is not supported at this time. - `kubectl` 1.21+ - Consul 1.11.2+ - HashiCorp Consul Helm chart 0.47.1+ From ad068aeeb31b92479b96d9e9031949d5af75df32 Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Mon, 7 Nov 2022 18:58:10 -0500 Subject: [PATCH 14/25] Reorder sections to maintain alphabetical sort --- .../configuration/gatewayclassconfig.mdx | 29 ++++++++++--------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx index e93f193a500c..e6bda0e02b3a 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx @@ -39,8 +39,8 @@ The following outline shows how to format the configurations in the `GatewayClas * [`envoy`](#image-envoy): string | optional * [`logLevel`](#loglevel): string | optional * [`nodeSelector`](#nodeselector): string | optional -* [`tolerations`](#tolerations): array of objects | optional * [`serviceType`](#servicetype): string | optional +* [`tolerations`](#tolerations): array of objects | optional * [`useHostPorts`](#usehostports): boolean | optional ## Specification @@ -159,8 +159,20 @@ Pods normally run on multiple nodes. You can specify a set of parameters in the * Type: string * Required: optional +### serviceType +Specifies the ingress methods for the gateway's Kubernetes service. +* Type: string +* Required: optional + +You can specify the following strings: +* `ClusterIP`: The gateway is only accessible from inside the cluster. +* `NodePort`: The gateway is exposed on each Kubernetes node at a static port. +* `LoadBalancer`: The gateway is exposed to external traffic by a load balancer. + +For more on Kubernetes services, see [Publishing Services](https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types). + ### tolerations -When opperating Kubernetes, it is possible to apply a taint to a node running pods. Tolerations allow you to specify which pods are allowed to run on those tained nodes. Refer to the [Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) for additional information. +When operating Kubernetes, it is possible to apply a taint to a node running pods. Tolerations allow you to specify which pods are allowed to run on those tainted nodes. Refer to the [Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) for additional information. * Type: Array of Objects * Required: optional @@ -182,6 +194,7 @@ The operation being applied to the taints being allowed. You can specify the following strings * `Equal` * `Exists` + #### toleration.value If the operator is "Equal", the value being matched @@ -199,18 +212,6 @@ You can specify the following strings: * `NoSchedule` * `PreferNoSchedule` -### serviceType -Specifies the ingress methods for the gateway's Kubernetes service. -* Type: string -* Required: optional - -You can specify the following strings: -* `ClusterIP`: The gateway is only accessible from inside the cluster. -* `NodePort`: The gateway is exposed on each Kubernetes node at a static port. -* `LoadBalancer`: The gateway is exposed to external traffic by a load balancer. - -For more on Kubernetes services, see [Publishing Services](https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types). - ### useHostPorts If set to `true`, then the Envoy container ports are mapped to host ports. * Type: boolean From 86cffa3976f5a218ca865594f956bedcbe7f01c7 Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Tue, 8 Nov 2022 10:31:12 -0500 Subject: [PATCH 15/25] Add example configuration for MeshService resource --- .../api-gateway/configuration/meshservice.mdx | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/configuration/meshservice.mdx b/website/content/docs/api-gateway/configuration/meshservice.mdx index 8847495874fb..828fbdbfa045 100644 --- a/website/content/docs/api-gateway/configuration/meshservice.mdx +++ b/website/content/docs/api-gateway/configuration/meshservice.mdx @@ -36,7 +36,23 @@ Specifies the name of the service in the Consul service mesh to send traffic to. ### peer Specifies the name of the peered Consul cluster from where the service is exported. If not specified, Consul defaults to the local datacenter. -You must apply a [`ServiceResolver`](/docs/connect/config-entries/service-resolver) for the referenced service. The `ServiceResolver` configuration entry enables Consul to resolve routes to upstream service instances. +You must apply a [`ServiceResolver`](/docs/connect/config-entries/service-resolver) for the referenced service. The `ServiceResolver` configuration entry enables Consul to resolve routes to upstream service instances. * Type: string * Required: optional + +## Example Configuration + +The following example creates a mesh service called `example-mesh-service`. Routes that use `example-mesh-service` as a backend will route traffic to the Consul service in the local datacenter named `echo`. + + + +```yaml hideClipboard +apiVersion: api-gateway.consul.hashicorp.com/v1alpha1 +kind: MeshService +metadata: + name: example-mesh-service +spec: + name: echo +``` + From b3585ec84280e7b7c8cd0ff8f7ab7ee1eef380fa Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Tue, 8 Nov 2022 10:31:36 -0500 Subject: [PATCH 16/25] Adjust wording + indentation of other docs --- .../configuration/gatewayclass.mdx | 24 +++++++++---------- .../usage/route-to-peered-services.mdx | 2 +- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/website/content/docs/api-gateway/configuration/gatewayclass.mdx b/website/content/docs/api-gateway/configuration/gatewayclass.mdx index 8150860bec59..2cdac8e28a76 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclass.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclass.mdx @@ -62,18 +62,18 @@ The following example creates a gateway class called `test-gateway-class`: - ```yaml - apiVersion: gateway.networking.k8s.io/v1alpha2 - kind: GatewayClass - metadata: - name: test-gateway-class - spec: - controllerName: 'hashicorp.com/consul-api-gateway-controller' - parametersRef: - group: api-gateway.consul.hashicorp.com - kind: GatewayClassConfig - name: test-gateway-class-config - description: The gateway class is for creating test gateways class configurations +```yaml +apiVersion: gateway.networking.k8s.io/v1alpha2 +kind: GatewayClass +metadata: + name: test-gateway-class +spec: + controllerName: 'hashicorp.com/consul-api-gateway-controller' + parametersRef: + group: api-gateway.consul.hashicorp.com + kind: GatewayClassConfig + name: test-gateway-class-config + description: The gateway class is for creating test gateways class configurations ``` diff --git a/website/content/docs/api-gateway/usage/route-to-peered-services.mdx b/website/content/docs/api-gateway/usage/route-to-peered-services.mdx index 93dceb3f0bed..5e762e6fa5f9 100644 --- a/website/content/docs/api-gateway/usage/route-to-peered-services.mdx +++ b/website/content/docs/api-gateway/usage/route-to-peered-services.mdx @@ -13,7 +13,7 @@ This topic describes how to configure Consul API Gateway to route traffic to ser 1. Verify that the [requirements](/docs/api-gateway/tech-specs) have been met. 1. Verify that the Consul API Gateway CRDs and controller have been installed and applied. Refer to [Installation](/docs/api-gateway/install) for details. 1. A peering connection must already be established between Consul clusters. Refer to [Cluster Peering on Kubernetes](/docs/connect/cluster-peering/k8s) for instructions. -1. The Consul service you want to route traffic to must be exported to the cluster containing your `Gateway`. Refer to [Cluster Peering on Kubernetes](/docs/connect/cluster-peering/k8s) for instructions. +1. The Consul service that you want to route traffic to must be exported to the cluster containing your `Gateway`. Refer to [Cluster Peering on Kubernetes](/docs/connect/cluster-peering/k8s) for instructions. 1. A `ServiceResolver` for the Consul service you want to route traffic to must be created in the cluster that contains your `Gateway`. Refer to [Service Resolver Configuration Entry](/docs/connect/config-entries/service-resolver) for instructions. ## Configuration From 382ac14af2871883ae92d9f1b030bfb73320afa5 Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Tue, 8 Nov 2022 10:39:26 -0500 Subject: [PATCH 17/25] Use consistent "example-" prefix for resource names in example code --- .../content/docs/api-gateway/configuration/gatewayclass.mdx | 6 +++--- .../docs/api-gateway/configuration/gatewayclassconfig.mdx | 4 ++-- .../docs/api-gateway/usage/route-to-peered-services.mdx | 2 -- 3 files changed, 5 insertions(+), 7 deletions(-) diff --git a/website/content/docs/api-gateway/configuration/gatewayclass.mdx b/website/content/docs/api-gateway/configuration/gatewayclass.mdx index 2cdac8e28a76..152926be8363 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclass.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclass.mdx @@ -58,7 +58,7 @@ Specifies a human-readable description of the gateway class. We recommend using * Required: optional ## Example Configuration -The following example creates a gateway class called `test-gateway-class`: +The following example creates a gateway class called `example-gateway-class`: @@ -66,13 +66,13 @@ The following example creates a gateway class called `test-gateway-class`: apiVersion: gateway.networking.k8s.io/v1alpha2 kind: GatewayClass metadata: - name: test-gateway-class + name: example-gateway-class spec: controllerName: 'hashicorp.com/consul-api-gateway-controller' parametersRef: group: api-gateway.consul.hashicorp.com kind: GatewayClassConfig - name: test-gateway-class-config + name: example-gateway-class-config description: The gateway class is for creating test gateways class configurations ``` diff --git a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx index e6bda0e02b3a..0f6f8246b51e 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx @@ -220,7 +220,7 @@ If set to `true`, then the Envoy container ports are mapped to host ports. ## Example Configuration -The following example creates a gateway class configuration called `test-gateway-class-config`. Traffic that passes through gateways created from the class configuration authenticate with Consul over HTTPS on port `8501`. Consul client agents communicate with server agents on port `8502` : +The following example creates a gateway class configuration called `example-gateway-class-config`. Traffic that passes through gateways created from the class configuration authenticate with Consul over HTTPS on port `8501`. Consul client agents communicate with server agents on port `8502` : @@ -228,7 +228,7 @@ The following example creates a gateway class configuration called `test-gateway apiVersion: api-gateway.consul.hashicorp.com/v1alpha1 kind: GatewayClassConfig metadata: - name: test-gateway-class-config + name: example-gateway-class-config spec: useHostPorts: true logLevel: 'trace' diff --git a/website/content/docs/api-gateway/usage/route-to-peered-services.mdx b/website/content/docs/api-gateway/usage/route-to-peered-services.mdx index 5e762e6fa5f9..1834c7b43aec 100644 --- a/website/content/docs/api-gateway/usage/route-to-peered-services.mdx +++ b/website/content/docs/api-gateway/usage/route-to-peered-services.mdx @@ -48,7 +48,6 @@ apiVersion: api-gateway.consul.hashicorp.com/v1alpha1 kind: MeshService metadata: name: example-mesh-service - ##... spec: name: echo peer: cluster-02 @@ -64,7 +63,6 @@ apiVersion: gateway.networking.k8s.io/v1beta1 kind: HTTPRoute metadata: name: example-route - ##... spec: ... rules: From 85b5d6bc3779ad65ca4256791d1a6111642ae538 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Thu, 10 Nov 2022 11:54:49 -0800 Subject: [PATCH 18/25] reframed the tolerations documentation; STILL A WIP --- .../configuration/gatewayclassconfig.mdx | 57 +++++++++---------- 1 file changed, 28 insertions(+), 29 deletions(-) diff --git a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx index 0f6f8246b51e..525003c66773 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx @@ -41,6 +41,10 @@ The following outline shows how to format the configurations in the `GatewayClas * [`nodeSelector`](#nodeselector): string | optional * [`serviceType`](#servicetype): string | optional * [`tolerations`](#tolerations): array of objects | optional + * [`key`](#tolerations): string | required + * [`operator`](#tolerations): string | required + * [`value`](#tolerations): string | optional + * [`effect`](#tolerations): string | optional * [`useHostPorts`](#usehostports): boolean | optional ## Specification @@ -172,45 +176,40 @@ You can specify the following strings: For more on Kubernetes services, see [Publishing Services](https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types). ### tolerations -When operating Kubernetes, it is possible to apply a taint to a node running pods. Tolerations allow you to specify which pods are allowed to run on those tainted nodes. Refer to the [Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) for additional information. +When operating Kubernetes, you can apply a _taint_ to a node. Kubernetes taints are properties that allow a node to repel pods. You can apply `tolerations` to your `GatewayClassConfig`, which allows pods to tolerate a taint and run on the nodes that would normally repel pods. * Type: Array of Objects * Required: optional -You can create an array of the following object to specify a toleration -#### toleration.key -The key value of the taint being described +When a pod matches the taint configuration `key`, it processes the `operation` configuration to determine how to apply the `effect`. The `value` is a secondary property that allows you to refine the match. Refer to the [Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) for additional information. -* Type: string -* Required: yes - -#### toleration.operator -The operation being applied to the taints being allowed. +The `tolerations` block has the following array of objects: -* Type: string -* Required: yes -* Default: Equal +| Parameter | Description | Type | Required | +| --- | --- | --- | --- | +| `key` | Specifies the `key` property for matching the node's taint configuration. Kubernetes taints are identified by their `key` properties. | String | Required | +| `operator` | Specifies an operation to apply for matching the taint to the toleration. You can specify the following strings:
  • `Equal`: Performs the action specified in the `effect` configuration if the `value` of the `key` in the taint configuration matches the `value` of the pod's `key` configuration.
  • `Exists`: Performs the action specified in the `effect` configuration if the `key` specified in the `tolerations` configuration exists in the taint configuration.
    • Default is `Equal`.| String | Required | +| `value` | Specifies a matching value in the taint node configuration when the `operator` is set to `Equal`. If a match is found, Consul API Gateway performs the action specified in the `effect` configuration. | String | Required if operator is set to `Equal`. | +| `effect` | Specifies the action that should occur when pod attempts to run on a tainted node. You can specify the following strings:
  • `NoExecute`: The node does not run the pod.
  • `NoSchedule`: The node may run the pod, but does not schedule it.
  • `PreferNoSchedule`: The node may run and schedule the pod, but the prod has a lower precedence than other pods being scheduled.
    • Default is `NoSchedule`. | String | Optional | -You can specify the following strings -* `Equal` -* `Exists` +In the following example, TBD -#### toleration.value -If the operator is "Equal", the value being matched - -* Type: string -* Required: If operator is set to "Equal" - -#### toleration.effect -The effect the taint should cause the pod + -* Type: string -* Required: no + ```yaml + apiVersion: api-gateway.consul.hashicorp.com/v1alpha1 + kind: GatewayClassConfig + metadata: + name: example-gateway-class-config + spec: + tolerations: + key: key1 + operator: Equal + value: value1 + effect: NoSchedule -You can specify the following strings: -* `NoExecute` -* `NoSchedule` -* `PreferNoSchedule` +``` + ### useHostPorts If set to `true`, then the Envoy container ports are mapped to host ports. From da86d9de1396512e0dda93b400cbb63c2e3a5b02 Mon Sep 17 00:00:00 2001 From: Sarah Alsmiller Date: Mon, 14 Nov 2022 09:55:51 -0600 Subject: [PATCH 19/25] add helm chart documentation --- website/content/docs/k8s/helm.mdx | 48 ++++++++++++++++++------------- 1 file changed, 28 insertions(+), 20 deletions(-) diff --git a/website/content/docs/k8s/helm.mdx b/website/content/docs/k8s/helm.mdx index 4a5206e54824..d6cd748cd157 100644 --- a/website/content/docs/k8s/helm.mdx +++ b/website/content/docs/k8s/helm.mdx @@ -226,14 +226,14 @@ Use these links to navigate to a particular top-level stanza. ``` and check the name of `metadata.name`. - - `controllerRole` ((#v-global-secretsbackend-vault-controllerrole)) (`string: ""`) - The Vault role to read Consul controller's webhook's + - `controllerRole` ((#v-global-secretsbackend-vault-controllerrole)) (`string: ""`) - The Vault role to read Consul controller's webhook's CA and issue a certificate and private key. - A Vault policy must be created which grants issue capabilities to + A Vault policy must be created which grants issue capabilities to `global.secretsBackend.vault.controller.tlsCert.secretName`. - `connectInjectRole` ((#v-global-secretsbackend-vault-connectinjectrole)) (`string: ""`) - The Vault role to read Consul connect-injector webhook's CA and issue a certificate and private key. - A Vault policy must be created which grants issue capabilities to + A Vault policy must be created which grants issue capabilities to `global.secretsBackend.vault.connectInject.tlsCert.secretName`. - `consulCARole` ((#v-global-secretsbackend-vault-consulcarole)) (`string: ""`) - The Vault role for all Consul components to read the Consul's server's CA Certificate (unauthenticated). @@ -296,14 +296,14 @@ Use these links to navigate to a particular top-level stanza. - `controller` ((#v-global-secretsbackend-vault-controller)) - - `tlsCert` ((#v-global-secretsbackend-vault-controller-tlscert)) - Configuration to the Vault Secret that Kubernetes will use on + - `tlsCert` ((#v-global-secretsbackend-vault-controller-tlscert)) - Configuration to the Vault Secret that Kubernetes will use on Kubernetes CRD creation, deletion, and update, to get TLS certificates used issued from vault to send webhooks to the controller. - `secretName` ((#v-global-secretsbackend-vault-controller-tlscert-secretname)) (`string: null`) - The Vault secret path that issues TLS certificates for controller webhooks. - - `caCert` ((#v-global-secretsbackend-vault-controller-cacert)) - Configuration to the Vault Secret that Kubernetes will use on + - `caCert` ((#v-global-secretsbackend-vault-controller-cacert)) - Configuration to the Vault Secret that Kubernetes will use on Kubernetes CRD creation, deletion, and update, to get CA certificates used issued from vault to send webhooks to the controller. @@ -312,14 +312,14 @@ Use these links to navigate to a particular top-level stanza. - `connectInject` ((#v-global-secretsbackend-vault-connectinject)) - - `caCert` ((#v-global-secretsbackend-vault-connectinject-cacert)) - Configuration to the Vault Secret that Kubernetes will use on + - `caCert` ((#v-global-secretsbackend-vault-connectinject-cacert)) - Configuration to the Vault Secret that Kubernetes will use on Kubernetes pod creation, deletion, and update, to get CA certificates used issued from vault to send webhooks to the ConnectInject. - `secretName` ((#v-global-secretsbackend-vault-connectinject-cacert-secretname)) (`string: null`) - The Vault secret path that contains the CA certificate for Connect Inject webhooks. - - `tlsCert` ((#v-global-secretsbackend-vault-connectinject-tlscert)) - Configuration to the Vault Secret that Kubernetes will use on + - `tlsCert` ((#v-global-secretsbackend-vault-connectinject-tlscert)) - Configuration to the Vault Secret that Kubernetes will use on Kubernetes pod creation, deletion, and update, to get TLS certificates used issued from vault to send webhooks to the ConnectInject. @@ -568,7 +568,7 @@ Use these links to navigate to a particular top-level stanza. - `enabled` ((#v-global-openshift-enabled)) (`boolean: false`) - If true, the Helm chart will create necessary configuration for running its components on OpenShift. - - `consulAPITimeout` ((#v-global-consulapitimeout)) (`string: 5s`) - The time in seconds that the consul API client will wait for a response from + - `consulAPITimeout` ((#v-global-consulapitimeout)) (`string: 5s`) - The time in seconds that the consul API client will wait for a response from the API before cancelling the request. - `cloud` ((#v-global-cloud)) - Enables installing an HCP Consul self-managed cluster. @@ -633,7 +633,7 @@ Use these links to navigate to a particular top-level stanza. Vault Secrets backend: If you are using Vault as a secrets backend, a Vault Policy must be created which allows `["create", "update"]` - capabilities on the PKI issuing endpoint, which is usually of the form `pki/issue/consul-server`. + capabilities on the PKI issuing endpoint, which is usually of the form `pki/issue/consul-server`. Please see the following guide for steps to generate a compatible certificate: https://learn.hashicorp.com/tutorials/consul/vault-pki-consul-secure-tls Note: when using TLS, both the `server.serverCert` and `global.tls.caCert` which points to the CA endpoint of this PKI engine @@ -669,13 +669,13 @@ Use these links to navigate to a particular top-level stanza. - `storageClass` ((#v-server-storageclass)) (`string: null`) - The StorageClass to use for the servers' StatefulSet storage. It must be able to be dynamically provisioned if you want the storage - to be automatically created. For example, to use + to be automatically created. For example, to use local(https://kubernetes.io/docs/concepts/storage/storage-classes/#local) storage classes, the PersistentVolumeClaims would need to be manually created. A `null` value will use the Kubernetes cluster's default StorageClass. If a default StorageClass does not exist, you will need to create one. - Refer to the [Read/Write Tuning](https://www.consul.io/docs/install/performance#read-write-tuning) - section of the Server Performance Requirements documentation for considerations + Refer to the [Read/Write Tuning](https://www.consul.io/docs/install/performance#read-write-tuning) + section of the Server Performance Requirements documentation for considerations around choosing a performant storage class. ~> **Note:** The [Reference Architecture](https://learn.hashicorp.com/tutorials/consul/reference-architecture#hardware-sizing-for-consul-servers) @@ -1442,8 +1442,8 @@ Use these links to navigate to a particular top-level stanza. already exist, it will be created. Turning this on overrides the `consulDestinationNamespace` setting. `addK8SNamespaceSuffix` may no longer be needed if enabling this option. - If mirroring is enabled, avoid creating any Consul resources in the following - Kubernetes namespaces, as Consul currently reserves these namespaces for + If mirroring is enabled, avoid creating any Consul resources in the following + Kubernetes namespaces, as Consul currently reserves these namespaces for system use: "system", "universal", "operator", "root". - `mirroringK8SPrefix` ((#v-synccatalog-consulnamespaces-mirroringk8sprefix)) (`string: ""`) - If `mirroringK8S` is set to true, `mirroringK8SPrefix` allows each Consul namespace @@ -1585,7 +1585,7 @@ Use these links to navigate to a particular top-level stanza. - `disruptionBudget` ((#v-connectinject-disruptionbudget)) - This configures the PodDisruptionBudget (https://kubernetes.io/docs/tasks/run-application/configure-pdb/) for the service mesh sidecar injector. - - `enabled` ((#v-connectinject-disruptionbudget-enabled)) (`boolean: true`) - This will enable/disable registering a PodDisruptionBudget for the + - `enabled` ((#v-connectinject-disruptionbudget-enabled)) (`boolean: true`) - This will enable/disable registering a PodDisruptionBudget for the service mesh sidecar injector. If this is enabled, it will only register the budget so long as the service mesh is enabled. @@ -1597,7 +1597,7 @@ Use these links to navigate to a particular top-level stanza. - `cni` ((#v-connectinject-cni)) - Configures consul-cni plugin for Consul Service mesh services - - `enabled` ((#v-connectinject-cni-enabled)) (`boolean: false`) - If true, then all traffic redirection setup will use the consul-cni plugin. + - `enabled` ((#v-connectinject-cni-enabled)) (`boolean: false`) - If true, then all traffic redirection setup will use the consul-cni plugin. Requires connectInject.enabled to also be true. - `logLevel` ((#v-connectinject-cni-loglevel)) (`string: null`) - Log level for the installer and plugin. Overrides global.logLevel @@ -1614,7 +1614,7 @@ Use these links to navigate to a particular top-level stanza. - `multus` ((#v-connectinject-cni-multus)) (`string: false`) - If multus CNI plugin is enabled with consul-cni. When enabled, consul-cni will not be installed as a chained CNI plugin. Instead, a NetworkAttachementDefinition CustomResourceDefinition (CRD) will be created in the helm release namespace. Following multus plugin standards, an annotation is required in order for the consul-cni plugin - to be executed and for your service to be added to the Consul Service Mesh. + to be executed and for your service to be added to the Consul Service Mesh. Add the annotation `'k8s.v1.cni.cncf.io/networks': '[{ "name":"consul-cni","namespace": "consul" }]'` to your pod to use the default installed NetworkAttachementDefinition CRD. @@ -1724,7 +1724,7 @@ Use these links to navigate to a particular top-level stanza. which can lead to hangs. In these environments it is recommend to use "Ignore" instead. This setting can be safely disabled by setting to "Ignore". - - `namespaceSelector` ((#v-connectinject-namespaceselector)) (`string`) - Selector for restricting the webhook to only specific namespaces. + - `namespaceSelector` ((#v-connectinject-namespaceselector)) (`string`) - Selector for restricting the webhook to only specific namespaces. Use with `connectInject.default: true` to automatically inject all pods in namespaces that match the selector. This should be set to a multiline string. See https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#matching-requests-namespaceselector for more details. @@ -1780,8 +1780,8 @@ Use these links to navigate to a particular top-level stanza. of the same name as their k8s namespace, optionally prefixed if `mirroringK8SPrefix` is set below. If the Consul namespace does not already exist, it will be created. Turning this on overrides the - `consulDestinationNamespace` setting. If mirroring is enabled, avoid creating any Consul - resources in the following Kubernetes namespaces, as Consul currently reserves these + `consulDestinationNamespace` setting. If mirroring is enabled, avoid creating any Consul + resources in the following Kubernetes namespaces, as Consul currently reserves these namespaces for system use: "system", "universal", "operator", "root". - `mirroringK8SPrefix` ((#v-connectinject-consulnamespaces-mirroringk8sprefix)) (`string: ""`) - If `mirroringK8S` is set to true, `mirroringK8SPrefix` allows each Consul namespace @@ -2304,6 +2304,10 @@ Use these links to navigate to a particular top-level stanza. beta.kubernetes.io/arch: amd64 ``` + - `tolerations` ((#v-apigateway-managedgatewayclass-tolerations)) (`string: ""`) - Toleration settings for gateway pods created with the managed gateway class. This + should be a multi-line string matching the Tolerations. + (https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) array in a Pod spec. + - `serviceType` ((#v-apigateway-managedgatewayclass-servicetype)) (`string: LoadBalancer`) - This value defines the type of service created for gateways (e.g. LoadBalancer, ClusterIP) - `useHostPorts` ((#v-apigateway-managedgatewayclass-usehostports)) (`boolean: false`) - This value toggles if the gateway ports should be mapped to host ports @@ -2366,6 +2370,10 @@ Use these links to navigate to a particular top-level stanza. beta.kubernetes.io/arch: amd64 ``` + - `tolerations` ((#v-apigateway-managedgatewayclass-tolerations)) (`string: ""`) - Toleration settings for the api gateway controller pod. This + should be a multi-line string matching the Tolerations + (https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) array in a Pod spec. + - `service` ((#v-apigateway-controller-service)) - Configuration for the Service created for the api-gateway-controller - `annotations` ((#v-apigateway-controller-service-annotations)) (`string: null`) - Annotations to apply to the api-gateway-controller service. From b13f74314f1139729914ae895a94b8e2e76a1700 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Mon, 14 Nov 2022 10:12:01 -0800 Subject: [PATCH 20/25] removed tolerations from gwcconfig configuration model reference --- .../configuration/gatewayclassconfig.mdx | 41 ------------------- 1 file changed, 41 deletions(-) diff --git a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx index 525003c66773..e6344a5b1ed1 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx @@ -40,11 +40,6 @@ The following outline shows how to format the configurations in the `GatewayClas * [`logLevel`](#loglevel): string | optional * [`nodeSelector`](#nodeselector): string | optional * [`serviceType`](#servicetype): string | optional -* [`tolerations`](#tolerations): array of objects | optional - * [`key`](#tolerations): string | required - * [`operator`](#tolerations): string | required - * [`value`](#tolerations): string | optional - * [`effect`](#tolerations): string | optional * [`useHostPorts`](#usehostports): boolean | optional ## Specification @@ -175,42 +170,6 @@ You can specify the following strings: For more on Kubernetes services, see [Publishing Services](https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types). -### tolerations -When operating Kubernetes, you can apply a _taint_ to a node. Kubernetes taints are properties that allow a node to repel pods. You can apply `tolerations` to your `GatewayClassConfig`, which allows pods to tolerate a taint and run on the nodes that would normally repel pods. - -* Type: Array of Objects -* Required: optional - -When a pod matches the taint configuration `key`, it processes the `operation` configuration to determine how to apply the `effect`. The `value` is a secondary property that allows you to refine the match. Refer to the [Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) for additional information. - -The `tolerations` block has the following array of objects: - -| Parameter | Description | Type | Required | -| --- | --- | --- | --- | -| `key` | Specifies the `key` property for matching the node's taint configuration. Kubernetes taints are identified by their `key` properties. | String | Required | -| `operator` | Specifies an operation to apply for matching the taint to the toleration. You can specify the following strings:
  • `Equal`: Performs the action specified in the `effect` configuration if the `value` of the `key` in the taint configuration matches the `value` of the pod's `key` configuration.
  • `Exists`: Performs the action specified in the `effect` configuration if the `key` specified in the `tolerations` configuration exists in the taint configuration.
    • Default is `Equal`.| String | Required | -| `value` | Specifies a matching value in the taint node configuration when the `operator` is set to `Equal`. If a match is found, Consul API Gateway performs the action specified in the `effect` configuration. | String | Required if operator is set to `Equal`. | -| `effect` | Specifies the action that should occur when pod attempts to run on a tainted node. You can specify the following strings:
  • `NoExecute`: The node does not run the pod.
  • `NoSchedule`: The node may run the pod, but does not schedule it.
  • `PreferNoSchedule`: The node may run and schedule the pod, but the prod has a lower precedence than other pods being scheduled.
    • Default is `NoSchedule`. | String | Optional | - -In the following example, TBD - - - - ```yaml - apiVersion: api-gateway.consul.hashicorp.com/v1alpha1 - kind: GatewayClassConfig - metadata: - name: example-gateway-class-config - spec: - tolerations: - key: key1 - operator: Equal - value: value1 - effect: NoSchedule - -``` - - ### useHostPorts If set to `true`, then the Envoy container ports are mapped to host ports. * Type: boolean From 4fff96eabd22eb4c1448ea12e2be1c9de8b18c4f Mon Sep 17 00:00:00 2001 From: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Date: Wed, 16 Nov 2022 07:41:28 -0800 Subject: [PATCH 21/25] Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> --- .../configuration/gatewayclassconfig.mdx | 2 +- .../api-gateway/configuration/meshservice.mdx | 12 +++++----- .../content/docs/api-gateway/tech-specs.mdx | 2 +- .../content/docs/api-gateway/usage/errors.mdx | 8 +++---- .../usage/reroute-http-requests.mdx | 12 +++++----- .../usage/route-to-peered-services.mdx | 8 +++---- .../content/docs/api-gateway/usage/usage.mdx | 2 +- website/content/docs/k8s/helm.mdx | 24 +++++++++---------- 8 files changed, 35 insertions(+), 35 deletions(-) diff --git a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx index e6344a5b1ed1..8f83a6cd890b 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx @@ -178,7 +178,7 @@ If set to `true`, then the Envoy container ports are mapped to host ports. ## Example Configuration -The following example creates a gateway class configuration called `example-gateway-class-config`. Traffic that passes through gateways created from the class configuration authenticate with Consul over HTTPS on port `8501`. Consul client agents communicate with server agents on port `8502` : +The following example creates a gateway class configuration called `example-gateway-class-config`. Traffic that passes through gateways created from the class configuration authenticates with Consul over HTTPS on port `8501`. Consul client agents communicate with server agents on port `8502`: diff --git a/website/content/docs/api-gateway/configuration/meshservice.mdx b/website/content/docs/api-gateway/configuration/meshservice.mdx index 828fbdbfa045..89b01ad20425 100644 --- a/website/content/docs/api-gateway/configuration/meshservice.mdx +++ b/website/content/docs/api-gateway/configuration/meshservice.mdx @@ -20,8 +20,8 @@ The service represented by the `MeshService` resource must either be in the same The following outline shows how to format the configurations in the `MeshService` object. Click on a property name to view details about the configuration. -* [`name`](#name): string | required -* [`peer`](#peer): string | optional +- [`name`](#name): string | required +- [`peer`](#peer): string | optional ## Specification @@ -34,16 +34,16 @@ Specifies the name of the service in the Consul service mesh to send traffic to. * Required: required ### peer -Specifies the name of the peered Consul cluster from where the service is exported. If not specified, Consul defaults to the local datacenter. +Specifies the name of the peered Consul cluster that exported the service. If not specified, Consul defaults to the local datacenter. You must apply a [`ServiceResolver`](/docs/connect/config-entries/service-resolver) for the referenced service. The `ServiceResolver` configuration entry enables Consul to resolve routes to upstream service instances. -* Type: string -* Required: optional +- Type: string +- Required: optional ## Example Configuration -The following example creates a mesh service called `example-mesh-service`. Routes that use `example-mesh-service` as a backend will route traffic to the Consul service in the local datacenter named `echo`. +The following example creates a mesh service called `example-mesh-service`. Routes that use `example-mesh-service` as a backend route traffic to the Consul service in the local datacenter named `echo`. diff --git a/website/content/docs/api-gateway/tech-specs.mdx b/website/content/docs/api-gateway/tech-specs.mdx index 5bfec5fc1699..b90706c3f0fb 100644 --- a/website/content/docs/api-gateway/tech-specs.mdx +++ b/website/content/docs/api-gateway/tech-specs.mdx @@ -47,7 +47,7 @@ The following table lists API Gateway limitations related to specific Consul fea | Consul Feature | Limitation | | -------------- | ---------- | -| [Admin partitions](/docs/enterprise/admin-partitions) | You can only deploy Consul API Gateway into the `default` admin partition. You can route to services in other admin partitions through peered connections. Refer to [Route Traffic to Peered Services](/consul/docs/api-gateway/usage/route-to-peered-services) for additional information. | +| [Admin partitions](/docs/enterprise/admin-partitions) | You can deploy Consul API Gateway into the `default` admin partition only. You can route to services in other `default` admin partitions through peered connections. Refer to [Route Traffic to Peered Services](/consul/docs/api-gateway/usage/route-to-peered-services) for additional information. | | Routing between datacenters | If you are connecting multiple Consul datacenters to create a federated network, you can route to services in other datacenters through peered connections. Refer to [Route Traffic to Peered Services](/consul/docs/api-gateway/usage/route-to-peered-services) for additional information. | ## Deployment Environments diff --git a/website/content/docs/api-gateway/usage/errors.mdx b/website/content/docs/api-gateway/usage/errors.mdx index 40f1d4011e7c..779f27344241 100644 --- a/website/content/docs/api-gateway/usage/errors.mdx +++ b/website/content/docs/api-gateway/usage/errors.mdx @@ -1,6 +1,6 @@ --- layout: docs -page_title: Use Consul API Gateway +page_title: Consul API Gateway Error Messages description: >- Learn how to apply a configured Consul API Gateway to your Kubernetes cluster, review the required fields for rerouting HTTP requests, and troubleshoot an error message. --- @@ -9,9 +9,9 @@ description: >- This topic provides information about potential error messages associated with Consul API Gateway. If you receive an error message that does not appear in this section, refer to the following resources: -* [Common Consul errors](/docs/troubleshoot/common-errors#common-errors-on-kubernetes) -* [Consul troubleshooting guide](/docs/troubleshoot/common-errors) -* [Consul Discuss forum](https://discuss.hashicorp.com/) +- [Common Consul errors](/docs/troubleshoot/common-errors#common-errors-on-kubernetes) +- [Consul troubleshooting guide](/docs/troubleshoot/common-errors) +- [Consul Discuss forum](https://discuss.hashicorp.com/)