184 lines
9.8 KiB
Plaintext
184 lines
9.8 KiB
Plaintext
---
|
||
layout: docs
|
||
page_title: Consul API Gateway Basic Usage
|
||
description: >-
|
||
This topic describes how to use Consul API Gateway.
|
||
---
|
||
|
||
|
||
# Usage
|
||
|
||
This topic describes how to use Consul API Gateway.
|
||
|
||
## Basic usage
|
||
|
||
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 (see [Installation](/docs/api-gateway/consul-api-gateway-install)).
|
||
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.
|
||
|
||
<CodeBlockConfig hideClipboard filename="values.yaml">
|
||
|
||
```yaml
|
||
apiGateway:
|
||
enabled: true
|
||
managedGatewayClass:
|
||
```
|
||
|
||
</CodeBlockConfig>
|
||
|
||
1. Issue the `kubectl apply` command to implement the configurations, e.g.:
|
||
|
||
```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
|
||
|
||
### Using the Consul API Gateway Binary
|
||
|
||
You can download the Consul API Gateway binary and use it to manually start the control plane server.
|
||
|
||
1. Download the binary from the [Consul API Gateway repository](https://github.com/hashicorp/consul-api-gateway).
|
||
1. Navigate to the `consul-api-gateway-main` directory and build the binary:
|
||
|
||
```shell-session
|
||
$ go build
|
||
```
|
||
|
||
1. (Optional) Copy the binary to the execution path, e.g.:
|
||
|
||
```shell-session
|
||
$ cp consul-api-gateway /usr/bin
|
||
```
|
||
|
||
1. Use the `server` command to interact with the Consul API Gateway binary:
|
||
|
||
```shell-session
|
||
$ ./consul-api-gateway server <options>
|
||
```
|
||
|
||
The following options are supported:
|
||
|
||
| Option | Description | Required | Default |
|
||
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------- |
|
||
| `-ca-file` | String value that specifies the path to the CA for the Consul server. | Required | none |
|
||
| `-ca-secret` | String value that specifies the CA secret for the Consul server. | Required | none |
|
||
| `-ca-secret-namespace` | String value that specifies the CA secret namespace for the Consul server. | Required | none |
|
||
| `-k8-context` | String value that specifies the Kubernetes context to use when starting the Consul server. | Optional | current context |
|
||
| `-k8-namespace` | String value that specifies the Kubernetes namespace to use when starting the Consul server. | Optional | `default` |
|
||
| `-log-json` | Boolean value that enables or disables JSON format for the log output. | Required | `false` |
|
||
| `-log-level` | String value that specifies the logging level. The following values are supported: <br/>- `trace` (highest level of detail) <br/>- `debug` <br/>- `info` <br/>- `warn` <br/>- `error` | Optional | `info` |
|
||
| `-metrics-port` | Integer value that specifies the port number for collecting metrics. | Optional | none |
|
||
| `-pprof` | Integer value that specifies the Go pprof port number for collecting metrics. | Optional | none |
|
||
| `-sds-server-host` | String value that specifies the host server for the secret discovery service (SDS). | Optional | `consul-api-gateway-controller.default.`<br/>`svc.cluster.`<br/>`local` |
|
||
| `-sds-server-host` | Integer value that specifies the port number for the secret discovery service (SDS). | Optional | `9090` |
|
||
|
||
You can also issue the `version` command to print the Consul API Gateway version to the console:
|
||
|
||
```shell-session
|
||
$ ./consul-api-gateway version
|
||
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.
|
||
|