From d9bbc819ce94847d098c4513dcc32c93f07ad21f Mon Sep 17 00:00:00 2001 From: hc-github-team-consul-core Date: Fri, 18 Nov 2022 10:38:37 -0500 Subject: [PATCH] Backport of Update docs for the release of Consul API Gateway v0.5 into release/1.14.x (#15451) * backport of commit 68ee017adfdf7cac37e1bc8fde5ae5e7caf1bddd * backport of commit f23b3662d89054fbf7b25298e023c3e8db779270 * backport of commit deaba3ef155f176cf17cc318c2b39355cba932fc * backport of commit d1f1ff50f8b3f295fcd1058dabcf8465b7268df0 * backport of commit e41ec340d8037ea8b7cd6e27577bb2e07d928363 * backport of commit 72a3bf2296f9a0453458d2f368421e705bdf9c52 * backport of commit 41dfa896534756bb74cb8c35d7291e7f3b6b77dd * backport of commit 9d4c77a51f7a602f22be272714d027fe8832316f * backport of commit 0d8bad1d020a0f02eccc83b1e2bea0e5782716a7 Co-authored-by: trujillo-adam Co-authored-by: Nathan Coleman Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- .../api-gateway/configuration/meshservice.mdx | 13 ++- .../content/docs/api-gateway/usage/errors.mdx | 60 ++++++++++ .../usage/reroute-http-requests.mdx | 58 ++++++++++ .../usage/route-to-peered-services.mdx | 77 +++++++++++++ .../docs/api-gateway/{ => usage}/usage.mdx | 108 ++---------------- website/data/docs-nav-data.json | 20 +++- 6 files changed, 235 insertions(+), 101 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/configuration/meshservice.mdx b/website/content/docs/api-gateway/configuration/meshservice.mdx index 2dd377fb68..8847495874 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 @@ -19,6 +21,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 +32,11 @@ 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 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. + +* Type: string +* Required: optional 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 0000000000..40f1d4011e --- /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 0000000000..8f457e934f --- /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 0000000000..0ce8c4cbb6 --- /dev/null +++ b/website/content/docs/api-gateway/usage/route-to-peered-services.mdx @@ -0,0 +1,77 @@ +--- +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. +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 + +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 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`. + + + +```yaml hideClipboard +apiVersion: consul.hashicorp.com/v1alpha1 +kind: ServiceResolver +metadata: + name: echo +spec: + redirect: + peer: cluster-02 + service: echo +``` + + + + +```yaml hideClipboard +apiVersion: api-gateway.consul.hashicorp.com/v1alpha1 +kind: MeshService +metadata: + name: example-mesh-service + ##... +spec: + name: echo + peer: cluster-02 +``` + + +After applying the configuration, an `HTTPRoute` may then reference `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 + ... +``` + 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 f5199d0c8f..31b6e78b4b 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 0f8cd54493..e21a8da7bd 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -1288,7 +1288,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",