status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Docs/api-gw-jwts-openshift-1-17-x (#19035) 

* update main apigw overview

* moved the tech specs to main gw folder

* merged tech specs into single topic

* restructure nav part 1

* fix typo in nav json file

* moved k8s install up one level

* restructure nav part 2

* moved and created all listeners and routes content

* moved errors ref and upgrades

* fix error in upgrade-k8s link

* moved conf refs to appropriate spots

* updated conf overview

* fixed some links and bad formatting

* fixed link

* added JWT on VMs usage page

* added JWT conf to APIGW conf entry

* added JWTs to HTTP route conf entry

* added new gatwaypolicy k8s conf reference

* added metadesc for gatewaypolicy conf ref

* added http route auth filter k8s conf ref

* added http route auth filter k8s conf ref to nav

* updates to k8s route conf ref to include extensionRef

* added JWTs usage page for k8s

* fixed link in gwpolicy conf ref

* added openshift installation info to installation pages

* fixed bad link on tech specs

* Apply suggestions from code review

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
Co-authored-by: Nathan Coleman <nathan.coleman@hashicorp.com>

* fixed VerityClaims param

* best guess at verifyclaims params

* tweaks to gateway policy dconf ref

* Docs/ce 475 retries timeouts for apigw (#19086)

* added timeout and retry conf ref for k8s

* added retry and TO filters to HTTP routes conf ref for VMs

* Apply suggestions from code review

Co-authored-by: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com>

* fix copy/paste error in http route conf entry

---------

Co-authored-by: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com>

* update links across site and add redirects

* 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>
Co-authored-by: Thomas Eckert <teckert@hashicorp.com>

* Applied feedback from review

* Apply suggestions from code review

* Apply suggestions from code review

Co-authored-by: Nathan Coleman <nathan.coleman@hashicorp.com>

* Update CRD configuration for responseHeaderModifiers

* Update Config Entry for http-route

* Add ResponseFilter example to service

* Update website/redirects.js

errant curly brace breaking the preview

* fix links and bad MD

* fixed md formatting issues

* fix formatting errors

* fix formatting errors

* Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx

* Apply suggestions from code review

* fixed typo

* Fix headers in http-route

* Apply suggestions from code review

Co-authored-by: John Maguire <john.maguire@hashicorp.com>
Co-authored-by: Nathan Coleman <nathan.coleman@hashicorp.com>

---------

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
Co-authored-by: Nathan Coleman <nathan.coleman@hashicorp.com>
Co-authored-by: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com>
Co-authored-by: Thomas Eckert <teckert@hashicorp.com>
Co-authored-by: John Maguire <john.maguire@hashicorp.com>
This commit is contained in:
trujillo-adam 2023-10-10 13:29:55 -07:00 committed by GitHub
parent 8bebfc147d
commit 78938c163a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
45 changed files with 3369 additions and 1465 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
website/content/docs/api-gateway/configuration/index.mdx
View File

@ -1,24 +0,0 @@
---
layout: docs
page_title: Consul API Gateway Configuration - Overview
description: >-
Configure your Consul API Gateway to manage traffic into your service mesh. Learn about the Kubernetes Gateway Specification items you can configure and how to configure custom API Gateways.
---
# Consul API Gateway Configuration Overview
This topic provides an overview of the configuration items that enable Consul API Gateway to manage traffic into your Consul service mesh.
- [Gateway](/consul/docs/api-gateway/configuration/gateway) defines the main infrastructure resource that links API gateway components. It specifies the name of the `GatewayClass` and one or more [listeners](/consul/docs/api-gateway/configuration/gateway#listeners), which specify the logical endpoints bound to the gateway's addresses.
- [GatewayClass](/consul/docs/api-gateway/configuration/gatewayclass) defines a class of gateway resources that you can use as a template for creating gateways.
- [GatewayClassConfig](/consul/docs/api-gateway/configuration/gatewayclassconfig) describes additional Consul API Gateway-related configuration parameters for the GatewayClass resource.
- [Routes](/consul/docs/api-gateway/configuration/routes) specifies the path from the gateway to the backend service(s) client to the listener.
- [Intentions](/consul/docs/connect/config-entries/service-intentions) specify traffic communication rules between services in the mesh. Intentions also enforce rules for service-to-service traffic routed through a Consul API gateway.
You can create a basic Gateway object using the default [`gatewayClassName`](/consul/docs/api-gateway/configuration/gateway#gatewayclassname) (`consul`). If you want to create custom Gateways suitable for your environment, complete the following steps:
1. Define a [GatewayClassConfig](/consul/docs/api-gateway/configuration/gatewayclassconfig) that contains your custom configurations.
1. Define a [GatewayClass](/consul/docs/api-gateway/configuration/gatewayclass) and configure the [`parametersRef.name`](/consul/docs/api-gateway/configuration/gatewayclass#parametersref-name) to reference the name of your [GatewayClassConfig](/consul/docs/api-gateway/configuration/gatewayclassconfig).
1. Define a [Gateway](/consul/docs/api-gateway/configuration/gateway) and configure the [`gatewayClassName`](/consul/docs/api-gateway/configuration/gateway#gatewayclassname) to reference the name of your [GatewayClass](/consul/docs/api-gateway/configuration/gatewayclass).
<!--TODO add diagram -->

45
website/content/docs/api-gateway/index.mdx
View File

@ -1,45 +0,0 @@
---
layout: docs
page_title: API Gateway for Kubernetes Overview
description: >-
Consul API Gateway enables external network client access to a service mesh on Kubernetes and forwards requests based on path or header information. Learn about how the k8s Gateway API specification configures Consul API Gateway so you can control access and simplify traffic management.
---
# API Gateway for Kubernetes overview
This topic provides an overview of the Consul API Gateway for deploying on Kubernetes. If you would like to deploy on virtual machines, refer to [API Gateways on Virtual Machines](/consul/docs/connect/gateways/api-gateway/usage).
## What is Consul API Gateway?
Consul API Gateway is an add-on for Consul that helps users control access to services running within a Consul service mesh. The API gateway enables external network clients to access applications and services running in a Consul datacenter. This type of network traffic is commonly referred to as "north-south" network traffic as it refers to the flow of data into and out of a specific environment. Requests from clients can also be forwarded based on path or request protocol.
Consul API Gateway solves the following primary use cases:
- **Controlling access at the point of entry**: Consul API Gateway allows users to set the protocols of external connection requests and provide clients with TLS certificates from trusted providers (e.g., Verisign, Let's Encrypt).
- **Simplifying traffic management**: The Consul API Gateway can load balance requests across services and route traffic to the appropriate service by matching one or more criteria, such as hostname, path, header presence or value, and HTTP Method type (e.g., GET, POST, PATCH).
## How Does Consul API Gateway Work?
Consul API Gateway can be deployed on Kubernetes-based runtime environments and requires that Consul service mesh be deployed on the Kubernetes cluster.
API Gateway routes traffic to services connected to the same service mesh. Those services can be running on the same Kubernetes cluster as the API Gateway, a different Kubernetes cluster, or another runtime, as long as they are connected to the same service mesh deployment and reachable over the network.
Consul API Gateway implements and is configured through the Kubernetes [Gateway API Specification](https://gateway-api.sigs.k8s.io/). This specification defines a set of custom resource definitions (CRD) that can create logical gateways which route traffic based on a client request's path or protocol.
### Supported Kubernetes Gateway Specification Features
The Consul API Gateway supports a subset of the Kubernetes [v1alpha2 Gateway API specification](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/). The following table
describes the supported features of the specification. For a complete list of features, including the list of gateway and route statuses and an explanation on how they
are used, see the [documentation in our GitHub repo](https://github.com/hashicorp/consul-api-gateway/blob/main/dev/docs/supported-features.md).
| Kubernetes Object | Description |
| ----- | ----------------------------- |
| [`GatewayClass`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayClass) | <ul><li>Parameter specification via `GatewayClassConfig` CRD</li><li>Controller matching on `"hashicorp.com/consul-api-gateway-controller"`</li></ul> |
| [`Gateway`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Gateway) | <ul><li>Supported protocols: `HTTP`, `HTTPS`, `TCP`</li><li>Header-based hostname matching (no SNI support)</li><li>Supported filters: header addition, removal, and setting</li><li>TLS modes supported: `terminate`</li><li>Certificate types supported: `core/v1/Secret`</li><li>Extended options: TLS version and cipher constraints</li></ul> |
| [`HTTPRoute`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRoute) | <ul><li>Weight-based load balancing</li><li>Supported rules: path, header, query, and method-based matching</li><li>Supported filters: header addition, removal, and setting</li><li>Supported backend types: <ol><li>`core/v1/Service` (must map to a registered Consul service)</li><li>`api-gateway.consul.hashicorp.com/v1alpha1/MeshService`</li></ol></li></ul> |
| [`TCPRoute`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.TCPRoute) | <ul><li>Supported backend types: <ol><li>`core/v1/Service` (must map to a registered Consul service)</li><li>`api-gateway.consul.hashicorp.com/v1alpha1/MeshService`</li></ol></li></ul> |
| [`ReferenceGrant`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferenceGrant) | <ul><li>Required to allow any reference from a `Gateway` to a Kubernetes `core/v1/Secret` in a different namespace.</li><ul><li>A Gateway with an unpermitted `certificateRefs` caused by the lack of a` ReferenceGrant` sets a `ResolvedRefs` status to `False` with the reason `InvalidCertificateRef`. The Gateway will not become ready in this case.</li></ul><li>Required to allow any reference from an `HTTPRoute` or `TCPRoute` to a Kubernetes `core/v1/Service` in a different namespace.</li><ul><li>A route with an unpermitted `backendRefs` caused by the lack of a `ReferenceGrant` sets a `ResolvedRefs` status to `False` with the reason `RefNotPermitted`. The gateway listener rejects routes with an unpermitted `backendRefs`.</li><li>WARNING: If a route `backendRefs` becomes unpermitted, the entire route is removed from the gateway listener. <ul><li>A `backendRefs` can become unpermitted when you delete a `ReferenceGrant` or add a new unpermitted `backendRefs` to an existing route.</li></ul></li></ul></ul> |
## Additional Resources
You can learn more about using Consul API Gateway by completing the [Consul API Gateway tutorial](/consul/tutorials/kubernetes/kubernetes-api-gateway).

71
website/content/docs/api-gateway/tech-specs.mdx
View File

@ -1,71 +0,0 @@
---
layout: docs
page_title: API gateway for Kubernetes technical specifications
description: >-
Learn about the requirements for installing and using the Consul API gateway for Kubernetes, including required ports, component version minimums, Consul Enterprise limitations, and compatible k8s cloud environments.
---
# API gateway for Kubernetes technical specifications
This topic describes the technical specifications associated with using Consul API gateway.
## Requirements
Verify that your environment meets the following requirements prior to using Consul API gateway.
### Datacenter requirements
Your datacenter must meet the following requirements prior to configuring the Consul API gateway:
- HashiCorp Consul Helm chart v1.2.0 and later
### TCP port requirements
The following table describes the TCP port requirements for each component of the API gateway.
| Port | Description | Component |
| ---- | ----------- | --------- |
| 20000 | Kubernetes readiness probe | Gateway instance pod |
| Configurable | Port for scraping Prometheus metrics. Disabled by default. | Gateway controller pod |
## Consul server deployments
- Consul Editions supported: CE and Enterprise
- Supported Consul Server deployment types:
- Self-Managed
- HCP Consul
### Limited Support of some Consul Features
The following table lists API gateway limitations related to specific Consul features
| Consul Feature | Limitation |
| -------------- | ---------- |
| 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
Consul API gateway can be deployed in the following Kubernetes-based environments:
- Generic Kubernetes
- AWS Elastic Kubernetes Service (EKS)
- Google Kubernetes Engine (GKE)
- Azure Kubernetes Service (AKS)
## Supported versions of Kubernetes Gateway API specification
Refer to the [release notes](/consul/docs/release-notes) for your version of Consul.
## Resource allocations
The following resources are allocated for each component of the API gateway.
### Gateway controller pod
- **CPU**: None. Either the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration.
- **Memory**: None. Either the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration.
### Gateway instance pod
- **CPU**: None. Either the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration.
- **Memory**: None. Either the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration.

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

@ -1,87 +0,0 @@
---
layout: docs
page_title: Deploy API Gateway for Kubernetes
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.
---
# Deploy API Gateway for Kubernetes
This topic describes how to use Consul API Gateway.
## Requirements
Complete the following steps to use Consul API Gateway in your network.
1. Verify that the [requirements](/consul/docs/api-gateway/tech-specs) have been met.
1. Verify that the Consul API Gateway CRDs were applied. Refer to [Installation](/consul/docs/api-gateway/install) for details.
## Configuration
Configure the following resources for your environment as described in [Consul API Gateway Configuration](/consul/docs/api-gateway/configuration).
1. [`Gateway`](/consul/docs/api-gateway/configuration/gateway)
1. [`Routes`](/consul/docs/api-gateway/configuration/routes)
1. [`Intentions`](/consul/docs/connect/config-entries/service-intentions)
## Apply configurations
Issue the `kubectl apply` command to implement the configurations:
```shell-session
$ kubectl apply -f gateway.yaml routes.yaml intentions.yaml
```
<!--- 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
```
--->

235
website/content/docs/connect/gateways/api-gateway/configuration/api-gateway.mdx → website/content/docs/connect/config-entries/api-gateway.mdx
View File

@ -1,12 +1,12 @@
---
layout: docs
page_title: API Gateway Configuration Entry Reference
description: Learn how to configure a Consul API Gateway on VMs.
description: Learn how to configure a Consul API gateway on VMs.
---
# API gateway configuration entry reference
This topic provides reference information for the API gateway configuration entry that you can deploy to networks in virtual machine (VM) environments. For reference information about configuring Consul API gateways on Kubernetes, refer to [Gateway Resource Configuration](/consul/docs/api-gateway/configuration/gateway).
This topic provides reference information for the API gateway configuration entry that you can deploy to networks in virtual machine (VM) environments. For reference information about configuring Consul API gateways on Kubernetes, refer to [Gateway Resource Configuration](/consul/docs/connect/gateways/api-gateway/configuration/gateway).
## Introduction
@ -35,6 +35,22 @@ The following list outlines field hierarchy, language-specific data types, and r
- [`Name`](#listeners-tls-certificates-name): string | no default
- [`Namespace`](#listeners-tls-certificates-namespace): string | no default <EnterpriseAlert inline />
- [`Partition`](#listeners-tls-certificates-partition): string | no default <EnterpriseAlert inline />
- [`default`](#listeners-default): map
- [`JWT`](#listeners-default-jwt): map
- [`Providers`](#listeners-default-jwt-providers): list
- [`Name`](#listeners-default-jwt-providers): string
- [`VerifyClaims`](#listeners-default-jwt-providers): map
- [`Path`](#listeners-default-jwt-providers): list
- [`Value`](#listeners-default-jwt-providers): string
- [`override`](#listeners-override): map
- [`JWT`](#listeners-override-jwt): map
- [`Providers`](#listeners-override-jwt-providers): list
- [`Name`](#listeners-override-jwt-providers): string
- [`VerifyClaims`](#listeners-override-jwt-providers): map
- [`Path`](#listeners-override-jwt-providers): list
- [`Value`](#listeners-override-jwt-providers): string
## Complete configuration
@ -72,6 +88,28 @@ Listeners = [
}
]
}
default = {
JWT = {
Providers = [
Name = "<provider>"
VerifyClaims = {
Path = ["<path to claim>"]
Value = "<value of claim>"
}
]
}
}
override = {
JWT = {
Providers = [
Name = "<provider>"
VerifyClaims = {
Path = ["<path to claim>"]
Value = "<value of claim>"
}
]
}
}
}
]
```
@ -105,6 +143,36 @@ Listeners = [
}
]
}
},
{
"default": {
"JWT": {
"Providers": [
{
"Name": "<name of provider>",
"VerifyClaims": {
"Path": ["<path to claim>"],
"Value": "<value of the claim>"
}
}
]
}
}
},
{
"override": {
"JWT": {
"Providers": [
{
"Name": "<name of provider>",
"VerifyClaims": {
"Path": ["<path to claim>"],
"Value": "<value of the claim>"
}
}
]
}
}
}
]
}
@ -329,3 +397,166 @@ Specifies the Enterprise [admin partition](/consul/docs/enterprise/admin-partiti
- Default: `"default"` in Enterprise
- Data type: string
### `Listeners[].default`
Specifies a block of default configurations to apply to the gateway listener. All routes attached to the listener inherit the default configurations. You can specify override configurations that have precedence over default configurations in the [`override` block](#listeners-override) as well as in the `JWT` block in the [HTTP route configuration entry](/consul/docs/connect/config-entries/http-route).
#### Values
- Default: None
- Data type: Map
### `Listeners[].default{}.JWT`
Specifies a block of default JWT verification configurations to apply to the gateway listener. Specify configurations that have precedence over the defaults in either the [`override.JWT` block](#listeners-override) or in the [`JWT` block](/consul/docs/connect/config-entries/http-route#rules-filters-jwt) in the HTTP route configuration. Refer to [Use JWTs to verify requests to API gateways](/consul/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-vms) for order of precedence and other details about using JWT verification in API gateways.
#### Values
- Default: None
- Data type: Map
### `Listeners[].default{}.JWT{}.Providers`
Specifies a list of default JWT provider configurations to apply to the gateway listener. A provider configuration contains the name of the provider and claims. Specify configurations that have precedence over the defaults in either the [`override.JWT.Providers` block](#listeners-override-providers) or in the [`JWT` block](/consul/docs/connect/config-entries/http-route#rules-filters-jwt-providers) of the HTTP route configuration. Refer to [Use JWTs to verify requests to API gateways](/consul/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-vms) for order of precedence and other details about using JWT verification in API gateways.
#### Values
- Default: None
- Data type: List of maps
The following table describes the parameters you can specify in a member of the `Providers` list:
| Parameter | Description | Data type | Default |
| --- | --- | --- | --- |
| `Name` | Specifies the name of the provider. | String | None |
| `VerifyClaims` | Specifies a list of paths and a value that define the claim that Consul verifies when it receives a request. The `VerifyClaims` map specifies the following settings: <ul><li>`Path`: Specifies a list of one or more registered or custom claims.</li><li>`Value`: Specifies the expected value of the claim.</li></ul> | Map | None |
Refer to [Configure JWT verification settings](#configure-jwt-verification-settings) for an example configuration.
### `Listeners[].override`
Specifies a block of configurations to apply to the gateway listener. The override settings have precedence over the configurations in the [`Listeners[].default` block](#listeners-default).
#### Values
- Default: None
- Data type: Map
### `Listeners[].override{}.JWT`
Specifies a block of JWT verification configurations to apply to the gateway listener. The override settings have precedence over the [`Listeners[].default` configurations](#listeners-default) as well as any route-specific JWT configurations.
#### Values
- Default: None
- Data type: Map
### `Listeners[].override{}.JWT{}.Providers`
Specifies a list of JWT provider configurations to apply to the gateway listener. A provider configuration contains the name of the provider and claims. The override settings have precedence over `Listeners[].defaults{}.JWT{}.Providers` as well as any listener-specific configuration.
#### Values
- Default: None
- Data type: List of maps
The following table describes the parameters you can specify in a member of the `Providers` list:
| Parameter | Description | Data type | Default |
| --- | --- | --- | --- |
| `Name` | Specifies the name of the provider. | String | None |
| `VerifyClaims` | Specifies a list of paths and a value that define the claim that Consul verifies when it receives a request. The `VerifyClaims` map specifies the following settings: <ul><li>`Path`: Specifies a list of one or more registered or custom claims.</li><li>`Value`: Specifies the expected value of the claim.</li></ul> | Map | None |
Refer to [Configure JWT verification settings](#configure-jwt-verification-settings) for an example configuration.
## Examples
The following examples demonstrate common API gateway configuration patterns for specific use cases.
### Configure JWT verification settings
The following example configures `listener-one` to verify that requests include a token with Okta user permissions by default. The listener also verifies that the token has an audience of `api.apps.organization.com`.
<Tabs>
<Tab heading="HCL" group="hcl">
```hcl
Kind = "api-gateway"
Name = "api-gateway"
Listeners = [
{
name = "listener-one"
port = 9001
protocol = "http"
# override and default are backed by the same type of data structure, see the following section for more on how they interact
override = {
JWT = {
Providers = [
{
Name = "okta",
VerifyClaims = {
Path = ["aud"],
Value = "api.apps.organization.com",
}
},
]
}
}
default = {
JWT = {
Providers = [
{
Name = "okta",
VerifyClaims = {
Path = ["perms", "role"],
Value = "user",
}
}
]
}
}
}
]
```
</Tab>
<Tab heading="JSON" group="json">
```json
{
"Kind": "api-gateway",
"Name": "api-gateway",
"Listeners": [
{
"name": "listener-one",
"port": 9001,
"protocol": "http",
"override": {
"JWT": {
"Providers": [{
"Name": "okta",
"VerifyClaims": {
"Path": ["aud"],
"Value": "api.apps.organization.com"
}
}]
}
},
"default": {
"JWT": {
"Providers": [{
"Name": "okta",
"VerifyClaims": {
"Path": ["perms", "role"],
"Value": "user"
}
}]
}
}
}
]
}
```
</Tab>
</Tabs>

1128
website/content/docs/connect/config-entries/http-route.mdx Normal file
View File

File diff suppressed because it is too large Load Diff

2
website/content/docs/connect/gateways/api-gateway/configuration/inline-certificate.mdx → website/content/docs/connect/config-entries/inline-certificate.mdx
View File

@ -7,7 +7,7 @@ description: Learn how to configure an inline certificate bound to an API Gatewa
# Inline certificate configuration reference
This topic provides reference information for the gateway inline certificate
configuration entry. For information about certificate configuration for Kubernetes environments, refer to [Gateway Resource Configuration](/consul/docs/api-gateway/configuration/gateway).
configuration entry. For information about certificate configuration for Kubernetes environments, refer to [Gateway Resource Configuration](/consul/docs/connect/gateways/api-gateway/configuration/gateway).
## Configuration model

2
website/content/docs/connect/gateways/api-gateway/configuration/tcp-route.mdx → website/content/docs/connect/config-entries/tcp-route.mdx
View File

@ -7,7 +7,7 @@ description: Learn how to configure a TCP Route that is bound to an API gateway
# TCP route configuration Reference
This topic provides reference information for the gateway TCP routes configuration
entry. Refer to [Route Resource Configuration](/consul/docs/api-gateway/configuration/routes) for information
entry. Refer to [Route Resource Configuration](/consul/docs/connect/gateways/api-gateway/configuration/routes) for information
about configuring API gateways in Kubernetes environments.
## Configuration model

4
website/content/docs/api-gateway/configuration/gateway.mdx → website/content/docs/connect/gateways/api-gateway/configuration/gateway.mdx
View File

@ -13,7 +13,7 @@ This topic provides full details about the `Gateway` resource.
A `Gateway` is an instance of network infrastructure that determines how service traffic should be handled. A `Gateway` contains one or more [`listeners`](#listeners) that bind to a set of IP addresses. An `HTTPRoute` or `TCPRoute` can then attach to a gateway listener to direct traffic from the gateway to a service.
Gateway instances derive their configurations from the [`GatewayClass`](/consul/docs/api-gateway/configuration/gatewayclass) resource, which acts as a template for individual `Gateway` deployments. Refer to [GatewayClass](/consul/docs/api-gateway/configuration/gatewayclass) for additional information.
Gateway instances derive their configurations from the [`GatewayClass`](/consul/docs/connect/gateways/api-gateway/configuration/gatewayclass) resource, which acts as a template for individual `Gateway` deployments. Refer to [GatewayClass](/consul/docs/connect/gateways/api-gateway/configuration/gatewayclass) for additional information.
Specify the following parameters to declare a `Gateway`:
@ -57,7 +57,7 @@ The following outline shows how to format the configurations in the `Gateway` ob
This topic provides details about the configuration parameters.
### gatewayClassName
Specifies the name of the [`GatewayClass`](/consul/docs/api-gateway/configuration/gatewayclass) resource used for the `Gateway` instance. Unless you are using a custom [GatewayClass](/consul/docs/api-gateway/configuration/gatewayclass), this value should be set to `consul`.
Specifies the name of the [`GatewayClass`](/consul/docs/connect/gateways/api-gateway/configuration/gatewayclass) resource used for the `Gateway` instance. Unless you are using a custom [GatewayClass](/consul/docs/connect/gateways/api-gateway/configuration/gatewayclass), this value should be set to `consul`.
* Type: string
* Required: required

2
website/content/docs/api-gateway/configuration/gatewayclass.mdx → website/content/docs/connect/gateways/api-gateway/configuration/gatewayclass.mdx
View File

@ -15,7 +15,7 @@ The `GatewayClass` specification includes the name of the controller (`controlle
When gateways are created from a `GatewayClass`, they use the parameters specified in the `GatewayClass` at the time of instantiation.
The `GatewayClass` resource is a generic Kubernetes gateway object. For configuration specific to Consul API Gateway, see [GatewayClassConfig](/consul/docs/api-gateway/configuration/gatewayclassconfig).
The `GatewayClass` resource is a generic Kubernetes gateway object. For configuration specific to Consul API Gateway, refer to [GatewayClassConfig](/consul/docs/connect/gateways/api-gateway/configuration/gatewayclassconfig).
## Configuration model
The following outline shows how to format the configurations in the `GatewayClass` object. Click on a property name to view details about the configuration.

0
website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx → website/content/docs/connect/gateways/api-gateway/configuration/gatewayclassconfig.mdx
View File

259
website/content/docs/connect/gateways/api-gateway/configuration/gatewaypolicy.mdx Normal file
View File

@ -0,0 +1,259 @@
---
layout: docs
page_title: GatewayPolicy configuration reference
description: Learn about the configuration options for the GatewayPolicy configuration resource. GatewayPolicy resources define API gateway polcies for Consul service mesh on Kubernetes.
---
# GatewayPolicy
This topic provides reference information for the API gateway policy resource. These resources define policies for listeners on API gateways deployed to Kubernetes-orchestrated networks.
## Configuration model
The following list outlines field hierarchy, data types, and requirements in a gateway policy resource. Click on a property name to view additional details, including default values.
- [`apiVersion`](#apiversion): string | required | must be set to `consul.hashicorp.com/v1alpha1`
- [`kind`](#kind): string | required | must be set to `GatewayPolicy`
- [`metadata`](#metadata): map | required
- [`name`](#metadata-name): string | required
- [`namespace`](#metadata-namespace): string | `default`
- [`spec`](#spec): map | required
- [`targetRef`](#spec-targetref): map | required
- [`namespace`](#spec-targetref): string | `default`
- [`name`](#spec-targetref): string | required
- [`kind`](#spec-targetref): string | required | must be set to `Gateway`
- [`group`](#spec-targetref): string | required
- [`sectionName`](#spec-targetref): string
- [`override`](#spec-override): map | required
- [`jwt`](#spec-override-jwt): map | required
- [`providers`](#spec-override-providers): list | required
- [`name`](#spec-override-providers): string | required
- [`verifyClaims`](#spec-override-providers): map | required
- [`path`](#spec-override-providers): list of strings | required
- [`value`](#spec-override-providers): string | required
- [`default`](#spec-default): map | required
- [`jwt`](#spec-default-jwt): map | required
- [`providers`](#spec-default-providers): list | required
- [`name`](#spec-default-providers): string | required
- [`verifyClaims`](#spec-default-providers): map | required
- [`path`](#spec-default-providers): list of strings | required
- [`value`](#spec-default-providers): string | required
## Complete configuration
When every field is defined, a gateway policy has the following form:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: GatewayPolicy
metadata:
name: <name for the policy>
namespace: <Consul namespace the policy applies to>
spec:
targetRef:
name: gateway
kind: Gateway
group: gateway.networking.kuberenetes.io
sectionName: <name of a specific listener the policy applies>
override:
jwt:
providers:
- name: "<name of the provider all listeners verify against>"
verifyClaims:
- path:
- "aud"
value: "api.apps.organization.com"
default:
jwt:
providers:
- name: "<name of the JWT provider to verify against>"
verifyClaims:
- path:
- "roles"
- "perm"
value: "user"
```
## Specification
This section provides details about the fields you can configure in the gateway policy resource.
### `apiVersion`
Specifies the version of the Consul API for integrating with Kubernetes. The value must be `consul.hashicorp.com/v1alpha1`.
#### Values
- Default: None
- This field is required.
- String value that must be set to `consul.hashicorp.com/v1alpha1`.
### `kind`
Specifies the type of configuration entry to implement. Must be set to `GatewayPolicy`.
#### Values
- Default: None
- This field is required.
- Data type: String value that must be set to `GatewayPolicy`.
### `metadata`
Map that contains an arbitrary name for the resource and the namespace it applies to.
#### Values
- Default: None
- Data type: Map
### `metadata.name`
Specifies a name for the resource. The name is metadata that you can use to reference the resource when performing Consul operations, such as applying the resource to a specific cluster.
#### Values
- Default: None
- This field is required.
- Data type: String
### `metadata.namespace`
Specifies the namespace that the configuration applies to. Refer to [namespaces](/consul/docs/enterprise/namespaces) for more information.
#### Values
- Default: None
- Data type: String
### `spec`
Map that contains the details about the gateway policy. The `apiVersion`, `kind`, and `metadata` fields are siblings of the `spec` field. All other configurations are children.
#### Values
- Default: None
- This field is required.
- Data type: Map
### `targetRef`
Map that contains references to the gateway that the policy applies to.
#### Values
- Default: None
- This field is required.
- Data type: Map
The following table describes the members of the `targetRef` map:
| Parameter | Description | Data type | Default |
| --- | --- | --- | --- |
| `namespace` | Specifies the namespace that the target reference is a member of. | String | `default` |
| `name` | Specifies the name of the API gateway that the policy attaches to. | String | None |
| `kind` | Specifies the type of resource that the policy attaches to. Must be set to `Gateway`. | String | None |
| `group` | Specifies the resource group. Must be set to `gateway.networking.kuberenetes.io`. | String | None |
| `sectionName` | Specifies a part of the gateway that the policy applies to. | String | None |
### `spec.override`
Map that contains configurations to apply to the listener when the policy is attached to the gateway. The override settings have precedence over the [`spec.default` configurations](#spec-default).
#### Values
- Default: None
- Data type: Map
### `spec.override.jwt`
Map that contains JWT verification configurations to apply to listeners when the policy is attached to the gateway. The override settings have precedence over the [`default` configurations](#listeners-default) as well as any route-specific JWT configurations defined in [`RouteAuthFilter` configurations](/consul/docs/connect/gateways/api-gateway/configuration/routeauthfilter).
#### Values
- Default: None
- Data type: Map
### `spec.override.jwt.providers`
Specifies a list of JWT provider configurations to apply to listeners when the policy is attached to the gateway listener. A provider configuration contains the name of the provider and claims. The override settings have precedence over defaults as well as any listener specific configuration. Refer to [Use JWTs to verify requests to API gateways on Kubernetes](/consul/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s) for additional information.
#### Values
- Default: None
- Data type: List of maps
The following table describes the parameters you can specify in a member of the `Providers` list:
| Parameter | Description | Data type | Default |
| --- | --- | --- | --- |
| `name` | Specifies the name of the provider. | String | None |
| `verifyClaims` | Specifies a list of paths and a value that define the claim. Consul verifies requests that match the claims declared in the listener JWT configuration and allow the request through the gateway. The `VerifyClaims` map specifies the following settings: <ul><li>`path`: Specifies a list of one or more registered or custom claims.</li><li>`value`: Specifies the expected value of the claim.</li></ul> | Map | None |
### `spec.default`
Map that contains default configurations to apply to listeners when the policy is attached to the gateway. All routes attached to the gateway listener inherit the default configurations. You can specify override configurations that have precedence over default configurations. Refer to [`spec.override`](#spec-override) for details.
#### Values
- Default: None
- Data type: Map
### `spec.default.jwt`
Specifies default JWT configurations to apply to listeners when the policy is attached to the gateway. Specify configurations that have precedence over the defaults in either the [`spec.override.JWT` block](#spec-override-jwt) or in an [`RouteAuthFilter`](/consul/docs/connect/gateways/api-gateway/configuration/routeauthfilter) attached to an HTTP route. Refer to [Use JWTs to verify requests to API gateways](/consul/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s) for order of precedence and other details about using JWT verification in API gateways.
#### Values
- Default: None
- Data type: Map
### `spec.default.jwt.providers`
Specifies default JWT provider configurations to apply to the listener when the policy is attached to the gateway. A provider configuration contains the name of the provider and claims. Specify configurations that have precedence over the defaults in either the [`spec.override.JWT.providers` block](#spec-override-jwt) or in an [`RouteAuthFilter`](/consul/docs/connect/gateways/api-gateway/configuration/routeauthfilter) attached to an HTTP route configuration. Refer to [Use JWTs to verify requests to API gateways](/consul/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s) for order of precedence and other details about using JWT verification in API gateways.
#### Values
- Default: None
- Data type: List of maps
The following table describes the parameters you can specify in a member of the `Providers` list:
| Parameter | Description | Data type | Default |
| --- | --- | --- | --- |
| `name` | Specifies the name of the provider. | String | None |
| `verifyClaims` | Specifies a list of paths and a value that define the claim. Consul verifies requests that match the claims declared in the listener JWT configuration and allow the request through the gateway. The `VerifyClaims` map specifies the following settings: <ul><li>`path`: Specifies a list of one or more registered or custom claims.</li><li>`value`: Specifies the expected value of the claim.</li></ul> | Map | None |
## Example configuration
In the following example, all requests through the gateway must have the `api.apps.organization.com` audience claim. Additionally, requests through the gateway must have a `user` role by default.
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: GatewayPolicy
metadata:
name: my-policy
spec:
targetRef:
name: gateway
kind: Gateway
group: gateway.networking.kuberenetes.io
sectionName: to-server
override:
jwt:
providers:
- name: "okta"
verifyClaims:
- path:
- "aud"
value: "api.apps.organization.com"
default:
jwt:
providers:
- name: "okta"
verifyClaims:
- path:
- "roles"
- "perm"
value: "user"
```

684
website/content/docs/connect/gateways/api-gateway/configuration/http-route.mdx
View File

@ -1,684 +0,0 @@
---
layout: docs
page_title: HTTP Route Configuration
description: Learn how to configure an HTTP Route bound to an API Gateway on VMs.
---
# HTTP route configuration reference
This topic provides reference information for the gateway routes configuration entry. Refer to [Route Resource Configuration](/consul/docs/api-gateway/configuration/routes) for information about configuring API gateway routes in Kubernetes environments.
## Configuration model
The following list outlines field hierarchy, language-specific data types, and
requirements in an `http-route` configuration entry. Click on a property name
to view additional details, including default values.
- [`Kind`](#kind): string | must be `http-route`
- [`Name`](#name): string | no default
- [`Namespace`](#namespace): string | no default <EnterpriseAlert inline />
- [`Partition`](#partition): string | no default <EnterpriseAlert inline />
- [`Meta`](#meta): map | no default
- [`Hostnames`](#hostnames): list | no default
- [`Parents`](#parents): list | no default
- [`Kind`](#parents-kind): string | must be `api-gateway`
- [`Name`](#parents-name): string | no default
- [`Namespace`](#parents-namespace): string | no default <EnterpriseAlert inline />
- [`Partition`](#parents-partition): string | no default <EnterpriseAlert inline />
- [`SectionName`](#parents-sectionname): string | no default
- [`Rules`](#rules): list | no default
- [`Filters`](#rules-filters): map | no default
- [`Headers`](#rules-filters-headers): list | no default
- [`Add`](#rules-filters-headers-add): map | no default
- [`Remove`](#rules-filters-headers-remove): list | no default
- [`Set`](#rules-filters-headers-set): map | no default
- [`URLRewrite`](#rules-filters-urlrewrite): map | no default
- [`Path`](#rules-filters-urlrewrite-path): string | no default
- [`Matches`](#rules-matches): list | no default
- [`Headers`](#rules-matches-headers): list | no default
- [`Match`](#rules-matches-headers-match): string | no default
- [`Name`](#rules-matches-headers-name): string | no default
- [`Value`](#rules-matches-headers-value): string | no default
- [`Method`](#rules-matches-method): string | no default
- [`Path`](#rules-matches-path): map | no default
- [`Match`](#rules-matches-path-match): string | no default
- [`Value`](#rules-matches-path-value): string | no default
- [`Query`](#rules-matches-query): list | no default
- [`Match`](#rules-matches-query-match): string | no default
- [`Name`](#rules-matches-query-name): string | no default
- [`Value`](#rules-matches-query-value): string | no default
- [`Services`](#rules-services): list | no default
- [`Name`](#rules-services-name): string | no default
- [`Namespace`](#rules-services-namespace): string <EnterpriseAlert inline />
- [`Partition`](#rules-services-partition): string <EnterpriseAlert inline />
- [`Weight`](#rules-services-weight): number | `1`
- [`Filters`](#rules-services-filters): map | no default
- [`Headers`](#rules-services-filters-headers): list | no default
- [`Add`](#rules-services-filters-headers-add): map | no default
- [`Remove`](#rules-services-filters-headers-remove): list | no default
- [`Set`](#rules-services-filters-headers-set): map | no default
- [`URLRewrite`](#rules-services-filters-urlrewrite): map | no default
- [`Path`](#rules-services-filters-urlrewrite-path): string | no default
## Complete configuration
When every field is defined, an `http-route` configuration entry has the following form:
<CodeTabs>
```hcl
Kind = "http-route"
Name = "<name of the route>"
Namespace = "<enterprise: namespace of the service>"
Partition = "<enterprise: partition of the service>"
Meta = {
"<any key>" = "<any value>"
}
Hostnames = ["<hostnames for which this HTTPRoute should respond to requests>"]
Parents = [
{
Kind = "api-gateway"
Name = "<name of the api-gateway to bind to>"
Namespace = "<enterprise: namespace of the service>"
Partition = "<enterprise: partition of the service>"
SectionName = "<optional name of a specific listener on the api-gateway to bind to>"
}
]
Rules = [
{
Filters = {
Headers = [
{
Add = {
"<name of header to add>" = "<value of header to add>"
}
Remove = [
"<name of header to remove from request>"
]
Set = {
"<name of header to set>" = "<value of header to set>"
}
}
]
URLRewrite = {
Path = "<path to rewrite request to>"
}
}
Matches = [
{
Headers = [
{
Match = "<type of match: exact, prefix or regex>"
Name = "<name of header to match on>"
Value = "<value of header to match on>"
}
]
Method = "<method type to match on>"
Path = {
Match = "<type of match: exact, prefix or regex>"
Value = "<value to match on>"
}
Query = [
{
Match = "<type of match: exact, present or regex>"
Name = "<name of query parameter to match on>"
Value = "<value of query parameter to match on>"
}
]
}
]
Services = [
{
Name = "<name of Consul service to route to>"
Namespace = "<enterprise: namespace of the service>"
Partition = "<enterprise: partition of the service>"
Weight = "<number proportional to other weights>"
Filters = {
Headers = [
{
Add = {
"<name of header to add>" = "<value of header to add>"
}
Remove = [
"<name of header to remove from request>"
]
Set = {
"<name of header to set>" = "<value of header to set>"
}
}
]
URLRewrite = {
Path = "<path to rewrite request to>"
}
}
}
]
}
]
```
```json
{
"Kind": "http-route",
"Name": "<name of the route>",
"Namespace": "<enterprise: namespace of the route>",
"Partition": "<enterprise: partition of the route>",
"Meta": {
"<any key>": "<any value>"
},
"Hostnames": [
"<hostnames for which this HTTPRoute should respond to requests>"
],
"Parents": [
{
"Kind": "api-gateway",
"Name": "<name of the api-gateway to bind to>",
"Namespace": "<enterprise: namespace of the route>",
"Partition": "<enterprise: partition of the route>",
"SectionName": "<optional name of a specific listener on the api-gateway to bind to>"
}
],
"Rules": [
{
"Filters": [
{
"Headers": [
{
"Add": [
{
"<name of header to add>": "<value of header to add>"
}
],
"Remove": ["<header to remove from request>"],
"Set": [
{
"<name of header to set>": "<value of header to set>"
}
]
}
],
"URLRewrite": [
{
"Path": "<path to rewrite request to>"
}
]
}
],
"Matches": [
{
"Headers": [
{
"Match": "<type of match: exact, prefix or regex>",
"Name": "<name of header to match on>",
"Value": "<value of header to match on>"
}
],
"Method": "<method type to match on>",
"Path": [
{
"Match": "<type of match: exact, prefix or regex>",
"Value": "<value to match on>"
}
],
"Query": [
{
"Match": "<type of match: exact, present or regex>",
"Name": "<name of query parameter to match on>",
"Value": "<value of query parameter to match on>"
}
]
}
],
"Services": [
{
"Name": "<name of Consul service to route to>",
"Namespace": "<enterprise: namespace of the route>",
"Partition": "<enterprise: partition of the route>",
"Weight": "<number proportional to other weights>",
"Filters": [
{
"Headers": [
{
"Add": [
{
"<name of header to add": "<value of header to add>"
}
],
"Remove": ["<header to remove from request>"],
"Set": [
{
"<name of header to set": "<value of header to set>"
}
]
}
],
"URLRewrite": [
{
"Path": "<path to rewrite request to>"
}
]
}
]
}
]
}
]
}
```
</CodeTabs>
## Specification
This section provides details about the fields you can configure in the `http-route` configuration entry.
### `Kind`
Specifies the type of configuration entry to implement. For HTTP routes, this must be `http-route`.
#### Values
- Default: none
- This field is required.
- Data type: string value that must be set to `"http-route"`.
### `Name`
Specifies a name for the configuration entry. The name is metadata that you can
use to reference the configuration entry when performing Consul operations,
such as applying a configuration entry to a specific cluster.
#### Values
- Default: Defaults to the name of the node after writing the entry to the Consul server.
- This field is required.
- Data type: string
### `Namespace` <EnterpriseAlert inline />
Specifies the Enterprise [namespace](/consul/docs/enterprise/namespaces) to apply to the configuration entry.
#### Values
- Default: `"default"` in Enterprise
- Data type: string
### `Partition` <EnterpriseAlert inline />
Specifies the Enterprise [admin partition](/consul/docs/enterprise/admin-partitions) to apply to the configuration entry.
#### Values
- Default: `"default"` in Enterprise
- Data type: string
### `Meta`
Specifies an arbitrary set of key-value pairs to associate with the route.
#### Values
- Default: none
- Data type: map containing one or more keys and string values.
### `Parents[]`
Specifies the list of gateways that this route binds to.
#### Values
- Default: none
- Data type: List of map. Each member of the list contains the following fields:
- `Kind`
- `Name`
- `Namespace` <EnterpriseAlert inline />
- `Partition` <EnterpriseAlert inline />
- `SectionName`
### `Parents[].Kind`
Specifies the type of resource to bind to. This field is required and must be
set to `"api-gateway"`
#### Values
- Default: none
- This field is required.
- Data type: string value set to `"api-gateway"`
### `Parents[].Name`
Specifies the name of the api-gateway to bind to.
#### Values
- Default: none
- This field is required.
- Data type: string
### `Parents[].Namespace` <EnterpriseAlert inline />
Specifies the Enterprise [namespace](/consul/docs/enterprise/namespaces) to apply to the configuration entry.
#### Values
- Default: `"default"` in Enterprise
- Data type: string
### `Parents[].Partition` <EnterpriseAlert inline />
Specifies the Enterprise [admin partition](/consul/docs/enterprise/admin-partitions) to apply to the configuration entry.
#### Values
- Default: `"default"` in Enterprise
- Data type: string
### `Parents[].SectionName`
Specifies the name of the listener to bind to on the `api-gateway`. If left
empty, this route binds to _all listeners_ on the parent gateway.
#### Values
- Default: ""
- Data type: string
### `Rules[]`
Specifies the list of HTTP-based routing rules that this route uses to construct a route table.
#### Values
- Default:
- Data type: List of maps. Each member of the list contains the following fields:
- `Filters`
- `Matches`
- `Services`
### `Rules[].Filters`
Specifies the list of HTTP-based filters used to modify a request prior to routing it to the upstream service.
#### Values
- Default: none
- Data type: Map that contains the following fields:
- `Headers`
- `UrlRewrite`
### `Rules[].Filters.Headers[]`
Defines operations to perform on matching request headers when an incoming request matches the `Rules.Matches` configuration.
#### Values
This field contains the following configuration objects:
| Parameter | Description | Type |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| `set` | Configure this field to rewrite the HTTP request header. It specifies the name of an HTTP header to overwrite and the new value to set. Any existing values associated with the header name are overwritten. You can specify the following configurations: <ul><li>`name`: Required string that specifies the name of the HTTP header to set.</li><li>`value`: Required string that specifies the value of the HTTP header to set.</li></ul> | List of maps |
| `add` | Configure this field to append the request header with a new value. It specifies the name of an HTTP header to append and the values to add. You can specify the following configurations: <ul><li>`name`: Required string that specifies the name of the HTTP header to append.</li><li>`value`: Required string that specifies the value of the HTTP header to add.</li></ul> | List of maps |
| `remove` | Configure this field to specify an array of header names to remove from the request header. | List of strings |
### `Rules[].Filters.URLRewrite`
Specifies rule for rewriting the URL of incoming requests when an incoming request matches the `Rules.Matches` configuration.
#### Values
- Default: none
- This field is a map that contains a `Path` field.
### Rules[].Filters.URLRewrite.Path
Specifies a path that determines how Consul API Gateway rewrites a URL path. Refer to [Reroute HTTP requests](/consul/docs/api-gateway/usage/reroute-http-requests) for additional information.
#### Values
The following table describes the parameters for `path`:
| Parameter | Description | Type |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ |
| `replacePrefixMatch` | Specifies a value that replaces the path prefix for incoming HTTP requests. The operation only affects the path prefix. The rest of the path is unchanged. | String |
| `type` | Specifies the type of replacement to use for the URL path. You can specify the following values: <ul><li>`ReplacePrefixMatch`: Replaces the matched prefix of the URL path (default). </li></ul> | String |
### `Rules[].Matches[]`
Specifies the matching criteria used in the routing table. When an incoming
request matches the given HTTPMatch configuration, traffic routes to
services specified in the [`Rules.Services`](#rules-services) field.
#### Values
- Default: none
- Data type: List containing maps. Each member of the list contains the following fields:
- `Headers`
- `Method`
- `Path`
- `Query`
### `Rules[].Matches[].Headers[]`
Specifies rules for matching incoming request headers. You can specify multiple rules in a list, as well as multiple lists of rules. If all rules in a single list are satisfied, then the route forwards the request to the appropriate service defined in the [`Rules.Services`](#rules-services) configuration. You can create multiple `Header[]` lists to create a range of matching criteria. When at least one list of matching rules are satisfied, the route forwards the request to the appropriate service defined in the [`Rules.Services`](#rules-services) configuration.
#### Values
- Default: none
- Data type: List containing maps with the following fields:
- `Match`
- `Name`
- `Value`
### `Rules.Matches.Headers.Match`
Specifies type of match for headers: `"exact"`, `"prefix"`, or `"regex"`.
#### Values
- Default: none
- Data type: string
### `Rules.Matches.Headers.Name`
Specifies the name of the header to match.
#### Values
- Default: none
- Data type: string
### `Rules[].Matches.Headers.Value`
Specifies the value of the header to match.
#### Values
- Default: none
- Data type: string
### `Rules[].Matches[].Method`
Specifies a list of strings that define matches based on HTTP request method.
#### Values
Specify one of the following string values:
- `HEAD`
- `POST`
- `PUT`
- `PATCH`
- `GET`
- `DELETE`
- `OPTIONS`
- `TRACE`
- `CONNECT`
### `Rules[].Matches[].Path`
Specifies the HTTP method to match.
#### Values
- Default: none
- Data type: map containing the following fields:
- `Match`
- `Value`
### `Rules[].Matches[].Path.Match`
Specifies type of match for the path: `"exact"`, `"prefix"`, or `"regex"`.
If set to `prefix`, Consul uses simple string matching to identify incoming request prefixes. For example, if the route is configured to match incoming requests to services prefixed with `/dev`, then the gateway would match requests to `/dev-` and `/deviate` and route to the upstream.
This deviates from the
[Kubernetes Gateway API specification](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io%2fv1beta1.PathMatchType), which matches on full path elements. In the previous example, _only_ requests to `/dev` or `/dev/` would match.
#### Values
- Default: none
- Data type: string
### `Rules[].Matches[].Path.Value`
Specifies the value of the path to match.
#### Values
- Default: none
- Data type: string
### `Rules[].Matches[].Query[]`
Specifies how a match is completed on a request’s query parameters.
#### Values
- Default: none
- Data type: List of map that contains the following fields:
- `Match`
- `Name`
- `Value`
### `Rules[].Matches[].Query[].Match`
Specifies type of match for query parameters: `"exact"`, `"prefix"`, or `"regex"`.
#### Values
- Default: none
- Data type: string
### `Rules[].Matches[].Query[].Name`
Specifies the name of the query parameter to match.
#### Values
- Default: none
- Data type: string
### `Rules[].Matches[].Query[].Value`
Specifies the value of the query parameter to match.
#### Values
- Default: none
- Data type: string
### `Rules[].Services[]`
Specifies the service that the API gateway routes incoming requests to when the
requests match the `Rules.Matches` configuration.
#### Values
- Default: none
- This field contains a list of maps. Each member of the list contains the following fields:
- `Name`
- `Weight`
- `Filters`
- `Namespace` <EnterpriseAlert inline />
- `Partition` <EnterpriseAlert inline />
### `Rules[].Services[].Name`
Specifies the name of an HTTP-based service to route to.
#### Values
- Default: none
- Data type: string
### `Rules[].Services[].Namespace` <EnterpriseAlert inline />
Specifies the Enterprise [namespace](/consul/docs/enterprise/namespaces) to apply to the configuration entry.
#### Values
- Default: `"default"` in Enterprise
- Data type: string
### `Rules[].Services.Partition` <EnterpriseAlert inline />
Specifies the Enterprise [admin partition](/consul/docs/enterprise/admin-partitions) to apply to the configuration entry.
#### Values
- Default: `"default"` in Enterprise
- Data type: string
### `Rules[].Services[].Weight`
Specifies the proportion of requests forwarded to the specified service. If no weight is specified, or if the specified
weight is set to less than or equal to `0`, the weight is normalized to `1`. The
proportion is determined by dividing the value of the weight by the sum of all
weights in the service list. For non-zero values, there may be some deviation
from the exact proportion depending on the precision an implementation
supports. Weight is not a percentage and the sum of weights does not need to
equal 100.
#### Values
- Default: none
- Data type: integer
### `Rules[].Services[].Filters`
Specifies the list of HTTP-based filters used to modify a request prior to
routing it to this upstream service.
#### Values
- Default: none
- Data type: Map that contains the following fields:
- `Headers`
- `UrlRewrite`
### `Rules[].Services[].Filters.Headers[]`
Defines operations to perform on matching request headers.
#### Values
This field contains the following configuration objects:
| Parameter | Description | Type |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| `set` | Configure this field to rewrite the HTTP request header. It specifies the name of an HTTP header to overwrite and the new value to set. Any existing values associated with the header name are overwritten. You can specify the following configurations: <ul><li>`name`: Required string that specifies the name of the HTTP header to set.</li><li>`value`: Required string that specifies the value of the HTTP header to set.</li></ul> | List of maps |
| `add` | Configure this field to append the request header with a new value. It specifies the name of an HTTP header to append and the values to add. You can specify the following configurations: <ul><li>`name`: Required string that specifies the name of the HTTP header to append.</li><li>`value`: Required string that specifies the value of the HTTP header to add.</li></ul> | List of maps |
| `remove` | Configure this field to specify an array of header names to remove from the request header. | List of strings |
### `Rules[].Services[].Filters.URLRewrite`
Specifies rule for rewriting the URL of incoming requests.
#### Values
- Default: none
- This field is a map that contains a `Path` field.

44
website/content/docs/connect/gateways/api-gateway/configuration/index.mdx Normal file
View File

@ -0,0 +1,44 @@
---
layout: docs
page_title: Consul API gateway configuration overview
description: >-
Configure your Consul API Gateway to manage traffic into your service mesh. Learn about the Kubernetes Gateway Specification items you can configure and how to configure custom API Gateways.
---
# Consul API gateway configuration overview
This topic provides an overview of the configuration items you can use to create API gateways, configure listeners, define routes, and apply additional resources that may be necessary to operate Consul API gateways in your environment.
## Configurations for virtual machines
Apply the following configuration items if your network runs on virtual machines nodes:
| Configuration | Description | Usage |
| --- | --- | --- |
| [`api-gateway`](/consul/docs/connect/config-entries/api-gateway) | Defines the main infrastructure resource for declaring an API gateway and listeners on the gateway. | [Deploy API gateway listeners on virtual machines](/consul/docs/connect/gateways/api-gateway/deploy/listeners-vms) |
| [`http-route`](/consul/docs/connect/config-entries/http-route) | Enables HTTP traffic to reach services in the mesh from a listener on the gateway.| <nobr>[Define routes on virtual machines](/consul/docs/connect/gateways/api-gateway/define-routes/routes-vms)</nobr> |
| [`tcp-route`](/consul/docs/connect/config-entries/tcp-route) | Enables TCP traffic to reach services in the mesh from a listener on the gateway.| [Define routes on virtual machines](/consul/docs/connect/gateways/api-gateway/define-routes/routes-vms) |
| <nobr>[`inline-certificate`](/consul/docs/connect/config-entries/inline-certificate)</nobr> | Provides gateway artificats with a CA certificate so that requests between the user and the gateway endpoint are encrypted. | [Encrypt API gateway traffic on virtual machines](/consul/docs/connect/gateways/api-gateway/secure-traffic/encrypt-vms) |
| [`service-intentions`](/consul/docs/connect/config-entries/service-intentions) | Specifies traffic communication rules between services in the mesh. Intentions also enforce rules for service-to-service traffic routed through a Consul API gateway. | General configuration for securing a service mesh |
## Configurations for Kubernetes
Apply the following configuration items if your network runs on Kubernetes:
| Configuration | Description | Usage |
| --- | --- | --- |
| [`Gateway`](/consul/docs/connect/gateways/api-gateway/configuration/gateway) | Defines the main infrastructure resource for declaring an API gateway and listeners on the gateway. It also specifies the name of the `GatewayClass`. | [Deploy listeners on Kubernetes](/consul/docs/connect/gateways/api-gateway/deploy/listeners-k8s) |
| [`GatewayClass`](/consul/docs/connect/gateways/api-gateway/configuration/gatewayclass) | Defines a class of gateway resources used as a template for creating gateways. The default gateway class is `consul` and is suitable for most API gateway implementations. | [Deploy listeners on Kubernetes](/consul/docs/connect/gateways/api-gateway/deploy/listeners-k8s) |
| [`GatewayClassConfig`](/consul/docs/connect/gateways/api-gateway/configuration/gatewayclassconfig) | Describes additional gateway-related configuration parameters for the `GatewayClass` resource. | [Deploy listeners on Kubernetes](/consul/docs/connect/gateways/api-gateway/deploy/listeners-k8s) |
| [`Routes`](/consul/docs/connect/gateways/api-gateway/configuration/routes) | Specifies paths from the gateway listener to backend services. | <nobr>[Define routes on Kubernetes](/consul/docs/connect/gateways/api-gateway/define-routes/routes-k8s)</nobr><p>[Reroute traffic in Kubernetes](/consul/docs/connect/gateways/api-gateway/define-routes/reroute-http-requests)</p><p>[Route traffic to peered services in Kubernetes](/consul/docs/connect/gateways/api-gateway/define-routes/route-to-peered-services)</p> |
| [`MeshServices`](/consul/docs/connect/gateways/api-gateway/configuration/meshservices) | Enables routes to reference services in Consul. | [Route traffic to peered services in Kubernetes](/consul/docs/connect/gateways/api-gateway/define-routes/route-to-peered-services) |
| [`ServiceIntentions`](/consul/docs/connect/config-entries/service-intentions) | Specifies traffic communication rules between services in the mesh. Intentions also enforce rules for service-to-service traffic routed through a Consul API gateway. | General configuration for securing a service mesh |
<!-- Reuse later for a topic about creating custom api gateway classes
You can create a basic Gateway object using the default [`gatewayClassName`](/consul/docs/connect/gateways/api-gateway/configuration/gateway#gatewayclassname) (`consul`). If you want to create custom Gateways suitable for your environment, complete the following steps:
1. Define a [GatewayClassConfig](/consul/docs/connect/gateways/api-gateway/configuration/gatewayclassconfig) that contains your custom configurations.
1. Define a [GatewayClass](/consul/docs/connect/gateways/api-gateway/configuration/gatewayclass) and configure the [`parametersRef.name`](/consul/docs/connect/gateways/api-gateway/configuration/configuration/gatewayclass#parametersref-name) to reference the name of your [GatewayClassConfig](/consul/docs/connect/gateways/api-gateway/configuration/gatewayclassconfig).
1. Define a [Gateway](/consul/docs/connect/gateways/api-gateway/configuration/configuration/gateway) and configure the [`gatewayClassName`](/consul/docs/connect/gateways/api-gateway/configuration/gateway#gatewayclassname) to reference the name of your [GatewayClass](/consul/docs/connect/gateways/api-gateway/configuration/gatewayclass).
<!--TODO add diagram -->

0
website/content/docs/api-gateway/configuration/meshservice.mdx → website/content/docs/connect/gateways/api-gateway/configuration/meshservice.mdx
View File

139
website/content/docs/connect/gateways/api-gateway/configuration/routeauthfilter.mdx Normal file
View File

@ -0,0 +1,139 @@
---
layout: docs
page_title: RouteAuthFilter configuration reference
description: Learn how to configure the `RouteAuthFilter` resource, which defines behaviors for gateway listeners that are attached to specific HTTP routes.
---
# RouteAuthFilter configuration reference
This topic provides reference information for the HTTP route auth filter resource, which defines authorization filter configurations for specific routes in Consul service mesh on Kubernetes-orchestrated networks.
## Configuration model
The following list outlines field hierarchy, data types, and requirements in an HTTP route auth filter resource. Click on a property name to view additional details, including default values.
- [`apiVersion`](#apiversion): string | required | must be set to `consul.hashicorp.com/v1alpha1`
- [`kind`](#kind): string | required | must be set to `RouteAuthFilter`
- [`metadata`](#metadata): map | required
- [`name`](#metadata-name): string | required
- [`namespace`](#metadata-namespace): string | `default`
- [`spec`](#spec): map | required
- [`jwt`](#spec-jwt): map | required
- [`providers`](#spec-providers): list | required
- [`name`](#spec-providers): string | required
- [`verifyClaims`](#spec-providers): map | required
- [`path`](#spec-providers): list of strings | required
- [`value`](#spec-providers): string | required
## Complete configuration
When every field is defined, an HTTP route auth filter has the following form:
## Specification
This section provides details about the fields you can configure in the HTTP route auth filter resource.
### `apiVersion`
Specifies the version of the Consul API for integrating with Kubernetes. The value must be `consul.hashicorp.com/v1alpha1`.
#### Values
- Default: None
- This field is required.
- String value that must be set to `consul.hashicorp.com/v1alpha1`.
### `kind`
Specifies the type of configuration entry to implement. Must be set to `RouteAuthFilter`.
#### Values
- Default: None
- This field is required.
- Data type: String value that must be set to `RouteAuthFilter`.
### `metadata`
Map that contains an arbitrary name for the resource and the namespace it applies to.
#### Values
- Default: None
- Data type: Map
### `metadata.name`
Specifies a name for the resource. The name is metadata that you can use to reference the resource when performing Consul operations, such as applying the resource to a specific cluster.
#### Values
- Default: None
- This field is required.
- Data type: String
### `metadata.namespace`
Specifies the namespace that the configuration applies to. Refer to [Namespaces](/consul/docs/enterprise/namespaces) for more information.
#### Values
- Default: `default`
- Data type: String
### `spec`
Map that contains the details about the HTTP route auth filter. The `apiVersion`, `kind`, and `metadata` fields are siblings of the `spec` field. All other configurations are children.
#### Values
- Default: None
- This field is required.
- Data type: Map
### `spec.jwt`
Map that contains JWT verification configurations to apply to listeners when the filter is attached to the route. These route-specific settings have precedence over the `default` configurations, but not `override` JWT configurations, that are defined in the [`GatewayPolicy`](/consul/docs/connect/gateways/api-gateway/configuration/gatewaypolicy) resource.
#### Values
- Default: None
- Data type: Map
### `spec.jwt.providers`
Specifies a list of JWT provider configurations to apply to listeners when the filter is attached to the route. A provider configuration contains the name of the provider and claims. The route-specific settings have precedence over the `default` configurations, but not `override` configurations, that are defined in the [`GatewayPolicy`](/consul/docs/connect/gateways/api-gateway/configuration/gatewaypolicy) resource. Refer to [Use JWTs to verify requests to API gateways on Kubernetes](/consul/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s) for additional information.
#### Values
- Default: None
- Data type: List of maps
The following table describes the parameters you can specify in a member of the `providers` list:
| Parameter | Description | Data type | Default |
| --- | --- | --- | --- |
| `name` | Specifies the name of the provider. | String | None |
| `verifyClaims` | Specifies a list of paths and a value that define the claim. Consul verifies requests that match the claims declared in the listener JWT configuration and allow the request through the gateway. The `VerifyClaims` map specifies the following settings: <ul><li>`path`: Specifies a list of one or more registered or custom claims.</li><li>`value`: Specifies the expected value of the claim.</li></ul> | Map | None |
## Example configuration
In the following example, requests sent to HTTP routes attached to the filter must have `admin` permissions.
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: RouteAuthFilter
metadata:
name: example-route-jwt-filter
namespace: default
spec:
JWT:
Providers:
- Name: "okta"
VerifyClaims:
- Path:
- "roles"
- "perm"
Value: "admin"
```

206
website/content/docs/connect/gateways/api-gateway/configuration/routeretryfilter.mdx Normal file
View File

@ -0,0 +1,206 @@
---
layout: docs
page_title: RouteRetryFilter configuration reference
description: >-
Learn how to configure the `RouteRetryFilter` resource, which defines retry settings for specific routes from an API gateway listener to the destination service in Consul service mesh.
---
# RouteRetryFilter configuration reference
This topic provides configuration reference information for details about the `RouteRetryFilter` resource, which defines retry settings for specific routes from an API gateway listener to the destination service in Consul service mesh.
## Introduction
Define the one or more configurations in the `spec` to define the retry logic for the route. Refer to the [retry logic example configuration](#example) for additional information.
To apply retry settings to a `HTTPRoute`, set the `rules.filters.type` parameter in an route to `extensionRef` and specify the name of the filter in `rules.filters.extensionRef.name` field. Refer to [Route resource configuration reference](/consul/docs/connect/gateways/api-gateway/configuration/routes) for additional information.
## Configuration Model
The following list outlines field hierarchy, data types, and requirements in a `RouteRetryFilter` resource. Click on a property name to view additional details, including default values.
- [`apiVersion`](#apiversion): string | required | must be set to `consul.hashicorp.com/v1alpha1`
- [`kind`](#kind): string | required | must be set to `RouteRetryFilter`
- [`metadata`](#metadata): map | required
- [`name`](#metadata-name): string | required
- [`namespace`](#metadata-namespace): string | `default`
- [`spec`](#spec): map | required
- [`numRetries`](#spec-numretries): number | `1`
- [`retryOnConnectFailure`](#spec-retryonconnectfailure): boolean | `false`
- [`retryOn`](#spec-retryon): list
- [`retryOnStatusCodes`](#spec-retryonstatuscodes): list
## Complete configuration
When every field is defined, this resource has the following form:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: RouteRetryFilter
metadata:
name: <name for the retry filter>
spec:
requestTimeout: <amount of time to wait before retrying>
numRetries: <number of times to retry>
retryOnConnectFailure: false
retryOn: ['<condition types that trigger retries>']
```
## Specification
This section provides details about the fields you can configure in the resource.
### `apiVersion`
Specifies the version of the Consul API for integrating with Kubernetes. The value must be `consul.hashicorp.com/v1alpha1`.
#### Values
- Default: None
- This field is required.
- String value that must be set to `consul.hashicorp.com/v1alpha1`.
### `kind`
Specifies the type of configuration entry to implement. Must be set to `RouteRetryFilter`.
#### Values
- Default: None
- This field is required.
- Data type: String value that must be set to `RouteRetryFilter`.
### `metadata`
Map that contains an arbitrary name for the resource and the namespace it applies to.
#### Values
- Default: None
- Data type: Map
### `metadata.name`
Specifies a name for the resource. The name is metadata that you can use to reference the resource when performing Consul operations, such as applying the resource to a specific cluster.
#### Values
- Default: None
- This field is required.
- Data type: String
### `metadata.namespace`
Specifies the namespace that the configuration applies to. Refer to [namespaces](/consul/docs/enterprise/namespaces) for more information.
#### Values
- Default: None
- Data type: String
### `spec`
Map that contains the details about the gateway policy. The `apiVersion`, `kind`, and `metadata` fields are siblings of the `spec` field. All other configurations are children.
### `spec.numRetries`
Specifies the number of times to retry the request when a retry condition occurs.
#### Values
- Default: `1`
- Data type: Integer
### `spec.retryOnConnectFailure`
Enables Consul to retry the request if the connection fails. Define the one or more retry configurations to define the retry logic for the route.
#### Values
- Default: `false`
- Data type: Boolean
### `spec.retryOn`
Specifies a list of conditions for Consul to retry requests based on the response from an upstream service. The following retry conditions are supported:
| Conditions | Description |
| :------------------- | :------------------------------------------------------------------------------------------------------- |
| `5xx` | Consul retries the request when an upstream responds with any 5xx error code or does not respond at all. |
| `gateway-error` | Consul retries the request when the upstream responds with a 502, 503, or 504 error. |
| `reset` | Consul retries the request when the upstream does not respond at all. |
| `connect-failure` | Consul retries the request when the connection to the upstream fails. |
| `envoy-ratelimited` | Consul retries the request when the header `x-envoy-ratelimited` is present. |
| `retriable-4xx` | Consul retries the request when the upstream responds with a retriable 4xx code. |
| `refused-stream` | Consul retries the request when the upstream resets the stream with a `REFUSED_STREAM` error code. |
| `cancelled` | Consul retries the request when the gRPC status code in the response headers is `cancelled`. |
| `deadline-exceeded` | Consul retries the request when the gRPC status code in the response headers is `deadline-exceeded`. |
| `internal` | Consul retries the request when the gRPC status code in the response headers is `internal`. |
| <nobr>`resource-exhausted`</nobr> | Consul retries the request when the gRPC status code in the response headers is `resource-exhausted`. |
| `unavailable` | Consul retries the request when the gRPC status code in the response headers is `unavailable`. |
#### Values
- Default: None
- Data type: List of strings. Strings must match one of the following values:
- `5xx`
- `gateway-error`
- `reset`
- `connect-failure`
- `envoy-ratelimited`
- `retriable-4xx`
- `refused-stream`
- `cancelled`
- `deadline-exceeded`
- `internal`
- `resource-exhausted`
- `unavailable`
### `spec.retryOnStatusCodes`
Specifies a list of integers for [HTTP response status codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) that trigger a retry request.
#### Values
- Default: None
- Data type: List of integers
## Example
The following example configures Consul to retry the route five times after 15 when the connection fails:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: RouteRetryFilter
metadata:
name: orders
spec:
numRetries: 5
retryOnConnectFailure: true
retryOn: ['reset']
---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
name: example-route
namespace: default
spec:
parentRefs:
- name: gateway
rules:
- backendRefs:
- name: example-service
kind: Service
port: 80
filters:
- type: ExtensionRef
extensionRef:
group: consul.hashicorp.com
kind: RouteRetryFilter
name: orders
```

433
website/content/docs/api-gateway/configuration/routes.mdx → website/content/docs/connect/gateways/api-gateway/configuration/routes.mdx
View File

@ -1,21 +1,250 @@
---
layout: docs
page_title: Route Resource Configuration
page_title: Route resource configuration reference
description: >-
The `HTTPRoute` and `TCPRoute` resources define Consul API Gateway routing behavior for traffic into the service mesh according to rules. Learn about its configuration model and reference specifications, and review an example configuration.
Learn about the configuration fields for `HTTPRoute` and `TCPRoute` resources for Consul API gateway. Apply routes to configure how Consul routes traffic into the service mesh according.
---
# Route Resource Configuration
# Route resource configuration reference
This topic describes how to create and configure `Route` resources. Routes are independent configuration objects that are associated with specific listeners.
## Create a `Route`
## Configuration model
Declare a route with either `kind: HTTPRoute` or `kind: TCPRoute` and configure the route parameters in the `spec` block.
Refer to the Kubernetes Gateway API documentation for each object type for details:
The following outline shows how to format the configurations for the `Route` object. The top-level `spec` field is the root for all configurations. Click on a property name to view details about the configuration.
- [HTTPRoute](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRoute)
- [TCPRoute](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.TCPRoute)
- [`parentRefs`](#parentrefs): array of objects | optional
- [`group`](#parentrefs): string | optional
- [`kind`](#parentrefs): string | optional
- [`name`](#parentrefs): string | required
- [`namespace`](#parentrefs): string | optional
- [`sectionName`](#parentrefs): string | optional
- [`rules`](#rules): list of objects | optional
- [`backendRefs`](#rules-backendrefs): list of objects | optional
- [`group`](#rules-backend-refs): string | optional
- [`kind`](#rules-backendrefs): string | optional
- [`name`](#rules-backendrefs): string | required
- [`namespace`](#rules-backendrefs): string | optional
- [`port`](#rules-backendrefs): integer | required
- [`weight`](#rules-backendrefs): integer | optional
- [`filters`](#rules-filters): list of objects | optional
- [`type`](#rules-filters-type): string | required
- [`requestHeaderModifier`](#rules-filters-requestheadermodifier): object | optional
- [`set`](#rules-filters-requestheadermodifier): array of objects | optional
- [`name`](#rules-filters-requestheadermodifier): string | required
- [`value`](#rules-filters-requestheadermodifier): string | required
- [`add`](#rules-filters-requestheadermodifier): array of objects | optional
- [`name`](#rules-filters-requestheadermodifier): string | required
- [`value`](#rules-filters-requestheadermodifier): string | required
- [`remove`](#rules-filters-requestheadermodifier): array of strings | optional
- [`responseHeaderModifier`](#rules-filters-responseheadermodifier): object | optional
- [`set`](#rules-filters-responseheadermodifier): array of objects | optional
- [`name`](#rules-filters-responseheadermodifier): string | required
- [`value`](#rules-filters-responseheadermodifier): string | required
- [`add`](#rules-filters-responseheadermodifier): array of objects | optional
- [`name`](#rules-filters-responseheadermodifier): string | required
- [`value`](#rules-filters-responseheadermodifier): string | required
- [`remove`](#rules-filters-responseheadermodifier): array of strings | optional
- [`urlRewrite`](#rules-filters-urlrewrite): object | optional
- [`path`](#rules-filters-urlrewrite-path): object | required
- [`replacePrefixMatch`](#rules-filters-urlrewrite-path): string | required
- [`type`](#rules-filters-urlrewrite-path): string | required
- [`extensionRef`](#rules-filters-extensionref): map
- [`group`](#rultes-filters-extensionref): string | must be set to `consul.hashicorp.com`
- [`kind`](#rultes-filters-extensionref): string | must be set to `RouteAuthFilter`
- [`name`](#rultes-filters-extensionref): string | must be set to `consul.hashicorp.com`
- [`matches`](#rules-matches): array of objects | optional
- [`path`](#rules-matches-path): list of objects | optional
- [`type`](#rules-matches-path): string | required
- [`value`](#rules-matches-path): string | required
- [`headers`](#rules-matches-headers): list of objects | optional
- [`type`](#rules-matches-headers): string | required
- [`name`](#rules-matches-headers): string | required
- [`value`](#rules-matches-headers): string | required
- [`queryParams`](#rules-matches-queryparams): list of objects | optional
- [`type`](#rules-matches-queryparams): string | required
- [`name`](#rules-matches-queryparams): string | required
- [`value`](#rules-matches-queryparams): string | required
- [`method`](#rules-matches-method): string | optional
## Specification
This topic provides details about the configuration parameters.
### `parentRefs`
This field contains the list of `Gateways` that the route should attach to. If not set, the route will not attach to a `Gateway`. The following table describes the objects you can configure in the `parentRefs` block:
| Parameter | Description | Type | Required |
| --- | --- | --- | --- |
| `group` | Specifies the Kubernetes API group of the `Gateway` to attach to. You can specify the following values: <ul><li>`gateway.networking.k8s.io`</li></ul>. Defaults to `gateway.networking.k8s.io`. | String | Optional |
| `kind` | Specifies the Kubernetes kind of the `Gateway` to attach to. you can specify the following values: <ul><li>`Gateway`</li></ul>. Defaults to `Gateway`. | String | Optional |
| `name` | Specifies the name of the `Gateway` the route is attached to. | String | Required |
| `namespace` | Specifies the Kubernetes namespace containing the `Gateway` to attach to. If the `Gateway` is in a different Kubernetes namespace than the `Route`, then you must specify a value. Defaults to the `Route` namespace. | String | Optional |
| `sectionName` | Specifies the name of a specific listener on the `Gateway` to attach to. The `Route` attempts to attach to all listeners on the `Gateway`. | String | Required |
### `rules`
The `rules` field contains a list of objects that define behaviors for network traffic that goes through the route. The rule configuration contains the following objects:
- [`backendRefs`](#rules-backendrefs): Specifies which backend services the `Route` references when processing traffic.
- [`filters`](#rules-filters): Specifies which operations Consul API Gateway performs when traffic goes through the `Route`.
- [`matches`](#rules-matches): Determines which requests Consul API Gateway processes.
Rules are optional.
### `rules.backendRefs`
This field specifies backend services that the `Route` references. The following table describes the parameters for `backendRefs`:
| Parameter | Description | Type | Required |
| --- | --- | --- | --- |
| `group` | Specifies the Kubernetes API Group of the referenced backend. You can specify the following values: <ul><li>`""`: Specifies the core Kubernetes API group. This value must be used when `kind` is set to `Service`. This is the default value if unspecified.</li><li>`api-gateway.consul.hashicorp.com`: This value must be used when `kind` is set to `MeshService`.</li></ul> | String | Optional |
| `kind` | Specifies the Kubernetes Kind of the referenced backend. You can specify the following values: <ul><li>`Service` (default): Indicates that the `backendRef` references a Service in the Kubernetes cluster. </li><li>`MeshService`: Indicates that the `backendRef` references a service in the Consul mesh. Refer to the `MeshService` [documentation](/consul/docs/connect/gateways/api-gateway/configuration/meshservice) for additional information.</li></ul> | String | Optional |
| `name` | Specifies the name of the Kubernetes Service or Consul mesh service resource. | String | Required |
| `namespace` | Specifies the Kubernetes namespace containing the Kubernetes Service or Consul mesh service resource. You must specify a value if the Service or Consul mesh service is defined in a different namespace from the `Route`. Defaults to the namespace of the `Route`. <br/>To create a route for a `backendRef` in a different namespace, you must also create a [ReferenceGrant](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferenceGrant). Refer to the [example route](#example-cross-namespace-backendref) configured to reference across namespaces. | String | Optional |
| `port` | Specifies the port number for accessing the Kubernetes or Consul service. | Integer | Required |
| `weight` | Specifies the proportion of requests sent to the backend. Computed as weight divided by the sum of all weights in this `backendRefs` list. Defaults to `1`. A value of `0` indicates that no requests should be sent to the backend. | Integer | Optional |
Refer to [Example cross-namespace backendRef](#example-cross-namespace-backendref) for an example configuration.
### `rules.filters`
The `filters` block defines steps for processing requests. You can configure filters to modify the properties of matching incoming requests and enable Consul API Gateway features, such as rewriting path prefixes (refer to [Reroute HTTP requests](/consul/docs/connect/gateways/api-gateway/define-routes/reroute-http-requests) for additional information).
- Type: Array of objects
- Required: Optional
### `rules.filters.type`
Specifies the type of filter you want to apply to the route. The parameter is optional and takes a string value.
You can specify the following values:
- `RequestHeaderModifier`: The `RequestHeaderModifier` type modifies the HTTP headers on the incoming request. You must define the [`rules.filters.requestHeaderModifier`](#rules-filters-requestheadermodifier) configurations to use this filter type.
- `ResponseHeaderModifier`: The `ResponseHeaderModifier` type modifies the HTTP headers on the outgoing response to the caller. You must define the [`rules.filters.requestHeaderModifier`](#rules-filters-requestheadermodifier) configurations to use this filter type.
- `URLRewrite`: The `URLRewrite` type modifies the URL path on the incoming request. You must define the [`rules.filters.urlRewrite`](#rules-filters-urlrewrite) configurations to use this filter type.
- `ExtensionRef`: Attaches an extension reference to an HTTP route. You can create extensions that enable different behaviors, such as defining JWT verification for requests to the route, and attach them to the route. You must define the [`rules.filters.extensionRef`](#rules-filters-extensionref) configuration to use this filter type.
### `rules.filters.requestHeaderModifier`
Defines operations to perform on matching request headers when `rules.filters.type` is configured to `RequestHeaderModifier`. This field contains the following configuration objects:
| Parameter | Description | Type | Required |
| --- | --- | --- | --- |
| `set` | Configure this field to rewrite the HTTP request header. It specifies the name of an HTTP header to overwrite and the new value to set. Any existing values associated with the header name are overwritten. You can specify the following configurations: <ul><li>`name`: Required string that specifies the name of the HTTP header to set.</li><li>`value`: Required string that specifies the value of the HTTP header to set.</li></ul> | List of objects | Optional |
| `add` | Configure this field to append the request header with a new value. It specifies the name of an HTTP header to append and the value(s) to add. You can specify the following configurations: <ul><li>`name`: Required string that specifies the name of the HTTP header to append.</li><li>`value`: Required string that specifies the value of the HTTP header to add.</li></ul> | List of objects | Optional |
| `remove` | Configure this field to specify an array of header names to remove from the request header. | Array of strings | Optional |
### `rules.filters.responseHeaderModifier`
Defines operations to perform on matching response headers when `rules.filters.type` is configured to `ResponseHeaderModifier`. This field contains the following configuration objects:
| Parameter | Description | Type | Required |
| --- | --- | --- | --- |
| `set` | Configure this field to rewrite the HTTP response header. It specifies the name of an HTTP header to overwrite and the new value to set. Any existing values associated with the header name are overwritten. You can specify the following configurations: <ul><li>`name`: Required string that specifies the name of the HTTP header to set.</li><li>`value`: Required string that specifies the value of the HTTP header to set.</li></ul> | List of objects | Optional |
| `add` | Configure this field to append the response header with a new value. It specifies the name of an HTTP header to append and the value(s) to add. You can specify the following configurations: <ul><li>`name`: Required string that specifies the name of the HTTP header to append.</li><li>`value`: Required string that specifies the value of the HTTP header to add.</li></ul> | List of objects | Optional |
| `remove` | Configure this field to specify an array of header names to remove from the response header. | Array of strings | Optional |
### `rules.filters.urlRewrite`
Specifies rules for rewriting the URL of incoming requests when `rules.filters.type` is configured to `URLRewrite`.
- Type: Object
- Required: Optional
### `rules.filters.urlRewrite.path`
Specifies a list of objects that determine how Consul API Gateway rewrites URL paths (refer to [Reroute HTTP requests](/consul/docs/connect/gateways/api-gateway/define-routes/reroute-http-requests) for additional information).
The following table describes the parameters for `path`:
| Parameter | Description | Type | Required |
| --- | --- | --- | --- |
| `replacePrefixMatch` | Specifies a value that replaces the path prefix for incoming HTTP requests. The operation only affects the path prefix. The rest of the path is unchanged. | String | Required |
| `type` | Specifies the type of replacement to use for the URL path. You can specify the following values: <ul><li>`ReplacePrefixMatch`: Replaces the matched prefix of the URL path (default). </li></ul> | String | Optional |
### `rules.filters.extensionRef`
Map that attaches an extension reference to an HTTP route when `rules.filters.type` is set to `ExtensionRef`. You can create extensions that enable different behaviors, such as defining JWT verification for requests to the route, and attach them to the route.
You can configure the following parameters:
| Parameter | Description | Data type | Default |
| --- | --- | --- | --- |
| `group` | Specifies the resource group. | String | None |
| `kind` | Specifies the type of extension reference. You can specify the following types: <ul><li>`RouteAuthFilter`: Contains JWT verification settings. Refer to [Use JWTs to verify requests to API gateways on Kubernetes](/consul/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s) for additional information.</li><li>`RouteRetryFilter`: Defines retry logic for the route if the request is unsuccessful. Refer to [RouteRetryFilter configuration reference](/consul/docs/connect/gateways/api-gateway/configuration/routeretryfilter) for additional information.</li><li>`RouteTimeoutFilter`: Specifies timeout settings for specific routes. Refer to [RouteTimeoutFilter configuration reference](/consul/docs/connect/gateways/api-gateway/configuration/routetimeoutfilter) for additional information. </li> </ul> | String | None |
| `name` | Specifies the name of the filter to attach to the route. | String | None |
### `rules.matches`
Specifies rules for matching incoming requests. You can apply [`filters`](#rulesfilters) to requests that match the defined rules. You can match incoming requests based on the following elements:
- [paths](#rules-matches-path)
- [headers](#rules-matches-headers)
- [query parameters](#rules-matches-queryparams)
- [request method](#rules-matches-method)
Each rule matches requests independently. As a result, a request matching any of the conditions is considered a match. You can configure several matching rules for each type to widen or narrow matches.
### `rules.matches.path`
Specifies a list of objects that define matches based on URL path. The following table describes the parameters for the `path` field:
| Parameter | Description | Type | Required |
| --- | --- | --- | --- |
| `type` | Specifies the type of comparison to use for matching the path value. You can specify the following types. <ul><li>`Exact`: Returns a match only when the entire path matches the `value` field (default).</li><li> `PathPrefix`: Returns a match when the path has the prefix defined in the `value` field.</li><li>`RegularExpression`: Returns a match when the path matches the regex defined in the `value` field.</li></ul> | String | Required |
| `value` | Specifies the value to match on. You can specify a specific string when `type` is `Exact` or `PathPrefix`. You can specify a regular expression if `type` is `RegularExpression`. | String | Required |
### `rules.matches.headers`
Specifies a list of objects that define matches based HTTP request headers. The following table describes the parameters for the `headers` field:
| Parameter | Description | Type | Required |
| --- | --- | --- | --- |
| `type` | Specifies the type of comparison to use for matching the header value. You can specify the following types. <ul><li>`Exact`: Returns a match only when the entire header matches the `value` field (default).</li><li> `RegularExpression`: Returns a match when the header matches the regex defined in the `value` field.</li></ul> | String | Required |
| `name` | Specifies the name of the header to match on. | String | Required |
| `value` | Specifies value to match on. You can specify a specific string or a regular expression. | String | Required |
### `rules.matches.queryParams`
Specifies a list of objects that define matches based query parameters. The following table describes the parameters for the `queryParams` field:
| Parameter | Description | Type | Required |
| --- | --- | --- | --- |
| `type` | Specifies the type of comparison to use for matching a query parameter value. You can specify the following types. <ul><li>`Exact`: Returns a match only when the query parameter match the `value` field (default).</li><li> `RegularExpression`: Returns a match when the query parameter matches the regex defined in the `value` field.</li></ul> | String | Required |
| `name` | Specifies the name of the query parameter to match on. | String | Required |
| `value` | Specifies value to match on. You can specify a specific string or a regular expression. | String | Required |
### `rules.matches.method`
Specifies a list of strings that define matches based on HTTP request method. You may specify the following values:
- `HEAD`
- `POST`
- `PUT`
- `PATCH`
- `GET`
- `DELETE`
- `OPTIONS`
- `TRACE`
- `CONNECT`
## Examples
Refer to the following Consul and Kubernetes Gateway API documentation for additional information:
- [Define routes on Kubernetes](/consul/docs/connect/gateways/api-gateway/define-routes/routes-k8s)
- [`HTTPRoute` in Kubernetes documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRoute)
- [`TCPRoute` in Kubernetes documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.TCPRoute)
### Basic route
The following example creates a route named `example-route` associated with a listener defined in `example-gateway`.
@ -38,94 +267,7 @@ The following example creates a route named `example-route` associated with a li
</CodeBlockConfig>
## Configuration model
The following outline shows how to format the configurations for the `Route` object. The top-level `spec` field is the root for all configurations. Click on a property name to view details about the configuration.
* [`parentRefs`](#parentrefs): array of objects | optional
* [`group`](#parentrefs): string | optional
* [`kind`](#parentrefs): string | optional
* [`name`](#parentrefs): string | required
* [`namespace`](#parentrefs): string | optional
* [`sectionName`](#parentrefs): string | optional
* [`rules`](#rules): list of objects | optional
* [`backendRefs`](#rules-backendrefs): list of objects | optional
* [`group`](#rules-backend-refs): string | optional
* [`kind`](#rules-backendrefs): string | optional
* [`name`](#rules-backendrefs): string | required
* [`namespace`](#rules-backendrefs): string | optional
* [`port`](#rules-backendrefs): integer | required
* [`weight`](#rules-backendrefs): integer | optional
* [`filters`](#rules-filters): list of objects | optional
* [`type`](#rules-filters-type): string | required
* [`requestHeaderModifier`](#rules-filters-requestheadermodifier): object | optional
* [`set`](#rules-filters-requestheadermodifier): array of objects | optional
* [`name`](#rules-filters-requestheadermodifier): string | required
* [`value`](#rules-filters-requestheadermodifier): string | required
* [`add`](#rules-filters-requestheadermodifier): array of objects | optional
* [`name`](#rules-filters-requestheadermodifier): string | required
* [`value`](#rules-filters-requestheadermodifier): string | required
* [`remove`](#rules-filters-requestheadermodifier): array of strings | optional
* [`urlRewrite`](#rules-filters-urlrewrite): object | optional
* [`path`](#rules-filters-urlrewrite-path): object | required
* [`replacePrefixMatch`](#rules-filters-urlrewrite-path): string | required
* [`type`](#rules-filters-urlrewrite-path): string | required
* [`matches`](#rules-matches): array of objects | optional
* [`path`](#rules-matches-path): list of objects | optional
* [`type`](#rules-matches-path): string | required
* [`value`](#rules-matches-path): string | required
* [`headers`](#rules-matches-headers): list of objects | optional
* [`type`](#rules-matches-headers): string | required
* [`name`](#rules-matches-headers): string | required
* [`value`](#rules-matches-headers): string | required
* [`queryParams`](#rules-matches-queryparams): list of objects | optional
* [`type`](#rules-matches-queryparams): string | required
* [`name`](#rules-matches-queryparams): string | required
* [`value`](#rules-matches-queryparams): string | required
* [`method`](#rules-matches-method): string | optional
## Specification
This topic provides details about the configuration parameters.
### parentRefs
This field contains the list of `Gateways` that the route should attach to. If not set, the route will not attach to a `Gateway`. The following table describes the objects you can configure in the `parentRefs` block:
| Parameter | Description | Type | Required |
| --- | --- | --- | --- |
| `group` | Specifies the Kubernetes API group of the `Gateway` to attach to. You can specify the following values: <ul><li>`gateway.networking.k8s.io`</li></ul>. Defaults to `gateway.networking.k8s.io`. | String | Optional |
| `kind` | Specifies the Kubernetes kind of the `Gateway` to attach to. you can specify the following values: <ul><li>`Gateway`</li></ul>. Defaults to `Gateway`. | String | Optional |
| `name` | Specifies the name of the `Gateway` the route is attached to. | String | Required |
| `namespace` | Specifies the Kubernetes namespace containing the `Gateway` to attach to. If the `Gateway` is in a different Kubernetes namespace than the `Route`, then you must specify a value. Defaults to the `Route` namespace. | String | Optional |
| `sectionName` | Specifies the name of a specific listener on the `Gateway` to attach to. The `Route` attempts to attach to all listeners on the `Gateway`. | String | Required |
### rules
The `rules` field contains a list of objects that define behaviors for network traffic that goes through the route. The rule configuration contains the following objects:
* [`backendRefs`](#rules-backendrefs): Specifies which backend services the `Route` references when processing traffic.
* [`filters`](#rules-filters): Specifies which operations Consul API Gateway performs when traffic goes through the `Route`.
* [`matches`](#rules-matches): Determines which requests Consul API Gateway processes.
Rules are optional.
### rules.backendRefs
This field specifies backend services that the `Route` references. The following table describes the parameters for `backendRefs`:
| Parameter | Description | Type | Required |
| --- | --- | --- | --- |
| `group` | Specifies the Kubernetes API Group of the referenced backend. You can specify the following values: <ul><li>`""`: Specifies the core Kubernetes API group. This value must be used when `kind` is set to `Service`. This is the default value if unspecified.</li><li>`api-gateway.consul.hashicorp.com`: This value must be used when `kind` is set to `MeshService`.</li></ul> | String | Optional |
| `kind` | Specifies the Kubernetes Kind of the referenced backend. You can specify the following values: <ul><li>`Service` (default): Indicates that the `backendRef` references a Service in the Kubernetes cluster. </li><li>`MeshService`: Indicates that the `backendRef` references a service in the Consul mesh. Refer to the `MeshService` [documentation](/consul/docs/api-gateway/configuration/meshservice) for additional information.</li></ul> | String | Optional |
| `name` | Specifies the name of the Kubernetes Service or Consul mesh service resource. | String | Required |
| `namespace` | Specifies the Kubernetes namespace containing the Kubernetes Service or Consul mesh service resource. You must specify a value if the Service or Consul mesh service is defined in a different namespace from the `Route`. Defaults to the namespace of the `Route`. <br/>To create a route for a `backendRef` in a different namespace, you must also create a [ReferenceGrant](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferenceGrant). Refer to the [example route](#example-cross-namespace-backendref) configured to reference across namespaces. | String | Optional |
| `port` | Specifies the port number for accessing the Kubernetes or Consul service. | Integer | Required |
| `weight` | Specifies the proportion of requests sent to the backend. Computed as weight divided by the sum of all weights in this `backendRefs` list. Defaults to `1`. A value of `0` indicates that no requests should be sent to the backend. | Integer | Optional |
#### Example cross-namespace backendRef
### Example cross-namespace backendRef
The following example creates a route named `example-route` in namespace `gateway-namespace`. This route has a `backendRef` in namespace `service-namespace`. Traffic is allowed because the `ReferenceGrant`, named `reference-grant` in namespace `service-namespace`, allows traffic from `HTTPRoutes` in `gateway-namespace` to `Services` in `service-namespace`.
@ -165,102 +307,3 @@ The following example creates a route named `example-route` in namespace `gatewa
```
</CodeBlockConfig>
### rules.filters
The `filters` block defines steps for processing requests. You can configure filters to modify the properties of matching incoming requests and enable Consul API Gateway features, such as rewriting path prefixes (refer to [Reroute HTTP requests](/consul/docs/api-gateway/usage/reroute-http-requests) for additional information).
* Type: Array of objects
* Required: Optional
### rules.filters.type
Specifies the type of filter you want to apply to the route. The parameter is optional and takes a string value.
You can specify the following values:
* `RequestHeaderModifier`: The `RequestHeaderModifier` type modifies the HTTP headers on the incoming request. You must define the [`rules.filters.requestHeaderModifier`](#rules-filters-requestheadermodifier) configurations to use this filter type.
* `URLRewrite`: The `URLRewrite` type modifies the URL path on the incoming request. You must define the [`rules.filters.urlRewrite`](#rules-filters-urlrewrite) configurations to use this filter type.
### rules.filters.requestHeaderModifier
Defines operations to perform on matching request headers when `rules.filters.type` is configured to `RequestHeaderModifier`. This field contains the following configuration objects:
| Parameter | Description | Type | Required |
| --- | --- | --- | --- |
| `set` | Configure this field to rewrite the HTTP request header. It specifies the name of an HTTP header to overwrite and the new value to set. Any existing values associated with the header name are overwritten. You can specify the following configurations: <ul><li>`name`: Required string that specifies the name of the HTTP header to set.</li><li>`value`: Required string that specifies the value of the HTTP header to set.</li></ul> | List of objects | Optional |
| `add` | Configure this field to append the request header with a new value. It specifies the name of an HTTP header to append and the value(s) to add. You can specify the following configurations: <ul><li>`name`: Required string that specifies the name of the HTTP header to append.</li><li>`value`: Required string that specifies the value of the HTTP header to add.</li></ul> | List of objects | Optional |
| `remove` | Configure this field to specify an array of header names to remove from the request header. | Array of strings | Optional |
### rules.filters.urlRewrite
Specifies rules for rewriting the URL of incoming requests when `rules.filters.type` is configured to `URLRewrite`.
* Type: Object
* Required: Optional
### rules.filters.urlRewrite.path
Specifies a list of objects that determine how Consul API Gateway rewrites URL paths (refer to [Reroute HTTP requests](/consul/docs/api-gateway/usage/reroute-http-requests) for additional information).
The following table describes the parameters for `path`:
| Parameter | Description | Type | Required |
| --- | --- | --- | --- |
| `replacePrefixMatch` | Specifies a value that replaces the path prefix for incoming HTTP requests. The operation only affects the path prefix. The rest of the path is unchanged. | String | Required |
| `type` | Specifies the type of replacement to use for the URL path. You can specify the following values: <ul><li>`ReplacePrefixMatch`: Replaces the matched prefix of the URL path (default). </li></ul> | String | Optional |
### rules.matches
Specifies rules for matching incoming requests. You can apply [`filters`](#rulesfilters) to requests that match the defined rules. You can match incoming requests based on the following elements:
* [paths](#rules-matches-path)
* [headers](#rules-matches-headers)
* [query parameters](#rules-matches-queryparams)
* [request method](#rules-matches-method)
Each rule matches requests independently. As a result, a request matching any of the conditions is considered a match. You can configure several matching rules for each type to widen or narrow matches.
### rules.matches.path
Specifies a list of objects that define matches based on URL path. The following table describes the parameters for the `path` field:
| Parameter | Description | Type | Required |
| --- | --- | --- | --- |
| `type` | Specifies the type of comparison to use for matching the path value. You can specify the following types. <ul><li>`Exact`: Returns a match only when the entire path matches the `value` field (default).</li><li> `PathPrefix`: Returns a match when the path has the prefix defined in the `value` field.</li><li>`RegularExpression`: Returns a match when the path matches the regex defined in the `value` field.</li></ul> | String | Required |
| `value` | Specifies the value to match on. You can specify a specific string when `type` is `Exact` or `PathPrefix`. You can specify a regular expression if `type` is `RegularExpression`. | String | Required |
### rules.matches.headers
Specifies a list of objects that define matches based HTTP request headers. The following table describes the parameters for the `headers` field:
| Parameter | Description | Type | Required |
| --- | --- | --- | --- |
| `type` | Specifies the type of comparison to use for matching the header value. You can specify the following types. <ul><li>`Exact`: Returns a match only when the entire header matches the `value` field (default).</li><li> `RegularExpression`: Returns a match when the header matches the regex defined in the `value` field.</li></ul> | String | Required |
| `name` | Specifies the name of the header to match on. | String | Required |
| `value` | Specifies value to match on. You can specify a specific string or a regular expression. | String | Required |
### rules.matches.queryParams
Specifies a list of objects that define matches based query parameters. The following table describes the parameters for the `queryParams` field:
| Parameter | Description | Type | Required |
| --- | --- | --- | --- |
| `type` | Specifies the type of comparison to use for matching a query parameter value. You can specify the following types. <ul><li>`Exact`: Returns a match only when the query parameter match the `value` field (default).</li><li> `RegularExpression`: Returns a match when the query parameter matches the regex defined in the `value` field.</li></ul> | String | Required |
| `name` | Specifies the name of the query parameter to match on. | String | Required |
| `value` | Specifies value to match on. You can specify a specific string or a regular expression. | String | Required |
### rules.matches.method
Specifies a list of strings that define matches based on HTTP request method. You may specify the following values:
* `HEAD`
* `POST`
* `PUT`
* `PATCH`
* `GET`
* `DELETE`
* `OPTIONS`
* `TRACE`
* `CONNECT`

114
website/content/docs/connect/gateways/api-gateway/configuration/routetimeoutfilter.mdx Normal file
View File

@ -0,0 +1,114 @@
---
layout: docs
page_title: RouteTimeoutFilter configuration reference
description: >-
Learn how to configure the `RouteTimeoutFilter` resource, which defines timeout settings for specific routes from an API gateway listener to the destination service in Consul service mesh.
---
# RouteTimeoutFilter configuration reference
This topic provides configuration reference information for details about the `RouteTimeoutFilter` resource, which defines timeout settings for specific routes from an API gateway listener to the destination service in Consul service mesh.
To apply retry settings to a `HTTPRoute`, set the `rules.filters.type` parameter in an route to `extensionRef` and specify the name of the filter in `rules.filters.extensionRef.name` field. Refer to [Route resource configuration reference](/consul/docs/connect/gateways/api-gateway/configuration/routes) for additional information.
## Configuration Model
The following list outlines field hierarchy, data types, and requirements in a `RouteTimeoutFilter` resource. Click on a property name to view additional details, including default values.
- [`apiVersion`](#apiversion): string | required | must be set to `consul.hashicorp.com/v1alpha1`
- [`kind`](#kind): string | required | must be set to `RouteTimeoutFilter`
- [`metadata`](#metadata): map | required
- [`name`](#metadata-name): string | required
- [`namespace`](#metadata-namespace): string | `default`
- [`spec`](#spec): map | required
- [`idleTimeout`](#spec-idletimeout): number | `0`
- [`requestTimeout`](#spec-retryonconnectfailure): number | `0`
## Complete configuration
When every field is defined, this resource has the following form:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: RouteTimeoutFilter
metadata:
name: <name for the retry filter>
spec:
idleTimeout: <amount of time the request stream can remain idle>
requestTimeout: <total amount of time Consul allows for processing the request stream>
```
## Specification
This section provides details about the fields you can configure in the resource.
### `apiVersion`
Specifies the version of the Consul API for integrating with Kubernetes. The value must be `consul.hashicorp.com/v1alpha1`.
#### Values
- Default: None
- This field is required.
- String value that must be set to `consul.hashicorp.com/v1alpha1`.
### `kind`
Specifies the type of configuration entry to implement. Must be set to `RouteTimeoutFilter`.
#### Values
- Default: None
- This field is required.
- Data type: String value that must be set to `RouteTimeoutFilter`.
### `metadata`
Map that contains an arbitrary name for the resource and the namespace it applies to.
#### Values
- Default: None
- Data type: Map
### `metadata.name`
Specifies a name for the resource. The name is metadata that you can use to reference the resource when performing Consul operations, such as applying the resource to a specific cluster.
#### Values
- Default: None
- This field is required.
- Data type: String
### `metadata.namespace`
Specifies the namespace that the configuration applies to. Refer to [namespaces](/consul/docs/enterprise/namespaces) for more information.
#### Values
- Default: None
- Data type: String
### `spec`
Map that contains the details about the gateway policy. The `apiVersion`, `kind`, and `metadata` fields are siblings of the `spec` field. All other configurations are children.
### `spec.idleTimeout
Specifies the total amount of time permitted for the request stream to be idle.
#### Values
- Default: 0
- Data type: Integer
### `spec.requestTimeout`
Specifies the total amount of time in nanoseconds, including retry attempts, Consul permits for the entire downstream request to be processed.
#### Values
- Default: 0
- Data type: Integer

10
website/content/docs/api-gateway/usage/reroute-http-requests.mdx → website/content/docs/connect/gateways/api-gateway/define-routes/reroute-http-requests.mdx
View File

@ -12,15 +12,15 @@ This topic describes how to configure Consul API Gateway to reroute HTTP request
## Requirements
1. Verify that the [requirements](/consul/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](/consul/docs/api-gateway/install) for details.
1. Verify that the Consul API Gateway CRDs and controller have been installed and applied. Refer to [Installation](/consul/docs/connect/gateways/api-gateway/deploy/install-k8s) for details.
## Configuration
Specify the following fields in your `Route` configuration. Refer to the [Route configuration reference](/consul/docs/api-gateway/configuration/routes) for details about the parameters.
Specify the following fields in your `Route` configuration. Refer to the [Route configuration reference](/consul/docs/connect/gateways/api-gateway/configuration/routes) for details about the parameters.
- [`rules.filters.type`](/consul/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`](/consul/docs/api-gateway/configuration/routes#rules-filters-urlrewrite): Specify the `path` configuration.
- [`rules.filters.urlRewrite.path`](/consul/docs/api-gateway/configuration/routes#rules-filters-urlrewrite-path): Contains the paths that incoming requests should be rewritten to based on the match conditions.
- [`rules.filters.type`](/consul/docs/connect/gateways/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`](/consul/docs/connect/gateways/api-gateway/configuration/routes#rules-filters-urlrewrite): Specify the `path` configuration.
- [`rules.filters.urlRewrite.path`](/consul/docs/connect/gateways/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.

18
website/content/docs/api-gateway/usage/route-to-peered-services.mdx → website/content/docs/connect/gateways/api-gateway/define-routes/route-to-peered-services.mdx
View File

@ -9,19 +9,19 @@ 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](/consul/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](/consul/docs/api-gateway/install) for details.
1. A peering connection must already be established between Consul clusters. Refer to [Cluster Peering on Kubernetes](/consul/docs/k8s/connect/cluster-peering/tech-specs) 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](/consul/docs/k8s/connect/cluster-peering/tech-specs) 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](/consul/docs/connect/config-entries/service-resolver) for instructions.
- Consul v1.14 or later
- Verify that the [requirements](/consul/docs/api-gateway/tech-specs) have been met.
- Verify that the Consul API Gateway CRDs and controller have been installed and applied. Refer to [Installation](/consul/docs/connect/gateways/api-gateway/deploy/install-k8s) for details.
- A peering connection must already be established between Consul clusters. Refer to [Cluster Peering on Kubernetes](/consul/docs/k8s/connect/cluster-peering/tech-specs) for instructions.
- 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](/consul/docs/k8s/connect/cluster-peering/tech-specs) for instructions.
- 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](/consul/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](/consul/docs/api-gateway/configuration/meshservice) for details about the parameters.
Specify the following fields in your `MeshService` configuration to use this feature. Refer to the [MeshService configuration reference](/consul/docs/connect/gateways/api-gateway/configuration/meshservice) for details about the parameters.
- [`name`](/consul/docs/api-gateway/configuration/meshservice#name)
- [`peer`](/consul/docs/api-gateway/configuration/meshservice#peer)
- [`name`](/consul/docs/connect/gateways/api-gateway/configuration/meshservice#name)
- [`peer`](/consul/docs/connect/gateways/api-gateway/configuration/meshservice#peer)
## Example

68
website/content/docs/connect/gateways/api-gateway/define-routes/routes-k8s.mdx Normal file
View File

@ -0,0 +1,68 @@
---
layout: docs
page_title: Define API gateway routes on Kubernetes
description: Learn how to define and attach HTTP and TCP routes to Consul API gateway listeners in Kubernetes-orchestrated networks.
---
# Define API gateway routes on Kubernetes
This topic describes how to configure HTTP and TCP routes and attach them to Consul API gateway listeners in Kubernetes-orchestrated networks. Routes are rule-based configurations that allow external clients to send requests to services in the mesh. For information
## Overview
The following steps describe the general workflow for defining and deploying routes:
1. Define a route configuration that specifies the protocol type, name of the gateway to attach to, and rules for routing requests.
1. Deploy the configuration to create the routes and attach them to the gateway.
Routes and the gateways they are attached to are eventually-consistent objects. They provide feedback about their current state through a series of status conditions. As a result, you must manually check the route status to determine if the route successfully bound to the gateway.
## Requirements
Verify that your environment meets the requirements specified in [Technical specifications for Kubernetes](/consul/docs/connect/gateways/api-gateway/tech-specs).
### OpenShift
If your Kubernetes-orchestrated network runs on OpenShift, verify that OpenShift is enabled for your Consul installation. Refer to [OpenShift requirements](/consul/docs/connect/gateways/api-gateway/tech-specs#openshift-requirements) for additional information.
## Define routes
Define route configurations and bind them to listeners configured on the gateway so that Consul can route incoming requests to services in the mesh.
1. Create a configuration file and specify the following fields:
- `apiVersion`: Specifies the Kuberenetes API gateway version. This must be set to `gateway.networking.k8s.io/v1beta1`
- `kind`: Set to `HTTPRoute` or `TCPRoute`.
- `metadata.name`: Specify a name for the route. The name is metadata that you can use to reference the configuration when performing Consul operations.
- `spec.parentRefs.name`: Specifies a list of API gateways that the route binds to.
- `spec. rules`: Specifies a list of routing rules for constructing a routing table that maps listeners to services.
Refer to the [`Routes` configuration reference](/consul/docs/connect/gateways/api-gateway/configuration/routes) for details about configuring route rules.
1. Configure any additional fields necessary for your use case, such as the namespace or admin partition.
1. Save the configuration.
The following example creates a route named `example-route` associated with a listener defined in `example-gateway`.
```yaml
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
name: example-route
spec:
parentRefs:
- name: example-gateway
rules:
- backendRefs:
- kind: Service
name: echo
port: 8080
```
## Deploy the route configuration
Apply the configuration to your cluster using the `kubectl` command. The following command applies the configuration to the `consul` namespace:
```shell-session
$ kubectl apply -f my-route.yaml -n consul
```

121
website/content/docs/connect/gateways/api-gateway/define-routes/routes-vms.mdx Normal file
View File

@ -0,0 +1,121 @@
---
layout: docs
page_title: Define API gateway routes on virtual machines
description: Learn how to define and attach HTTP and TCP routes to Consul API gateway listeners so that requests from external clients can reach services in the mesh.
---
# Define API gateway routes on virtual machines
This topic describes how to configure HTTP and TCP routes and attach them to Consul API gateway listeners. Routes are rule-based configurations that allow external clients to send requests to services in the mesh.
## Overview
The following steps describe the general workflow for defining and deploying routes:
1. Define routes in an HTTP or TCP configuration entry. The configuration entry includes rules for routing requests, target services in the mesh for the traffic, and the name of the gateway to attach to.
1. Deploy the configuration entry to create the routes and attach them to the gateway.
Routes and the gateways they are attached to are eventually-consistent objects. They provide feedback about their current state through a series of status conditions. As a result, you must manually check the route status to determine if the route is bound to the gateway successfully.
## Requirements
The following requirements must be satisfied to use API gateways on VMs:
- Consul 1.15 or later
- A Consul cluster with service mesh enabled. Refer to [`connect`](/consul/docs/agent/config/config-files#connect)
- Network connectivity between the machine deploying the API Gateway and a Consul cluster agent or server
### ACL requirements
If ACLs are enabled, you must present a token with the following permissions to
configure Consul and deploy API gateway routes:
- `mesh: read`
- `mesh: write`
Refer [Mesh Rules](/consul/docs/security/acl/acl-rules#mesh-rules) for
additional information about configuring policies that enable you to interact
with Consul API gateway configurations.
## Define the routes
Define route configurations and bind them to listeners configured on the gateway so that Consul can route incoming requests to services in the mesh.
1. Create a route configuration entry file and specify the following settings:
- `Kind`: Set to `http` or `tcp`.
- `Name`: Specify a name for the route. The name is metadata that you can use to reference the configuration when performing Consul operations.
- `Parents`: Specifies a list of API gateways that the route binds to.
- `Rules`: If you are configuring HTTP routes, define a list of routing rules for constructing a routing table that maps listeners to services. Each member of the list is a map that may containing the following fields:
- `Filters`
- `Matches`
- `Services`
Refer to the [HTTP route configuration entry](/consul/docs/connect/config-entries/http-route) and [TCP route configuration entry](/consul/docs/connect/config-entries/tcp-route) reference for details about configuring routes.
1. Configure any additional fields necessary for your use case, such as the namespace or admin partition.
1. Save the configuration.
The following example routes requests from the listener on the API gateway at port `8443` to services in Consul based on the path of the request. When an incoming request starts at path `/`, Consul forwards 90 percent of the requests to the `ui` service and 10 percent to `experimental-ui`. Consul also forwards requests starting with `/api` to `api`.
```hcl
Kind = "http-route"
Name = "my-http-route"
// Rules define how requests will be routed
Rules = [
// Send all requests to UI services with 10% going to the "experimental" UI
{
Matches = [
{
Path = {
Match = "prefix"
Value = "/"
}
}
]
Services = [
{
Name = "ui"
Weight = 90
},
{
Name = "experimental-ui"
Weight = 10
}
]
},
// Send all requests that start with the path `/api` to the API service
{
Matches = [
{
Path = {
Match = "prefix"
Value = "/api"
}
}
]
Services = [
{
Name = "api"
}
]
}
]
Parents = [
{
Kind = "api-gateway"
Name = "my-gateway"
SectionName = "my-http-listener"
}
]
```
## Deploy the route configuration
Run the `consul config write` command to attach the routes to the specified gateways. The following example writes a configuration called `my-http-route.hcl`:
```shell-session
$ consul config write my-http-route.hcl
```

74
website/content/docs/connect/gateways/api-gateway/deploy/listeners-k8s.mdx Normal file
View File

@ -0,0 +1,74 @@
---
layout: docs
page_title: Deploy API gateway listeners in Kubernetes
description: >-
Learn how to create API gateway configurations in Kubernetes that enable you to instantiate gateway instances.
---
# Deploy API gateway listeners in Kubernetes
This topic describes how to deploy Consul API gateway listeners to Kubernetes-orchestrated environments. If you want to implement API gateway listeners on VMs, refer to [Deploy API gateway listeners to virtual machines](/consul/docs/connect/gateways/api-gateway/deploy/listeners-vms).
## Overview
API gateways have one or more listeners that serve as ingress points for requests to services in a Consul service mesh. Create an [API gateway configuration](/consul/docs/connect/gateways/api-gateway/configuration/gateway) and define listeners that expose ports on the endpoint for ingress. Apply the configuration to direct Kubernetes to start API gateway services.
### Routes
After deploying the gateway, attach HTTP or TCP [routes](/consul/docs/connect/gateways/api-gateway/configuration/routes) to listeners defined in the gateway to control how requests route to services in the network.
### Intentions
Configure Consul intentions to allow or prevent traffic between gateway listeners and services in the mesh. Refer to [Service intentions](/consul/docs/connect/intentions) for additional information.
## Requirements
1. Verify that your environment meets the requirements specified in [Technical specifications for Kubernetes](/consul/docs/connect/gateways/api-gateway/tech-specs).
1. Verify that the Consul API Gateway CRDs were applied. Refer to [Installation](/consul/docs/connect/gateways/api-gateway/install-k8s) for details.
1. If your Kubernetes-orchestrated network runs on OpenShift, verify that OpenShift is enabled for your Consul installation. Refer to [OpenShift requirements](/consul/docs/connect/gateways/api-gateway/tech-specs#openshift-requirements) for additional information.
## Define the gateway and listeners
Create an API gateway values file that defines the gateway and listeners.
1. Specify the following fields:
- `apiVersion`: Specifies the Kubernetes gateway API version. Must be `gateway.networking.k8s.io/v1beta1`.
- `kind`: Specifies the type of configuration entry to implement. This must be `Gateway`.
- `metadata.name`: Specify a name for the gateway configuration. The name is metadata that you can use to reference the configuration when performing Consul operations.
- `spec.gatewayClassName`: Specify the name of a `gatewayClass` configuration. Gateway classes are template-like resources in Kubernetes for instantiating gateway services. Specify `consul` to use the default gateway class shipped with Consul. Refer to the [GatewayClass configuration reference](/consul/docs/connect/gateways/api-gateway/configuration/gatewayclass) for additional information.
- `spec.listeners`: Specify a list of listener configurations. Each listener is map containing the following fields:
- `port`: Specifies the port that the listener receives traffic on.
- `name`: Specifies a unique name for the listener.
- `protocol`: You can set either `tcp` or `http`
- `allowedRoutes.namespaces`: Contains configurations for determining which namespaces are allowed to attach a route to the listener.
1. Configure any additional fields necessary for your use case, such as the namespace or admin partition. Refer to the [API gateway configuration entry reference](/consul/docs/connect/gateways/api-gateway/configuration/gateway) for additional information.
1. Save the configuration.
In the following example, the API gateway specifies an HTTP listener on port `80`:
```yaml
apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
name: my-gateway
namespace: consul
spec:
gatewayClassName: consul
listeners:
- protocol: HTTP
port: 80
name: http
allowedRoutes:
namespaces:
from: "All"
```
## Deploy the API gateway and listeners
Apply the configuration to your cluster using the `kubectl` command. The following command applies the configuration to the `consul` namespace:
```shell-session
$ kubectl apply -f my-gateway.yaml -n consul
```

113
website/content/docs/connect/gateways/api-gateway/deploy/listeners-vms.mdx Normal file
View File

@ -0,0 +1,113 @@
---
layout: docs
page_title: Deploy API gateway listeners to virtual machines
description: Learn how to configure and Consul API gateways and gateway listeners on virtual machines so that you can enable ingress requests to services in your service mesh in VM environments.
---
# Deploy API gateway listeners to virtual machines
This topic describes how to deploy Consul API gateway listeners to networks that operate in virtual machine (VM) environments. If you want to implement API gateway listeners in a Kubernetes environment, refer to [Deploy API gateway listeners to Kubernetes](/consul/docs/connect/gateways/api-gateway/deploy/listeners-k8s).
## Overview
API gateways have one or more listeners that serve as ingress points for requests to services in a Consul service mesh. Create an [API gateway configuration entry](/consul/docs/connect/config-entries/api-gateway) and define listeners that expose ports on the endpoint for ingress.
The following steps describe the general workflow for deploying a Consul API gateway to a VM environment:
1. Create an API gateway configuration entry. The configuration entry includes listener configurations and references to TLS certificates.
1. Deploy the API gateway configuration entry to create the listeners.
### Encryption
To encrypt traffic between the external client and the service that the API gateway routes traffic to, define an inline certificate configuration and attach it to your listeners. Refer to [Encrypt API gateway traffic on virtual machines](/consul/docs/connect/gateways/api-gateway/secure-traffic/encrypt-vms) for additional information.
### Routes
After deploying the gateway, attach [HTTP](/consul/docs/connect/config-entries/http-route) routes and [TCP](/consul/docs/connect/config-entries/tcp-route) routes to listeners defined in the gateway to control how requests route to services in the network. Refer to [Define API gateway routes on VMs](/consul/docs/connect/gateways/api-gateway/define-routes/routes-vms) for additional information.
## Requirements
The following requirements must be satisfied to use API gateways on VMs:
- Consul 1.15 or later
- A Consul cluster with service mesh enabled. Refer to [`connect`](/consul/docs/agent/config/config-files#connect)
- Network connectivity between the machine deploying the API Gateway and a
Consul cluster agent or server
### ACL requirements
If ACLs are enabled, you must present a token with the following permissions to
configure Consul and deploy API gateways:
- `mesh: read`
- `mesh: write`
Refer to [Mesh Rules](/consul/docs/security/acl/acl-rules#mesh-rules) for
additional information about configuring policies that enable you to interact
with Consul API gateway configurations.
## Define the gateway and listeners
Create an API gateway configuration entry that defines listeners and TLS certificates
in the mesh.
1. Specify the following fields:
- `Kind`: Specifies the type of configuration entry to implement. This must be `api-gateway`.
- `Name`: Specify a name for the gateway configuration. The name is metadata that you can use to reference the configuration entry when performing Consul operations.
- `Listeners`: Specify a list of listener configurations. Each listener is map containing the following fields:
- `Port`: Specifies the port that the listener receives traffic on.
- `Name`: Specifies a unique name for the listener.
- `Protocol`: You can set either `tcp` or `http`
- `TLS`: Defines TLS encryption configurations for the listener.
Refer to the [API gateway configuration entry reference](/consul/docs/connect/config-entries/api-gateway) for details on how to define fields in the `Listeners` block.
1. Configure any additional fields necessary for your use case, such as the namespace or admin partition. Refer to the [API gateway configuration entry reference](/consul/docs/connect/config-entries/api-gateway) for additional information.
1. Save the configuration.
In the following example, the API gateway specifies an HTTP listener on port `8443`. It also requires an inline-certificate configuration entry named `my-certificate` that contains a valid certificate and private key pair:
```hcl
Kind = "api-gateway"
Name = "my-gateway"
// Each listener configures a port which can be used to access the Consul cluster
Listeners = [
{
Port = 8443
Name = "my-http-listener"
Protocol = "http"
TLS = {
Certificates = [
{
Kind = "inline-certificate"
Name = "my-certificate"
}
]
}
}
]
```
Refer to [API Gateway Configuration Reference](/consul/docs/connect/gateways/api-gateway/configuration/api-gateway) for
information about all configuration fields.
Gateways and routes are eventually-consistent objects that provide feedback
about their current state through a series of status conditions. As a result,
you must manually check the route status to determine if the route
bound to the gateway successfully.
## Deploy the API gateway and listeners
Use the `consul config write` command to implement the API gateway configuration entry. The following command applies the configuration entry for the main gateway object:
```shell-session
$ consul config write gateways.hcl
```
Run the following command to deploy an API gateway instance:
```shell-session
$ consul connect envoy -gateway api -register -service my-api-gateway
```
The command directs Consul to configure Envoy as an API gateway. Gateways and routes are eventually-consistent objects that provide feedback about their current state through a series of status conditions. As a result, you must manually check the route status to determine if the route successfully bound to the gateway successfully.

2
website/content/docs/api-gateway/usage/errors.mdx → website/content/docs/connect/gateways/api-gateway/errors.mdx
View File

@ -57,7 +57,7 @@ Consul API Gateway generates this error when the required CRD files have not bee
The installation process typically fails after this error message is generated.
**Resolution:**
Install the required CRDs. Refer to the [Consul API Gateway installation instructions](/consul/docs/api-gateway/install#installation) for instructions.
Install the required CRDs. Refer to the [Consul API Gateway installation instructions](/consul/docs/connect/gateways/api-gateway/deploy/install-k8s) for instructions.
## Operation cannot be fulfilled, the object has been modified

71
website/content/docs/connect/gateways/api-gateway/index.mdx
View File

@ -1,28 +1,61 @@
---
layout: docs
page_title: API Gateways Overview
description: API gateways are objects in Consul that enable ingress requests to services in your service mesh. Learn about API gateways for VMs in this overview.
page_title: API gateways overview
description: API gateways provide an ingress point for service mesh traffic. Learn how API gateways add listeners for external traffic and route HTTP requests to services in the mesh.
---
# API gateway overview
# API gateways overview
API gateways enable external network clients to access applications and services
running in a Consul datacenter. This type of network traffic is commonly
called _north-south_ network traffic because it refers to the flow of
data into and out of a specific environment. API gateways can also forward
requests from clients to specific destinations based on path or request
protocol.
This topic provides overview information about API gateways in Consul. API gateways enable external network clients to access applications and services running in a Consul datacenter. Consul API gateways can also forward requests from clients to specific destinations based on path or request protocol.
## API gateway use cases
API gateways solve the following primary use cases:
- **Control access at the point of entry**: Set the protocols of external connection
requests and secure inbound connections with TLS certificates from trusted
providers, such as Verisign and Let's Encrypt.
- **Simplify traffic management**: Load balance requests across services and route
traffic to the appropriate service by matching one or more criteria, such as
hostname, path, header presence or value, and HTTP method.
- **Control access at the point of entry**: Set the protocols of external connection requests and secure inbound connections with TLS certificates from trusted providers, such as Verisign and Let's Encrypt.
- **Simplify traffic management**: Load balance requests across services and route traffic to the appropriate service by matching one or more criteria, such as hostname, path, header presence or value, and HTTP method.
Consul supports API
gateways for virtual machines and Kubernetes networks. Refer to the following documentation for next steps:
- [API Gateways on VMs](/consul/docs/connect/gateways/api-gateway/usage)
- [API Gateways for Kubernetes](/consul/docs/api-gateway).
## Workflows
You can deploy API gateways to networks that implement a variety of computing environments:
- Services hosted on VMs
- Kubernetes-orchestrated service containers
- Kubernetes-orchestrated service containers in OpenShift
The following steps describe the general workflow for deploying a Consul API gateways:
1. For Kubernetes-orchestrated services, install Consul on your cluster. For Kubernetes-orchestrated services on OpenShift, you must also enable the `openShift.enabled` parameter. Refer to [Install Consul on Kubernetes](/consul/docs/connect/gateways/api-gateway/install-k8s) for additional information.
1. Define and deploy the API gateway configurations to create the API gateway artifacts. For VM-hosted services, create configuration entries for the gateway service, listeners configurations, and references to TLS certificates. For Kubernetes-orchestrated, configurations also include `GatewayClassConfig`s and `parametersRef`s.
1. Define and deploy routes between the gateway listeners and services in the mesh.
Gateway configurations are modular, so you can define and attach routes and inline certificates to multiple gateways.
## Technical specifications
Refer to [Technical specifications for API gateways on Kubernetes](/consul/docs/connect/gateways/api-gateway/tech-specs) for additional details and considerations about using API gateways in Kubernetes-orchestrated networks.
## Guidance
Refer to the following resources for help setting up and using API gateways:
### Tutorials
- [Control access into the service mesh with Consul API gateway](/consul/tutorials/developer-mesh/kubernetes-api-gateway)
### Usage documentation
- [Deploy API gateway listeners to VMs](/consul/docs/connect/gateways/api-gateway/deploy/listeners-vms)
- [Deploy API gateway listeners to Kubernetes](/consul/docs/connect/gateways/api-gateway/deploy/listeners-k8s)
- [Deploy API gateway routes to VMs](/consul/docs/connect/gateways/api-gateway/define-routes/routes-vms)
- [Deploy API gateway routes to Kubernetes](/consul/docs/connect/gateways/api-gateway/define-routes/routes-k8s)
- [Reroute HTTP requests in Kubernetes](/consul/docs/connect/gateways/api-gateway/define-routes/reroute-http-requests)
- [Route traffic to peered services in Kubernetes](/consul/docs/connect/gateways/api-gateway/define-routes/route-to-peered-services)
- [Encrypt API gateway traffic on VMs](/consul/docs/connect/gateways/api-gateway/secure-traffic/encrypt-vms)
- [Use JWTs to verify requests to API gateways on VMs](/consul/docs/connect/gateways/api-gateway/secure-traffic/jwts-vms)
- [Use JWTs to verify requests to API gateways on Kubernetes](/consul/docs/connect/gateways/api-gateway/secure-traffic/jwts-k8s)
### Reference
- [API gateway configuration reference overview](/consul/docs/connect/gateways/api-gateway/configuration/)
- [Error messages](/consul/docs/connect/gateways/api-gateway/errors)

16
website/content/docs/api-gateway/install.mdx → website/content/docs/connect/gateways/api-gateway/install-k8s.mdx
View File

@ -7,7 +7,7 @@ description: >-
# Install API gateway for Kubernetes
The Consul API gateway ships with Consul and is automatically installed when you install Consul on Kubernetes. Before you begin the installation process, verify that the environment you are deploying Consul and the API gateway in meets the requirements listed in the [Technical Specifications](/consul/docs/api-gateway/tech-specs). Refer to the [Release Notes](/consul/docs/release-notes) for any additional information about the version you are deploying.
The Consul API gateway ships with Consul and is automatically installed when you install Consul on Kubernetes. Before you begin the installation process, verify that the environment you are deploying Consul and the API gateway in meets the requirements listed in the [Technical Specifications](/consul/docs/connect/gateways/api-gateway/tech-specs). Refer to the [Release Notes](/consul/docs/release-notes) for any additional information about the version you are deploying.
1. Create a `values.yaml` file for configuring your Consul API gateway deployment and include the following settings:
@ -26,6 +26,20 @@ The Consul API gateway ships with Consul and is automatically installed when you
The Consul Helm chart deploys the API gateway using the configuration specified in the `values.yaml` file. Refer to [Helm Chart Configuration - `connectInject.apiGateway`](/consul/docs/k8s/helm#apigateway) for information about the Helm chart configuration options.
1. If you are installing Consul on an OpenShift Kubernetes cluster, you must include the `global.openShift.enabled` parameter and set it to `true`:
<CodeBlockConfig filename="values.yaml">
```yaml
global:
openshift:
enabled: true
```
</CodeBlockConfig>
Refer to [OpenShift requirements](/consul/docs/connect/gateways/api-gateway/tech-specs#openshift-requirements) for additional information.
1. Install Consul API Gateway using the standard Consul Helm chart or Consul K8s CLI specify the custom values file. Refer to the [Consul Helm chart](https://github.com/hashicorp/consul-k8s/releases) in GitHub releases for the available versions.
<Tabs>

66
website/content/docs/connect/gateways/api-gateway/secure-traffic/encrypt-vms.mdx Normal file
View File

@ -0,0 +1,66 @@
---
layout: docs
page_title: Encrypt API gateway traffic on virtual machines
description: Learn how to define inline certificate config entries and deploy them to Consul. Inline certificate configuration entries enable you to attach TLS certificates and keys to gateway listeners so that traffic between external clients and gateway listeners is encrypted.
---
# Encrypt API gateway traffic on virtual machines
This topic describes how to make TLS certificates available to API gateways so that requests between the user and the gateway endpoint are encrypted.
## Requirements
- Consul 1.15 or later
- You must have a certificate and key from your CA
- A Consul cluster with service mesh enabled. Refer to [`connect`](/consul/docs/agent/config/config-files#connect)
- Network connectivity between the machine deploying the API gateway and a
Consul cluster agent or server
### ACL requirements
If ACLs are enabled, you must present a token with the following permissions to
configure Consul and deploy API gateways:
- `mesh: read`
- `mesh: write`
Refer [Mesh Rules](/consul/docs/security/acl/acl-rules#mesh-rules) for
additional information about configuring policies that enable you to interact
with Consul API gateway configurations.
## Define TLS certificates
1. Create an [`inline-certificate` configuration entry](/consul/docs/connect/gateways/api-gateway/configuration/inline-certificate) and specify the following fields:
- `Kind`: Specifies the type of configuration entry. This must be set to `inline-certificate`.
- `Name`: Specify the name in the [API gateway listener configuration](/consul/docs/connect/gateways/api-gateway/configuration/api-gateway#listeners) to bind the certificate to that listener.
- `Certificate`: Specifies the inline public certificate to use for TLS as plain text.
- `PrivateKey`: Specifies the inline private key to use for TLS as plain text.
1. Configure any additional fields necessary for your use case, such as the namespace or admin partition. Refer to the [`inline-certificate` configuration entry](/consul/docs/connect/gateways/api-gateway/configuration/inline-certificate) reference for additional information.
1. Save the configuration.
The following example defines a certificate named `my-certificate`. API gateway configurations that specify `inline-certificate` in the `Certificate.Kind` field and `my-certificate` in the `Certificate.Name` field are able to use the certificate.
```hcl
Kind = "inline-certificate"
Name = "my-certificate"
Certificate = <<EOF
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
EOF
PrivateKey = <<EOF
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----
EOF
```
## Deploy the configuration to Consul
Run the `consul config write` command to enable listeners to use the certificate. The following example writes a configuration called `my-certificate.hcl`:
```shell-session
$ consul config write my-certificate.hcl
```

72
website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx Normal file
View File

@ -0,0 +1,72 @@
---
layout: docs
page_title: Use JWTs to verify requests to API gateways on Kubernetes
description: Learn how to use JSON web tokens (JWT) to verify requests from external clients to listeners on an API gateway on Kubernetes-orchestrated networks.
---
# Use JWTs to verify requests to API gateways on Kubernetes
This topic describes how to use JSON web tokens (JWT) to verify requests to API gateways deployed to Kubernetes-orchestrated containers. If your API gateway is deployed to virtual machines, refer to [Use JWTs to verify requests to API gateways on VMs](/consu/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-vms).
## Overview
You can configure API gateways to use JWTs to verify incoming requests so that you can stop unverified traffic at the gateway. You can configure JWT verification at different levels:
- Listener defaults: Define basic defaults that apply to all routes attached to a listener.
- HTTP route-specific settings: You can define JWT authentication settings for specific HTTP routes. Route-specific JWT settings override default listener configurations.
- Listener overrides: Define override settings that take precedence over default and route-specific configurations. This enables you to set enforceable policies for listeners.
Complete the following steps to use JWTs to verify requests:
1. Define a policy that specifies default and override settings for API gateway listeners and attach it to the gateway.
1. Define an HTTP route auth filter that specifies route-specific JWT verification settings.
1. Attach the auth filter to the HTTP route values file.
1. Apply the configurations.
## Requirements
- Consul v1.17+
- Consul on Kubernetes CLI or Helm chart v1.3.0+
- JWT details, such as claims and provider
## Define override and default settings
Create a `GatewayPolicy` values file and configure the following fields to define default and override settings for JWT verification. Refer to [`GatewayPolicy` configuration reference](/consul/docs/connect/gateways/api-gateway/configuration/gatewaypolicy) for details.
- `kind`: Must be set to `GatewayPolicy`
- `metadata.name`: Specifies a name for the policy.
- `spec.targetRef.name`: Specifies the name of the API gateway to attach the policy to.
- `spec.targetRef.kind`: Specifies the kind of resource to attach to the policy to. Must be set to `Gateway`.
- `spec.targetRef.group`: Specifies the resource group. Unless you have created a custom group, this should be set to `gateway.networking.kuberenetes.io`.
- `spec.targetRef.sectionName`: Specifies a part of the gateway that the policy applies to.
- `spec.targetRef.override.jwt.providers`: Specifies a list of providers and claims used to verify requests to the gateway. The override settings take precedence over the default and route-specific JWT verification settings.
- `spec.targetRef.default.jwt.providers`: Specifies a list of default providers and claims used to verify requests to the gateway.
## Define an HTTP route auth filter
Create an `RouteAuthFilter` values file and configure the following fields. Refer to [`RouteAuthFilter` configuration reference](/consul/docs/connect/gateways/api-gateway/configuration/routeauthfilter) for details.
- `kind`: Must be set to `HTTRouteAuthFilter`
- `metadata.name`: Specifies a name for the filter.
- `metadata.namespace`: Specifies the Consul namespace the filter applies to.
- `spec.jwt.providers`: Specifies a list of providers and claims used to verify requests to the gateway. The override settings take precedence over the default and route-specific JWT verification settings.
## Attach the auth filter to your HTTP routes
In the `filters` field of your HTTP route configuration, add the following fields. Refer to the [`extensionRef` configuration reference](/consul/docs/connect/gateways/api-gateway/configuration/routes#rules-filters-extensionref) for details:
- `type: extensionRef`: Declare list of extension references.
- `extensionRef.group`: Specifies the resource group. Unless you have created a custom group, this should be set to `gateway.networking.kuberenetes.io`.
- `extensionRef.kind`: Specifies the type of extension reference to attach to the route. Must be `RouteAuthFilter`
- `extensionRef.name`: Specifies the name of the auth filter.
## Apply the configurations
Run the `kubectl apply` command and specify the values files to apply the configurations. The following example applies the values files stored in the `jwt-routes` directory:
```shell-session
$ kubectl apply -f jwt-routes
```

43
website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-vms.mdx Normal file
View File

@ -0,0 +1,43 @@
---
layout: docs
page_title: Use JWTs to verify requests to API gateways on virtual machines
description: Learn how to use JSON web tokens (JWT) to verify requests from external clients to listeners on an API gateway.
---
# Use JWTs to verify requests to API gateways on virtual machines
This topic describes how to use JSON web tokens (JWT) to verify requests to API gateways on virtual machines (VM). If your services are deployed to Kubernetes-orchestrated containers, refer to [Use JWTs to verify requests to API gateways on Kubernetes](/consul/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-vms).
## Overview
You can configure API gateways to use JWTs to verify incoming requests so that you can stop unverified traffic at the gateway. You can configure JWT verification at different levels:
- Listener defaults: Define basic defaults that apply to all routes attached to a listener.
- HTTP route-specific settings: You can define JWT authentication settings for specific HTTP routes. Route-specific JWT settings override default configurations.
- Listener overrides: Define override settings that take precedence over default and route-specific configurations. This enables you to set enforceable policies for listeners.
Complete the following steps to use JWTs to verify requests:
1. Configure default and override settings for listeners in the API gateway configuration entry.
1. Define route-specific JWT verification settings as filters in the HTTP route configuration entries.
1. Write the configuration entries to Consul to begin verifying requests using JWTs.
## Requirements
- Consul 1.17 or later
- JWT details, such as claims and provider
## Configure default and override settings
Define default and override settings for JWT verification in the [API gateway configuration entry](/consul/docs/connect/gateways/api-gateway/configuration/api-gateway).
1. Add a `default.JWT` block to the listener that you want to apply JWT verification to. Consul applies these configurations to routes attached to the listener. Refer to the [`Listeners.default.JWT`](/consul/docs/connect/config-entries/api-gateway#listeners-default-jwt) configuration reference for details.
1. Add an `override.JWT` block to the listener that you want to apply JWT verification policies to. Consul applies these configurations to all routes attached to the listener, regardless of the `default` or route-specific settings. Refer to the [`Listeners.override.JWT`](/consul/docs/connect/config-entries/api-gateway#listeners-override-jwt) configuration reference for details.
1. Apply the settings in the API gateway configuration entry. You can use the [`/config` API endpoint](/consul/api-docs/config#apply-configuration) or the [`consul config write` command](/consul/commands/config/write).
## Configure verification for specific HTTP routes
Define filters to enable route-specific JWT verification settings in the [HTTP route configuration entry](/consul/docs/connect/config-entries/http-route).
1. Add a `JWT` configuration to the `rules.filter` block. Route-specific configurations that overlap the [default settings ](/consul/docs/connect/config-entries/api-gateway#listeners-default-jwt) in the API gateway configuration entry take precedence. Configurations defined in the [listener override settings](/consul/docs/connect/config-entries/api-gateway#listeners-override-jwt) take the highest precedence.
1. Apply the settings in the API gateway configuration entry. You can use the [`/config` API endpoint](/consul/api-docs/config#apply-configuration) or the [`consul config write` command](/consul/commands/config/write).

157
website/content/docs/connect/gateways/api-gateway/tech-specs.mdx Normal file
View File

@ -0,0 +1,157 @@
---
layout: docs
page_title: API gateway for Kubernetes technical specifications
description: >-
Learn about the requirements for installing and using the Consul API gateway for Kubernetes, including required ports, component version minimums, Consul Enterprise limitations, and compatible k8s cloud environments.
---
# API gateway for Kubernetes technical specifications
This topic describes the requirements and technical specifications associated with using Consul API gateway.
## Datacenter requirements
Your datacenter must meet the following requirements prior to configuring the Consul API gateway:
- HashiCorp Consul Helm chart v1.2.0 and later
## TCP port requirements
The following table describes the TCP port requirements for each component of the API gateway.
| Port | Description | Component |
| ---- | ----------- | --------- |
| 20000 | Kubernetes readiness probe | Gateway instance pod |
| Configurable | Port for scraping Prometheus metrics. Disabled by default. | Gateway controller pod |
## OpenShift requirements
You can deploy API gateways to Kubernetes clusters managed by Red Hat OpenShift, which is a security-conscious, opinionated wrapper for Kubernetes. To enable OpenShift support, add the following parameters to your Consul values file and apply the configuration:
```yaml
openshift:
enabled: true
```
Refer to the following topics for additional information:
- [Install Consul on OpenShift clusters with Helm](/consul/docs/k8s/installation/install#install-consul-on-openshift-clusters)
- [Install Consul on OpenShift clusters with the `consul-k8s` CLI](/consul/docs/k8s/installation/install-cli#install-consul-on-openshift-clusters)
### Security context constraints
OpenShift requires a security context constraint (SCC) configuration, which restricts pods to specific groups. You can create a custom SCC or use one of the default constraints. Refer to the [OpenShift documentation](https://docs.openshift.com/container-platform/4.13/authentication/managing-security-context-constraints.html) for additional information.
By default, the SCC is set to `restricted-v2` for the `managedGatewayClass` that Consul automatically creates. The `restricted-v2` SCC is one of OpenShifts default SCCs, but you can specify a different SCC in the `openshiftSCCName` parameter:
```yaml
connectInject:
apiGateway:
managedGatewayClass:
openshiftSCCName: "restricted-v2"
```
### Privileged container ports
Containers cannot use privileged ports when OpenShift is enabled. Privileged ports are 1 through 1024, and serving applications from that range is a security risk.
To allow gateway listeners to use privileged port numbers, specify an integer value in the `mapPrivilegedContainerPorts` field of your Consul values configuration. Consul adds the value to listener port numbers that are set to a number in the privileged container range. Consul maps the configured port number to the total port number so that traffic sent to the configured port number is correctly forwarded to the service.
For example, if a gateway listener is configured to port `80` and the `mapPrivilegedContainerPorts` field is configured to `2000`, then the actual port number on the underlying container is `2080`.
You can set the `mapPrivilegedContainerPorts` parameter in the following map in your Consul values file:
```yaml
connectInject:
apiGateway:
managedGatewayClass:
mapPrivilegedContainerPorts: <value>
```
## Supported versions of the Kubernetes gateway API specification
Refer to the [release notes](/consul/docs/release-notes) for your version of Consul.
## Supported Kubernetes gateway specification features
Consul API gateways for Kuberentes support a subset of the Kubernetes Gateway API specification. For a complete list of features, including the list of gateway and route statuses and an explanation on how they
are used, refer to the [documentation in our GitHub repo](https://github.com/hashicorp/consul-api-gateway/blob/main/dev/docs/supported-features.md):
### `GatewayClass`
The `GatewayClass` resource describes a class of gateway configurations to use a template for creating `Gateway` resources. You can also specify custom API gateway configurations in a `GatewayClassConfig` CRD and attach them to resource to the `GatewayClass` using the `parametersRef` field.
You must specify the `"hashicorp.com/consul-api-gateway-controller"` controller so that Consul can manage gateways generated by the `GatewayClass`. Refer to the [Kubernetes `GatewayClass` documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayClass) for additional information.
### `Gateway`
The `Gateway` resource is the core API gateway component. Gateways have one or more listeners that can route `HTTP`, `HTTPS`, or `TCP` traffic. You can define header-based hostname matching for listeners, but SNI is not supported.
You can apply filters to add, remove, and set header values on incoming requests. Gateways support the `terminate` TLS mode and `core/v1/Secret` TLS certificates. Extended option support includes TLS version and cipher constraints. Refer to the [Kubernetes `Gateway` documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Gateway) for additional information.
### `HTTPRoute`
`HTTPRoute` configurations determine HTTP paths between listeners defined on the gateway and services in the mesh. You can specify weights to load balance traffic, as well as define rules for matching request paths, headers, queries, and methods to ensure that traffic is routed appropriately. You can apply filters to add, remove, and set header values on requests sent through th route.
Routes support the following backend types:
- `core/v1/Service` backend types when the route maps to service registered with Consul.
- `api-gateway.consul.hashicorp.com/v1alpha1/MeshService`.
Refer to [Kubernetes `HTTPRoute` documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRoute) for additional information.
### `TCPRoute`
`TCPRoute` configurations determine TCP paths between listeners defined on the gateway and services in the mesh. Routes support the following backend types:
- `core/v1/Service` backend types when the route maps to service registered with Consul.
- `api-gateway.consul.hashicorp.com/v1alpha1/MeshService`.
Refer to [Kubernetes `TCPRoute` documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.TCPRoute) for additional information.
### `ReferenceGrant`
`ReferenceGrant` resources allow resources to reference resources in other namespaces. They are required to allow references from a `Gateway` to a Kubernetes `core/v1/Secret` in a different namespace. Without a `ReferenceGrant`, `backendRefs` attached to the gateway may not be permitted. As a result, the `ReferenceGrant` sets a `ResolvedRefs` status to `False` with the reason `InvalidCertificateRef`, which prevents the gateway from becoming ready.
`ReferenceGrant` resources are also required for references from an `HTTPRoute` or `TCPRoute` to a Kubernetes `core/v1/Service` in a different namespace. Without a `ReferenceGrant`, `backendRefs` attached to the route may not be permitted. As a result, Kubernetes sets a `ResolvedRefs` status to `False` with the reason `RefNotPermitted`, which causes the gateway listener to reject the route.
If a route `backendRefs` becomes unpermitted, the entire route is removed from the gateway listener. A `backendRefs` can become unpermitted when you delete a `ReferenceGrant` or add a new unpermitted `backendRefs` to an existing route.
Refer to the [Kubernetes `ReferenceGrant` documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferenceGrant) for additional information.
## Consul server deployments
- Consul Enterprise and the free community edition are both supported.
- Supported Consul Server deployment types:
- Self-Managed
- HCP Consul
### Consul feature support
API gateways on Kubernetes support all Consul features, but you can only route traffic between multiple datacenters through peered connections. Refer to [Route Traffic to Peered Services](/consul/docs/connect/gateways/api-gateway/define-routes/route-to-peered-services) for additional information. WAN federation is not supported.
## Deployment Environments
Consul API gateway can be deployed in the following Kubernetes-based environments:
- Standard Kubernetes environments
- AWS Elastic Kubernetes Service (EKS)
- Google Kubernetes Engine (GKE)
- Azure Kubernetes Service (AKS)
## Resource allocations
The following resources are allocated for each component of the API gateway.
### Gateway controller pod
- **CPU**: None. Either the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration.
- **Memory**: None. Either the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration.
### Gateway instance pod
- **CPU**: None. Either the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration.
- **Memory**: None. Either the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration.

8
website/content/docs/api-gateway/upgrades.mdx → website/content/docs/connect/gateways/api-gateway/upgrades-k8s.mdx
View File

@ -5,9 +5,9 @@ description: >-
Upgrade Consul API Gateway to use newly supported features. Learn about the requirements, procedures, and post-configuration changes involved in standard and specific version upgrades.
---
# Upgrade Consul API gateway for Kubernetes
# Upgrade API gateway for Kubernetes
Since Consul v1.15, the Consul API gateway is a native feature within the Consul binary and is installed during the normal Consul installation process. Since Consul on Kubernetes v1.2 (Consul v1.16), the CRDs necessary for using the Consul API gateway for Kubernetes are also included. You can install Consul v1.16 using the Consul Helm chart v1.2 and later. Refer to [Install API gateway for Kubernetes](/consul/docs/api-gateway/install) for additional information.
Since Consul v1.15, the Consul API gateway is a native feature within the Consul binary and is installed during the normal Consul installation process. Since Consul on Kubernetes v1.2 (Consul v1.16), the CRDs necessary for using the Consul API gateway for Kubernetes are also included. You can install Consul v1.16 using the Consul Helm chart v1.2 and later. Refer to [Install API gateway for Kubernetes](/consul/docs/connect/gateways/api-gateway/deploy/install-k8s) for additional information.
## Introduction
@ -67,7 +67,7 @@ If you are able to tolerate downtime for your applications, you should delete pr
1. Create `ServiceIntentions` allowing `Gateways` to communicate with any backend services that they route to. Refer to [Service intentions configuration entry reference](/consul/docs/connect/config-entries/service-intentions) for additional information.
1. Change any existing `Gateways` to reference the new `GatewayClass` `consul`. Refer to [gatewayClass](/consul/docs/api-gateway/configuration/gateway#gatewayclassname) for additional information.
1. Change any existing `Gateways` to reference the new `GatewayClass` `consul`. Refer to [gatewayClass](/consul/docs/connect/gateways/api-gateway/configuration/gateway#gatewayclassname) for additional information.
1. After updating all of your `gateway` configurations to use the new controller, you can remove the `apiGateway` block from the Helm chart and upgrade your Consul cluster. This completely removes the old gateway controller.
@ -130,7 +130,7 @@ If you are unable to tolerate any downtime, you can complete the following steps
1. Create `ServiceIntentions` allowing `Gateways` to communicate with any backend services that they route to. Refer to [Service intentions configuration entry reference](/consul/docs/connect/config-entries/service-intentions) for additional information.
1. Change any existing `Gateways` to reference the new `GatewayClass` `consul`. Refer to [gatewayClass](/consul/docs/api-gateway/configuration/gateway#gatewayclassname) for additional information.
1. Change any existing `Gateways` to reference the new `GatewayClass` `consul`. Refer to [gatewayClass](/consul/docs/connect/gateways/api-gateway/configuration/gateway#gatewayclassname) for additional information.
1. After updating all of your `gateway` configurations to use the new controller, you can remove the `apiGateway` block from the Helm chart and upgrade your Consul cluster. This completely removes the old gateway controller.

211
website/content/docs/connect/gateways/api-gateway/usage.mdx
View File

@ -1,211 +0,0 @@
---
layout: docs
page_title: API Gateways on Virtual Machines
description: Learn how to configure and Consul API gateways and gateway routes on virtual machines so that you can enable ingress requests to services in your service mesh in VM environments.
---
# API gateways on virtual machines
This topic describes how to deploy Consul API gateways to networks that operate
in virtual machine (VM) environments. If you want to implement an API gateway
in a Kubernetes environment, refer to [API Gateway for Kubernetes](/consul/docs/api-gateway).
## Introduction
Consul API gateways provide a configurable ingress points for requests into a Consul network. Use the following configuration entries to set up API gateways:
- [API gateway](/consul/docs/connect/gateways/api-gateway/configuration/api-gateway): Provides an endpoint for requests to enter the network. Define listeners that expose ports on the endpoint for ingress.
- [HTTP routes](/consul/docs/connect/gateways/api-gateway/configuration/http-route) and [TCP routes](/consul/docs/connect/gateways/api-gateway/configuration/tcp-route): The routes attach to listeners defined in the gateway and control how requests route to services in the network.
- [Inline certificates](/consul/docs/connect/gateways/api-gateway/configuration/inline-certificate): Makes TLS certificates available to gateways so that requests between the user and the gateway endpoint are encrypted.
You can configure and reuse configuration entries separately. You can define and attach routes and inline certificates to multiple gateways.
The following steps describe the general workflow for deploying a Consul API
gateway to a VM environment:
1. Create an API gateway configuration entry. The configuration entry includes
listener configurations and references to TLS certificates.
1. Deploy the API gateway configuration entry to create the listeners.
1. Create and deploy routes to bind to the gateway.
Refer to [API Gateway for Kubernetes](/consul/docs/api-gateway) for information
about using Consul API gateway on Kubernetes.
## Requirements
The following requirements must be satisfied to use API gateways on VMs:
- Consul 1.15 or later
- A Consul cluster with service mesh enabled. Refer to [`connect`](/consul/docs/agent/config/config-files#connect)
- Network connectivity between the machine deploying the API Gateway and a
Consul cluster agent or server
If ACLs are enabled, you must present a token with the following permissions to
configure Consul and deploy API gateways:
- `mesh: read`
- `mesh: write`
Refer [Mesh Rules](/consul/docs/security/acl/acl-rules#mesh-rules) for
additional information about configuring policies that enable you to interact
with Consul API gateway configurations.
## Create the API gateway configuration
Create an API gateway configuration that defines listeners and TLS certificates
in the mesh. In the following example, the API gateway specifies an HTTP
listener on port `8443` that routes can use to connect external traffic to
services in the mesh.
```hcl
Kind = "api-gateway"
Name = "my-gateway"
// Each listener configures a port which can be used to access the Consul cluster
Listeners = [
{
Port = 8443
Name = "my-http-listener"
Protocol = "http"
TLS = {
Certificates = [
{
Kind = "inline-certificate"
Name = "my-certificate"
}
]
}
}
]
```
Refer to [API Gateway Configuration Reference](/consul/docs/connect/gateways/api-gateway/configuration/api-gateway) for
information about all configuration fields.
Gateways and routes are eventually-consistent objects that provide feedback
about their current state through a series of status conditions. As a result,
you must manually check the route status to determine if the route
bound to the gateway successfully.
## Deploy the API gateway
Use the `consul config write` command to implement the API gateway
configuration entries. The following command applies the configuration entry
for the main gateway object:
```shell-session
$ consul config write gateways.hcl
```
Run the following command to deploy an API gateway instance:
```shell-session
$ consul connect envoy -gateway api -register -service my-api-gateway
```
The command directs Consul to configure Envoy as an API gateway.
## Route requests
Define route configurations and bind them to listeners configured on the
gateway so that Consul can route incoming requests to services in the mesh.
Create HTTP or TCP routes by setting the `Kind` parameter to `http-route` or
`tcp-route` and configuring rules that define request traffic flows.
The following example routes requests from the listener on the API gateway at
port `8443` to services in Consul based on the path of the request. When an
incoming request starts at path `/`, Consul forwards 90 percent of the requests
to the `ui` service and 10 percent to `experimental-ui`. Consul also forwards
requests starting with `/api` to `api`.
```hcl
Kind = "http-route"
Name = "my-http-route"
// Rules define how requests will be routed
Rules = [
// Send all requests to UI services with 10% going to the "experimental" UI
{
Matches = [
{
Path = {
Match = "prefix"
Value = "/"
}
}
]
Services = [
{
Name = "ui"
Weight = 90
},
{
Name = "experimental-ui"
Weight = 10
}
]
},
// Send all requests that start with the path `/api` to the API service
{
Matches = [
{
Path = {
Match = "prefix"
Value = "/api"
}
}
]
Services = [
{
Name = "api"
}
]
}
]
Parents = [
{
Kind = "api-gateway"
Name = "my-gateway"
SectionName = "my-http-listener"
}
]
```
Create this configuration by saving it to a file called `my-http-route.hcl` and using the command
```shell-session
$ consul config write my-http-route.hcl
```
Refer to [HTTP Route Configuration Entry Reference](/consul/docs/connect/gateways/api-gateway/configuration/http-route)
and [TCP Route Configuration Entry Reference](/consul/docs/connect/gateways/api-gateway/configuration/tcp-route) for details about route configurations.
## Add a TLS certificate
Define an [`inline-certificate` configuration entry](/consul/docs/connect/gateways/api-gateway/configuration/inline-certificate) with a name matching the name in the [API gateway listener configuration](/consul/docs/connect/gateways/api-gateway/configuration/api-gateway#listeners) to bind the certificate to that listener. The inline certificate configuration entry takes a public certificate and private key in plaintext.
The following example defines a certificate named `my-certificate`. API gateway configurations that specify `inline-certificate` in the `Certificate.Kind` field and `my-certificate` in the `Certificate.Name` field are able to use the certificate.
```hcl
Kind = "inline-certificate"
Name = "my-certificate"
Certificate = <<EOF
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
EOF
PrivateKey = <<EOF
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----
EOF
```
Create this configuration by saving it to a file called `my-certificate.hcl` and using the command
```shell-session
$ consul config write my-certificate.hcl
```

4
website/content/docs/connect/gateways/index.mdx
View File

@ -50,8 +50,8 @@ API gateways solve the following primary use cases:
hostname, path, header presence or value, and HTTP method.
Refer to the following documentation for information on how to configure and deploy API gateways:
- [API Gateways on VMs](/consul/docs/connect/gateways/api-gateway/usage)
- [API Gateways for Kubernetes](/consul/docs/api-gateway).
- [API Gateways on VMs](/consul/docs/connect/gateways/api-gateway/deploy/listeners-vms)
- [API Gateways for Kubernetes](/consul/docs/connect/gateways/api-gateway/deploy/listeners-k8s).
## Ingress Gateways

19
website/content/docs/k8s/installation/install-cli.mdx
View File

@ -247,6 +247,25 @@ You can include the `-auto-approve` option set to `true` to proceed with the ins
The pre-install checks may fail if existing `PersistentVolumeClaims` (PVC) are detected. Refer to the [uninstall instructions](/consul/docs/k8s/operations/uninstall#uninstall-consul) for information about removing PVCs.
## Custom installation
You can create a values file and specify parameters to overwrite the default Helm chart installation. Add the `-f` and specify your values file to implement your configuration, for example:
```shell-session
$ consul-k8s install -f values.yaml
```
### Install Consul on OpenShift clusters
[Red Hat OpenShift](https://www.redhat.com/en/technologies/cloud-computing/openshift) is a security-conscious, opinionated wrapper for Kubernetes. To install Consul on OpenShift-managed Kubernetes, set `global.openshift.enabled=true` in your [custom installation](#custom-installation) values file:
```yaml
global:
openshift:
enabled: true
Refer to [`openshift` in the Helm chart reference](/consul/docs/k8s/helm#v-global-openshift) for additional information.
## Check the Consul cluster status
Issue the `consul-k8s status` command to view the status of the installed Consul cluster.

23
website/content/docs/k8s/installation/install.mdx
View File

@ -104,6 +104,18 @@ NAME: consul
...
```
### Install Consul on OpenShift clusters
[Red Hat OpenShift](https://www.redhat.com/en/technologies/cloud-computing/openshift) is a security-conscious, opinionated wrapper for Kubernetes. To install Consul on OpenShift-managed Kubernetes, set `global.openshift.enabled=true` in your [custom installation](#custom-installation) values file:
```yaml
global:
openshift:
enabled: true
```
Refer to [`openshift` in the Helm chart reference](/consul/docs/k8s/helm#v-global-openshift) for additional information.
### Enable the Consul CNI plugin
By default, Consul injects a `connect-inject-init` init container as part of the Kubernetes pod startup process when Consul is in [transparent proxy mode](/consul/docs/connect/transparent-proxy).
@ -132,7 +144,7 @@ To configure the plugin to be installed, add the following configuration to your
logLevel: info
cniBinDir: "/opt/cni/bin"
cniNetDir: "/etc/cni/net.d"
```
```
</CodeBlockConfig>
</Tab>
@ -151,8 +163,7 @@ To configure the plugin to be installed, add the following configuration to your
logLevel: info
cniBinDir: "/home/kubernetes/bin"
cniNetDir: "/etc/cni/net.d"
```
```
</CodeBlockConfig>
</Tab>
@ -196,7 +207,7 @@ By default, Consul Service Mesh is enabled on almost all namespaces within a Kub
1. specify a `namespaceSelector` that matches a label attached to each namespace where you want to deploy the service mesh. In order to default to enabling service mesh on select namespaces by label, the `connectInject.default` value must be set to `true`.
<CodeBlockConfig filename="values.yaml">
<CodeBlockConfig filename="values.yaml">
```yaml
global:
@ -207,9 +218,9 @@ By default, Consul Service Mesh is enabled on almost all namespaces within a Kub
namespaceSelector: |
matchLabels:
connect-inject : enabled
```
```
</CodeBlockConfig>
</CodeBlockConfig>
1. Label the namespaces where you would like to enable Consul Service Mesh.

2
website/content/docs/release-notes/consul-api-gateway/v0_2_x.mdx
View File

@ -39,7 +39,7 @@ Supported version of the [Gateway API](https://gateway-api.sigs.k8s.io/) spec: `
~> **Note**: If your current deployment has routes and and services that cross namespaces, those routes will not be applied to their gateways until cross namespace reference policies are created for them.
For detailed information on upgrading, including how to create the required reference policies, please refer to the [upgrade details page](/consul/docs/api-gateway/upgrades)
For detailed information on upgrading, including how to create the required reference policies, please refer to the [upgrade details page](/consul/docs/connect/gateways/api-gateway/upgrades-k8s)
## Change logs

2
website/content/docs/release-notes/consul-api-gateway/v0_3_x.mdx
View File

@ -47,7 +47,7 @@ Supported version of the [Gateway API](https://gateway-api.sigs.k8s.io/) spec: `
## Upgrading
For detailed information on upgrading, please refer to the [upgrade details page](/consul/docs/api-gateway/upgrades)
For detailed information on upgrading, please refer to the [upgrade details page](/consul/docs/connect/gateways/api-gateway/upgrades-k8s)
## Changelogs

6
website/content/docs/release-notes/consul-api-gateway/v0_4_x.mdx
View File

@ -31,7 +31,7 @@ description: >-
to rewrite the URL path in a client's HTTP request before sending the request
to a service. For example, you could configure the gateway to change the path
from `//store/checkout` to `//cart/checkout`. Refer to the [usage
documentation](/consul/docs/connect/gateways/api-gateway/usage) for additional information.
documentation](/consul/docs/connect/gateways/api-gateway/define-routes/reroute-http-requests) for additional information.
## What has Changed
@ -41,7 +41,7 @@ description: >-
in a future version of the standard.
After upgrading to this version of Consul API Gateway, you should rename all
existing `ReferencePolicy` to `ReferenceGrant`. Refer to the [Upgrades](/consul/docs/api-gateway/upgrades)
existing `ReferencePolicy` to `ReferenceGrant`. Refer to the [Upgrades](/consul/docs/connect/gateways/api-gateway/upgrades-k8s)
instructions for additional details.
## Supported Software
@ -60,7 +60,7 @@ Supported version of the [Gateway API](https://gateway-api.sigs.k8s.io/) spec: v
## Upgrading
For detailed information on upgrading, please refer to the [Upgrades page](/consul/docs/api-gateway/upgrades)
For detailed information on upgrading, please refer to the [Upgrades page](/consul/docs/connect/gateways/api-gateway/upgrades-k8s)
## Known Issues
The following issues are know to exist in the v0.4.0 release

4
website/content/docs/release-notes/consul-api-gateway/v0_5_x.mdx
View File

@ -13,7 +13,7 @@ We are pleased to announce the following updates to Consul API Gateway.
- **Consul Dataplane Support:** Consul 1.14 introduces a simplified deployment architecture that eliminates the need to deploy node-level Consul clients on Kubernetes. This is referred to as Consul Dataplane. API Gateway 0.5.0 supports this type of deployment.
- **Routing to Services in Peered Clusters:** API Gateway now supports the ability to route traffic to services that are imported from peered Consul clusters. Cluster peering is was added in Consul 1.14. Refer to the `MeshService` [documentation](/consul/docs/api-gateway/configuration/meshservice) for additional information.
- **Routing to Services in Peered Clusters:** API Gateway now supports the ability to route traffic to services that are imported from peered Consul clusters. Cluster peering is was added in Consul 1.14. Refer to the `MeshService` [documentation](/consul/docs/connect/gateways/api-gateway/configuration/meshservice) for additional information.
- **Deploy in Admin Partitions:** API Gateway can now be deployed in any Consul admin partition. Previous versions of API Gateway could only be deployed in the default partition. The partition is configured in the `GatewayClassConfig`.
@ -40,7 +40,7 @@ Supported version of the [Gateway API](https://gateway-api.sigs.k8s.io/) spec: v
## Upgrading
For detailed information on upgrading, please refer to the [Upgrades page](/consul/docs/api-gateway/upgrades)
For detailed information on upgrading, please refer to the [Upgrades page](/consul/docs/connect/gateways/api-gateway/upgrades-k8s)
## Known issues
At the time of release, there are no known issues in API Gateway v0.5.0

2
website/content/docs/release-notes/consul-k8s/v1_2_x.mdx
View File

@ -37,7 +37,7 @@ We are pleased to announce the following Consul updates.
- **External Authorization:** The external authorization Envoy extension lets you delegate data plane authorization requests to external systems. Refer to the [Delegate authorization to an external service](/consul/docs/connect/proxies/envoy-extensions/usage/ext-authz) for more information on how to use this extension.
- **Simplified API Gateway installation for Consul on Kubernetes:** API Gateway is now built into Consul. This enables a simplified installation and configuration process for Consul on Kubernetes. Refer to the [API Gateway installation](/consul/docs/api-gateway/install) for more information on the simplified native installation method.
- **Simplified API Gateway installation for Consul on Kubernetes:** API Gateway is now built into Consul. This enables a simplified installation and configuration process for Consul on Kubernetes. Refer to the [API Gateway installation](/consul/docs/connect/gateways/api-gateway/install-k8s) for more information on the simplified native installation method.
- **FIPS compliance (Enterprise):** HashiCorp now offers FIPS 140-2 compliant builds of Consul Enterprise that meet the security needs of federal agencies protecting sensitive, unclassified information with approved cryptographic measures. These builds use certified cryptographic modules and restrict configuration settings to comply with FIPS 140-2 Level 1 requirements, enabling compliant Consul deployments. Refer to the [Consul Enterprise FIPS](/consul/docs/enterprise/fips) for more information on FIPS compliance.

2
website/content/docs/release-notes/consul/v1_16_x.mdx
View File

@ -37,7 +37,7 @@ We are pleased to announce the following Consul updates.
- **External Authorization:** The external authorization Envoy extension lets you delegate data plane authorization requests to external systems. Refer to the [Delegate authorization to an external service](/consul/docs/connect/proxies/envoy-extensions/usage/ext-authz) for more information on how to use this extension.
- **Simplified API Gateway installation for Consul on Kubernetes:** API Gateway is now built into Consul. This enables a simplified installation and configuration process for Consul on Kubernetes. Refer to the [API Gateway installation](/consul/docs/api-gateway/install) for more information on the simplified native installation method.
- **Simplified API Gateway installation for Consul on Kubernetes:** API Gateway is now built into Consul. This enables a simplified installation and configuration process for Consul on Kubernetes. Refer to the [API Gateway installation](/consul/docs/connect/gateways/api-gateway/install-k8s) for more information on the simplified native installation method.
- **FIPS compliance (Enterprise):** HashiCorp now offers FIPS 140-2 compliant builds of Consul Enterprise that meet the security needs of federal agencies protecting sensitive, unclassified information with approved cryptographic measures. These builds use certified cryptographic modules and restrict configuration settings to comply with FIPS 140-2 Level 1 requirements, enabling compliant Consul deployments. Refer to the [Consul Enterprise FIPS](/consul/docs/enterprise/fips) for more information on FIPS compliance.

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

@ -410,19 +410,19 @@
},
{
"title": "API gateway",
"href": "/consul/docs/connect/gateways/api-gateway/configuration/api-gateway"
"path": "connect/config-entries/api-gateway"
},
{
"title": "HTTP route",
"href": "/consul/docs/connect/gateways/api-gateway/configuration/http-route"
"path": "connect/config-entries/http-route"
},
{
"title": "TCP route",
"href": "/consul/docs/connect/gateways/api-gateway/configuration/tcp-route"
"path": "connect/config-entries/tcp-route"
},
{
"title": "Inline certificate",
"href": "/consul/docs/connect/gateways/api-gateway/configuration/inline-certificate"
"path": "connect/config-entries/inline-certificate"
},
{
"title": "Ingress gateway",
@ -694,29 +694,116 @@
"path": "connect/gateways/api-gateway"
},
{
"title": "Usage",
"path": "connect/gateways/api-gateway/usage"
"title": "Technical specifications for Kubernetes",
"path": "connect/gateways/api-gateway/tech-specs"
},
{
"title": "Install on Kubernetes",
"path": "connect/gateways/api-gateway/install-k8s"
},
{
"title": "Upgrade on Kubernetes",
"path": "connect/gateways/api-gateway/upgrades-k8s"
},
{
"title": "Deploy listeners",
"routes": [
{
"title": "Deploy listeners to VMs",
"path": "connect/gateways/api-gateway/deploy/listeners-vms"
},
{
"title": "Deploy listeners to Kubernetes",
"path": "connect/gateways/api-gateway/deploy/listeners-k8s"
}
]
},
{
"title": "Define routes",
"routes": [
{
"title": "Define routes on VMs",
"path": "connect/gateways/api-gateway/define-routes/routes-vms"
},
{
"title": "Define routes on Kubernetes",
"path": "connect/gateways/api-gateway/define-routes/routes-k8s"
},
{
"title": "Reroute traffic in Kubernetes",
"path": "connect/gateways/api-gateway/define-routes/reroute-http-requests"
},
{
"title": "Route to peered services in Kubernetes",
"path": "connect/gateways/api-gateway/define-routes/route-to-peered-services"
}
]
},
{
"title": "Secure traffic",
"routes": [
{
"title": "Encrypt traffic on virtual machines",
"path": "connect/gateways/api-gateway/secure-traffic/encrypt-vms"
},
{
"title": "Verify incoming requests with JWTs on virtual machines",
"path": "connect/gateways/api-gateway/secure-traffic/verify-jwts-vms"
},
{
"title": "Verify incoming requests with JWTs on Kubernetes",
"path": "connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s"
}
]
},
{
"title": "Configuration",
"routes": [
{
"title": "API Gateway",
"path": "connect/gateways/api-gateway/configuration/api-gateway"
"title": "Overview",
"path": "connect/gateways/api-gateway/configuration"
},
{
"title": "HTTP Route",
"path": "connect/gateways/api-gateway/configuration/http-route"
"title": "Gateway",
"path": "connect/gateways/api-gateway/configuration/gateway"
},
{
"title": "TCP Route",
"path": "connect/gateways/api-gateway/configuration/tcp-route"
"title": "GatewayClass",
"path": "connect/gateways/api-gateway/configuration/gatewayclass"
},
{
"title": "Inline Certificate",
"path": "connect/gateways/api-gateway/configuration/inline-certificate"
"title": "GatewayClassConfig",
"path": "connect/gateways/api-gateway/configuration/gatewayclassconfig"
},
{
"title": "GatewayPolicy",
"path": "connect/gateways/api-gateway/configuration/gatewaypolicy"
},
{
"title": "RouteAuthFilter",
"path": "connect/gateways/api-gateway/configuration/routeauthfilter"
},
{
"title": "Routes",
"path": "connect/gateways/api-gateway/configuration/routes"
},
{
"title": "RouteRetryFilter",
"path": "connect/gateways/api-gateway/configuration/routeretryfilter"
},
{
"title": "RouteTimeoutFilter",
"path": "connect/gateways/api-gateway/configuration/routetimeoutfilter"
},
{
"title": "MeshService",
"path": "connect/gateways/api-gateway/configuration/meshservice"
}
]
},
{
"title": "Error Messages",
"path": "connect/gateways/api-gateway/errors"
}
]
},
@ -1734,77 +1821,6 @@
{
"divider": true
},
{
"title": "API Gateway for Kubernetes",
"routes": [
{
"title": "Overview",
"path": "api-gateway"
},
{
"title": "Installation",
"path": "api-gateway/install"
},
{
"title": "Technical Specifications",
"path": "api-gateway/tech-specs"
},
{
"title": "Upgrades",
"path": "api-gateway/upgrades"
},
{
"title": "Usage",
"routes": [
{
"title": "Deploy",
"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",
"routes": [
{
"title": "Overview",
"path": "api-gateway/configuration"
},
{
"title": "Gateway",
"path": "api-gateway/configuration/gateway"
},
{
"title": "GatewayClass",
"path": "api-gateway/configuration/gatewayclass"
},
{
"title": "GatewayClassConfig",
"path": "api-gateway/configuration/gatewayclassconfig"
},
{
"title": "Routes",
"path": "api-gateway/configuration/routes"
},
{
"title": "MeshService",
"path": "api-gateway/configuration/meshservice"
}
]
}
]
},
{
"title": "Network Infrastructure Automation",
"routes": [

55
website/redirects.js
View File

@ -137,6 +137,61 @@ module.exports = [
destination: '/consul/docs/ecs/reference/compatibility',
permanent: true,
},
{
source: '/consul/docs/connect/gateways/api-gateway/usage',
destination:
'/consul/docs/connect/gateways/api-gateway/deploy/listeners-vms',
permanent: true,
},
{
source: '/consul/docs/agi-gateway',
destination: '/consul/docs/connect/gateways/agi-gateway',
permanent: true,
},
{
source: '/consul/docs/api-gateway/install',
destination: '/consul/docs/connect/gateways/api-gateway/deploy/install-k8s',
permanent: true,
},
{
source: '/consul/docs/api-gateway/usage/reroute-http-requests',
destination:
'/consul/docs/connect/gateways/api-gateway/define-routes/reroute-http-requests',
permanent: true,
},
{
source: '/consul/docs/api-gateway/usage/route-to-peered-services',
destination:
'/consul/docs/connect/gateways/api-gateway/route-to-peered-services',
permanent: true,
},
{
source: '/consul/docs/api-gateway/usage/errors',
destination: '/consul/docs/connect/gateways/api-gateway/errors',
permanent: true,
},
{
source: '/consul/docs/api-gateway/usage/usage',
destination:
'/consul/docs/connect/gateways/api-gateway/deploy/listeners-k8s',
permanent: true,
},
{
source: '/consul/docs/api-gateway/upgrades',
destination: '/consul/docs/connect/gateways/api-gateway/upgrades-k8s',
permanent: true,
},
{
source: '/consul/docs/api-gateway/configuration/',
destination: '/consul/docs/connect/gateways/api-gateway/configuration/',
permanent: true,
},
{
source: '/consul/docs/api-gateway/configuration/:slug',
destination:
'/consul/docs/connect/gateways/api-gateway/configuration/:slug',
permanent: true,
},
{
source: '/consul/docs/connect/failover',
destination: '/consul/docs/connect/manage-traffic/failover',