github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Backport of Update docs for the release of Consul API Gateway v0.5 into release/1.14.x (#15451) 

* backport of commit 68ee017adf

* backport of commit f23b3662d8

* backport of commit deaba3ef15

* backport of commit d1f1ff50f8

* backport of commit e41ec340d8

* backport of commit 72a3bf2296

* backport of commit 41dfa89653

* backport of commit 9d4c77a51f

* backport of commit 0d8bad1d02

Co-authored-by: trujillo-adam <ajosetru@gmail.com>
Co-authored-by: Nathan Coleman <nathan.coleman@hashicorp.com>
Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
pull/15457/head
hc-github-team-consul-core 2022-11-18 10:38:37 -05:00 committed by GitHub
parent 84838e57f0
commit d9bbc819ce
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 235 additions and 101 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
website/content/docs/api-gateway/configuration/meshservice.mdx
View File

@ -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

60
website/content/docs/api-gateway/usage/errors.mdx Normal file
View File

@ -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/)
<!---
***************************************************************************
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
website/content/docs/api-gateway/usage/reroute-http-requests.mdx Normal file
View File

@ -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`.
<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>

77
website/content/docs/api-gateway/usage/route-to-peered-services.mdx Normal file
View File

@ -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`.
<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 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>

108
website/content/docs/api-gateway/usage.mdx → website/content/docs/api-gateway/usage/usage.mdx
View File

@ -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.
<CodeBlockConfig hideClipboard filename="values.yaml">
@ -27,55 +30,14 @@ Complete the following steps to use Consul API Gateway in your network.
</CodeBlockConfig>
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`.
<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>
<!--- Commented out per https://github.com/hashicorp/consul/pull/11951/files#r791204596
@ -126,57 +88,5 @@ consul-api-gateway 0.1.0
```
--->
## 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
**Recommended Action:**
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.
**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.

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

@ -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",