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

Backport of docs: remove multiport docs, add v1dns flag into release/1.19.x (#21294)

Browse Source 
docs: remove multiport docs, add v1dns flag (#21278)

* docs: remove multiport docs, add v1dns flag

* v2 catalog notice + redirects

* redirect fixes

* Update website/content/docs/k8s/helm.mdx



---------

Co-authored-by: Dan Stough <dan.stough@hashicorp.com>
Co-authored-by: boruszak <jeffrey.boruszak@hashicorp.com>
Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
pull/21306/head
hc-github-team-consul-core 6 months ago committed by GitHub
parent c8ee4b1c2f
commit 67d3576665
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
20 changed files with 26 additions and 4421 deletions
Show Stats Download Patch File Download Diff File

391
website/content/commands/resource.mdx
Unescape View File

@ -1,391 +0,0 @@
---
layout: commands
page_title: 'Commands: Resource'
description: >-
The `consul resource` command interacts with Consul's v2 catalog of services and its resources. It exposes top-level commands for reading and filtering data from the registry.
---
# Consul Resource
Command: `consul resource`
<Note>
You must enable the [v2 catalog API](/consul/docs/concept/catalog/v2) to use this command.
</Note>
Use the `resource` command to apply, list, read, and delete resources when interacting with Consul's v2 catalog through the command line. For more information, refer to [v2 catalog API](/consul/docs/concept/catalog/v2).
## Usage
```text
Usage: consul resource <subcommand> [options]
# ...
Subcommands:
apply Write or update resource information
delete Delete resource information
list Read all resources by type
read Read resource information
```
## Subcommands
You can issue the following subcommands with the `consul resource` command.
### `apply`
`consul resource apply` writes or updates a resource at a given file path.
The following table shows the required [ACLs permission](/consul/api-docs/api-structure#authentication) to run the `apply` command:
| ACL Required |
| ------------ |
| `operator:write` |
#### Command Options
- `-f=<filepath>` - (Required) The path to the file that defines the Consul resource. When the file that defines the resource is in the current working directory, you may optionally omit this flag and pass the resource filename only.
#### Example usage
The following command applies a traffic permissions resource to Consul that restricts service-to-service communication to authorized services only.
```shell-session hideClipboard
$ consul resource apply -f=trafficpermissions.hcl
```
### `delete`
`consul resource delete` removes a Consul resource at a given file path.
The following table shows the required [ACL permissions](/consul/api-docs/api-structure#authentication) to run the `delete` command:
| ACL Required |
| ------------ |
| `operator:write` |
#### Command Options
- `-f=<filepath>` - (Required) The path to the file that defines the Consul resource. When the file that defines the resource is in the current working directory, you may optionally omit this flag and pass the resource filename only.
#### Example usage
The following command removes a traffic permissions resource from Consul that restricts service-to-service communication to authorized services only.
```shell-session hideClipboard
$ consul resource delete -f=trafficpermissions.hcl
```
### `list`
`consul resource list` outputs information about resources according to the type of resource and the location where the resource is applied.
This command must be issued with a resource type. By formatting the type on the command line as `group.groupVersion.kind`, you can return all matching resources. For example, you can list information about services with `catalog.v2beta1.Service` and TCP routes with `mesh.v2beta1.TCPRoute`. Refer to [v2 catalog](/consul/docs/architecture/v2/catalog#catalog-structure) for more information.
Do not include a resource name when listing resources.
The following table shows the required [ACL permissions](/consul/api-docs/api-structure#authentication) to run the `list` command:
| ACL Required |
| ------------ |
| `operator:read` |
#### Command Options
The following flags enable you to filter results.
- `-partition=<string>` - The partition where the resources apply.
- `-namespace=<string>` - The namespace where the resources apply.
#### Example usage
The following command lists resources that apply to services registered with the v2 catalog API, and includes a sample output for the `api` and `web` services registered in [configure multi-port services](/consul/docs/k8s/multiport/configure):
```shell-session hideClipboard
$ consul resource list catalog.v2beta1.Service
{
"resources": [
{
"data": {
"ports": [
{
"protocol": "PROTOCOL_TCP",
"targetPort": "api",
"virtualPort": 80
},
{
"protocol": "PROTOCOL_MESH",
"targetPort": "mesh"
}
],
"virtualIps": [
"10.96.216.242"
],
"workloads": {
"prefixes": [
"api-7c86cd8cb9"
]
}
},
"generation": "01HE8QWYFCTNEC2Q5JXKNXH6QW",
"id": {
"name": "api",
"tenancy": {
"namespace": "default",
"partition": "default",
},
"type": {
"group": "catalog",
"groupVersion": "v2beta1",
"kind": "Service"
},
"uid": "01HE8QWYFCTNEC2Q5JXJ97M429"
},
"metadata": {
"k8s-namespace": "default",
"managed-by": "consul-k8s-endpoints-controller-v2"
},
"status": {
"consul.io/endpoint-manager": {
"conditions": [
{
"message": "A valid workload selector is present within the service.",
"reason": "SelectorFound",
"state": "STATE_TRUE",
"type": "EndpointsManaged"
},
{
"message": "Found workload identities associated with this service: \"api\".",
"reason": "WorkloadIdentitiesFound",
"state": "STATE_TRUE",
"type": "BoundIdentities"
}
],
"observedGeneration": "01HE8QWYFCTNEC2Q5JXKNXH6QW",
"updatedAt": "2023-11-02T19:24:27.295564638Z"
}
},
"version": "118"
},
{
"data": {
"ports": [
{
"protocol": "PROTOCOL_TCP",
"targetPort": "admin",
"virtualPort": 90
},
{
"protocol": "PROTOCOL_MESH",
"targetPort": "mesh"
}
],
"virtualIps": [
"10.96.231.41"
],
"workloads": {
"prefixes": [
"api-7c86cd8cb9"
]
}
},
"generation": "01HE8QWYFJCXYXT2F4SBZE95Q4",
"id": {
"name": "api-admin",
"tenancy": {
"namespace": "default",
"partition": "default",
},
"type": {
"group": "catalog",
"groupVersion": "v2beta1",
"kind": "Service"
},
"uid": "01HE8QWYFJCXYXT2F4SAHV7KG8"
},
"metadata": {
"k8s-namespace": "default",
"managed-by": "consul-k8s-endpoints-controller-v2"
},
"status": {
"consul.io/endpoint-manager": {
"conditions": [
{
"message": "A valid workload selector is present within the service.",
"reason": "SelectorFound",
"state": "STATE_TRUE",
"type": "EndpointsManaged"
},
{
"message": "Found workload identities associated with this service: \"api\".",
"reason": "WorkloadIdentitiesFound",
"state": "STATE_TRUE",
"type": "BoundIdentities"
}
],
"observedGeneration": "01HE8QWYFJCXYXT2F4SBZE95Q4",
"updatedAt": "2023-11-02T19:24:27.589881680Z"
}
},
"version": "122"
},
{
"data": {
"ports": [
{
"protocol": "PROTOCOL_TCP",
"targetPort": "80",
"virtualPort": 80
},
{
"protocol": "PROTOCOL_MESH",
"targetPort": "mesh"
}
],
"virtualIps": [
"10.96.157.170"
],
"workloads": {
"prefixes": [
"web-6fd5c8bf57"
]
}
},
"generation": "01HE8QWYA9RSW2RS8GS5P538ZB",
"id": {
"name": "web",
"tenancy": {
"namespace": "default",
"partition": "default",
},
"type": {
"group": "catalog",
"groupVersion": "v2beta1",
"kind": "Service"
},
"uid": "01HE8QWYA9RSW2RS8GS3922SK0"
},
"metadata": {
"k8s-namespace": "default",
"managed-by": "consul-k8s-endpoints-controller-v2"
},
"status": {
"consul.io/endpoint-manager": {
"conditions": [
{
"message": "A valid workload selector is present within the service.",
"reason": "SelectorFound",
"state": "STATE_TRUE",
"type": "EndpointsManaged"
},
{
"message": "Found workload identities associated with this service: \"web\".",
"reason": "WorkloadIdentitiesFound",
"state": "STATE_TRUE",
"type": "BoundIdentities"
}
],
"observedGeneration": "01HE8QWYA9RSW2RS8GS5P538ZB",
"updatedAt": "2023-11-02T19:24:27.190972222Z"
}
},
"version": "115"
}
]
}
```
### `read`
`consul resource read` outputs information about resources according to the type and name of the resource.
This command must be issued with a resource type and a resource name. By formatting the type on the command line as `group.groupVersion.kind`, you can return all matching resources. For example, you can read information about services with `catalog.v2beta1.Service`, TCP routes with `mesh.v2beta1.TCPRoute`, and traffic permissions with `auth.v2beta1.TrafficPermissions`. Refer to [v2 catalog](/consul/docs/architecture/v2/catalog#catalog-structure) for more information.
The following table shows the required [ACL permissions](/consul/api-docs/api-structure#authentication) to run the `read` command:
| ACL Required |
| ------------ |
| `operator:read` |
#### Command Options
- `-partition=<string>` - The partition where the resource applies.
- `-namespace=<string>` - The namespace where the resource applies.
- `-stale` - Permits any Consul server to respond to the request. This flag enables for lower latency and higher throughput, but may result in stale data. This option has no effect on non-read operations.
- `-token` - A Consul ACL token to include with the request.
#### Example usage
The following example demonstrates a command to read the `web` service and includes an example output that includes information such as ports, virtual IPs, and status.
```shell-session hideClipboard
$ consul resource read catalog.v2beta1.Service web
{
"data": {
"ports": [
{
"protocol": "PROTOCOL_TCP",
"targetPort": "80",
"virtualPort": 80
},
{
"protocol": "PROTOCOL_MESH",
"targetPort": "mesh"
}
],
"virtualIps": [
"10.96.98.157"
],
"workloads": {
"prefixes": [
"web-6fd5c8bf57"
]
}
},
"generation": "01HE6MPDXC1J6ZMEMPN1460Z6K",
"id": {
"name": "web",
"tenancy": {
"namespace": "default",
"partition": "default",
},
"type": {
"group": "catalog",
"groupVersion": "v2beta1",
"kind": "Service"
},
"uid": "01HE6MPDXC1J6ZMEMPN0648FVB"
},
"metadata": {
"k8s-namespace": "default",
"managed-by": "consul-k8s-endpoints-controller-v2"
},
"status": {
"consul.io/endpoint-manager": {
"conditions": [
{
"message": "A valid workload selector is present within the service.",
"reason": "SelectorFound",
"state": "STATE_TRUE",
"type": "EndpointsManaged"
},
{
"message": "Found workload identities associated with this service: \"web\".",
"reason": "WorkloadIdentitiesFound",
"state": "STATE_TRUE",
"type": "BoundIdentities"
}
],
"observedGeneration": "01HE6MPDXC1J6ZMEMPN1460Z6K",
"updatedAt": "2023-11-01T23:49:59.172604219Z"
}
},
"version": "137"
}
```

4
website/content/docs/architecture/catalog.mdx
Unescape View File

@ -14,7 +14,9 @@ For more information about the information returned when querying the catalog, i
Consul tracks information about registered services through its catalog API. This API records user-defined information about the external services, such as their partitions and required health checks. It also records information that Consul assigns for its own operations, such as an ID for each service instance and the [Raft indices](/consul/docs/architecture/consensus) when the instance is registered and modified.
Consul uses v1 of the catalog API by default. Consul v1.17.0 and later ships with version 2 (v2) of the catalog API. V2 is intended for testing and development purposes. V1 and V2 of the catalog APIs cannot run concurrently in a Consul deployment. There is no migration path between catalog versions. For more information, refer to [Consul v2 Catalog API](/consul/docs/architecture/v2/catalog).
### v2 Catalog
Consul introduced an experimental v2 Catalog API in v1.17.0. This API supported multi-port Service configurations on Kubernetes, and it was made available for testing and development purposes. The v2 catalog and its support for multiport Kubernetes Services were deprecated in the v1.19.0 release.
## Catalog structure

61
website/content/docs/architecture/v2/catalog.mdx
Unescape View File

@ -1,61 +0,0 @@
---
layout: docs
page_title: Consul catalog v2 architecture
description: Learn about version 2 of the Consul catalog, which uses GAMMA specified resources. Learn how the v2 catalog corresponds to the v1 catalog.
---
<Warning>
The v2 catalog API and Traffic Permissions API are currently in beta. This documentation supports testing and development scenarios. Do not use these APIs in secure production environments.
</Warning>
# Consul catalog v2 architecture
This topic provides information about version 2 (v2) of the Consul catalog API. The catalog tracks registered services and their locations for both service discovery and service mesh use cases.
Consul supports the v2 catalog for service mesh use cases on Kubernetes deployments only. For more information about Consul’s default catalog, refer to [v1 Catalog API](/consul/docs/architecture/catalog).
## Introduction
When Consul registers services, it records [user-defined and Consul-assigned information](/consul/docs/architecture/catalog#catalog-structure). To determine a service’s identity, v1 of the catalog API records the following information:
- IDs of the specific _service instances_ that are registered
- Locations of the _nodes_ the instances run on
- Names of the _services_ the instances are associated with
This information enables Consul to associate service names with the individual instances and their unique network addresses, which makes it essential to Consul’s service discovery and service mesh operations.
The [Consul v1 catalog API](/consul/docs/architecture/catalog) was designed prior to the introduction of Consul’s service mesh features. One major implication of this design is that communication in Consul’s service mesh is secured through Consul's ACL system, which requires that a Kubernetes ServiceAccount resource match the Service name. As a result, only one Kubernetes Service can represent a service instance in the v1 catalog.
The v2 catalog API aligns more closely with the [Kubernetes Gateway API's GAMMA initiative](https://gateway-api.sigs.k8s.io/concepts/gamma/), which conceptualizes a Kubernetes Service as having two facets:
- The Service _front end_ is a combination of cluster IP and DNS name
- The Service _back end_ is a collection of endpoint IPs
For more information about the differences between the two facets and their impact on how Kubernetes directs requests, refer to [The Different Facets of a Service](https://gateway-api.sigs.k8s.io/concepts/service-facets/) in the Kubernetes documentation.
Consul's v2 catalog API makes a similar distinction, enabling it associate Kubernetes Pods with multiple Kubernetes Services. As a direct result of this change in catalog structure, Consul can register Services and Pods with multiple ports. For more information about how the differences between the catalog API impacts other Consul operations, refer to [changes to Consul's existing architecture](#changes-to-consul-s-existing-architecture).
The v2 catalog API is available alongside the existing v1 catalog API, but the catalogs cannot be used simultaneously. The v2 catalog is disabled by default. This beta release is for testing and development purposes only. We do not recommend implementing v2 in production environments or migrating to v2 until the API is generally available.
## Catalog structure
Consul v1.17 introduces a new version of the catalog API designed to bridge differences between the Consul and Kubernetes data models. The v2 catalog API continues to track services and nodes for Consul, but it replaces service instances with _workloads_ and _workload identities_.
### Catalog resources
The following table describes resources in the v2 catalog, how they generally compare to the v1 catalog and Kubernetes resources, and whether they are created by Kubernetes or computed by Consul when it registers a service.
| Catalog v2 resource | Resource group | Description | Catalog v1 analogue | Kubernetes analogue | Source |
| :------------------ | :------------- | :---------- | :--------------------------- | :--------------------------- | :----- |
| Service | `catalog` | The name of the service Consul registers a workload under. | Service | [Kubernetes Service](https://kubernetes.io/docs/concepts/services-networking/service/) | Created by Kubernetes |
| Node | `catalog` | The address of the Consul node where the workload runs. | Node | [Kubernetes Node](https://kubernetes.io/docs/concepts/architecture/nodes/) | Computed by Consul |
| Workload | `catalog` | An application instance running in a set of one or more Pods scheduled according to a Kubernetes Workload resource such as a Deployment or StatefulSet. | Service instance | [Kubernetes Pod](https://kubernetes.io/docs/concepts/workloads/pods/) | Created by Kubernetes |
| Workload identity | `auth` | Provides a distinct identity for a workload to assume. Each workload identity is tied to an Envoy proxy. This identity is used when Consul generates mTLS certificates. | Service name | [Kubernetes Service Accounts](https://kubernetes.io/docs/concepts/security/service-accounts/) | Created by Kubernetes |
| Service endpoint | Maps services to workload addresses and endpoints. | None | [Kubernetes Endpoints](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/endpoints-v1/) | Computed by Consul |
| Health status | `catalog` | A resource for reporting the health status of a workload. | Service instance health status | [PodStatus](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#PodStatus) | Created by Kubernetes |
| Health check | None | A resource for defining the health checks for a workload. | [Service instance health check](/consul/docs/services/usage/checks) | [Liveness, Readiness, and Startup Probes](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#container-probes) | Created by Kubernetes |
| Proxy configuration | `mesh` | Represents a configuration for a sidecar or gateway proxy. | `Proxy` field in service definition | None | Created by Kubernetes or user CRD |
| Destinations | `catalog` | Represents explicit service upstreams. When using the v1 catalog, these upstreams are configured in Helm chart as [Upstream Service annotations](/consul/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams) | [Proxy Configuration](/consul/docs/connect/proxies/envoy#envoy-proxy-configuration-for-service-mesh) | None | Created by Kubernetes |
| Traffic permissions| `auth` | Enables L4 traffic authorization according to workload identity instead of service identity. | [Service intentions](/consul/docs/connect/intentions) | None | Created by user CRD |

51
website/content/docs/architecture/v2/groups.mdx
Unescape View File

@ -1,51 +0,0 @@
---
layout: docs
page_title: Consul resource groups
description: Learn about resource groups in version 2 of Consul's internal architecture. The auth, catalog, and mesh groups structure Consul's ability to target individual workloads or an entire collection of workload endpoints.
---
<Warning>
The v2 catalog API and Traffic Permissions API are currently in beta. This documentation supports testing and development scenarios. Do not use these APIs in secure production environments.
</Warning>
# Consul resource groups
This topic provides an overview of resource groups in Consul's v2 architecture.
Refer to the [`consul resource` CLI command reference](/consul/docs/commands/resource) to learn about using the Consul CLI to interact with resources.
## Introduction
Consul's v2 architecture manages workloads using _resources_. Each resource is part of a _resource group_.
These resource groups structure Consul's ability to target either an _individual workload identity_ or an _entire collection of workload endpoints_ when managing service mesh traffic. There are three resource groups in the v2 API:
- `auth` group: Resources apply to workload identity
- `catalog` group: Resources apply to all workloads associated with a service
- `mesh` group: Resources apply to either workload identities or all workloads
For example, traffic permissions are part of the `auth` group. Permissions allow or deny traffic according to the other v2 catalog resource in the `auth` group, the workload identity. Meanwhile, when Consul routes service mesh traffic it applies rules to workloads based on the Service, which is a resource in the `catalog` group.
One practical impact of resource groups is that the [HTTPRoute](/consul/docs/k8s/multiport/reference/httproute), [GRPCRoute](/consul/docs/k8s/multiport/reference/grpcroute), and [TCPRoute](/consul/docs/k8s/multiport/reference/tcproute) CRDs require you to specify a `name` and `type` in configuration blocks. The `catalog.v2beta1.Service` type indicates that the rules defined in these CRDs apply to all workloads registered in the Consul catalog under the given name.
You can also use the `consul resource` command to return information about Consul resources in each group using a `group.groupVersion.kind` syntax. Refer to [`consul resource`](/consul/docs/commands/resource) for more information.
## Resource group reference
The following table describes the Consul resources that belong to each resource group and the resource's `group.groupVersion.kind` syntax.
| Resource `group` | v2 resource | Consul resource syntax |
| :------------------ | :-------- | :---- |
| `auth` | Traffic permissions | `auth.v2beta1.TrafficPermissions` |
| `auth` | Workload identity | `auth.v2beta1.WorkloadIdentity` |
| `catalog` | Service | `catalog.v2beta1.Service` |
| `catalog` | Node | `catalog.v2beta1.Node` |
| `catalog` | Workload | `catalog.v2beta1.Workload` |
| `catalog` | Health status | `catalog.v2beta1.HealthStatus` |
| `catalog` | Destinations | `catalog.v2beta1.Destination` |
| `mesh` | GRPCRoute | `mesh.v2beta1.GRPCRoute` |
| `mesh` | HTTPRoute | `mesh.v2beta1.HTTPRoute` |
| `mesh` | Proxy configuration | `mesh.v2beta1.ProxyConfiguration` |
| `mesh` | TCPRoute | `mesh.v2beta1.TCPRoute` |

77
website/content/docs/architecture/v2/index.mdx
Unescape View File

@ -1,77 +0,0 @@
---
layout: docs
page_title: Consul v2 architecture
description: Learn about version 2 of Consul's internal architecture, which replaces services and service instances with workloads and workload identities.
---
<Warning>
The v2 catalog API and Traffic Permissions API are currently in beta. This documentation supports testing and development scenarios. Do not use these APIs in secure production environments.
</Warning>
# Consul v2 architecture
This topic provides an overview of Consul's v2 architecture changes and their impact on Consul operations.
In the v1.17.0 release, Consul introduced the option to enable the [v2 catalog API](/consul/docs/architecture/v2/catalog) for testing and development on Kubernetes deployments. The v2 catalog is one of several changes in development to simplify and streamline Consul's architecture.
## Overview
The v2 architecture changes include the following:
- [v2 catalog API](/consul/docs/architecture/v2/catalog)
- [Resource groups](/consul/docs/architecture/v2/groups)
## Differences between v1 and v2
The change in data models introduced by the v2 architecture impacts several aspects of Consul’s operations.
### Traffic permissions resource replaces service intentions
The most significant change to Consul’s architecture and operations when using the v2 catalog structure is the introduction of the traffic permissions resource. This resource replaces the service intentions configuration entry, and enables authorized service-to-service communication for both L4 and L7 applications.
For more information about this resource, including example configurations, refer to [Traffic permissions configuration reference](/consul/docs/k8s/multiport/reference/trafficpermissions).
### HTTPRoute, GRPCRoute, and TCPRoute resources for traffic management
You can configure traffic management behavior such as service splitting in an `HTTPRoute`, `GRPCRoute`, or `TCPRoute` resource. In the v1 catalog, this behavior is defined in dedicated configuration entries. For examples, refer to [service splitter configuration entry reference](/consul/docs/connect/config-entries/service-splitter#examples).
For more information about these resource, including specifications and example configurations, refer to [HTTPRoute resource configuration reference](/consul/docs/k8s/multiport/reference/httproute), [GRPCRoute resource configuration reference](/consul/docs/k8s/multiport/reference/grpcroute), and [TCPRoute resource configuration reference](/consul/docs/k8s/multiport/reference/tcproute).
### New proxy configuration resource
In the v1 catalog, a service’s sidecar proxy and its behavior is [defined in the `Proxy` field of the service definition](/consul/docs/services/usage/define-services). You can also separately [define a service mesh proxy](/consul/docs/connect/proxies/deploy-service-mesh-proxies) and [configure proxy defaults](/consul/docs/connect/config-entries/proxy-defaults).
In the v2 catalog, the `ProxyConfiguration` resource configures a workload's sidecar proxy behavior according to Consul workload identity. Refer to [ProxyConfiguration resource configuration reference](/consul/docs/k8s/multiport/reference/proxyconfiguration) for more information.
## Constraints and limitations
Be aware of the following constraints and technical limitations on the v2 catalog API:
- The v2 catalog API only supports deployments using [Consul dataplanes](/consul/docs/connect/dataplane) instead of client agents. Consul on Kubernetes uses dataplanes by default.
- The v1 and v2 catalog APIs cannot run concurrently. Because configuration entries are part of the v1 catalog, you cannot use them when the v2 catalog is enabled. Use v2 resources instead.
- The Consul UI does not support the v2 catalog API in this release. You must disable the UI in the Helm chart in order to use the v2 catalog API.
- Secondary datacenters in WAN-federated deployments cannot enable the v2 catalog API in this release.
- HCP Consul Dedicated does not support the v2 catalog API in this release.
- You cannot [link a self-managed cluster to HCP Consul Central](/hcp/docs/consul/self-managed) to access its UI or view observability metrics when it uses the v2 catalog.
- We do not recommend updating existing clusters to enable the v2 catalog in this release. Instead, deploy a new Consul cluster and [enable the v2 catalog in the Helm chart](/consul/docs/k8s/multiport/configure#enable-the-v2-catalog).
## Guidance
The following resources are available to help you use the v2 catalog API:
### Usage documentation
- [use the v2 Catalog API](/consul/docs/k8s/multiport)
- [Configure multi-port services](/consul/docs/k8s/multiport/configure)
- [Split TCP traffic between multiple ports](/consul/docs/k8s/multiport/traffic-split)
### Reference documentation
- [`consul resource` CLI command](/consul/docs/k8s/multiport/reference/resource-command)
- [GRPCRoute configuration reference](/consul/docs/k8s/multiport/reference/grpcroute)
- [HTTPRoute configuration reference](/consul/docs/k8s/multiport/reference/httproute)
- [ProxyConfiguration configuration reference](/consul/docs/k8s/multiport/reference/proxyconfiguration)
- [TCPRoute configuration reference](/consul/docs/k8s/multiport/reference/tcproute)
- [TrafficPermissions configuration reference](/consul/docs/k8s/multiport/reference/trafficpermissions)

2
website/content/docs/install/ports.mdx
Unescape View File

@ -115,8 +115,6 @@ In both local and remote cases, incoming traffic comes from the mesh gateways.
HCP Consul Dedicated assigns port `8502` to clusters, instead of the default `8503`.
When the [v2 catalog](/consul/docs/architecture/v2/catalog) is enabled, all API calls from external systems, such as the Consul CLI and Terraform provider, use this port.
### Server RPC
The following table lists information about the Server RPC port defaults:

19
website/content/docs/k8s/helm.mdx
Unescape View File

@ -763,25 +763,14 @@ Use these links to navigate to a particular top-level stanza.
- `experiments` ((#v-global-experiments)) (`array<string>: []`) - Consul feature flags that will be enabled across components.
Supported feature flags:
- `resource-apis`:
_**Warning**_! This feature is under active development. It is not
recommended for production use. Setting this flag during an
upgrade could risk breaking your Consul cluster.
If this flag is set, Consul components will use the
V2 resources APIs for all operations.
- `v2tenancy`:
_**Warning**_! This feature is under active development. It is not
recommended for production use. Setting this flag during an
upgrade could risk breaking your Consul cluster.
If this flag is set, Consul V2 resources (catalog, mesh, auth, etc)
will use V2 implementations for tenancy (partitions and namesapces)
instead of bridging to the existing V1 implementations. The
`resource-apis` feature flag must also be set.
- `v1dns`:
When this flag is set, Consul agents use the legacy DNS implementation.
This setting exists in the case a DNS bug is found after the refactoring introduced in v1.19.0.
Example:
```yaml
experiments: [ "resource-apis" ]
experiments: [ "v1dns" ]
```
### server ((#h-server))

491
website/content/docs/k8s/multiport/configure.mdx
Unescape View File

@ -1,491 +0,0 @@
---
layout: docs
page_title: Configure multi-port services
description: Learn how to enable the v2 catalog and configure services to support multiple ports in Consul on Kubernetes. You can configure multiple ports on a single service or multiple services and ports in a single container.
---
# Configure multi-port services
<Warning>
The v2 catalog API and Traffic Permissions API are currently in beta. This documentation supports testing and development scenarios. Do not use these APIs in secure production environments.
</Warning>
<Note>
Multi-port services and selecting workloads using multiple services require enabling [Consul's v2 architecture](/consul/docs/architecture/v2).
</Note>
This page describes the process for integrating a service that uses multiple ports in a single container when running Consul on Kubernetes deployments. It includes example configurations to demonstrate an end-to-end deployment test of Consul's multi-port features.
## Requirements
Registering multi-port services with Consul requires Kubernetes. Multi-port services are not supported on VM deployments.
### Version requirements
Consul deployments that use the v2 catalog enabled must meet the following minimum version requirements:
- `consul` v1.18.0
- `consul-k8s` CLI v1.4.0 or `hashicorp/consul` Helm chart release v1.4.0
- `consul-dataplane` v1.4.0
To install or update the `consul-k8s CLI`, refer to [install the latest version](/consul/docs/k8s/installation/install-cli#install-the-latest-version) or [upgrade the CLI](/consul/docs/k8s/upgrade/upgrade-cli#upgrade-the-cli).
The required version of Consul dataplanes deploy automatically when using the latest version of `consul-k8s`. Dataplane version is configured manually when you [modify `imageConsulDataplane`](/consul/docs/k8s/helm#v-global-imageconsuldataplane) in the Helm chart.
For more information about upgrading Helm charts, refer to [Upgrade Helm chart version](/consul/docs/k8s/upgrade#upgrade-helm-chart-version).
### Annotation requirements
The examples on this page include the following required annotations in Kubernetes Deployment resources:
```yaml
spec:
template:
metadata:
annotations:
"consul.hashicorp.com/mesh-inject": "true"
"consul.hashicorp.com/transparent-proxy": "true"
```
These annotations inject Consul dataplanes and enable transparent proxy mode so that the services can curl each other on ports configured in the Kubernetes Service resource. Refer to [annotations and labels](/consul/docs/k8s/annotations-and-labels) for more information.
## Enable the v2 catalog
To enable the v2 catalog and its support for multi-port services, set `global.experiments: ["resource-apis"]` and `ui.enabled: false`. The following example includes these parameters in a Helm chart with additional configurations for the Consul installation:
<CodeBlockConfig name="values.yaml">
```yaml
global:
enabled: true
name: consul
image: hashicorp/consul:1.18.0
datacenter: dc1
tls:
enabled: true
acls:
manageSystemACLs: true
experiments: ["resource-apis"]
server:
enabled: true
replicas: 1
connectInject:
enabled: true
ui:
enabled: false
```
</CodeBlockConfig>
Then install Consul to your Kubernetes cluster using either the `consul-k8s` CLI or Helm.
<Tabs>
<Tab heading="consul-k8s CLI" group="consul-k8s">
```shell-session
$ consul-k8s install -config-file=values.yaml
```
</Tab>
<Tab heading="Helm" group="helm">
```shell-session
$ helm install consul hashicorp/consul --create-namespace --namespace consul --version 1.4.0 --values values.yaml
```
</Tab>
</Tabs>
## Define the multi-port service
Consul's v2 catalog supports two new methods for registering services on the mesh in Kubernetes:
- **Method 1**: Register a Kubernetes service that select workloads which expose multiple ports
- **Method 2**: Register multiple Kubernetes Services that direct traffic to an explicit port on the same workload
These methods affect how the Services are addressed in Kubernetes.
Each tab in the following example contains a configuration that defines an `api` service using one of these methods. Both definitions schedule a Pod running two containers that each support traffic to one of the ports exposed by the Service. In `Method 1`, both services are addressed using `api` because both services are exposed by a single service. In `Method 2`, `api` and `api-admin` are defined as separate services and can be addressed using distinct names.
<Tabs>
<Tab heading="Method 1" group="method1">
<CodeBlockConfig filename="api.yaml">
```yaml
apiVersion: v1
kind: ServiceAccount
metadata:
name: api
---
apiVersion: v1
kind: Service
metadata:
name: api
spec:
selector:
app: api
ports:
- name: api
port: 80
targetPort: api
- name: admin
port: 90
targetPort: admin
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: api
spec:
replicas: 1
selector:
matchLabels:
app: api
template:
metadata:
labels:
app: api
annotations:
"consul.hashicorp.com/mesh-inject": "true"
"consul.hashicorp.com/transparent-proxy": "true"
spec:
containers:
- name: api
image: hashicorp/http-echo:latest
args:
- -text="hello world"
- -listen=:8080
ports:
- containerPort: 8080
name: api
- name: api-admin
image: hashicorp/http-echo:latest
args:
- -text="hello world from 9090 admin"
- -listen=:9090
ports:
- containerPort: 9090
name: admin
serviceAccountName: api
```
</CodeBlockConfig>
</Tab>
<Tab heading="Method 2" group="method2">
<CodeBlockConfig filename="api.yaml">
```yaml
apiVersion: v1
kind: ServiceAccount
metadata:
name: api
---
apiVersion: v1
kind: Service
metadata:
name: api
spec:
selector:
app: api
ports:
- name: api
port: 80
targetPort: api
---
apiVersion: v1
kind: Service
metadata:
name: api-admin
spec:
selector:
app: api
ports:
- name: admin
port: 90
targetPort: admin
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: api
spec:
replicas: 1
selector:
matchLabels:
app: api
template:
metadata:
labels:
app: api
annotations:
"consul.hashicorp.com/mesh-inject": "true"
"consul.hashicorp.com/transparent-proxy": "true"
spec:
containers:
- name: api
image: hashicorp/http-echo:latest
args:
- -text="hello world"
- -listen=:8080
ports:
- containerPort: 8080
name: api
- name: api-admin
image: hashicorp/http-echo:latest
args:
- -text="hello world from 9090 admin"
- -listen=:9090
ports:
- containerPort: 9090
name: admin
serviceAccountName: api
```
</CodeBlockConfig>
</Tab>
</Tabs>
For testing purposes, the following example defines a Service to function as a static client that you can use to verify that the multi-port services function correctly.
<CodeBlockConfig filename="web.yaml">
```yaml
apiVersion: v1
kind: ServiceAccount
metadata:
name: web
---
apiVersion: v1
kind: Service
metadata:
name: web
spec:
selector:
app: web
ports:
- port: 80
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: web
spec:
replicas: 1
selector:
matchLabels:
app: web
template:
metadata:
labels:
app: web
annotations:
"consul.hashicorp.com/mesh-inject": "true"
"consul.hashicorp.com/transparent-proxy": "true"
spec:
containers:
- name: web
image: curlimages/curl:latest
# Just spin & wait forever, we'll use `kubectl exec` to demo
command: ['/bin/sh', '-c', '--']
args: ['while true; do sleep 30; done;']
serviceAccountName: web
```
</CodeBlockConfig>
To apply these services to your Kubernetes deployment and register them with Consul, run the following command:
```shell-session
$ kubectl apply -f api.yaml -f web.yaml
```
## Configure traffic permissions
Consul uses traffic permissions to validate communication between services based on L4 identity. When ACLs are enabled for the service mesh, traffic permissions deny all services by default. In order to allow traffic between the static client and the multi-port service, create CRDs that allow traffic to each port.
The following examples create Consul CRDs that allow traffic to only one port of the multi-port service. Each resource separately denies `web` permission when it is a source of traffic to one of the services. These traffic permissions work with either method for defining a multi-port service. When following the instructions on this page, apply these permissions individually when you validate the ports.
<CodeTabs tabs={[ "Allow port 80", "Allow port 90" ]}>
<CodeBlockConfig filename="allow-80.yaml">
```yaml
apiVersion: auth.consul.hashicorp.com/v2beta1
kind: TrafficPermissions
metadata:
name: web-to-api
spec:
destination:
identityName: api
action: ACTION_ALLOW
permissions:
- sources:
- identityName: web
destinationRules:
- portNames: ["api"]
```
</CodeBlockConfig>
<CodeBlockConfig filename="allow-90.yaml">
```yaml
apiVersion: auth.consul.hashicorp.com/v2beta1
kind: TrafficPermissions
metadata:
name: web-to-admin
spec:
destination:
identityName: api
action: ACTION_ALLOW
permissions:
- sources:
- identityName: web
destinationRules:
- portNames: ["admin"]
```
</CodeBlockConfig>
</CodeTabs>
## Validate multi-port connection
To open a shell to the `web` container, you need the name of the Pod it currently runs on. Run the following command to return a list of Pods:
```shell-session
$ kubectl get pods
NAME READY STATUS RESTARTS AGE
api-5784b54bcc-tp98l 3/3 Running 0 6m55s
web-6dcbd684bc-gk8n5 2/2 Running 0 6m55s
```
Set environment variables to remember the pod name for the web workload for use in future commands.
<CodeBlockConfig hideClipboard>
```shell-session
$ export WEB_POD=web-6dcbd684bc-gk8n5
```
</CodeBlockConfig>
### Apply traffic permissions
Use the `web` Pod's name to open a shell session and test the `api` service on both ports. When ACLs are enabled, these commands fail until you apply a traffic permissions resource.
<Tabs>
<Tab heading="Method 1" group="method1">
Test the `api` service on port 80.
```shell-session
$ kubectl exec -it ${WEB_POD} -c web -- curl api:80
```
Then test the `api` service on port 90.
```shell-session
$ kubectl exec -it ${WEB_POD} -c web -- curl api:90
```
</Tab>
<Tab heading="Method 2" group="method2">
Test the `api` service on port 80.
```shell-session
$ kubectl exec -it ${WEB_POD} -c web -- curl api:80
```
Then test the `api-admin` service on port 90.
```shell-session
$ kubectl exec -it ${WEB_POD} -c web -- curl api-admin:90
```
</Tab>
</Tabs>
Apply the CRD to allow traffic to port 80:
```shell-session
$ kubectl apply -f allow-80.yaml
```
<Tabs>
<Tab heading="Method 1" group="method1">
Then, open a shell session in the `web` container and test the `api` service on port 80.
```shell-session
$ kubectl exec -it ${WEB_POD} -c web -- curl api:80
hello world
```
</Tab>
<Tab heading="Method 2" group="method2">
Then, open a shell session in the `web` container and test the `api` service on port 80.
```shell-session
$ kubectl exec -it ${WEB_POD} -c web -- curl api:80
hello world
```
</Tab>
</Tabs>
Apply the CRD to allow traffic to port 90:
```shell-session
$ kubectl apply -f allow-90.yaml
```
<Tabs>
<Tab heading="Method 1" group="method1">
Then, open a shell session in the `web` container and test the `api` service on port 90.
```shell-session
$ kubectl exec -it ${WEB_POD} -c web -- curl api:90
hello world from 9090 admin
```
</Tab>
<Tab heading="Method 2" group="method2">
Then, open a shell session in the `web` container and test the `api-admin` service on port 90.
```shell-session
$ kubectl exec -it ${WEB_POD} -c web -- curl api-admin:90
hello world from 9090 admin
```
</Tab>
</Tabs>
## Next steps
After applying traffic permissions and validating service-to-service communication within your service mesh, you can manage traffic between multi-port services, filter traffic between ports based on L7 header information, or direct match HTTP query parameters to a specific port.
Refer to the following pages for more information:
- [Split traffic between services](/consul/docs/k8s/multiport/traffic-split)
- [gRPC route example: route traffic by matching header](/consul/docs/k8s/multiport/reference/httproute#route-traffic-by-matching-header)
- [HTTP route example: route traffic by matching header](/consul/docs/k8s/multiport/reference/httproute#route-traffic-by-matching-header)
- [HTTP route example: route traffic by matching header and query parameter](/consul/docs/k8s/multiport/reference/httproute#route-traffic-by-matching-header-and-query-parameter)

70
website/content/docs/k8s/multiport/index.mdx
Unescape View File

@ -1,70 +0,0 @@
---
layout: docs
page_title: Use the v2 Catalog API
description: Consul on Kubernetes supports the Catalog V2 API, which unlocks new service discovery and service mesh workflows. Learn how Consul’s Catalog V2 API supports workloads with multiple ports and selecting a workload using multiple services.
---
<Warning>
The v2 catalog API and Traffic Permissions API are currently in beta. This documentation supports testing and development scenarios. Do not use these APIs in secure production environments.
</Warning>
# Use the v2 Catalog API
This topic describes the process to use the v2 catalog API to register a service with multiple ports or select a workload using multiple services on Kubernetes deployments. For information about the v2 catalog’s contents and structure, refer to [v2 catalog architecture](/consul/docs/architecture/v2/catalog).
## Workflow
To use a multi-port service in Consul on Kubernetes deployments, complete the following steps:
1. Enable the v2 catalog with ACLs enabled. Add `global.experiments: ["resource-apis"]`, `ui.enabled: false`, and `manageSystemACLs: true` to a cluster's Helm chart before deploying Consul.
1. Use the `"consul.hashicorp.com/mesh-inject": "true"` and `"consul.hashicorp.com/transparent-proxy": "true"` annotations so that Consul automatically registers the service with transparent proxy mode enabled when Kubernetes deploys containers.
1. Configure traffic permissions. When ACLs are enabled, Consul denies all traffic by default. You can use the `TrafficPermissions` CRD to allow traffic to services.
For an example configuration and instructions for each of the steps in this workflow, refer to [configure multi-port services](/consul/docs/k8s/multiport/configure).
### Advanced proxy and route configuration workflow
You can also configure Envoy proxies and sidecar behavior with the proxy configurations resource, and manage traffic between services at the L4 and L7 networking layers with the TCP, HTTP, and gRPC route resources. After you [configure multi-port services](/consul/docs/k8s/multiport/configure), complete the following steps:
1. Define the resource's behavior in a custom resource definition (CRD). For specifications and example configurations, refer to the [configuration reference](#reference-documentation) for each resource.
1. Apply the resource to your cluster.
For an example configuration and instructions for each of the steps in this workflow, refer to [split TCP service traffic between ports](/consul/docs/k8s/multiport/traffic-split).
## Constraints and limitations
Be aware of the following constraints and technical limitations on using multi-port services and the v2 catalog API:
- Multi-port services are available for deployments using [Consul dataplanes](/consul/docs/connect/dataplane) instead of client agents. Consul on Kubernetes uses dataplanes by default.
- When running the v2 catalog for multi-port services, you cannot run the v1 catalog API at the same time.
- Because configuration entries are part of the v1 catalog, you cannot use them when the v2 catalog is enabled. Use v2 resources instead to configure multi-port service behavior in the service mesh.
- The Consul UI does not support multi-port services in this release. You must disable the UI in the Helm chart in order to use multi-port services.
- HCP Consul Dedicated does not support multi-port services in this release.
- You cannot [link a self-managed Enterprise cluster to HCP Consul Central](/hcp/docs/consul/self-managed) to access its UI or view observability metrics when it uses the v2 catalog.
- We do not recommend updating existing clusters to enable the v2 catalog in this release. To register multi-port services, deploy a new Consul cluster that enables the v2 catalog.
## Guidance
The following resources are available to help you use the v2 Catalog API:
### Architecture
- [v2 architecture overview](/consul/docs/architecture/v2/catalog)
- [v2 Consul catalog](/consul/docs/architecture/v2/catalog)
- [v2 resource groups](/consul/docs/architecture/v2/catalog)
### Usage documentation
- [Configure v2 services with multiple ports](/consul/docs/k8s/multiport/configure)
- [Split TCP traffic between v2 services with multiple ports](/consul/docs/k8s/multiport/traffic-split)
### Reference documentation
- [`consul resource` CLI command](/consul/commands/resource)
- [`GRPCRoute` resource configuration reference](/consul/docs/k8s/multiport/reference/grpcroute)
- [`HTTPRoute` resource configuration reference](/consul/docs/k8s/multiport/reference/httproute)
- [`ProxyConfiguration` resource configuration reference](/consul/docs/k8s/multiport/reference/proxyconfiguration)
- [`TCPRoute` resource configuration reference](/consul/docs/k8s/multiport/reference/tcproute)
- [`TrafficPermissions` resource configuration reference](/consul/docs/k8s/multiport/reference/trafficpermissions)

808
website/content/docs/k8s/multiport/reference/grpcroute.mdx
Unescape View File

@ -1,808 +0,0 @@
---
layout: docs
page_title: GRPCRoute resource configuration reference
description: The GRPCRoute resource CRD configures L7 gRPC traffic behavior within the service mesh. GRPCRoute requires the v2 catalog API. Learn how to configure the GRPCRoute CRD with specifications and example configurations.
---
# GRPCRoute resource configuration reference
This page provides reference information for the `GRPCRoute` resource, which defines L7 gRPC traffic within the service mesh.
This custom resource definition (CRD) describes a resource related to the [Kubernetes GAMMA initiative](https://gateway-api.sigs.k8s.io/concepts/gamma/) that requires the [v2 catalog API](/consul/docs/architecture/v2/catalog). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog). For more information about GAMMA resources, refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/gamma/).
## Configuration model
The following list outlines field hierarchy, language-specific data types, and requirements in a gRPC route CRD. Click on a property name to view additional details, including default values.
- [`apiVersion`](#apiversion): string | required | must be set to `mesh.consul.hashicorp.com/v2beta1`
- [`kind`](#kind): string | required | must be set to `GRPCRoute`
- [`metadata`](#metadata): map | required
- [`name`](#metadata-name): string | required
- [`namespace`](#metadata-namespace): string | optional <EnterpriseAlert inline />
- [`spec`](#spec): map | required
- [`parentRefs`](#spec-parentrefs): map | required
- [`port`](#spec-parentrefs-port): string
- [`ref`](#spec-parentrefs-ref): string | required
- [`name`](#spec-parentrefs-ref-name): string
- [`type`](#spec-parentrefs-ref-type): map
- [`group`](#spec-parentrefs-ref-type): string
- [`groupVersion`](#spec-parentrefs-ref-type): string
- [`kind`](#spec-parentrefs-ref-type): string
- [`rules`](#spec-rules): map | required
- [`backendRefs`](#spec-rules-backendrefs): map
- [`backendRef`](#spec-rules-backendrefs-backendref): map
- [`datacenter`](#spec-rules-backendrefs-backendref-datacenter): string
- [`port`](#spec-rules-backendrefs-backendref-port): string
- [`ref`](#spec-rules-backendrefs-backendref-ref): map
- [`name`](#spec-rules-backendrefs-backendref-ref-name): string
- [`type`](#spec-rules-backendrefs-backendref-ref-type): map
- [`group`](#spec-rules-backendrefs-backendref-ref-type): string
- [`groupVersion`](#spec-rules-backendrefs-backendref-ref-type): string
- [`kind`](#spec-rules-backendrefs-backendref-ref-type): string
- [`filters`](#spec-rules-backendrefs-filters): map
- [`requestHeaderModifier`](#spec-rules-backendrefs-filters-requestheadermodifier): map
- [`add`](#spec-rules-backendrefs-filters-requestheadermodifier): map
- [`set`](#spec-rules-backendrefs-filters-requestheadermodifier): map
- [`remove`](#spec-rules-backendrefs-filters-requestheadermodifier): map
- [`responseHeaderModifier`](#spec-rules-backendrefs-filters-responseheadermodifier): map
- [`add`](#spec-rules-backendrefs-filters-responseheadermodifier): map
- [`set`](#spec-rules-backendrefs-filters-responseheadermodifier): map
- [`remove`](#spec-rules-backendrefs-filters-responseheadermodifier): map
- [`urlRewrite`](#spec-rules-backendrefs-filters-urlrewrite): map
- [`pathPrefix`](#spec-rules-backendrefs-filters-urlrewrite): string
- [`weight`](#spec-rules-backendrefs-weight): number | `1`
- [`filters`](#spec-rules-filters): map
- [`requestHeaderModifier`](#spec-rules-filters-requestheadermodifier): map
- [`add`](#spec-rules-filters-requestheadermodifier): map
- [`set`](#spec-rules-filters-requestheadermodifier): map
- [`remove`](#spec-rules-filters-requestheadermodifier): map
- [`responseHeaderModifier`](#spec-rules-filters-responseheadermodifier): map
- [`add`](#spec-rules-filters-responseheadermodifier): map
- [`set`](#spec-rules-filters-responseheadermodifier): map
- [`remove`](#spec-rules-filters-responseheadermodifier): map
- [`urlRewrite`](#spec-rules-filters-urlrewrite): map
- [`pathPrefix`](#spec-rules-filters-urlrewrite): string
- [`matches`](#spec-rules-matches): map
- [`headers`](#spec-rules-matches-headers): map
- [`name`](#spec-rules-matches-headers-name): string
- [`type`](#spec-rules-matches-headers-type): string
- [`value`](#spec-rules-matches-headers-value): string
- [`method`](#spec-rules-matches-method): map
- [`method`](#spec-rules-matches-method-method): string
- [`service`](#spec-rules-matches-method-service): string
- [`type`](#spec-rules-matches-method-type): string
- [`retries`](#spec-rules-retries): map
- [`number`](#spec-rules-retries-number): map
- [`value`](#spec-rules-retries-number): number
- [`onConditions`](#spec-rules-retries-onconditions): map of strings
- [`onConnectFailure`](#spec-rules-retries-onconnectfailure): boolean | `false`
- [`onStatusCodes`](#spec-rules-retries-onconditions): map of numbers
- [`timeouts`](#spec-rules-timeouts): map
- [`idle`](#spec-rules-timeouts-idle): string
- [`request`](#spec-rules-timeouts-request): string
## Complete configuration
When every field is defined, a gRPC route resource CRD has the following form:
```yaml
apiVersion: mesh.consul.hashicorp.com/v2beta1 # required
kind: GRPCRoute # required
metadata:
name: <CRDName>
namespace: <namespace>
spec:
parentRefs:
port: <portRoutedFrom>
- ref:
name: <nameRoutedFrom>
type:
group: <catalog>
groupVersion: <v2beta1>
kind: <Service>
rules:
- backendRefs:
- backendRef:
datacenter: <datacenterRoutedTo>
port: "<portRoutedTo>"
ref:
name: <nameRoutedTo>
type:
group: <catalog>
groupVersion: <v2beta1>
kind: <Service>
filters:
- requestHeaderModifier:
add:
name: <headerName>
value: <headerValue>
- responseHeaderModifier:
set:
name: <headerName>
value: <headerValue>
urlRewrite:
pathPrefix: <path/prefix>
weight: 1
filters:
requestHeaderModifier:
remove:
name: <headerName>
value: <headerValue>
responseHeaderModifier:
add:
name: <headerName>
value: <headerValue>
urlRewrite:
pathPrefix: <path/prefix>
matches:
headers:
name: <nameToMatch>
type: <typeToMatch>
value: <valueToMatch>
method:
method: <methodToMatch>
service: <serviceToMatch>
type: <typeToMatch>
retries:
number:
value: 1
onConditions: ["cancelled", "unavailable"]
onConnectFailure: false
onStatusCodes: [400, 404]
timeouts:
idle: <1s>
request: <1s>
```
## Specification
This section provides details about the fields you can configure in the `GRPCRoute` custom resource definition (CRD).
### `apiVersion`
Specifies the version of the Consul API for integrating with Kubernetes. The value must be `mesh.consul.hashicorp.com/v2beta1`.
#### Values
- Default: None
- This field is required.
- String value that must be set to `mesh.consul.hashicorp.com/v2beta1`.
### `kind`
Specifies the type of CRD to implement. Must be set to `GRPCRoute`.
#### Values
- Default: None
- This field is required.
- Data type: String value that must be set to `GRPCRoute`.
### `metadata`
Map that contains an arbitrary name for the CRD and the namespace it applies to.
#### Values
- Default: None
- Data type: Map
### `metadata.name`
Specifies a name for the CRD. The name is metadata that you can use to reference the resource when performing Consul operations, such as using the `consul resource` command. Refer to [`consul resource`](/consul/docs/k8s/connect/multiport/reference/resource-command) for more information.
#### Values
- Default: None
- This field is required.
- Data type: String
### `metadata.namespace` <EnterpriseAlert inline />
Specifies the namespace that the service resolver 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 `GRPCRoute` CRD. The `apiVersion`, `kind`, and `metadata` fields are siblings of the spec field. All other configurations are children.
When using this CRD, the `spec` field closely resembles the `GRPCRoute` GAMMA resource. Refer to [GRPCRoute in the Kubernetes documentation](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1alpha2.GRPCRoute).
#### Values
- Default: None
- This field is required.
- Data type: Map
### `spec.parentRefs`
Specifies the services and other resources to attach the route to. You can only define one `parentsRefs` configuration for each route. To attach the route to multiple resources, specify additional [`spec.parentRefs.ref`](#spec-parentrefs-ref) configurations in the `parentsRefs` block. You can only specify the name of one port for the route. Any resources that send traffic through the route use the same port.
#### Values
- Default: None
- This field is required.
- Data type: Map
### `spec.parentRefs.port`
Specifies the port for the Consul service that the configuration applies to. This parameter can be either a virtual port number, such as a Kubernetes service port, or a non-numeric target port value representing a named workload port.
If you are not targeting a virtual port, specify the workload port name directly.
#### Values
- Default: None
- Data type: String
### `spec.parentRefs.ref`
Specifies the resource that the route attaches to.
#### Values
- Default: None
- Data type: Map
### `spec.parentRefs.ref.name`
Specifies the user-defined name of the resource that the configuration applies to.
#### Values
- Default: None
- Data type: String
### `spec.parentRefs.ref.type`
Specifies the type of resource that the configuration applies to. To reference a service in the Consul catalog, configure the resource type as `catalog.v2beta1.Service`.
#### Values
- Default: None
- Data type: Map containing the following parameters:
| Parameter | Description | Data type | Default |
| :------------ | :------------------------------------------------------------------- | :-------- | :------- |
| `group` | Specifies a group for the resource type within the Kubernetes cluster. To reference a service in the Consul catalog, set this parameter to `catalog`. | String | None |
| `groupVersion` | Specifies a groupVersion for the resource type within the Kubernetes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String | None |
| `kind` | Specifies the kind of the Kubernetes object the resource applies to. To reference a service in the Consul catalog, set this parameter to `Service`. | String | None |
### `spec.rules`
Specifies rules for sidecar proxies to direct a service's gRPC traffic within the service mesh, including filtering, retry, and timeout behavior.
#### Values
- Default: None
- Data type: Map
### `spec.rules.backendRefs`
Specifies the Kubernetes Service backend to direct GRPC traffic to when a request matches the service described in [`spec.parentRefs`](#spec-parentrefs). The Service backend is the collection of endpoint IPs for the service. Refer to [the Kubernetes Gateway API specification](https://gateway-api.sigs.k8s.io/concepts/gamma/#an-overview-of-the-gateway-api-for-service-mesh) for more information about Service backends.
When a valid Service backend cannot be reached and no additional filters apply, traffic that matches the rule returns a 500 status code.
When different Service backends are specified in [`spec.rules.backendRefs.weight`](#spec-rules-backendrefs-weight) and one of the backends is invalid, Consul continues to apply the specified weights instead of adjusting the relative weights to exclude traffic to the invalid backend. For example, when traffic is configured in a 50-50 split between `api` and `admin` and no valid endpoints for `admin` can be reached, the 50% of traffic intended for `admin` returns with a 500 status code.
#### Values
- Default: None
- Data type: Map
### `spec.rules.backendRefs.backendRef`
Specifies an individual Service backend where matching requests should be sent.
#### Values
- Default: None
- Data type: Map
### `spec.rules.backendRefs.backendRef.datacenter`
Specifies the name of the Consul datacenter that registered the Service backend that the configuration routes traffic to.
#### Values
- Default: None
- Data type: String
### `spec.rules.backendRefs.backendRef.port`
Specifies the port for the Consul service that the configuration routes traffic to. This parameter can be either a virtual port number, such as a Kubernetes service port, or a non-numeric target port value representing a named workload port.
If you are not targeting a virtual port, specify the workload port name directly.
#### Values
- Default: None
- Data type: String
### `spec.rules.backendRefs.backendRef.ref`
The Consul service that the configuration routes traffic to.
#### Values
- Default: None
- Data type: Map
### `spec.rules.backendRefs.backendRef.ref.name`
Specifies the user-defined name of the resource that the configuration routes traffic to.
#### Values
- Default: None
- Data type: String
### `spec.rules.backendRefs.backendRef.ref.type`
Specifies the type of resource that the configuration routes traffic to. To reference a service in the Consul catalog, configure the resource type as `catalog.v2beta1.Service`.
#### Values
- Default: None
- Data type: Map containing the following parameters:
| Parameter | Description | Data type | Default |
| --- | --- | --- | --- |
| `group` | Specifies a group for the resource type within the Kubernetes cluster. To reference a service in the Consul catalog, set this parameter to `catalog`. | String | None |
| `groupVersion` | Specifies a groupVersion for the resource type within the Kubernetes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String | None |
| `kind` | Specifies the kind of the Kubernetes object for the resource. To reference a service in the Consul catalog, set this parameter to `Service`. | String | None |
### `spec.rules.backendRefs.filters`
Specifies filtering behavior for services configured in the same [`spec.rules.backendRefs`](#spec-rules-backendrefs) block.
#### Values
- Default: None
- Data type: Map
### `spec.rules.backendRefs.filters.requestHeaderModifier`
Specifies a set of header modification rules applied to requests routed with the gRPC route resource.
#### Values
- Default: None
- Values: Object containing one or more fields that define header modification rules:
- `add`: Map of one or more key-value pairs.
- `set`: Map of one or more key-value pairs.
- `remove`: Map of one or more key-value pairs.
The following table describes how to configure values for request headers:
| Rule | Description | Type |
| --- | --- | --- |
| `add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | Map of strings |
| `set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | Map of strings |
| `remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | List of strings |
##### Use variable placeholders
For `add` and `set`, if the service is configured to use Envoy as the proxy, the value may contain variables to interpolate dynamic metadata into the value. For example, using the variable `%DOWNSTREAM_REMOTE_ADDRESS%` allows you to pass a value that is generated when the split occurs.
### `spec.rules.backendRefs.filters.responseHeaderModifier`
Specifies a set of header modification rules applied to responses routed with the gRPC route resource.
#### Values
- Default: None
- Values: Object containing one or more fields that define header modification rules:
- `add`: Map of one or more key-value pairs.
- `set`: Map of one or more key-value pairs.
- `remove`: Map of one or more key-value pairs.
The following table describes how to configure values for request headers:
| Rule | Description | Type |
| --- | --- | --- |
| `add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | Map of strings |
| `set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | Map of strings |
| `remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | List of strings |
##### Use variable placeholders
For `add` and `set`, if the service is configured to use Envoy as the proxy, the value may contain variables to interpolate dynamic metadata into the value. For example, using the variable `%DOWNSTREAM_REMOTE_ADDRESS%` allows you to pass a value that is generated when the split occurs.
### `spec.rules.backendRefs.filters.urlRewrite`
Specifies a path to modify the URL with when a request is forwarded.
#### Values
- Default: None
- Data type: Map containing the following parameter:
| Parameter | Description | Data type | Default |
| :------------ | :------------------------------------------------------------------------------------------------- | --------- | ------- |
| `pathPrefix` | Specifies the path that is prepended to the URL. | String | None |
### `spec.rules.backendRefs.weight`
Specifies the proportion of requests routed to the specified service.
This proportion is relative to the sum of all weights in the [`spec.rules.backendRefs`](#spec-rules-backendrefs) block. As a result, weights do not need to add up to 100. When only one backend is specified and the weight is greater then 0, Consul forwards 100% of traffic to the backend.
When this parameter is not specified, Consul defaults to `1`.
#### Values
- Default: `1`
- Data type: Integer
### `spec.rules.filters`
Specifies filtering behavior for all requests that match the service defined in [`spec.parentRefs`](#spec-parent-refs).
#### Values
- Default: None
- Data type: Map
### `spec.rules.filters.requestHeaderModifier`
Specifies a set of header modification rules applied to requests that match the service defined in [`spec.parentRefs`](#spec-parent-refs).
#### Values
- Default: None
- Values: Object containing one or more fields that define header modification rules:
- `add`: Map of one or more key-value pairs.
- `set`: Map of one or more key-value pairs.
- `remove`: Map of one or more key-value pairs.
The following table describes how to configure values for request headers:
| Rule | Description | Type |
| --- | --- | --- |
| `add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | Map of strings |
| `set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | Map of strings |
| `remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | List of strings |
##### Use variable placeholders
For `add` and `set`, if the service is configured to use Envoy as the proxy, the value may contain variables to interpolate dynamic metadata into the value. For example, using the variable `%DOWNSTREAM_REMOTE_ADDRESS%` allows you to pass a value that is generated when the split occurs.
### `spec.rules.filters.responseHeaderModifier`
Specifies a set of header modification rules applied to responses from services matching [`spec.parentRefs`](#spec-parent-refs).
#### Values
- Default: None
- Values: Object containing one or more fields that define header modification rules:
- `add`: Map of one or more key-value pairs.
- `set`: Map of one or more key-value pairs.
- `remove`: Map of one or more key-value pairs.
The following table describes how to configure values for request headers:
| Rule | Description | Type |
| --- | --- | --- |
| `add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | Map of strings |
| `set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | Map of strings |
| `remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | List of strings |
##### Use variable placeholders
For `add` and `set`, if the service is configured to use Envoy as the proxy, the value may contain variables to interpolate dynamic metadata into the value. For example, using the variable `%DOWNSTREAM_REMOTE_ADDRESS%` allows you to pass a value that is generated when the split occurs.
### `spec.rules.filters.urlRewrite`
Specifies a path to modify the URL with when a request matching [`spec.parentRefs`](#spec-parent-refs) is forwarded.
#### Values
- Default: None
- Data type: Map containing the following parameter:
| Parameter | Description | Data type | Default |
| :------------ | :------------------------------------------------------------------------------------------------- | --------- | ------- |
| `pathPrefix` | Specifies a path to prepend to the URL when a request matching [`spec.parentRefs`](#spec-parent-refs) is forwarded. | String | None |
### `spec.rules.matches`
Specifies rules for matching traffic to services described in [`spec.parentRefs`](#spec-parent-refs) according to the request header or method.
#### Values
- Default: None
- Data type: Map
### `spec.rules.matches.headers`
Specifies criteria for matching gRPC request headers.
When [`spec.rules.matches.headers.value`] is specified multiple times, a request must match all of the specified values for the route to be selected.
#### Values
- Default: None
- Data type: Map
### `spec.rules.matches.headers.name`
Specifies the name of a gRPC request header to match on.
#### Values
- Default: None
- Data type: String
### `spec.rules.matches.headers.type`
Specifies a type of match to perform on the gRPC request header. Supported match types include: unspecified, exact, regex, present, prefix, and suffix.
#### Values
- Default: None
- Data type: String that should match one of the following values:
- `HEADER_MATCH_TYPE_UNSPECIFIED`
- `HEADER_MATCH_TYPE_EXACT`
- `HEADER_MATCH_TYPE_REGEX`
- `HEADER_MATCH_TYPE_PRESENT`
- `HEADER_MATCH_TYPE_PREFIX`
- `HEADER_MATCH_TYPE_SUFFIX`
### `spec.rules.matches.headers.value`
Specifies the value of the gRPC request header to match. When this field is specified multiple times, a request must match all of the specified values for the route to be selected.
#### Values
- Default: None
- Data type: String
### `spec.rules.matches.method`
Specifies criteria for matching a service and a gRPC request method. When configuring this field, either [`spec.rules.matches.method.method`](#spec-rules-matches-method-method) or [`spec.rules.matches.method.service`](#spec-rules-matches-method-service) must be a non-empty string.
#### Values
- Default: None
- Data type: Map
### `spec.rules.matches.method.method`
Specifies the value of the method to match. When empty or omitted, all methods match.
#### Values
- Default: None
- Data type: String
### `spec.rules.matches.method.service`
Specifies the value of the service to match. When empty or omitted, all services match.
#### Values
- Default: None
- Data type: String
### `spec.rules.matches.method.type`
Specifies a type of match to perform on the gRPC request method. Supported match types include: unspecified, exact, and regex.
#### Values
- Default: None
- Data type: String that should match one of the following values:
- `GRPC_METHOD_MATCH_TYPE_UNSPECIFIED`
- `GRPC_METHOD_MATCH_TYPE_EXACT`
- `GRPC_METHOD_MATCH_TYPE_REGEX`
### `spec.rules.retries`
Specifies retry logic for routing gRPC traffic.
#### Values
- Default: None
- Data type: Map
### `spec.rules.retries.number`
Specifies the number of retries to attempt when a request fails.
#### Values
- Default: None
- Data type: Map that contains the following parameter:
| Parameter | Description | Data type | Default |
| :-------- | :------------------------------------------- | --------- | ------- |
| `value` | Specifies the number of retries to attempt. | Integer | None |
### `spec.rules.retries.onConditions`
Specifies Envoy conditions that cause an automatic retry attempt.
#### Values
- Default: None
- Data type: Map of strings
### `spec.rules.retries.onConnectFailure`
Enables an automatic retry attempt when a connection failure error occurs.
#### Values
- Default: `false`
- Data type: Boolean
### `spec.rules.retries.onStatusCodes`
Specifies the response status codes that are eligible for retry attempts.
#### Values
- Default: None
- Data type: Map of integers
### `spec.rules.timeouts`
Specifies timeout logic when routing gRPC traffic
#### Values
- Default: None
- Data type: Map
### `spec.rules.timeouts.idle`
Specifies the total amount of time permitted for the request stream to be idle before a timeout occurs.
This field accepts a string indicating the number of seconds. For example, indicate five seconds with `5s` and five milliseconds with `0.005s`.
#### Values
- Default: None
- Data type: String
### `spec.rules.timeouts.request`
Specifies the total amount of time spent processing the entire downstream request, including retries, before triggering a timeout.
This field accepts a string indicating the number of seconds. For example, indicate five seconds with `5s` and five milliseconds with `0.005s`.
#### Values
- Default: None
- Data type: String
## Examples
The following examples demonstrate common GRPCRoute CRD configuration patterns for specific use cases.
### Split gRPC traffic between two ports
The following example splits traffic for the `api` service. GRPC traffic for services registered to the Consul catalog that are available at the `api-workload` port is split so that 50% of the traffic routes to the service at the `api-workload` port and 50% routes to the service at the `admin-workload` port.
```yaml
apiVersion: mesh.consul.hashicorp.com/v2beta1
kind: GRPCRoute
metadata:
name: api-split
namespace: default
spec:
parentRefs:
- ref:
type:
group: catalog
groupVersion: v2beta1
kind: Service
name: api
# The virtual port number for the "api-workload" target port.
port: "80"
rules:
- backendRefs:
- backendRef:
ref:
type:
group: catalog
groupVersion: v2beta1
kind: Service
name: api
# The virtual port number for the "api-workload" target port.
port: "80"
weight: 50
- backendRef:
ref:
type:
group: catalog
groupVersion: v2beta1
kind: Service
name: api
# The virtual port number for the "admin-workload" target port.
port: "90"
weight: 50
```
### Route traffic by matching header
The following example routes gRPC traffic for the `api` service according to its header. GRPC traffic for services registered to the Consul catalog that are available at the `api-workload` port are routed according to the following criteria:
- For traffic with a header that contains a `x-debug` value of exactly `1`, Consul modifies the response and request headers and routes to the `api` service at the `api-workload` port.
- For traffic with a header that contains a `x-debug` value of exactly `2`, Consul modifies the response and request headers and routes to the `api-admin` service at the `admin-workload` port.
This example also includes how to include filters that modify request or response headers.
```yaml
apiVersion: mesh.consul.hashicorp.com/v2beta1
kind: GRPCRoute
metadata:
name: api-match-split
namespace: default
spec:
parentRefs:
- ref:
type:
group: catalog
groupVersion: v2beta1
kind: Service
name: api
# The virtual port number for the "api-workload" target port.
port: "80"
rules:
- matches:
- headers:
- type: "HEADER_MATCH_TYPE_EXACT"
name: "x-debug"
value: "1"
filters:
- requestHeaderModifier:
add:
- name: "request-foo"
value: "request-bar"
- responseHeaderModifier:
add:
- name: "response-foo"
value: "response-bar"
backendRefs:
- backendRef:
ref:
type:
group: catalog
groupVersion: v2beta1
kind: Service
name: api
# The virtual port number for the "api-workload" target port.
port: "80"
- matches:
- headers:
- type: "HEADER_MATCH_TYPE_EXACT"
name: "x-debug"
value: "2"
filters:
- requestHeaderModifier:
add:
- name: "request-foo"
value: "request-bar"
- responseHeaderModifier:
add:
- name: "response-foo"
value: "response-bar"
backendRefs:
- backendRef:
ref:
type:
group: catalog
groupVersion: v2beta1
kind: Service
name: api-admin
# The virtual port number for the "admin-workload" target port.
port: "90"
```

925
website/content/docs/k8s/multiport/reference/httproute.mdx
Unescape View File

@ -1,925 +0,0 @@
---
layout: docs
page_title: HTTPRoute resource configuration reference
description: The HTTPRoute resource CRD configures L7 HTTP traffic behavior within the service mesh. HTTPRoute is a GAMMA resource that requires the v2 catalog API. Learn how to configure the HTTPRoute CRD with specifications and example configurations.
---
# HTTPRoute resource configuration reference
This page provides reference information for the `HTTPRoute` resource, which defines behavior for L7 HTTP traffic within the service mesh.
This custom resource definition (CRD) describes a resource related to the [Kubernetes GAMMA initiative](https://gateway-api.sigs.k8s.io/concepts/gamma/) that requires the [v2 catalog API](/consul/docs/architecture/v2/catalog). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog). For more information about GAMMA resources, refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/gamma/).
## Configuration model
The following list outlines field hierarchy, language-specific data types, and requirements in an HTTP route CRD. Click on a property name to view additional details, including default values.
- [`apiVersion`](#apiversion): string | required | must be set to `mesh.consul.hashicorp.com/v2beta1`
- [`kind`](#kind): string | required | must be set to `HTTPRoute`
- [`metadata`](#metadata): map | required
- [`name`](#metadata-name): string | required
- [`namespace`](#metadata-namespace): string | optional <EnterpriseAlert inline />
- [`spec`](#spec): map | required
- [`parentRefs`](#spec-parentrefs): map | required
- [`port`](#spec-parentrefs-port): string
- [`ref`](#spec-parentrefs-ref): string | required
- [`name`](#spec-parentrefs-ref-name): string
- [`type`](#spec-parentrefs-ref-type): map
- [`group`](#spec-parentrefs-ref-type): string
- [`groupVersion`](#spec-parentrefs-ref-type): string
- [`kind`](#spec-parentrefs-ref-type): string
- [`rules`](#spec-rules): map | required
- [`backendRefs`](#spec-rules-backendrefs): map
- [`backendRef`](#spec-rules-backendrefs-backendref): map
- [`datacenter`](#spec-rules-backendrefs-backendref-datacenter): string
- [`port`](#spec-rules-backendrefs-backendref-port): string
- [`ref`](#spec-rules-backendrefs-backendref-ref): map
- [`name`](#spec-rules-backendrefs-backendref-ref-name): string
- [`type`](#spec-rules-backendrefs-backendref-ref-type): map
- [`group`](#spec-rules-backendrefs-backendref-ref-type): string
- [`groupVersion`](#spec-rules-backendrefs-backendref-ref-type): string
- [`kind`](#spec-rules-backendrefs-backendref-ref-type): string
- [`filters`](#spec-rules-backendrefs-filters): map
- [`requestHeaderModifier`](#spec-rules-backendrefs-filters-requestheadermodifier): map
- [`add`](#spec-rules-backendrefs-filters-requestheadermodifier): map
- [`set`](#spec-rules-backendrefs-filters-requestheadermodifier): map
- [`remove`](#spec-rules-backendrefs-filters-requestheadermodifier): map
- [`responseHeaderModifier`](#spec-rules-backendrefs-filters-responseheadermodifier): map
- [`add`](#spec-rules-backendrefs-filters-responseheadermodifier): map
- [`set`](#spec-rules-backendrefs-filters-responseheadermodifier): map
- [`remove`](#spec-rules-backendrefs-filters-responseheadermodifier): map
- [`urlRewrite`](#spec-rules-backendrefs-filters-urlrewrite): map
- [`pathPrefix`](#spec-rules-backendrefs-filters-urlrewrite): string
- [`weight`](#spec-rules-backendrefs-weight): number | `1`
- [`filters`](#spec-rules-filters): map
- [`requestHeaderModifier`](#spec-rules-filters-requestheadermodifier): map
- [`add`](#spec-rules-filters-requestheadermodifier): map
- [`set`](#spec-rules-filters-requestheadermodifier): map
- [`remove`](#spec-rules-filters-requestheadermodifier): map
- [`responseHeaderModifier`](#spec-rules-filters-responseheadermodifier): map
- [`add`](#spec-rules-filters-responseheadermodifier): map
- [`set`](#spec-rules-filters-responseheadermodifier): map
- [`remove`](#spec-rules-filters-responseheadermodifier): map
- [`urlRewrite`](#spec-rules-filters-urlrewrite): map
- [`pathPrefix`](#spec-rules-filters-urlrewrite): string
- [`matches`](#spec-rules-matches): map
- [`headers`](#spec-rules-matches-headers): map
- [`name`](#spec-rules-matches-headers-name): string
- [`type`](#spec-rules-matches-headers-type): string
- [`value`](#spec-rules-matches-headers-value): string
- [`method`](#spec-rules-matches-method): string
- [`path`](#spec-rules-matches-path): map
- [`type`](#spec-rules-matches-path-type): string
- [`value`](#spec-rules-matches-path-value): string
- [`queryParams`](#spec-rules-matches-queryparams): map
- [`name`](#spec-rules-matches-queryparams-name): string
- [`type`](#spec-rules-matches-queryparams-type): string
- [`value`](#spec-rules-matches-queryparams-value): string
- [`retries`](#spec-rules-retries): map
- [`number`](#spec-rules-retries-number): map
- [`value`](#spec-rules-retries-number): number
- [`onConditions`](#spec-rules-retries-onconditions): map of strings
- [`onConnectFailure`](#spec-rules-retries-onconnectfailure): boolean | `false`
- [`onStatusCodes`](#spec-rules-retries-onconditions): map of integers
- [`timeouts`](#spec-rules-timeouts): map
- [`idle`](#spec-rules-timeouts-idle): string
- [`request`](#spec-rules-timeouts-request): string
## Complete configuration
When every field is defined, an HTTP route CRD has the following form:
```yaml
apiVersion: mesh.consul.hashicorp.com/v2beta1 # required
kind: HTTPRoute # required
metadata:
name: <crdName>
namespace: <namespace>
spec:
parentRefs:
port: <portRoutedFrom>
- ref:
name: <nameRoutedFrom>
type:
group: <catalog>
groupVersion: <v2beta1>
kind: <Service>
rules:
- backendRefs:
- backendRef:
datacenter: <datacenterRoutedTo>
port: <portRoutedTo>
ref:
name: <nameRoutedTo>
type:
group: <catalog>
groupVersion: <v2beta1>
kind: <Service>
filters:
- requestHeaderModifier:
add:
name: <headerName>
value: <headerValue>
- responseHeaderModifier:
set:
name: <headerName>
value: <headerValue>
urlRewrite:
pathPrefix: <path/prefix>
weight: 1
filters:
requestHeaderModifier:
remove:
name: <headerName>
value: <headerValue>
responseHeaderModifier:
add:
name: <headerName>
value: <headerValue>
urlRewrite:
pathPrefix: <path/prefix>
matches:
headers:
name: <nameToMatch>
type: <HEADER_MATCH_TYPE_EXACT>
value: <valueToMatch>
method: <methodToMatch>
path:
type: <PATH_MATCH_TYPE_EXACT>
value: /
queryParams:
name: <nameToMatch>
type: <QUERY_PARAM_MATCH_TYPE_EXACT>
value: <valueToMatch>
retries:
number:
value: 1
onConditions: ["cancelled", "unavailable"]
onConnectFailure: false
onStatusCodes: [400, 404]
timeouts:
idle: <1s>
request: <1s>
```
## Specification
This section provides details about the fields you can configure in the `HTTPRoute` custom resource definition (CRD).
### `apiVersion`
Specifies the version of the Consul API for integrating with Kubernetes. The value must be `mesh.consul.hashicorp.com/v2beta1`.
#### Values
- Default: None
- This field is required.
- String value that must be set to `mesh.consul.hashicorp.com/v2beta1`.
### `kind`
Specifies the type of CRD to implement. Must be set to `HTTPRoute`.
#### Values
- Default: None
- This field is required.
- Data type: String value that must be set to `HTTPRoute`.
### `metadata`
Map that contains an arbitrary name for the CRD and the namespace it applies to.
#### Values
- Default: None
- Data type: Map
### `metadata.name`
Specifies a name for the CRD. The name is metadata that you can use to reference the resource when performing Consul operations, such as using the `consul resource` command. Refer to [`consul resource`](/consul/docs/k8s/connect/multiport/reference/resource-command) for more information.
#### Values
- Default: None
- This field is required.
- Data type: String
### `metadata.namespace` <EnterpriseAlert inline />
Specifies the namespace that the service resolver 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 `HTTPRoute` CRD. The `apiVersion`, `kind`, and `metadata` fields are siblings of the spec field. All other configurations are children.
When using this CRD, the `spec` field closely resembles the `HTTPRoute` GAMMA resource. Refer to [HTTPRoute in the Kubernetes documentation](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRoute).
#### Values
- Default: None
- This field is required.
- Data type: Map
### `spec.parentRefs`
Specifies the services and other resources to attach the route to. You can only define one `parentsRefs` configuration for each route. To attach the route to multiple resources, specify additional [`spec.parentRefs.ref`](#spec-parentrefs-ref) configurations in the `parentsRefs` block. You can only specify the name of one port for the route. Any resources that send traffic through the route use the same port.
#### Values
- Default: None
- This field is required.
- Data type: Map
### `spec.parentRefs.port`
Specifies the port for the Consul service that the configuration applies to. This parameter can be either a virtual port number, such as a Kubernetes service port, or a non-numeric target port value representing a named workload port.
If you are not targeting a virtual port, specify the workload port name directly.
#### Values
- Default: None
- Data type: String
### `spec.parentRefs.ref`
Specifies the resource that the route attaches to.
#### Values
- Default: None
- Data type: Map
### `spec.parentRefs.ref.name`
Specifies the user-defined name of the resource that the configuration applies to.
#### Values
- Default: None
- Data type: String
### `spec.parentRefs.ref.type`
Specifies the type of resource that the configuration applies to. To reference a service in the Consul catalog, configure the resource type as `catalog.v2beta1.Service`.
#### Values
- Default: None
- Data type: Map containing the following parameters:
| Parameter | Description | Data type | Default |
| :------------ | :------------------------------------------------------------------- | :-------- | :------- |
| `group` | Specifies a group for the resource type within the Kubernetes cluster. To reference a service in the Consul catalog, set this parameter to `catalog`. | String | None |
| `groupVersion` | Specifies a groupVersion for the resource type within the Kubernetes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String | None |
| `kind` | Specifies the kind of the Kubernetes object the resource applies to. To reference a service in the Consul catalog, set this parameter to `Service`. | String | None |
### `spec.rules`
Specifies rules for sidecar proxies to direct a service's HTTP traffic within the service mesh, including filtering, retry, and timeout behavior.
#### Values
- Default: None
- Data type: Map
### `spec.rules.backendRefs`
Specifies the Kubernetes Service backend to direct HTTP traffic to when a request matches the service described in [`spec.parentRefs`](#spec-parentrefs). The Service backend is the collection of endpoint IPs for the service. Refer to [the Kubernetes Gateway API specification](https://gateway-api.sigs.k8s.io/concepts/gamma/#an-overview-of-the-gateway-api-for-service-mesh) for more information about Service backends.
When a valid Service backend cannot be reached and no additional filters apply, traffic that matches the rule returns a 500 status code.
When different Service backends are specified in [`spec.rules.backendRefs.weight`](#spec-rules-backendrefs-weight) and one of the backends is invalid, Consul continues to apply the specified weights instead of adjusting the relative weights to exclude traffic to the invalid backend. For example, when traffic is configured in a 50-50 split between `api` and `admin` and no valid endpoints for `admin` can be reached, the 50% of traffic intended for `admin` returns with a 500 status code.
#### Values
- Default: None
- Data type: Map
### `spec.rules.backendRefs.backendRef`
Specifies an individual Service backend where matching requests should be sent.
#### Values
- Default: None
- Data type: Map
### `spec.rules.backendRefs.backendRef.datacenter`
Specifies the name of the Consul datacenter that registered the Service backend that the configuration routes traffic to.
#### Values
- Default: None
- Data type: String
### `spec.rules.backendRefs.backendRef.port`
Specifies the name of the port for the Consul service that the configuration routes traffic to. This parameter can be either a virtual port number, such as a Kubernetes service port, or a non-numeric target port value representing a named workload port.
If you are not targeting a virtual port, specify the workload port name directly.
#### Values
- Default: None
- Data type: String
### `spec.rules.backendRefs.backendRef.ref`
The Consul service that the configuration routes traffic to.
#### Values
- Default: None
- Data type: Map
### `spec.rules.backendRefs.backendRef.ref.name`
Specifies the user-defined name of the resource that the configuration routes traffic to.
#### Values
- Default: None
- Data type: String
### `spec.rules.backendRefs.backendRef.ref.type`
Specifies the type of resource that the configuration routes traffic to. To reference a service in the Consul catalog, configure the resource type as `catalog.v2beta1.Service`.
#### Values
- Default: None
- Data type: Map containing the following parameters:
| Parameter | Description | Data type | Default |
| `group` | Specifies a group for the resource type within the Kubernetes cluster. To reference a service in the Consul catalog, set this parameter to `catalog`. | String | None |
| `groupVersion` | Specifies a groupVersion for the resource type within the Kubernetes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String | None |
| `kind` | Specifies the kind of the Kubernetes object for the resource. To reference a service in the Consul catalog, set this parameter to `Service`. | String | None |
### `spec.rules.backendRefs.filters`
Specifies filtering behavior for services configured in the same [`spec.rules.backendRefs`](#spec-rules-backendrefs) block.
#### Values
- Default: None
- Data type: Map
### `spec.rules.backendRefs.filters.requestHeaderModifier`
Specifies a set of header modification rules applied to requests routed with the HTTPRoute resource.
#### Values
- Default: None
- Values: Object containing one or more fields that define header modification rules:
- `add`: Map of one or more key-value pairs.
- `set`: Map of one or more key-value pairs.
- `remove`: Map of one or more key-value pairs.
The following table describes how to configure values for request headers:
| Rule | Description | Type |
| --- | --- | --- |
| `add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings |
| `set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings |
| `remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings |
##### Use variable placeholders
For `add` and `set`, if the service is configured to use Envoy as the proxy, the value may contain variables to interpolate dynamic metadata into the value. For example, using the variable `%DOWNSTREAM_REMOTE_ADDRESS%` allows you to pass a value that is generated when the split occurs.
### `spec.rules.backendRefs.filters.responseHeaderModifier`
Specifies a set of header modification rules applied to responses routed with the HTTPRoute resource.
#### Values
- Default: None
- Values: Object containing one or more fields that define header modification rules:
- `add`: Map of one or more key-value pairs.
- `set`: Map of one or more key-value pairs.
- `remove`: Map of one or more key-value pairs.
The following table describes how to configure values for request headers:
| Rule | Description | Type |
| --- | --- | --- |
| `add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings |
| `set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings |
| `remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings |
##### Use variable placeholders
For `add` and `set`, if the service is configured to use Envoy as the proxy, the value may contain variables to interpolate dynamic metadata into the value. For example, using the variable `%DOWNSTREAM_REMOTE_ADDRESS%` allows you to pass a value that is generated when the split occurs.
### `spec.rules.backendRefs.filters.urlRewrite`
Specifies a path to modify the URL with when a request is forwarded.
#### Values
- Default: None
- Data type: Map containing the following parameter:
| Parameter | Description | Data type | Default |
| :------------ | :------------------------------------------------------------------------------------------------- | --------- | ------- |
| `pathPrefix` | Specifies the path that is prepended to the URL. | String | None |
### `spec.rules.backendRefs.weight`
Specifies the proportion of requests routed to the specified service.
This proportion is relative to the sum of all weights in the [`spec.rules.backendRefs`](#spec-rules-backendrefs) block. As a result, weights do not need to add up to 100. When only one backend is specified and the weight is greater then 0, Consul forwards 100% of traffic to the backend.
When this parameter is not specified, Consul defaults to `1`.
#### Values
- Default: `1`
- Data type: Integer
### `spec.rules.filters`
Specifies filtering behavior for all requests that match the service defined in [`spec.parentRefs`](#spec-parent-refs).
#### Values
- Default: None
- Data type: Map
### `spec.rules.filters.requestHeaderModifier`
Specifies a set of header modification rules applied to requests that match the service defined in [`spec.parentRefs`](#spec-parent-refs).
#### Values
- Default: None
- Values: Object containing one or more fields that define header modification rules:
- `add`: Map of one or more key-value pairs.
- `set`: Map of one or more key-value pairs.
- `remove`: Map of one or more key-value pairs.
The following table describes how to configure values for request headers:
| Rule | Description | Type |
| --- | --- | --- |
| `add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings |
| `set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings |
| `remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings |
##### Use variable placeholders
For `add` and `set`, if the service is configured to use Envoy as the proxy, the value may contain variables to interpolate dynamic metadata into the value. For example, using the variable `%DOWNSTREAM_REMOTE_ADDRESS%` allows you to pass a value that is generated when the split occurs.
### `spec.rules.filters.responseHeaderModifier`
Specifies a set of header modification rules applied to responses from services matching [`spec.parentRefs`](#spec-parent-refs).
#### Values
- Default: None
- Values: Object containing one or more fields that define header modification rules:
- `add`: Map of one or more key-value pairs.
- `set`: Map of one or more key-value pairs.
- `remove`: Map of one or more key-value pairs.
The following table describes how to configure values for request headers:
| Rule | Description | Type |
| --- | --- | --- |
| `add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings |
| `set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings |
| `remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings |
##### Use variable placeholders
For `add` and `set`, if the service is configured to use Envoy as the proxy, the value may contain variables to interpolate dynamic metadata into the value. For example, using the variable `%DOWNSTREAM_REMOTE_ADDRESS%` allows you to pass a value that is generated when the split occurs.
### `spec.rules.filters.urlRewrite`
Specifies a path to modify the URL with when a request matching [`spec.parentRefs`](#spec-parent-refs) is forwarded.
#### Values
- Default: None
- Data type: Map containing the following parameter:
| Parameter | Description | Data type | Default |
| :------------ | :------------------------------------------------------------------------------------------------- | --------- | ------- |
| `pathPrefix` | Specifies a path to prepend to the URL when a request matching [`spec.parentRefs`](#spec-parent-refs) is forwarded. | String | None |
### `spec.rules.matches`
Specifies rules for matching traffic to services described in [`spec.parentRefs`](#spec-parent-refs) according to the request header or method.
#### Values
- Default: None
- Data type: Map
### `spec.rules.matches.headers`
Specifies criteria for matching HTTP request headers.
When [`spec.rules.matches.headers.value`] is specified multiple times, a request must match all of the specified values for the route to be selected.
#### Values
- Default: None
- Data type: Map
### `spec.rules.matches.headers.name`
Specifies the name of a HTTP request header to match on.
#### Values
- Default: None
- Data type: String
### `spec.rules.matches.headers.type`
Specifies a type of match to perform on the HTTP request header. Supported match types include: unspecified, exact, regex, present, prefix, and suffix.
#### Values
- Default: None
- Data type: String that should match one of the following values:
- `HEADER_MATCH_TYPE_UNSPECIFIED`
- `HEADER_MATCH_TYPE_EXACT`
- `HEADER_MATCH_TYPE_REGEX`
- `HEADER_MATCH_TYPE_PRESENT`
- `HEADER_MATCH_TYPE_PREFIX`
- `HEADER_MATCH_TYPE_SUFFIX`
### `spec.rules.matches.headers.value`
Specifies the value of the HTTP request header to match. When this field is specified multiple times, a request must match all of the specified values for the route to be selected.
#### Values
- Default: None
- Data type: String
### `spec.rules.matches.method`
Specifies the value of the HTTP method to match.
#### Values
- Default: None
- Data type: String
### `spec.rules.matches.path`
Specifies an HTTP request path to match. When this field is not specified, the CRD matches on the `/` path by default.
#### Values
- Default: None
- Data type: Map
### `spec.rules.matches.path.type`
Specifies a type of match to perform on the HTTP path. Supported match types include: unspecified, exact, prefix, and regex.
#### Values
- Default: None
- Data type: String that should match one of the following values:
- `PATH_MATCH_TYPE_UNSPECIFIED`
- `PATH_MATCH_TYPE_EXACT`
- `PATH_MATCH_TYPE_PREFIX`
- `PATH_MATCH_TYPE_REGEX`
### `spec.rules.matches.path.value`
Value of the HTTP path to match on.
#### Values
- Default: `/`
- Data type: String
### `spec.rules.matches.queryParams`
Specifies HTTP query parameters to match on. When [`spec.rules.matches.queryParams.value`] is specified multiple times, a request must match all of the specified values for the route to be selected.
#### Values
- Default: None
- Data type: Map
### `spec.rules.matches.queryParams.name`
Specifies the name of the HTTP query parameter to match. Query parameters matches require exact matches between strings.
If multiple entries specify identical query parameter names, only the first entry with an equivalent name matches. Subsequent entries with an equivalent query parameter name are ignored. If an HTTP request repeats a query parameter, the behavior is intentionally undefined because different data planes have different capabilities. However, we recommend that matching against the first value of the parameter if the data plane supports it, as this behavior is expected in other load balancing contexts.
Do not route traffic based on repeated query parameters, as differences in data plane implementations may produce errors.
#### Values
- Default: None
- Data type: String
### `spec.rules.matches.queryParams.type`
Specifies a type of match to perform on the HTTP request header. Supported match types include: unspecified, exact, regex, and present.
#### Values
- Default: None
- Data type: String that should match one of the following values:
- `HEADER_MATCH_TYPE_UNSPECIFIED`
- `HEADER_MATCH_TYPE_EXACT`
- `HEADER_MATCH_TYPE_REGEX`
- `HEADER_MATCH_TYPE_PRESENT`
### `spec.rules.matches.queryParams.value`
Specifies the value of the HTTP query parameter to match.
#### Values
- Default: None
- Data type: String
### `spec.rules.retries`
Specifies retry logic for routing HTTP traffic.
#### Values
- Default: None
- Data type: Map
### `spec.rules.retries.number`
Specifies the number of retries to attempt when a request fails.
#### Values
- Default: None
- Data type: Map that contains the following parameter:
| Parameter | Description | Data type | Default |
| :-------- | :------------------------------------------- | --------- | ------- |
| `value` | Specifies the number of retries to attempt. | Integer | None |
### `spec.rules.retries.onConditions`
Specifies Envoy conditions that cause an automatic retry attempt.
#### Values
- Default: None
- Data type: Map of strings
### `spec.rules.retries.onConnectFailure`
Enables an automatic retry attempt when a connection failure error occurs.
#### Values
- Default: `false`
- Data type: Boolean
### `spec.rules.retries.onStatusCodes`
Specifies the response status codes that are eligible for retry attempts.
#### Values
- Default: None
- Data type: Map of integers
### `spec.rules.timeouts`
Specifies timeout logic when routing HTTP traffic
#### Values
- Default: None
- Data type: Map
### `spec.rules.timeouts.idle`
Specifies the total amount of time permitted for the request stream to be idle before a timeout occurs.
This field accepts a string indicating the number of seconds. For example, indicate five seconds with `5s` and five milliseconds with `0.005s`.
#### Values
- Default: None
- Data type: String
### `spec.rules.timeouts.request`
Specifies the total amount of time spent processing the entire downstream request, including retries, before triggering a timeout.
This field accepts a string indicating the number of seconds. For example, indicate five seconds with `5s` and five milliseconds with `0.005s`.
#### Values
- Default: None
- Data type: String
## Examples
The following examples demonstrate common HTTP route CRD configuration patterns for specific use cases.
### Split HTTP traffic between two ports
The following example splits traffic for the `api` service. HTTP traffic for services registered to the Consul catalog that are available at the `api` port is split so that 50% of the traffic routes to the service at the `api` port and 50% routes to the service at the `admin` port.
```yaml
apiVersion: mesh.consul.hashicorp.com/v2beta1
kind: HTTPRoute
metadata:
name: api-split
namespace: default
spec:
parentRefs:
- ref:
type:
group: catalog
groupVersion: v2beta1
kind: Service
name: api
# The virtual port number for the "api-workload" target port.
port: "80"
rules:
- backendRefs:
- backendRef:
ref:
type:
group: catalog
groupVersion: v2beta1
kind: Service
name: api
# The virtual port number for the "api-workload" target port.
port: "80"
weight: 50
- backendRef:
ref:
type:
group: catalog
groupVersion: v2beta1
kind: Service
name: api
# The virtual port number for the "admin-workload" target port.
port: "90"
weight: 50
```
### Route traffic by matching header
The following examples routes HTTP traffic for the `api` service according to its header HTTP traffic for services registered to the Consul catalog that are available at the `api-workload` port are routed according to the following criteria:
- For traffic with a header that contains a `x-debug` value of exactly `1`, Consul routes to the `api` service at the `api-workload` port.
- For traffic with a header that contains a `x-debug` value of exactly `2`, Consul routes to the `api-admin` service at the `admin-workload` port.
This example also configures Consul to modify request and response headers when routing traffic.
```yaml
apiVersion: mesh.consul.hashicorp.com/v2beta1
kind: HTTPRoute
metadata:
name: api-filter
namespace: default
spec:
parentRefs:
- ref:
type:
group: catalog
groupVersion: v2beta1
kind: Service
name: api
# The virtual port number for the "api-workload" target port.
port: "80"
rules:
- matches:
- headers:
- type: "HEADER_MATCH_TYPE_EXACT"
name: "x-debug"
value: "1"
filters:
- requestHeaderModifier:
add:
- name: "request-foo"
value: "request-bar"
- responseHeaderModifier:
add:
- name: "response-foo"
value: "response-bar"
backendRefs:
- backendRef:
ref:
type:
group: catalog
groupVersion: v2beta1
kind: Service
name: api
# The virtual port number for the "api-workload" target port.
port: "80"
- matches:
- headers:
- type: "HEADER_MATCH_TYPE_EXACT"
name: "x-debug"
value: "2"
filters:
- requestHeaderModifier:
add:
- name: "request-foo"
value: "request-bar"
- responseHeaderModifier:
add:
- name: "response-foo"
value: "response-bar"
backendRefs:
- backendRef:
ref:
type:
group: catalog
groupVersion: v2beta1
kind: Service
name: api-admin
# The virtual port number for the "admin-workload" target port.
port: "90"
```
### Route traffic by matching header and query parameter
The following examples routes HTTP traffic for the `api` service according to its header HTTP traffic for services registered to the Consul catalog that are available at the `api-workload` port are routed according to the following criteria:
- For traffic with a header _and_ a query parameter that both contain `x-debug` values of exactly `1`, Consul routes to the `api` service at the `api-workload` port.
- For traffic with a header _and_ a query parameter that both contain `x-debug` values of exactly `2`, Consul routes to the `api-admin` service at the `admin-workload` port.
```yaml
apiVersion: mesh.consul.hashicorp.com/v2beta1
kind: HTTPRoute
metadata:
name: api-match-split
namespace: default
spec:
parentRefs:
- ref:
type:
group: catalog
groupVersion: v2beta1
kind: Service
name: api
# The virtual port number for the "api-workload" target port.
port: "80"
rules:
- matches:
- headers:
- type: "HEADER_MATCH_TYPE_EXACT"
name: "x-debug"
value: "1"
queryParams:
- type: "QUERY_PARAM_MATCH_TYPE_EXACT"
name: "x-debug"
value: "1"
backendRefs:
- backendRef:
ref:
type:
group: catalog
groupVersion: v2beta1
kind: Service
name: api
# The virtual port number for the "api-workload" target port.
port: "80"
- matches:
- headers:
- type: "HEADER_MATCH_TYPE_EXACT"
name: "x-debug"
value: "2"
queryParams:
- type: "QUERY_PARAM_MATCH_TYPE_EXACT"
name: "x-debug"
value: "2"
backendRefs:
- backendRef:
ref:
type:
group: catalog
groupVersion: v2beta1
kind: Service
name: api-admin
# The virtual port number for the "admin-workload" target port.
port: "90"
```

691
website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx
Unescape View File

@ -1,691 +0,0 @@
---
layout: docs
page_title: ProxyConfiguration resource configuration reference
description: The ProxyConfiguration resource CRD configures sidecar proxy behavior within the service mesh. Learn how to configure bootstrap and dynamic configurations for proxies according to Workload characteristics with specifications and example configurations.
---
# ProxyConfiguration resource configuration reference
This page provides reference information for the `ProxyConfigurations` resource, which defines proxy behavior for traffic within the service mesh. The resource specifies both bootstrap and dynamic configurations for proxies.
This custom resource definition (CRD) describes a resource related to the [Kubernetes GAMMA initiative](https://gateway-api.sigs.k8s.io/concepts/gamma/) that requires the [v2 catalog API](/consul/docs/architecture/v2/catalog). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog). For more information about GAMMA resources, refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/gamma/).
## Configuration model
The following list outlines field hierarchy, language-specific data types, and requirements in a ProxyConfiguration CRD. Click on a property name to view additional details, including default values.
- [`apiVersion`](#apiversion): string | required | must be set to `mesh.consul.hashicorp.com/v2beta1`
- [`kind`](#kind): string | required | must be set to `ProxyConfiguration`
- [`metadata`](#metadata): map | required
- [`name`](#metadata-name): string | required
- [`namespace`](#metadata-namespace): string | optional <EnterpriseAlert inline />
- [`spec`](#spec): map | required
- [`workloads`](#spec-workloads): map
- [`filter`](#spec-workloads): string
- [`names`](#spec-workloads): array of strings
- [`prefixes`](#spec-workloads): array of strings
- [`bootstrapConfig`](#spec-bootstrapconfig): map
- [`dogstatsdUrl`](#spec-bootstrapconfig): string
- [`overrideJsonTpl`](#spec-bootstrapconfig): string
- [`prometheusBindAddr`](#spec-bootstrapconfig): string
- [`readyBindAddr`](#spec-bootstrapconfig): string
- [`staticClustersJson`](#spec-bootstrapconfig): string
- [`staticListenersJson`](#spec-bootstrapconfig): string
- [`statsBindAddr`](#spec-bootstrapconfig): string
- [`statsConfigJson`](#spec-bootstrapconfig): string
- [`statsFlushInterval`](#spec-bootstrapconfig): string
- [`statsSinksJson`](#spec-bootstrapconfig): string
- [`statsTags`](#spec-bootstrapconfig): array of strings
- [`statsdUrl`](#spec-bootstrapconfig): string
- [`telemetryCollectorBindSocketDir`](#spec-bootstrapconfig): string
- [`tracingConfigJson`](#spec-bootstrapconfig): string
- [`dynamicConfig`](#spec-dynamicconfig): map
- [`accessLogs`](#spec-dynamicconfig-accesslogs): map
- [`enabled`](#spec-dynamicconfig-accesslogs-enabled): boolean | `false`
- [`disableListenerLogs`](#spec-dynamicconfig-accesslogs-disablelistenerlogs): boolean | `false`
- [`jsonFormat`](#spec-dynamicconfig-accesslogs-jsonformat): string
- [`path`](#spec-dynamicconfig-accesslogs-path): string
- [`textFormat`](#spec-dynamicconfig-accesslogs-textformat): string
- [`type`](#spec-dynamicconfig-accesslogs-type): string
- [`exposeConfig`](#spec-dynamicconfig-exposeconfig): map
- [`exposePaths`](#spec-dynamicconfig-exposeconfig-exposepaths): map
- [`listenerPort`](#spec-dynamicconfig-exposeconfig-exposepaths-listenerport): integer
- [`localPathPort`](#spec-dynamicconfig-exposeconfig-exposepaths-localpathport): integer
- [`path`](#spec-dynamicconfig-exposeconfig-exposepaths-path): string
- [`protocol`](#spec-dynamicconfig-exposeconfig-exposepaths-protocol): string
- [`inboundConnections`](#spec-dynamicconfig-inboundconnections): map
- [`balanceInboundConnections`](#spec-dynamicconfig-inboundconnections-balanceinboundconnections): string
- [`maxInboundConnections`](#spec-dynamicconfig-exposeconfig-inboundconnections-maxinboundconnections): integer
- [`listenerTracingJson`](#spec-dynamicconfig-listenertracingjson): string
- [`localClusterJson`](#spec-dynamicconfig-localclusterjson): string
- [`localConnection`](#spec-dynamicconfig-localconnection): map
- [`connectTimeout`](#spec-dynamicconfig-localconnection-connecttimeout): string
- [`requestTimeout`](#spec-dynamicconfig-localconnection-requesttimeout): string
- [`meshGatewayMode`](#spec-dynamicconfig-meshgatewaymode): string
- [`mode`](#spec-dynamicconfig-mode): string
- [`publicListenerJson`](#spec-dynamicconfig-publiclistenerjson): string
- [`transparentProxy`](#spec-dynamicconfig-transparentproxy): map
- [`dialedDirectly`](#spec-dynamicconfig-transparentproxy-dialeddirectly): boolean | `false`
- [`outboundListenerPort`](#spec-dynamicconfig-transparentproxy-outboundlistenerport): integer | `15001`
## Complete configuration
When every field is defined, an ProxyConfigurations CRD has the following form:
```yaml
apiVersion: mesh.consul.hashicorp.com/v2beta1 # required
kind: ProxyConfiguration # required
metadata:
name: <crdName>
namespace: <namespace>
spec:
workloads: # required
filter: "Service.Meta.version == v1"
names: ["api", "admin"]
prefixes: ["<pre>", "<fix>"]
bootstrapConfig:
dogstatsdUrl: <udp://127.0.0.1:8125>
overrideJsonTpl: <escapeHatchTemplate>
prometheusBindAddr: <0.0.0.0>
readyBindAddr: <ip:port>
staticClustersJson: <jsonObject>
staticListenersJson: <jsonObject>
statsBindAddr: <0.0.0.0>
statsConfigJson: <jsonObject>
statsFlushInterval: 5000ms
statsSinkJson: <jsonObject>
statsTags:
- <customTag>
statsdUrl: <udp://127.0.0.1:8125>
telemetryCollectorBindSocketDir: <path/to/directory>
tracingConfigJson: <jsonObject>
dynamicConfig:
accessLogs:
enabled: false
disableListenerLogs: false
jsonFormat: <jsonObject>
path: <log/output/path>
textFormat: <customFormatString>
type: <LOG_SINK_TYPE_DEFAULT>
exposeConfig:
exposePaths:
listenerPort: 42
localPathPort: 4242
path: </metrics>
protocol: <EXPOSE_PATH_PROTOCOL_HTTP>
inboundConnections:
balanceInboundConnections: <exact_balance>
maxInboundConnections: 1024
listenerTracingJson: <jsonObject>
localClusterJson: <jsonObject>
localConnection:
connectTimeout: <1s>
requestTimeout: <1s>
meshGatewayMode: <MESH_GATEWAY_MODE_LOCAL>
mode: <PROXY_MODE_TRANSPARENT>
publicListenerJson: <jsonObject>
transparentProxy:
dialedDirectly: false
outboundListenerPort: 15001
```
## Specification
This section provides details about the fields you can configure in the `ProxyConfiguration` custom resource definition (CRD).
### `apiVersion`
Specifies the version of the Consul API for integrating with Kubernetes. The value must be `mesh.consul.hashicorp.com/v2beta1`.
#### Values
- Default: None
- This field is required.
- String value that must be set to `mesh.consul.hashicorp.com/v2beta1`.
### `kind`
Specifies the type of CRD to implement. Must be set to `ProxyConfiguration`.
#### Values
- Default: None
- This field is required.
- Data type: String value that must be set to `ProxyConfiguration`.
### `metadata`
Map that contains an arbitrary name for the CRD and the namespace it applies to.
#### Values
- Default: None
- Data type: Map
### `metadata.name`
Specifies a name for the CRD. The name is metadata that you can use to reference the resource when performing Consul operations, such as using the `consul resource` command. Refer to [`consul resource`](/consul/docs/k8s/connect/multiport/reference/resource-command) for more information.
#### Values
- Default: None
- This field is required.
- Data type: String
### `metadata.namespace` <EnterpriseAlert inline />
Specifies the namespace that the proxy 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 `ProxyConfiguration` CRD. 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.workloads`
Specifies the workloads that the proxy configuration applies to. You can select workloads by name, prefix, or by using a filter expression.
#### Values
- Default: None
- This field is required.
- Data type: Map that can contain the following parameters:
| Parameter | Description | Data type | Default |
| :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
| `filter` | Specifies an expression that filters workloads. For more information about creating and using expressions to filter, refer to [filtering](/consul/api-docs/features/filtering). | String | None |
| `names` | Specifies one or more names of workloads the proxy configuration applies to. | Array of strings | None |
| `prefixes` | Specifies one or more prefixes. Proxy configurations apply to workloads with one of the prefixes. | Array of strings | None |
### `spec.bootstrapConfig`
Specifies initial bootstrap settings for the Envoy proxy, as well as proxy configuration settings that require the proxy to restart when applied. For more information, refer to [Envoy proxy bootstrap configuration](/consul/docs/connect/proxies/envoy#bootstrap-configuration).
#### Values
- Default: None
- Data type: Map
### `spec.bootstrapConfig.dogstatsdUrl`
Specifies a URL that identifies a DataDog DogStatsD listener. Envoy sends metrics to this listener.
Format the URL as `udp://ip:port` or `unix://uds/path`. For example, `udp://127.0.0.1:8125` configures a local UDP DogStatsD listener for every host. TCP is not supported.
The UDP URL must use an IP address. DNS names are not supported.
For more information about configuring a UNIX domain socket with DogStatsD, refer to [the DataDog documentation](https://docs.datadoghq.com/developers/dogstatsd/unix_socket?tab=kubernetes#setup).
#### Values
- Default: None
- Data type: String
### `spec.bootstrapConfig.overrideJsonTpl`
<Warning>
This field offers complete control of the proxy's bootstrap. Be aware that major deviations from the default template may break Consul's ability to correctly manage the proxy or enforce its security model.
</Warning>
Specifies a template in Go template syntax to use in place of [the default template](https://github.com/hashicorp/consul/blob/71d45a34601423abdfc0a64d44c6a55cf88fa2fc/command/connect/envoy/bootstrap_tpl.go#L129) when generating the bootstrap configuration using the [`consul connect envoy` command](/consul/commands/connect/envoy). For information about the variables Consul can interpolate in the template, refer to the [documentation in `bootstrap_tpl.go`](https://github.com/hashicorp/consul/blob/71d45a34601423abdfc0a64d44c6a55cf88fa2fc/command/connect/envoy/bootstrap_tpl.go#L5).
Refer to [Envoy proxy escape-hatch overrides](/consul/docs/connect/proxies/envoy#escape-hatch-overrides) for more information.
#### Values
- Default: None
- Data type: String
### `spec.bootstrapConfig.prometheusBindAddr`
Configures the proxy to expose a Prometheus metrics endpoint to the public network. Format the endpoint as `ip:port`. The port and IP and port combination must be free within the network namespace where the proxy runs. The IP `0.0.0.0` binds to all available interfaces or a pod IP address if supported by your existing network settings.
#### Values
- Default: None
- Data type: String
### `spec.bootstrapConfig.readyBindAddr`
Specifies the location to configure the proxy's readiness probe. Format as `ip:port`.
By default, the proxy does not have a readiness probe configured on it.
#### Values
- Default: None
- Data type: String
### `spec.bootstrapConfig.staticClustersJson`
Specifies one or more [Envoy clusters](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/cluster/v3/cluster.proto) to append to the array of [static clusters](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/bootstrap/v3/bootstrap.proto#envoy-v3-api-field-config-bootstrap-v3-bootstrap-staticresources-clusters) in the bootstrap configuration.
This field enables you to add custom clusters, such as tracing sinks, to the bootstrap configuration. In order to configure a single cluster, specify a single JSON object with the cluster details.
Refer to [Envoy proxy advanced bootstrap options](/consul/docs/connect/proxies/envoy#advanced-bootstrap-options) for more information and examples.
#### Values
- Default: None
- Data type: String
### `spec.bootstrapConfig.staticListenersJson`
Specifies one or more [Envoy listeners](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/listener/v3/listener.proto) to append to the array of [static listeners](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/bootstrap/v3/bootstrap.proto#envoy-v3-api-field-config-bootstrap-v3-bootstrap-staticresources-listeners) definitions.
You can use this field to set up limited access that bypasses the service mesh's mTLS or authorization for health checks or metrics.
Refer to [Envoy proxy advanced bootstrap options](/consul/docs/connect/proxies/envoy#advanced-bootstrap-options) for more information and examples.
#### Values
- Default: None
- Data type: String
### `spec.bootstrapConfig.statsBindAddr`
Specifies that the proxy should expose the `/stats` prefix to the _public_ network at the `ip:port` provided. The IP and port combination must be free within the network namespace where the proxy runs. The IP `0.0.0.0` binds to all available interfaces or a pod IP address if supported by your existing network settings.
#### Values
- Default: None
- Data type: String
### `spec.bootstrapConfig.statsConfigJson`
Specifies a complete [stats config](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/bootstrap/v3/bootstrap.proto#envoy-v3-api-field-config-bootstrap-v3-bootstrap-stats-config).
When provided, this field overrides [`spec.bootstrapConfig.statsTags`](#spec-bootstrapconfig-statstags) and enables full control over dynamic tag replacements.
Refer to [Envoy proxy advanced bootstrap options](/consul/docs/connect/proxies/envoy#advanced-bootstrap-options) for more information and examples.
#### Values
- Default: None
- Data type: String
### `spec.bootstrapConfig.statsFlushInterval`
Configures Envoy's [`stats_flush_interval`](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/bootstrap/v3/bootstrap.proto#envoy-v3-api-field-config-bootstrap-v3-bootstrap-stats-flush-interval), which measures the length of the interval between stats sink flushes.
#### Values
- Default: None
- Data type: String
### `spec.bootstrapConfig.statsSinkJson`
Specifies one or more [stats sinks](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/bootstrap/v3/bootstrap.proto#envoy-v3-api-field-config-bootstrap-v3-bootstrap-stats-sinks) to append to sinks defined using [`spec.bootstrapConfig.statsdUrl`](#spec-bootstrapconfig-statsdurl) or [`spec.bootstrapConfig.dogstatsdUrl`](#spec-bootstrapconfig-dogstatsdurl).
Refer to [Envoy proxy advanced bootstrap options](/consul/docs/connect/proxies/envoy#advanced-bootstrap-options) for more information and examples.
#### Values
- Default: None
- Data type: String
### `spec.bootstrapConfig.statsTags`
Specifies one or more static tags to add to all metrics produced by the proxy.
#### Values
- Default: None
- Data type: Array of strings
### `spec.bootstrapConfig.statsdUrl`
Specifies a URL that identifies a StatsD listener. Envoy sends metrics to this listener.
Format the URL as `udp://ip:port`. For example, `udp://127.0.0.1:8125` configures a local StatsD listener for every host. TCP is not supported.
The URL must use an IP address. DNS names are not supported.
#### Values
- Default: None
- Data type: String
### `spec.bootstrapConfig.telemetryCollectorBindSocketDir`
Specifies the directory of the Unix socket Envoy sends metrics to so that the Consul telemetry collector can collect them.
The socket is not configured by default.
#### Values
- Default: None
- Data type: String
### `spec.bootstrapConfig.tracingConfigJson`
Specifies a configuration for an external tracing provider as described in [the Envoy documentation](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/bootstrap/v3/bootstrap.proto#envoy-v3-api-field-config-bootstrap-v3-bootstrap-tracing). Most tracing providers also require adding static clusters to define the endpoints to send tracing data to.
Refer to [Envoy proxy advanced bootstrap options](/consul/docs/connect/proxies/envoy#advanced-bootstrap-options) for more information and examples.
#### Values
- Default: None
- Data type: String
### `spec.dynamicConfig`
Specifies configuration settings for the Envoy proxy that are applied without restarting the proxy. For more information, refer to [Envoy proxy dynamic configuration](/consul/docs/connect/proxies/envoy#dynamic-configuration).
#### Values
- Default: None
- Data type: Map
### `spec.dynamicConfig.accessLogs`
Specifies the format and output for the proxy's access logs.
#### Values
- Default: None
- Data type: Map
### `spec.dynamicConfig.accessLogs.enabled`
When set to `true`, this parameter enables access logs for the proxy.
#### Values
- Default: `false`
- Data type: Boolean
### `spec.dynamicConfig.accessLogs.usableListenerLogs`
When set to `true`, this parameter disables listener logs for connections that the proxy rejected because they did not have a matching listener filter.
#### Values
- Default: `false`
- Data type: Boolean
### `spec.dynamicConfig.accessLogs.jsonFormat`
Specifies a JSON format dictionary for the access logs. Refer to [format dictionaries in the Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#format-dictionaries) for more information.
When this field is specified, you cannot also specify [`spec.dynamicConfig.accessLogs.textFormat`](#spec-dynamicconfig-accesslogs-textformat) in the same configuration.
### `spec.dynamicConfig.accessLogs.path`
Specifies a file output path for the access logs.
#### Values
- Default: None
- Data type: String
### `spec.dynamicConfig.accessLogs.textFormat`
Specifies a format string for the access logs. Refer to [default format string in the Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#default-format-string) for more information.
When this field is specified, you cannot also specify [`spec.dynamicConfig.accessLogs.jsonFormat`](#spec-dynamicconfig-accesslogs-jsonformat) in the same configuration.
#### Values
- Default: None
- Data type: String
### `spec.dynamicConfig.accessLogs.type`
Specifies the output type for the access logs.
#### Values
- Default: None
- Data type: String containing one of the following values:
- `LOG_SINK_TYPE_DEFAULT`
- `LOG_SINK_TYPE_FILE`
- `LOG_SINK_TYPE_STDERR`
- `LOG_SINK_TYPE_STDOUT`
### `spec.dynamicConfig.exposeConfig`
Specifies configurations for exposing the proxy.
Refer to [expose paths configuration reference](/consul/docs/connect/proxies/proxy-config-reference#expose-paths-configuration-reference) for more information.
#### Values
- Default: None
- Data type: Map
### `spec.dynamicConfig.exposeConfig.exposePaths`
Specifies a configuration for exposing an HTTP path through the proxy.
Refer to [expose paths configuration reference](/consul/docs/connect/proxies/proxy-config-reference#expose-paths-configuration-reference) for more information.
#### Values
- Default: None
- Data type: Map
### `spec.dynamicConfig.exposeConfig.exposePaths.listenerPort`
Specifies the port where the proxy listens for connections. This port must be available for the listener to be set up. If the port is not free, Envoy does not expose a listener for the path but the proxy registration does not fail.
#### Values
- Default: None
- Data type: Integer
### `spec.dynamicConfig.exposeConfig.exposePaths.localPathPort`
Specifies the port where the local service is listening for connections to the path.
#### Values
- Default: None
- Data type: Integer
### `spec.dynamicConfig.exposeConfig.exposePaths.path`
The HTTP path to expose. Prefix the path with a slash. For example, `/metrics`.
#### Values
- Default: None
- Data type: String
### `spec.dynamicConfig.exposeConfig.exposePaths.protocol`
Specifies the protocol of the listener, either HTTP or HTTP/2. For gRPC, use HTTP/2.
#### Values
- Default: None
- Data type: String containing one of the following values:
- `EXPOSE_PATH_PROTOCOL_HTTP`
- `EXPOSE_PATH_PROTOCOL_HTTP2`
### `spec.dynamicConfig.inboundConnections`
Specifies configurations for how the proxy handles inbound connections.
#### Values
- Default: None
- Data type: Map
### `spec.dynamicConfig.inboundConnections.balanceInboundConnections`
Specifies the strategy for balancing inbound connections across Envoy worker threads. Consul's service mesh Envoy integration supports the following values:
| Value | Description |
| :---- | :---------- |
| Empty string | Inbound connections are not balanced. |
| `exact_balance` | Balances inbound connections with [Envoy's Exact Balance Strategy](https://cloudnative.to/envoy/api-v3/config/listener/v3/listener.proto.html#config-listener-v3-listener-connectionbalanceconfig-exactbalance). |
#### Values
- Default: `""`
- Data type: String
### `spec.dynamicConfig.inboundConnections.maxInboundConnections`
Specifies the maximum number of concurrent inbound connections to the local application instance. If not specified, inherits the Envoy default of `1024`.
#### Values
- Default: `1024`
- Data type: Integer
### `spec.dynamicConfig.listenerTracingJson`
Specifies a tracing configuration to be inserted in the proxy's public and upstreams listeners. Refer to [the Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-msg-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-tracing) for more information.
#### Values
- Default: None
- Data type: String
### `spec.dynamicConfig.localClusterJson`
Specifies a complete Envoy cluster to be delivered in place of the local application cluster. Use this field to customize timeouts, rate limits, and load balancing strategy.
Refer to [cluster configuration in the Envoy documentation](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/cluster/v3/cluster.proto) for more information.
#### Values
- Default: None
- Data type: String
### `spec.dynamicConfig.localConnection`
Specifies timeout settings for the proxy's connection to the local application. Apply settings separately for each port.
Specify this field as a map containing a key/value. The map keys correspond to port names on the workload. The value contains this parameter's sub-fields.
#### Values
- Default: None
- Data type: Map
### `spec.dynamicConfig.localConnection.connectTimeout`
Specifies the length of time the proxy is allowed to attempt connections to the local application instance before timing out.
This field accepts a string indicating the number of seconds. For example, indicate five seconds with `5s` and five milliseconds with `0.005s`.
#### Values
- Default: None
- Data type: String
### `spec.dynamicConfig.localConnection.requestTimeout`
Specifies the length of time the proxy is allowed to attempt HTTP requests to the local application instance. Applies to HTTP-based protocols only.
This field accepts a string indicating the number of seconds. For example, indicate five seconds with `5s` and five milliseconds with `0.005s`.
#### Values
- Default: None
- Data type: String
### `spec.dynamicConfig.meshGatewayMode`
Specifies the proxy's mode of operation for resolving upstreams in remote datacenter destinations. Refer to [Mesh gateway configuration reference](/consul/docs/connect/proxies/proxy-config-reference#mesh-gateway-configuration-reference) for more information.
#### Values
- Default: None
- Data type: String containing one of the following values:
- `MESH_GATEWAY_MODE_UNSPECIFIED`
- `MESH_GATEWAY_MODE_NONE`
- `MESH_GATEWAY_MODE_LOCAL`
- `MESH_GATEWAY_MODE_REMOTE`
### `spec.dynamicConfig.mode`
Configures the proxy to operate in transparent, direct, or default mode. Refer to [proxy modes](/consul/docs/connect/proxies/proxy-config-reference#proxy-modes) for more information.
#### Values
- Default: None
- Data type: String containing one of the following values:
- `PROXY_MODE_DEFAULT`
- `PROXY_MODE_TRANSPARENT`
- `PROXY_MODE_DIRECT`
### `spec.dynamicConfig.publicListenerJson`
Specifies a complete Envoy listener for Consul to deliver in place of the main public listener that the proxy uses to accept inbound connections. Refer to [escape-hatch overrides](/consul/docs/connect/proxies/envoy#escape-hatch-overrides) for more information
#### Values
- Default: None
- Data type: String
### `spec.dynamicConfig.transparentProxy`
Specifies additional configurations for operating proxies in transparent proxy mode. Refer to [transparent proxy configuration reference](/consul/docs/connect/proxies/proxy-config-reference#transparent-proxy-configuration-reference) for more information.
#### Values
- Default: None
- Data type: Map
### `spec.dynamicConfig.transparentProxy.dialedDirectly`
Determines whether this proxy instance's IP address can be dialed directly by transparent proxies. Transparent proxies typically dial upstreams using the _virtual_ tagged address, which load balances across instances. A database cluster with a leader is an example where dialing individual instances can be helpful.
#### Values
- Default: `false`
- Data type: Boolean
### `spec.dynamicConfig.transparentProxy.outboundListenerPort`
Specifies the port the proxy listens on for outbound traffic to capture and redirect.
#### Values
- Default: `15001`
- Data type: Integer
## Examples
The following examples demonstrate common ProxyConfiguration CRD configuration patterns for specific use cases.
### Set a timeout on a subset of proxies
The following example configures sidecar proxies scheduled with workloads whose names begin with `static-server-`. When these workloads attempt connections with the local `web` application, both requests and responses time out after 123 second.
```yaml
apiVersion: mesh.consul.hashicorp.com/v2beta1
kind: ProxyConfiguration
metadata:
name: static-server-override-one
spec:
workloads:
prefixes:
- "static-server-"
bootstrapConfig:
statsBindAddr: "127.0.0.1:6666"
dynamicConfig:
# Only the web port should be enabled using the TPs
localConnection:
web:
connectTimeout: "123s" # This ALWAYS has to end in 's'. If you want ms, you need to use "0.123s"
requestTimeout: "123s"
```

345
website/content/docs/k8s/multiport/reference/tcproute.mdx
Unescape View File

@ -1,345 +0,0 @@
---
layout: docs
page_title: TCPRoute resource configuration reference
description: The TCPRoute resource CRD configures L4 TCP behavior within the service mesh. TCPRoute is a GAMMA resource that requires the v2 catalog API. Learn how to configure the TCPRoute CRD with specifications and example configurations.
---
# TCPRoute resource configuration reference
This page provides reference information for the `TCPRoute` resource, which defines Transport Layer (L4) TCP traffic within the service mesh.
This custom resource definition (CRD) describes a resource related to the [Kubernetes GAMMA initiative](https://gateway-api.sigs.k8s.io/concepts/gamma/) that requires the [v2 catalog API](/consul/docs/architecture/v2/catalog). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog). For more information about GAMMA resources, refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/gamma/).
## Configuration model
The following list outlines field hierarchy, language-specific data types, and requirements in an TCP route CRD. Click on a property name to view additional details, including default values.
<Tabs>
<Tab heading="YAML" group="yaml">
- [`apiVersion`](#apiversion): string | required | must be set to `mesh.consul.hashicorp.com/v2beta1`
- [`kind`](#kind): string | required | must be set to `TCPRoute`
- [`metadata`](#metadata): map | required
- [`name`](#metadata-name): string | required
- [`namespace`](#metadata-namespace): string | optional <EnterpriseAlert inline />
- [`spec`](#spec): map | required
- [`parentRefs`](#spec-parentrefs): map | required
- [`port`](#spec-parentrefs-port): string
- [`ref`](#spec-parentrefs-ref): string | required
- [`name`](#spec-parentrefs-ref-name): string
- [`type`](#spec-parentrefs-ref-type): map
- [`group`](#spec-parentrefs-ref-type): string
- [`groupVersion`](#spec-parentrefs-ref-type): string
- [`kind`](#spec-parentrefs-ref-type): string
- [`rules`](#spec-rules): map | required
- [`backendRefs`](#spec-rules-backendrefs): map
- [`backendRef`](#spec-rules-backendrefs-backendref): map
- [`datacenter`](#spec-rules-backendrefs-backendref-datacenter): string
- [`port`](#spec-rules-backendrefs-backendref-port): string
- [`ref`](#spec-rules-backendrefs-backendref-ref): map
- [`name`](#spec-rules-backendrefs-backendref-ref-name): string
- [`type`](#spec-rules-backendrefs-backendref-ref-type): map
- [`group`](#spec-rules-backendrefs-backendref-ref-type): string
- [`groupVersion`](#spec-rules-backendrefs-backendref-ref-type): string
- [`kind`](#spec-rules-backendrefs-backendref-ref-type): string
- [`weight`](#spec-rules-backendrefs-weight): number
</Tab>
</Tabs>
## Complete configuration
When every field is defined, a TCP route CRD has the following form:
```yaml
apiVersion: mesh.consul.hashicorp.com/v2beta1 # required
kind: TCPRoute # required
metadata:
name: <crdName>
namespace: <namespace>
spec:
parentRefs:
port: <portRoutedFrom>
- ref:
name: <nameRoutedFrom>
type:
group: <catalog>
groupVersion: <v2beta1>
kind: <Service>
rules:
- backendRefs:
- backendRef:
datacenter: <datacenterRoutedTo>
port: <portRoutedTo>
ref:
name: <nameRoutedTo>
type:
group: <catalog>
groupVersion: <v2beta1>
kind: <Service>
weight: 1
```
## Specification
This section provides details about the fields you can configure in the `TCPRoute` custom resource definition (CRD).
### `apiVersion`
Specifies the version of the Consul API for integrating with Kubernetes. The value must be `mesh.consul.hashicorp.com/v2beta1`.
#### Values
- Default: None
- This field is required.
- String value that must be set to `mesh.consul.hashicorp.com/v2beta1`.
### `kind`
Specifies the type of CRD to implement. Must be set to `TCPRoute`.
#### Values
- Default: None
- This field is required.
- Data type: String value that must be set to `TCPRoute`.
### `metadata`
Map that contains an arbitrary name for the CRD and the namespace it applies to.
#### Values
- Default: None
- Data type: Map
### `metadata.name`
Specifies a name for the CRD. The name is metadata that you can use to reference the resource when performing Consul operations, such as using the `consul resource` command. Refer to [`consul resource`](/consul/docs/k8s/connect/multiport/reference/resource-command) for more information.
#### Values
- Default: None
- This field is required.
- Data type: String
### `metadata.namespace` <EnterpriseAlert inline />
Specifies the namespace that the service resolver 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 `TCPRoute` CRD. The `apiVersion`, `kind`, and `metadata` fields are siblings of the spec field. All other configurations are children.
When using this CRD, the `spec` field closely resembles the `TCPRoute` GAMMA resource. Refer to [TCPRoute in the Kubernetes documentation](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1alpha2.TCPRoute).
#### Values
- Default: None
- This field is required.
- Data type: Map
### `spec.parentRefs`
Specifies the services and other resources to attach the route to. You can only define one `parentsRefs` configuration for each route. To attach the route to multiple resources, specify additional [`spec.parentRefs.ref`](#spec-parentrefs-ref) configurations in the `parentsRefs` block. You can only specify one port for the route. Any resources that send traffic through the route use the same port.
#### Values
- Default: None
- This field is required.
- Data type: Map
### `spec.parentRefs.port`
Specifies the port for the Consul service that the configuration applies to. This parameter can be either a virtual port number, such as a Kubernetes service port, or a non-numeric target port value representing a named workload port.
If you are not targeting a virtual port, specify the workload port name directly.
#### Values
- Default: None
- Data type: String
### `spec.parentRefs.ref`
Specifies the resource that the route attaches to.
#### Values
- Default: None
- Data type: Map
### `spec.parentRefs.ref.name`
Specifies the user-defined name of the resource that the configuration applies to.
#### Values
- Default: None
- Data type: String
### `spec.parentRefs.ref.type`
Specifies the type of resource that the configuration applies to. To reference a service in the Consul catalog, configure the resource type as `catalog.v2beta1.Service`.
#### Values
- Default: None
- Data type: Map containing the following parameters:
| Parameter | Description | Data type | Default |
| :------------ | :------------------------------------------------------------------- | :-------- | :------- |
| `group` | Specifies a group for the resource type within the Kubernetes cluster. To reference a service in the Consul catalog, set this parameter to `catalog`. | String | None |
| `groupVersion` | Specifies a groupVersion for the resource type within the Kubernetes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String | None |
| `kind` | Specifies the kind of the Kubernetes object the resource applies to. To reference a service in the Consul catalog, set this parameter to `Service`. | String | None |
### `spec.rules`
Specifies rules for sidecar proxies to direct a service's TCP traffic within the service mesh.
#### Values
- Default: None
- Data type: Map
### `spec.rules.backendRefs`
Specifies the Kubernetes Service backend to direct TCP traffic to when a request matches the service described in [`spec.parentRefs`](#spec-parentrefs). The Service backend is the collection of endpoint IPs for the service. Refer to [the Kubernetes Gateway API specification](https://gateway-api.sigs.k8s.io/concepts/gamma/#an-overview-of-the-gateway-api-for-service-mesh) for more information about Service backends.
When a valid Service backend cannot be reached and no additional filters apply, traffic that matches the rule returns a 500 status code.
When different Service backends are specified in [`spec.rules.backendRefs.weight`](#spec-rules-backendrefs-weight) and one of the backends is invalid, Consul continues to apply the specified weights instead of adjusting the relative weights to exclude traffic to the invalid backend. For example, when traffic is configured in a 50-50 split between `api` and `admin` and no valid endpoints for `admin` can be reached, the 50% of traffic intended for `admin` returns with a 500 status code.
#### Values
- Default: None
- Data type: Map
### `spec.rules.backendRefs.backendRef`
Specifies an individual Service backend where matching requests should be sent.
#### Values
- Default: None
- Data type: Map
### `spec.rules.backendRefs.backendRef.datacenter`
Specifies the name of the Consul datacenter that registered the Service backend that the configuration routes traffic to.
#### Values
- Default: None
- Data type: String
### `spec.rules.backendRefs.backendRef.port`
Specifies the port for the Consul service that the configuration routes traffic to. This parameter can be either a virtual port number, such as a Kubernetes service port, or a non-numeric target port value representing a named workload port.
If you are not targeting a virtual port, specify the workload port name directly.
#### Values
- Default: None
- Data type: String
### `spec.rules.backendRefs.backendRef.ref`
The Consul service that the configuration routes traffic to.
#### Values
- Default: None
- Data type: Map
### `spec.rules.backendRefs.backendRef.ref.name`
Specifies the user-defined name of the resource that the configuration routes traffic to.
#### Values
- Default: None
- Data type: String
### `spec.rules.backendRefs.backendRef.ref.type`
Specifies the type of resource that the configuration routes traffic to. To reference a service in the Consul catalog, configure the resource type as `catalog.v2beta1.Service`.
#### Values
- Default: None
- Data type: Map containing the following parameters:
| Parameter | Description | Data type | Default |
| :------------ | :------------------------------------------------------------------- | :-------- | :------- |
| `group` | Specifies a group for the resource type within the Kubernetes cluster. To reference a service in the Consul catalog, set this parameter to `catalog`. | String | None |
| `groupVersion` | Specifies a groupVersion for the resource type within the Kubernetes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String | None |
| `kind` | Specifies the kind of the Kubernetes object for the resource. To reference a service in the Consul catalog, set this parameter to `Service`. | String | None |
### `spec.rules.backendRefs.weight`
Specifies the proportion of requests routed to the specified service.
This proportion is relative to the sum of all weights in the [`spec.rules.backendRefs`](#spec-rules-backendrefs) block. As a result, weights do not need to add up to 100. When only one backend is specified and the weight is greater then 0, Consul forwards 100% of traffic to the backend.
When this parameter is not specified, Consul defaults to `1`.
#### Values
- Default: `1`
- Data type: Integer
## Examples
The following examples demonstrate common TCPRoute CRD configuration patterns for specific use cases.
### Split TCP traffic between two ports
The following example splits traffic for the `api` service. TCP traffic for services registered to the Consul catalog that are available at the `api-workload` port is split so that 50% of the traffic routes to the service at the `api-workload` port and 50% routes to the service at the `admin-workload` port.
```yaml
apiVersion: mesh.consul.hashicorp.com/v2beta1
kind: TCPRoute
metadata:
name: api-split
namespace: default
spec:
parentRefs:
- ref:
type:
group: catalog
groupVersion: v2beta1
kind: Service
name: api
# The virtual port number for the "api-workload" target port.
port: "80"
rules:
- backendRefs:
- backendRef:
ref:
type:
group: catalog
groupVersion: v2beta1
kind: Service
name: api
# The virtual port number for the "api-workload" target port.
port: "80"
weight: 50
- backendRef:
ref:
type:
group: catalog
groupVersion: v2beta1
kind: Service
name: api
# The virtual port number for the "admin-workload" target port.
port: "90"
weight: 50
```

245
website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
Unescape View File

@ -1,245 +0,0 @@
---
layout: docs
page_title: TrafficPermissions resource configuration reference
description: The TrafficPermissions CRD defines rules for allowing and denying traffic between services within the service mesh. Learn how to configure traffic permissions for the v2 catalog to authorize service-to-service communication in a network with zero-trust security.
---
# TrafficPermissions configuration reference
This page provides reference information for the `TrafficPermissions` resource, which authorizes east-west traffic between services within the service mesh. The traffic permissions CRD replaces the service intentions CRD when using the v2 catalog API. Refer to [changes to Consul's existing architecture](/consul/docs/architecture/v2/catalog#changes-to-consul-s-existing-architecture) for more information.
This custom resource definition (CRD) describes a resource related to the [Kubernetes GAMMA initiative](https://gateway-api.sigs.k8s.io/concepts/gamma/) that requires the [v2 catalog API](/consul/docs/architecture/v2/catalog). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog). For more information about GAMMA resources, refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/gamma/).
## Configuration model
The following list outlines field hierarchy, language-specific data types, and requirements in a traffic permissions CRD. Click on a property name to view additional details, including default values.
- [`apiVersion`](#apiversion): string | required | must be set to `auth.consul.hashicorp.com/v2beta1`
- [`kind`](#kind): string | required | must be set to `TrafficPermissions`
- [`metadata`](#metadata): map | required
- [`name`](#metadata-name): string | required
- [`namespace`](#metadata-namespace): string | optional <EnterpriseAlert inline />
- [`spec`](#spec): map | required
- [`destination`](#spec-destination): map
- [`identityName`](#spec-destination-identityname): string
- [`action`](#spec-action): string
- [`permissions`](#spec-permissions): list of maps
- [`sources`](#spec-permissions-sources): list of maps
- [`identityName`](#spec-permissions-sources-identityname): string
- [`destinationRules`](#spec-permissions-destinationrules): list of maps
- [`portNames`](#spec-permissions-destinationrules-portnames): array of strings
## Complete configuration
When every field is defined, a traffic permissions CRD has the following form:
```yaml
apiVersion: auth.consul.hashicorp.com/v2beta1 # required
kind: TrafficPermissions # required
metadata:
name: <permissionsResourceName>
namespace: <default>
spec:
destination:
identityName: <permissionsDestinationService>
action: allow
permissions:
- sources:
- identityName: <sourceWorkloadIdentity>
destinationRules:
- portNames:
- <servicePortName>
```
## Specification
This section provides details about the fields you can configure in the `TrafficPermissions` custom resource definition (CRD).
### `apiVersion`
Specifies the version of the Consul API for integrating with Kubernetes. The value must be `auth.consul.hashicorp.com/v2beta1`.
#### Values
- Default: None
- This field is required.
- String value that must be set to `auth.consul.hashicorp.com/v2beta1`.
### `kind`
Specifies the type of CRD to implement. Must be set to `TrafficPermissions`.
#### Values
- Default: None
- This field is required.
- Data type: String value that must be set to `TrafficPermissions`.
### `metadata`
Map that contains an arbitrary name for the CRD and the namespace it applies to.
#### Values
- Default: None
- Data type: Map
### `metadata.name`
Specifies a name for the CRD. The name is metadata that you can use to reference the resource when performing Consul operations, such as using the `consul resource` command. Refer to [`consul resource`](/consul/docs/k8s/connect/multiport/reference/resource-command) for more information.
#### Values
- Default: None
- This field is required.
- Data type: String
### `metadata.namespace` <EnterpriseAlert inline />
Specifies the namespace that the service resolver 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 `TrafficPermissions` CRD. 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.destination`
Specifies the proxies of the services where these traffic permissions apply.
#### Values
- Default: None
- Data type: Map
### `spec.destination.identityName`
Specifies the Workload identity for a service. The permissions you configure in this `TrafficPermissions` CRD apply to sidecar proxies when a request has this identity as their destination.
#### Values
- Default: None
- Data type: String
### `spec.action`
Specifies whether the proxy should _allow traffic_ or _deny traffic_ between the destination in [`spec.destination`](#spec-destination) and the sources in [`spec.permissions.sources`](#spec-permissions-sources).
`ACTION_DENY` is a governance feature available in Consul Enterprise that cannot be overridden by another `ACTION_ALLOW`.
By default, Consul allows traffic between all services. When the Helm value `global.acls.manageSystemACLs` is set to `true`, then Consul operates in "default-deny" mode. In this mode, `TrafficPermissions` CRDs that allow traffic between services are required for service-to-service traffic.
#### Values
- Default: None
- Data type: String that must contain one of the following values:
- `ACTION_ALLOW`
- `ACTION_DENY` <EnterpriseAlert inline />
### `spec.permissions`
Permissions is a list of the traffic permissions Consul evaluates requests against. When the list contains more than one permission, Consul follows OR semantics to select the permission.
#### Values
- Default: None
- Data type: List of maps
### `spec.permissions.sources`
Lists sources for traffic in the permission. This block contains information Consul uses to evaluate the service that originated the request when the sidecar proxy authorizes incoming traffic.
To specify wildcard references in this block using `*`, omit all other fields. For example, you can apply traffic permissions to all namespaces using the wildcard, but you cannot specify an identity name, partition, peer, or sameness group in the same source.
#### Values
- Default: None
- Data type: List of maps
### `spec.permissions.sources.identityName`
Specifies the Workload identity for the service that originates the request.
#### Values
- Default: None
- Data type: String
### `spec.permissions.destinationRules`
Specifies L7 properties to match against when Consul enforces traffic permissions.
When [`spec.action`](#spec-action) _allows traffic_, Consul authorizes requests to the destination service when the request matches one or more rules defined in this block. Requests that do not match any rules are denied.
When [`spec.action`](#spec-action) _denies traffic_, Consul denies authorization to requests that match one or more rules defined in this block. Requests that do not match any rules are allowed.
#### Values
- Default: None
- Data type: List of maps
### `spec.permissions.destinationRules.portNames`
Specifies a port name that the Kubernetes Pod's container exposes at the destination.
#### Values
- Default: None
- Data type: String
## Examples
The following examples demonstrate common `TrafficPermissions` CRD configuration patterns for specific use cases.
### Allow traffic to multiple ports
The following example configures traffic permissions to allow traffic when the `web` service makes a request to the `api` service on the `api` port or `admin` port.
```yaml
apiVersion: auth.consul.hashicorp.com/v2beta1
kind: TrafficPermissions
metadata:
name: api-allow-web-all
spec:
destination:
identityName: "api"
action: ACTION_ALLOW
permissions:
- sources:
- identityName: "web"
destinationRules:
- portNames: ["api", "admin"]
```
### Deny traffic between a service and a specific port <EnterpriseAlert inline />
The following example configures traffic permissions to deny traffic when the `web` service makes a request to the `api` service on the `admin` port.
This `ACTION_DENY` cannot be overridden by another `ACTION_ALLOW`.
```yaml
apiVersion: auth.consul.hashicorp.com/v2beta1
kind: TrafficPermissions
metadata:
name: web-to-admin-port-deny
spec:
destination:
identityName: api
action: ACTION_DENY
permissions:
- sources:
- identityName: web
destinationRules:
- portNames: ["admin"]
```

113
website/content/docs/k8s/multiport/traffic-split.mdx
Unescape View File

@ -1,113 +0,0 @@
---
layout: docs
page_title: Split traffic between multi-port services
description: Learn how to configure Consul to split TCP traffic between two ports of a multi-port service using the TCPRoute resource and the v2 catalog API
---
# Split TCP traffic between multi-port services
<Warning>
The v2 catalog API is currently in beta. This documentation supports testing and development scenarios. Do not use the v2 catalog API in secure production environments.
</Warning>
This page describes the process for splitting TCP, HTTP, and gRPC traffic between two ports of a multi-port service. It includes an example TCPRoute resource configuration to demonstrate Consul's multi-port features.
## Prerequisites
Splitting traffic between two ports of a multi-port service requires the [v2 catalog API](/consul/docs/architecture/v2/catalog).
In addition, they are two different workflows for registering Services in Kubernetes using the v2 catalog API. The instructions on this page offer examples for two configuration methods:
- **Method 1**: Register a Kubernetes service that select workloads which expose multiple ports
- **Method 2**: Register multiple Kubernetes Services that direct traffic to an explicit port on the same workload
For guidance on enabling the v2 catalog, deploying multi-port services using these methods, and applying traffic permissions to the services, refer to [configure multi-port services](/consul/docs/k8s/multiport/configure).
## Overview
Complete the following steps to implement a split in TCP traffic between two services:
1. Define the resource's behavior in a custom resource definition (CRD).
1. Apply the resource to your cluster.
## Define route resource
The following example splits traffic for the `api` service. TCP traffic for services registered to the Consul catalog that are available at the `api-workload` port is split so that 50% of the traffic routes to the service at the `api-workload` port and 50% routes to the service at the `admin-workload` port.
<CodeBlockConfig filename="api-split.yaml">
```yaml
apiVersion: mesh.consul.hashicorp.com/v2beta1
kind: TCPRoute
metadata:
name: api-split
spec:
parentRefs:
- ref:
type:
group: catalog
groupVersion: v2beta1
kind: Service
name: api
# The virtual port number for the "api-workload" target port.
port: "80"
rules:
- backendRefs:
- backendRef:
ref:
type:
group: catalog
groupVersion: v2beta1
kind: Service
name: api
# The virtual port number for the "api-workload" target port.
port: "80"
weight: 50
- backendRef:
ref:
type:
group: catalog
groupVersion: v2beta1
kind: Service
name: api
# The virtual port number for the "admin-workload" target port.
port: "90"
weight: 50
```
</CodeBlockConfig>
## Apply the resource
Use the `kubectl` command to apply the resource to your Consul cluster.
```shell-session
$ kubectl apply -f api-split.yaml
```
<Tabs>
<Tab heading="Method 1" group="method1">
Then, open a shell session in the `web` container and test the `api` service on port 90.
```shell-session
$ kubectl exec -it ${WEB_POD} -c web -- curl api:90
```
</Tab>
<Tab heading="Method 2" group="method2">
Then, open a shell session in the `web` container and test the `api-admin` service on port 90.
```shell-session
$ kubectl exec -it ${WEB_POD} -c web -- curl api-admin:90
```
</Tab>
</Tabs>
Half of the traffic should respond with the `hello world` response from port 80, instead of port 90's response of `hello world from 9090 admin`. Repeat the command several times to verify that you receive both responses.

4
website/content/docs/release-notes/consul/v1_17_x.mdx
Unescape View File

@ -15,13 +15,13 @@ We are pleased to announce the following Consul updates.
These APIs are the foundation for future versions of Consul and enable new functionalities, such as multi-port and host-name-based canary routing and routing traffic through headless services in native Kubernetes deployments.
For more information, refer to the [Catalog API v2](/consul/docs/k8s/multiport#catalog-api-v2-beta) section in the documentation.
For more information, refer to the [Catalog API v2](/consul/docs/v1.17.x/k8s/multiport#catalog-api-v2-beta) section in the documentation.
<Note> These APIs are in beta and under active development, so we do not recommend using them in production. </Note>
- **Multi-port services in Consul:** You can now register services with multiple ports per service. The v2 catalog API enables a single sidecar proxy to support workloads on different ports. This significantly reduces the operational overhead for managing Consul service mesh. Support for other runtimes outside of Kubernetes is planned for future releases of Consul.
Refer to the [Multi-port services for service mesh](/consul/docs/k8s/multiport#catalog-api-v2-beta) and [Configure multi-port services](/consul/docs/k8s/multiport/configure) for more information.
Refer to the [Multi-port services for service mesh](/consul/docs/v1.17.x/k8s/multiport#catalog-api-v2-beta) and [Configure multi-port services](/consul/docs/k8s/multiport/configure) for more information.
<Note> Multi-port is currently a beta feature in Consul v1.17. </Note>

43
website/content/docs/security/acl/acl-rules.mdx
Unescape View File

@ -19,7 +19,6 @@ The following table provides an overview of the resources you can use to create
| `partition`<br/>`partition_prefix` | <EnterpriseAlert inline /> Controls access to one or more admin partitions. <br/>See [Admin Partition Rules](#admin-partition-rules) for details. | Yes |
| `agent`<br/>`agent_prefix` | Controls access to the utility operations in the [Agent API](/consul/api-docs/agent), such as `join` and `leave`. <br/>See [Agent Rules](#agent-rules) for details. | Yes |
| `event`<br/>`event_prefix` | Controls access to event operations in the [Event API](/consul/api-docs/event), such as firing and listing events. <br/>See [Event Rules](#event-rules) for details. | Yes |
| `identity`<br/>`identity_prefix` | Controls access to workload identity operations in the [Catalog v2 group](/consul/docs/architecture/v2/catalog).
| `key`<br/>`key_prefix` &nbsp; | Controls access to key/value store operations in the [KV API](/consul/api-docs/kv). <br/>Can also use the `list` access level when setting the policy disposition. <br/>Has additional value options in Consul Enterprise for integrating with [Sentinel](https://docs.hashicorp.com/sentinel/consul). <br/>See [Key/Value Rules](#key-value-rules) for details. | Yes |
| `keyring` &nbsp; &nbsp; &nbsp; | Controls access to keyring operations in the [Keyring API](/consul/api-docs/operator/keyring). <br/>See [Keyring Rules](#keyring-rules) for details. | No |
| `mesh` &nbsp; &nbsp; &nbsp; | Provides operator-level permissions for resources in the admin partition, such as ingress gateways or mesh proxy defaults. See [Mesh Rules](#mesh-rules) for details. | No |
@ -248,48 +247,6 @@ operation, so to enable this feature in a Consul environment with ACLs enabled,
give agents a token with access to this event prefix, in addition to configuring
[`disable_remote_exec`](/consul/docs/agent/config/config-files#disable_remote_exec) to `false`.
## Identity Rules
The `identity` and `identity_prefix` resources control workload-identity-level registration and read access to the [Catalog v2 API group](/consul/docs/architecture/v2/catalog).
Specify the resource label in identity rules to set the scope of the rule.
The resource label in the following example is empty. As a result, the rules allow read-only access to any workload identity name with the empty prefix.
The rules also allow read-write access to the `app` identity and deny all access to the `admin` identity:
<CodeTabs heading="Example identity rules">
```hcl
identity_prefix "" {
policy = "read"
}
identity "app" {
policy = "write"
}
identity "admin" {
policy = "deny"
}
```
```json
{
"identity_prefix": {
"": {
"policy": "read"
}
},
"identity": {
"app": {
"policy": "write"
},
"admin": {
"policy": "deny"
}
}
}
```
</CodeTabs>
## Key/Value Rules
The `key` and `key_prefix` resources control access to key/value store operations in the [KV API](/consul/api-docs/kv).

9
website/data/commands-nav-data.json
Unescape View File

@ -494,15 +494,6 @@
"title": "reload",
"path": "reload"
},
{
"title": "resource",
"path": "resource",
"badge": {
"text": "v2",
"type": "outlined",
"color": "neutral"
}
},
{
"title": "rtt",
"path": "rtt"

59
website/data/docs-nav-data.json
Unescape View File

@ -106,23 +106,6 @@
"title": "v1 Catalog",
"path": "architecture/catalog"
},
{
"title": "v2 architecture",
"routes": [
{
"title": "Overview",
"path": "architecture/v2"
},
{
"title": "Catalog",
"path": "architecture/v2/catalog"
},
{
"title": "Resource groups",
"path": "architecture/v2/groups"
}
]
},
{
"title": "Improving Consul Resilience",
"path": "architecture/improving-consul-resilience"
@ -1601,48 +1584,6 @@
}
]
},
{
"title": "V2 Catalog API",
"routes": [
{
"title": "Overview",
"path": "k8s/multiport"
},
{
"title": "Configure multi-port services",
"path": "k8s/multiport/configure"
},
{
"title": "Split TCP traffic between multiple ports",
"path": "k8s/multiport/traffic-split"
},
{
"title": "Reference",
"routes": [
{
"title": "GRPCRoute resource",
"path": "k8s/multiport/reference/grpcroute"
},
{
"title": "HTTPRoute resource",
"path": "k8s/multiport/reference/httproute"
},
{
"title": "ProxyConfiguration resource",
"path": "k8s/multiport/reference/proxyconfiguration"
},
{
"title": "TCPRoute resource",
"path": "k8s/multiport/reference/tcproute"
},
{
"title": "TrafficPermissions resource",
"path": "k8s/multiport/reference/trafficpermissions"
}
]
}
]
},
{
"title": "L7 traffic management",
"routes": [

39
website/redirects.js
Unescape View File

@ -212,16 +212,6 @@ module.exports = [
destination: '/consul/docs/v1.8.x/agent/config-entries/:slug',
permanent: true,
},
{
source: '/consul/docs/k8s/multiport/reference/resource-command/:slug',
destination: '/consul/commands/resource/:slug',
permanent: true,
},
{
source: '/consul/commands/:version(v1\.(?:8|9|10|11|12|13|14|15|16|17)\.x)/resource/:slug*',
destination: '/consul/docs/:version/k8s/multiport/reference/resource-command/:slug',
permanent: true
},
{
source: '/consul/docs/architecture/catalog/v1/:slug',
destination: '/consul/docs/architecture/catalog/:slug',
@ -230,26 +220,31 @@ module.exports = [
{
source: '/consul/docs/:version(v1\.(?:8|9|10|11|12|13|14|15|16|17)\.x)/architecture/catalog/:slug*',
destination: '/consul/docs/:version/architecture/catalog/v1/:slug',
permanent: true
},
{
source: '/consul/docs/architecture/catalog/v2/:slug',
destination: '/consul/docs/architecture/v2/catalog/:slug',
permanent: true,
},
{
source: '/consul/docs/:version(v1\.(?:8|9|10|11|12|13|14|15|16|17)\.x)/architecture/v2/catalog/:slug*',
destination: '/consul/docs/:version/architecture/catalog/v2/:slug',
permanent: true
},
{
source: '/consul/docs/nia/network-drivers/terraform-cloud',
destination: '/consul/docs/nia/network-drivers/hcp-terraform',
permanent: true
permanent: true,
},
{
source: '/consul/docs/:version(v1\.(?:8|9|10|11|12|13|14|15|16|17)\.x)/nia/network-drivers/hcp-terraform',
destination: '/consul/docs/:version/nia/network-drivers/terraform-cloud',
permanent: true
permanent: true,
},
{
source: '/consul/docs/k8s/multiport/:slug',
destination: '/consul/docs/architecture/catalog#v2-catalog',
permanent: true,
},
{
source: 'consul/docs/architecture/v2/:slug*',
destination: '/consul/docs/architecture/catalog#v2-catalog',
permanent: true,
},
{
source: '/consul/commands/resource/:slug',
destination: '/consul/docs/architecture/catalog#v2-catalog',
permanent: true,
},
]

Write Preview
Loading…
Cancel
Save