-
Notifications
You must be signed in to change notification settings - Fork 4.4k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update docs for the release of Consul API Gateway v0.5 (#15015)
* added usage folder to organize use case docs for CAPIgw * Add peer field to MeshService configuration page * Add first pass at guide for routing to peered services * Add exception to same-datacenter restriction for referenced Consul service * Add example HTTPRoute referencing the MeshService as backendRef * Add example ServiceResolver * Add note about current ServiceResolver requirement ServiceResolver may eventually be created implicitly by the API gateway controller, but that decision is pending. * tweaks to the usage page for routing to peered services * tweaks to the description in the configuration reference * resolved TO-DOs from previous iteration * Remove datacenter federation from limited support matrix * added tolerations doc * Remove note excluding k8s 1.24 since we now support it * Reorder sections to maintain alphabetical sort * Add example configuration for MeshService resource * Adjust wording + indentation of other docs * Use consistent "example-" prefix for resource names in example code * reframed the tolerations documentation; STILL A WIP * add helm chart documentation * removed tolerations from gwcconfig configuration model reference * Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> * update version to 0.5.0 * Update install.mdx * added release notes for v.0.5.x Co-authored-by: Nathan Coleman <nathan.coleman@hashicorp.com> Co-authored-by: Sarah Alsmiller <sarah.alsmiller@hashicorp.com> Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Co-authored-by: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com> manual cherry-pick because backport to stable website failed
- Loading branch information
1 parent
9f7ed93
commit 02d192e
Showing
12 changed files
with
350 additions
and
136 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,60 @@ | ||
| --- | ||
| layout: docs | ||
| 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. | ||
| --- | ||
|
|
||
| # 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/) | ||
|
|
||
| <!--- | ||
| *************************************************************************** | ||
| Use markdown's Reference-Style links when including hyperlinks. This makes it easier to read the content im markdown. | ||
|
|
||
| Each common error should have its own section on this page. Each section | ||
| should start with a heading line that is a short description of the error or | ||
| the text of the error. | ||
|
|
||
| Two examples: | ||
| ### Failed opening file during installation | ||
| ### Message: "Can't connect to repository" when running Helm chart | ||
|
|
||
| ******** Template for new Error Messages ******** | ||
| Copy and paste the following 13 lines when adding a new error message to this page. | ||
|
|
||
| ### Title for this error | ||
|
|
||
| ``` | ||
| Replace with text of example error message | ||
| ``` | ||
| **Conditions:** | ||
| REPLACE THIS with description of when and why the error is typically seen | ||
|
|
||
| **Impact:** | ||
| REPLACE THIS with description of most likely impact of the event that caused this error to occur | ||
|
|
||
| **Resolution:** | ||
| REPLACE THIS with the actions the user should take to try to correct the situation | ||
|
|
||
| *************************************************************************** | ||
| ---> | ||
|
|
||
| ## 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. |
58 changes: 58 additions & 0 deletions
58
website/content/docs/api-gateway/usage/reroute-http-requests.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
|
|
||
| Specify the following fields in your `Route` configuration. 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. | ||
|
|
||
| To configure the route to accept paths with or 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/`. As a result, requests to `/incoming-request-prefix/request-path` are received by `backendRef` as `/prefix-backend-receives/request-path`. | ||
|
|
||
| <CodeBlockConfig filename="route.yaml"> | ||
|
|
||
| ```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/ | ||
| ``` | ||
| </CodeBlockConfig> |
76 changes: 76 additions & 0 deletions
76
website/content/docs/api-gateway/usage/route-to-peered-services.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,76 @@ | ||
| --- | ||
| 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 cluster peering connection. | ||
|
|
||
| ## 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. | ||
| 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 | ||
|
|
||
| Specify 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`. | ||
|
|
||
| <CodeBlockConfig filename="serviceresolver.yaml"> | ||
|
|
||
| ```yaml hideClipboard | ||
| apiVersion: consul.hashicorp.com/v1alpha1 | ||
| kind: ServiceResolver | ||
| metadata: | ||
| name: echo | ||
| spec: | ||
| redirect: | ||
| peer: cluster-02 | ||
| service: echo | ||
| ``` | ||
| </CodeBlockConfig> | ||
| <CodeBlockConfig filename="meshservice.yaml"> | ||
| ```yaml hideClipboard | ||
| apiVersion: api-gateway.consul.hashicorp.com/v1alpha1 | ||
| kind: MeshService | ||
| metadata: | ||
| name: example-mesh-service | ||
| spec: | ||
| name: echo | ||
| peer: cluster-02 | ||
| ``` | ||
| </CodeBlockConfig> | ||
| After applying the `meshservice.yaml` configuration, an `HTTPRoute` may then reference `example-mesh-service` as its `backendRef`. | ||
|
|
||
| <CodeBlockConfig filename="route.yaml"> | ||
|
|
||
| ```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 | ||
| ... | ||
| ``` | ||
| </CodeBlockConfig> |
Oops, something went wrong.