From 1859dd1ca8de52a3d6928b8947dfbea4c2d335ee Mon Sep 17 00:00:00 2001 From: boruszak Date: Wed, 25 Oct 2023 14:06:15 -0700 Subject: [PATCH 01/57] Catalog concept pages creation --- .../content/docs/architecture/catalog/v1.mdx | 62 +++++++++ .../content/docs/architecture/catalog/v2.mdx | 123 ++++++++++++++++++ website/data/docs-nav-data.json | 13 ++ 3 files changed, 198 insertions(+) create mode 100644 website/content/docs/architecture/catalog/v1.mdx create mode 100644 website/content/docs/architecture/catalog/v2.mdx diff --git a/website/content/docs/architecture/catalog/v1.mdx b/website/content/docs/architecture/catalog/v1.mdx new file mode 100644 index 000000000000..db56d13bda4b --- /dev/null +++ b/website/content/docs/architecture/catalog/v1.mdx @@ -0,0 +1,62 @@ +--- +layout: docs +page_title: v1 Catalog API +description: +--- + +# v1 Catalog API + +This topic provides conceptual information about version 1 (v1) of the Consul catalog API. The catalog tracks registered services and their locations for both service discovery and service mesh use cases. + +For more information about the information returned when querying the catalog, including filtering options when querying the catalog for a list of nodes, services, or gateways, refer to the [`/catalog` endpoint reference in the HTTP API documentation](/consul/api-docs/catalog). + +## Introduction + +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 introduces a second version of the Catalog API for testing and development purposes. The catalog APIs cannot run concurrently in a Consul deployment. There is no migration path between catalog versions at this time. For more information, refer to [Consul v2 Catalog API](/consul/docs/architecture/catalog/v2). + +## Catalog structure + +When Consul registers a service instance using the v1 catalog API, it records the following information about each instance: + +v1 Catalog field +Description +User-defined or Consul-computed? +ID +A unique identifier for a service instance. +Consul +Node + +Consul +Address +The address of the node where the service instance is running. +Consul +Tagged Addresses + + +User +NodeMeta + + +User +Datacenter +The name of the datacenter the service is registered in. +User +Service +The name of the service Consul registers the service instance under. +User +Agent Check +The health status of service last reported by the Consul agent. +Consul +Health Checks +The health checks defined for the service. Refer to [define health checks](/consul/docs/services/usage/checks) for more information. +User +Partition +The name of the admin partition the service is registered in. Refer to [admin partitions](/consul/docs/enterprise/admin-partitions) for more information. +User +Locality +Refer to [`locality`](/consul/docs/agent/config/config-files#locality) for more information. +User + +Depending on the configuration entries or custom resource definitions you apply to your Consul installation, additional information such as [proxy default behavior](/consul/docs/connect/config-entries/proxy-defaults) is automatically recorded to the catalog for services. You can return this information using the [`/catalog` HTTP API endpoint](/consul/api-docs/catalog). diff --git a/website/content/docs/architecture/catalog/v2.mdx b/website/content/docs/architecture/catalog/v2.mdx new file mode 100644 index 000000000000..4997154d546b --- /dev/null +++ b/website/content/docs/architecture/catalog/v2.mdx @@ -0,0 +1,123 @@ +--- +layout: docs +page_title: v2 Catalog API +description: +--- + +# v2 Catalog API + + +The v2 catalog API is in a beta release for testing and development purposes. Do not use the v2 catalog or multi-port services in secure production environments. + + +This topic provides conceptual information about version 2 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 on Kubernetes deployments only. For more information about Consul’s default catalog, refer to [v1 Catalog API](/consul/docs/architecture/catalog/v1). + +## Introduction + +When Consul registers services, it records [user-defined and Consul-assigned information](/consul/docs/architecture/catalog/v1#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, and it is essential to Consul’s service discovery and service mesh operations. + +The [Consul v1 Catalog API](/consul/docs/architecture/catalog/v1) was designed prior to the introduction of Consul’s service mesh features. 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 service can represent a Kubernetes Workload in the v1 catalog. + +Since then, the cloud networking needs for applications have evolved and workarounds were developed. For example, [Kubernetes Pods with multiple ports](/consul/docs/k8s/connect#kubernetes-pods-with-multiple-ports) demonstrates how you can schedule a service with multiple ports so that Consul registers it in the catalog as distinct services with their own service instances. However, this workaround results in additional resource consumption because Consul requires that each service and port use their own proxy and Consul dataplane so that it can recognize them as distinct services. + +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 still tracks services and nodes for Consul, but replaces service instances with _workloads_ and _workload identites_. + +The following table describes resources in the v2 catalog and compares them to the v1 catalog and Kubernetes resources. It also states whether these resources are defined by the user or computed by Consul when it registers a service. + + +V2 Catalog resource +Description +Catalog v1 resource analogue +Kubernetes resource analogue +User-defined or Consul-computed +Service +The name of the service Consul registers a workload under +Service +X +User +Node +The address of the node where the workload runs. +Node +Node +Consul +Workload +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 Workloads +User +Workload identities +Provides a distinct identity for a Kubernetes Workload to assume in a Kubernetes cluster. +Service instance +Kubernetes Service Accounts +User +Service endpoints +Maps services to workload addresses and endpoints. + + + + +Consul +Health status +A resource for reporting the health status of a workload +Agent check +X +Consul +Health check +A resource for defining the health checks for a workload. +Health check + + +User +Proxy configuration +Represents a configuration for a sidecar or gateway proxy. +`Proxy` field in service definition + + +User +Destinations +Represents explicit service upstreams +Upstream service annotations +X +User +Traffic permissions +Enables L4 traffic authorization according to workload identity instead of service identity +Service intentions +X +User + + +Refer to [`consul resource`](/consul/docs/k8s/multiport/reference/resource-command) for more information about using the Consul CLI to interact with the v2 catalog. + +## Changes to Consul’s existing architecture + +The change in data models introduced by the v2 Catalog API 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 TrafficPermissions 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 [TrafficPermissions configuration reference](/consul/docs/k8s/multiport/reference/trafficpermissions). + +### HTTP route resource for L7 traffic management + +You can configure L7 traffic management behavior, such as service splitting, in an `HTTPRoute` 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 this resource, including example configurations, refer to [HTTPRoute configuration reference](/consul/docs/k8s/multiport/reference/httproute). + +### 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). + +The v2 catalog introduces the `ProxyConfiguration` resource, enabling the automatic configuration of sidecar proxy behavior according to Consul workload identity. Refer to [ProxyConfiguration configuration reference](/consul/docs/k8s/multiport/reference/proxyconfiguration) for more information. diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 2989c955e646..8a30bd1d9faa 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -102,6 +102,19 @@ "title": "Overview", "path": "architecture" }, + { + "title": "Catalog", + "routes": [ + { + "title": "v1 API", + "path": "architecture/catalog/v1" + }, + { + "title": "v2 API", + "path": "architecture/catalog/v2" + } + ] + }, { "title": "Improving Consul Resilience", "path": "architecture/improving-consul-resilience" From db661ba5a59a8137ab39eb4052da9f543e03de95 Mon Sep 17 00:00:00 2001 From: boruszak Date: Wed, 25 Oct 2023 15:06:41 -0700 Subject: [PATCH 02/57] Multi-port services overview - initial update --- website/content/docs/k8s/multiport/index.mdx | 68 +++++++++----------- 1 file changed, 29 insertions(+), 39 deletions(-) diff --git a/website/content/docs/k8s/multiport/index.mdx b/website/content/docs/k8s/multiport/index.mdx index 0cdc6fca92aa..c411906d902a 100644 --- a/website/content/docs/k8s/multiport/index.mdx +++ b/website/content/docs/k8s/multiport/index.mdx @@ -1,10 +1,10 @@ --- layout: docs -page_title: Multi-port services for service mesh -description: Consul on Kubernetes supports multi-port services for both service discovery and service mesh scenarios. Learn about Consul’s v2 catalog changes to support multiple ports for a service running in a single container. +page_title: Multi-port services overview +description: Consul on Kubernetes supports multi-port services for both service discovery and service mesh scenarios. Learn how Consul’s v2 catalog supports multiple ports for a service running in a single container. --- -# Multi-port services for service mesh +# Multi-port services overview @@ -12,39 +12,7 @@ Multi-port services are part of a beta release. This documentation supports test -This topic describes changes to Consul's catalog that allow you to register a service with multiple ports on Kubernetes deployments. - -## Introduction - -When Consul registers services, v1 of its catalog API tracks 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 catalog API was designed prior to the introduction of Consul’s service mesh features. The service mesh uses Consul's ACL system, which requires a Kubernetes ServiceAccount resource to match the Service name. As a result, only one service can represent a Kubernetes Workload in the Consul catalog. - -Since then, the cloud networking needs for applications have evolved and the Consul catalog adapted to support workarounds for these needs. For example, [Kubernetes Pods with multiple ports](/consul/docs/k8s/connect#kubernetes-pods-with-multiple-ports) demonstrates how you can schedule a service with multiple ports so that Consul registers it in the catalog as distinct services with their own service instances. However, this workaround results in additional resource consumption because Consul requires that each service and port use their own proxy and Consul dataplane so that it can recognize them as distinct services. - -### Catalog API v2 beta - -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 still tracks services and nodes for Consul, but replaces service instances with _workloads_ and _workload identites_. - -- `Workload` is 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. It is similar to [Kubernetes Workloads](https://kubernetes.io/docs/concepts/workloads/). -- `WorkloadIdentities` provide a distinct identity for a Workload to assume in a Kubernetes cluster. They are similar to [Kubernetes Service Accounts](https://kubernetes.io/docs/concepts/security/service-accounts/). - -This catalog structure enables Consul to associate a single Kubernetes Workload with multiple services in its catalog. - -The v2 catalog API also tracks the following information about services when they are registered with Consul: - -- `ServiceEndpoints` maps services to workload addresses and endpoints. This resource is computed by Consul. -- `HealthStatus` is a resource for reporting the health status of a workload. -- `HealthCheck` is a resource for defining the health checks for a workload. -- `ProxyConfiguration` represents a configuration for a sidecar or gateway proxy, similar to the `Proxy` field in the current service definition. -- `Destinations` represents explicit service upstreams. -- `TrafficPermissions` is a replacement for the `ServiceIntentions` custom resource definition (CRD). Traffic permissions replace service intentions for all services in the v2 catalog, which enables L4 traffic authorization according to workload identity instead of service identity. - -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. +This topic describes the process to register a service with multiple ports on Kubernetes deployments using the v2 catalog API. For information about the v2 catalog’s contents and structure, refer to [v2 catalog API](/consul/docs/architecture/catalog/v2). ## Workflow @@ -57,13 +25,35 @@ To use a multi-port service in Consul on Kubernetes deployments, complete the fo 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). +[Link to/describe advanced routing configurations re: examples on configuration pages] + ## Constraints and limitations Be aware of the following constraints and technical limitations on using multi-port services and the v2 catalog API: -- The v2 catalog API beta does not support connections with client agents. It is only available for Kubernetes deployments, which use [Consul dataplanes](/consul/docs/connect/dataplane) instead of client agents. +- Consul client agents do not support multi-port services or the v2 catalog API beta. Kubernetes deployments support multi-port services using [Consul dataplanes](/consul/docs/connect/dataplane) instead of client agents. - The v1 and v2 catalog APIs cannot run concurrently. - The Consul UI does not support multi-port services or the v2 catalog API in this release. You must disable the UI in the Helm chart in order to use the v2 catalog API. - HCP Consul does not support multi-port services or the v2 catalog API in this release. You cannot [link a self-managed cluster to HCP Consul](/hcp/docs/consul/self-managed) to access its UI or view observability metrics when it uses the v2 catalog. -- The v2 catalog API does not support ACLs in the beta release. -- We do not recommend updating existing clusters to enable the v2 catalog in this release. To use the v2 catalog, deploy a new Consul cluster. \ No newline at end of file +- 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 multi-port services: + +### Concepts + +- [v2 catalog API](/consul/docs/architecture/catalog/v2) + +### Usage documentation + +- [Configure multi-port services](/consul/docs/k8s/multiport/configure) + +### 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) From 75aacc10eae4c371f40c07b0c02e0914e91873ff Mon Sep 17 00:00:00 2001 From: boruszak Date: Wed, 25 Oct 2023 15:14:33 -0700 Subject: [PATCH 03/57] CLI command page creation --- .../docs/k8s/multiport/resource-command.mdx | 130 ++++++++++++++++++ website/data/docs-nav-data.json | 4 + 2 files changed, 134 insertions(+) create mode 100644 website/content/docs/k8s/multiport/resource-command.mdx diff --git a/website/content/docs/k8s/multiport/resource-command.mdx b/website/content/docs/k8s/multiport/resource-command.mdx new file mode 100644 index 000000000000..471d15d00376 --- /dev/null +++ b/website/content/docs/k8s/multiport/resource-command.mdx @@ -0,0 +1,130 @@ +--- +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` + +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 [options] + + # ... + +Subcommands: + + apply Write or update resource information + delete Delete resource information + list Read all resources by type + read Read resource information +``` + +On Kubernetes deployments, you must use a `kubectl exec` command to open a shell to the Consul server's container before you can run this Consul CLI command. + +## 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 table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). + +| ACL Required | +| ------------ | +| `operator:write` | + +#### Command Options + +- `-f=` - (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 TrafficPermissions resource to Consul that restricts service-to-service communication to authorized services only. + +```shell-session hideClipboard +$ consul resource apply -f=trafficpermissions.yaml +``` + +### `delete` + +`consul resource delete`removes a Consul resource at a given file path. + +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). + +| ACL Required | +| ------------ | +| `operator:write` | + +#### Command Options + +- `-f=` - (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 TrafficPermissions resource from Consul that restricts service-to-service communication to authorized services only. + +```shell-session hideClipboard +$ consul resource delete -f=trafficpermissions.yaml +``` + +### `list` + +`consul resource list` outputs names of resources according to the type of resource and the location where the resource is applied. + +This command must be issued with a resource type. All resource definitions include a `type` configuration block that contains a `group`, `groupVersion`, and `kind`. By formatting the `type` on the command line as `group.groupVersion.kind`, you can return all resources with a matching `type` in the configuration. + +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). + +| ACL Required | +| ------------ | +| `operator:read` | + +#### Command Options + +The following flags enable you to filter results. + +- `-partition=` - The partition where the resources apply. +- `-namespace=` - The namespace where the resources apply. +- `-peer=` - The clusters with established cluster peering connections where the resources apply. + +#### Example usage + +The following command lists resources that apply to the `card-processor` service when the service runs on the `billing partition` in the `payments` namespace on peer cluster `dc2-store`. + +```shell-session hideClipboard +$ consul resource list catalog.v2beta1.Service card-processor -partition=billing -namespace=payments -peer=dc2-store +``` + +### `read` + +`consul resource list` outputs names of resources according to the type of resource or where the resource is applied. + +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). + +| ACL Required | +| ------------ | +| `operator:read` | + +#### Command Options + +- `-partition=` - The partition where the resource applies. +- `-namespace=` - The namespace where the resource applies. +- `-peer=` - The clusters with established cluster peering connections where the resource applies. +- `-consistent=` - Determines whether Consul returns stale resource information. Set this flag to `true` to prevent Consul from returning stale information. +- `-json` - Include this flag to output the response in JSON format. + +#### Example usage + +The following command outputs the resource that applies to a specific `card-processor` service when the service runs on the `billing partition` in the `payments` namespace on peer cluster `dc2-store`. + +```shell-session hideClipboard +$ consul resource read catalog.v2beta1.Service card-processor -partition=billing -namespace=payments -peer=dc2-store +``` diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 8a30bd1d9faa..cefaceb82cd1 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -1537,6 +1537,10 @@ { "title": "Configure multi-port services", "path": "k8s/multiport/configure" + }, + { + "title": "Consul resource command", + "path": "k8s/multiport/resource-command" } ] }, From b6741a91479871f630cdd5c75539260d0f8662e1 Mon Sep 17 00:00:00 2001 From: boruszak Date: Wed, 25 Oct 2023 15:15:41 -0700 Subject: [PATCH 04/57] File location adjustment --- .../docs/k8s/multiport/{ => reference}/resource-command.mdx | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename website/content/docs/k8s/multiport/{ => reference}/resource-command.mdx (100%) diff --git a/website/content/docs/k8s/multiport/resource-command.mdx b/website/content/docs/k8s/multiport/reference/resource-command.mdx similarity index 100% rename from website/content/docs/k8s/multiport/resource-command.mdx rename to website/content/docs/k8s/multiport/reference/resource-command.mdx From 0966354aa8da84a2cb36839d3f5f44d494943f73 Mon Sep 17 00:00:00 2001 From: boruszak Date: Wed, 25 Oct 2023 15:15:55 -0700 Subject: [PATCH 05/57] nav --- website/data/docs-nav-data.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index cefaceb82cd1..6e347a958ab3 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -1540,7 +1540,7 @@ }, { "title": "Consul resource command", - "path": "k8s/multiport/resource-command" + "path": "k8s/multiport/reference/resource-command" } ] }, From 66c98eb151f7ab2c4c6134b2c56e6c308ddf5c2e Mon Sep 17 00:00:00 2001 From: boruszak Date: Wed, 25 Oct 2023 15:23:54 -0700 Subject: [PATCH 06/57] New resource pages - creation --- .../k8s/multiport/reference/grpcroute.mdx | 135 +++++++++ .../k8s/multiport/reference/httproute.mdx | 263 ++++++++++++++++++ .../reference/proxyconfiguration.mdx | 96 +++++++ .../docs/k8s/multiport/reference/tcproute.mdx | 135 +++++++++ .../reference/trafficpermissions.mdx | 116 ++++++++ website/data/docs-nav-data.json | 29 +- 6 files changed, 772 insertions(+), 2 deletions(-) create mode 100644 website/content/docs/k8s/multiport/reference/grpcroute.mdx create mode 100644 website/content/docs/k8s/multiport/reference/httproute.mdx create mode 100644 website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx create mode 100644 website/content/docs/k8s/multiport/reference/tcproute.mdx create mode 100644 website/content/docs/k8s/multiport/reference/trafficpermissions.mdx diff --git a/website/content/docs/k8s/multiport/reference/grpcroute.mdx b/website/content/docs/k8s/multiport/reference/grpcroute.mdx new file mode 100644 index 000000000000..2595602140ec --- /dev/null +++ b/website/content/docs/k8s/multiport/reference/grpcroute.mdx @@ -0,0 +1,135 @@ +--- +layout: docs +page_title: Reference topic for structured information +description: Front-load meta descriptions with keywords and keyword +phrases to help readers find the information they are searching for. +--- + +# GRPCRoute configuration reference + +This sample page template shows how to format high structured reference +information. + +## Configuration model + +The following list outlines field hierarchy, language-specific data types, +and requirements in . Click on a property name +to view additional details, including default values. + +- [`elem_a`](#elema): data type | default +- [`elem_b`](#elemb): data type | default +- [`spec`](#elemb): data type | default +- [`elem_ba`](#elembelemba): data type | default +- [`elem_baa`](#elembelembaelembaa): data type | default +- [`elem_baaa`](#elembelembaelembaa): data type | default +- [`elem_baab`](#elembelembaelembaa): data type | default +- [`elem_baac`](#elembelembaelembaa): data type | default +- [`element_bab`](#elembelembaelembab): data type | default + +## Complete configuration + +The complete configuration follows the configuration model. Use tabs for +each markup language you expect pracitioners to use. + +```yaml +element_a: +element_b: +element_bb: +element_bbb: +element_bbba: +element_bbbb: +element_bbbc: +- +element_bbbd: +``` +## Specification + +The specification block contains the details about each configuration. It +is a flattened representation of the configuration model block that allows +for extended descriptions, examples, and other information to help readers +understand the behavior of the configurations. + +### `Elem_a` + +Use this space to thoroughly, but succinctly, document the configuration +item. This format is intended to allow you to create complete documentation, +however, _stay within the scope of the reference_. If the description +deviates from the reference material, create a new Concept topic or add the +information to an existing Concept. + +#### Values + +- Default: default value or none +- This field is required. . Click on a property name +to view additional details, including default values. + +- [`apiVersion`](#apiversion): string | required +- [`kind`](#kind): string | required +- [`metadata`](#metadata): object | required + - [`name`](#metadata-name): string | required + - [`namespace`](#metadata-namespace): string | optional +- [`spec`](#spec): object | required + - [`parentRefs`](#spec-parentrefs): + - [`ref`](#spec-parentrefs-ref): + - [`type`](#spec-parentrefs-ref-type): +- [`group`] +- [`groupVersion`] +- [`kind`] +- [`name`] +- [`section`] +- [`tenancy`] + - [`namespace`] + - [`partition`] + - [`peerName`] + - [‘port’] + - [`rules`](#spec-rules): + - [`backendRefs`] + - [`backendRef`] + - [`ref`] + - [`type`] + - [`group`] + - [`groupVersion`] + - [`kind`] + - [`name`] + - [`section`] + - [`tenancy`] + - [`namespace`] + - [`partition`] + - [`peerName`] + - [`datacenter`] +- [`port`] + - [`weight`] + +## Complete configuration + +The complete configuration follows the configuration model. Use tabs for +each markup language you expect pracitioners to use. + +```yaml +apiVersion: +kind: HTTPRoute +metadata: +spec: + parentRefs: + port: + ref: + name: + section: + tenancy: + namespace: + partition: + peerName: + type: + group: + groupVersion: + kind: + rules: + backendRefs: + backendRef: + datacenter: + port: + ref: + name: + tenancy: + namespace: + partition: + peerName: + type: + group: + groupVersion: + kind: + filters: + requestHeaderModifier: + add: + name: + value: + remove: + name: + value: + set: + name: + value: + responseHeaderModifier: + add: + name: + value: + remove: + name: + value: + set: + name: + value: + urlRewrite: + pathPrefix: + weight: + filters: + requestHeaderModifier: + add: + name: + value: + remove: + name: + value: + set: + name: + value: + responseHeaderModifier: + add: + name: + value: + remove: + name: + value: + set: + name: + value: + urlRewrite: + pathPrefix: + matches: + headers: + invert: + name: + type: + method: + path: + type: + queryParams: + name: + type: + retries: + number: + onConditions: + onConnectFailure: + onStatusCodes: + timeouts: + idle: + nanos: + seconds: + request: + nanos: + seconds: + status: + conditions: + lastTransitionTime: + message: + reason: + status: + type: + lastSyncedTime: +``` +## Specification + +The specification block contains the details about each configuration. It +is a flattened representation of the configuration model block that allows +for extended descriptions, examples, and other information to help readers +understand the behavior of the configurations. + +### `Elem_a` + +Use this space to thoroughly, but succinctly, document the configuration +item. This format is intended to allow you to create complete documentation, +however, _stay within the scope of the reference_. If the description +deviates from the reference material, create a new Concept topic or add the +information to an existing Concept. + +#### Values + +- Default: default value or none +- This field is required. . Click on a property name +to view additional details, including default values. + +- [`elem_a`](#elema): data type | default +- [`elem_b`](#elemb): data type | default +- [`spec`](#elemb): data type | default +- [`elem_ba`](#elembelemba): data type | default +- [`elem_baa`](#elembelembaelembaa): data type | default +- [`elem_baaa`](#elembelembaelembaa): data type | default +- [`elem_baab`](#elembelembaelembaa): data type | default +- [`elem_baac`](#elembelembaelembaa): data type | default +- [`element_bab`](#elembelembaelembab): data type | default + +## Complete configuration + +The complete configuration follows the configuration model. Use tabs for +each markup language you expect pracitioners to use. + +```yaml +element_a: +element_b: +element_bb: +element_bbb: +element_bbba: +element_bbbb: +element_bbbc: +- +element_bbbd: +``` +## Specification + +The specification block contains the details about each configuration. It +is a flattened representation of the configuration model block that allows +for extended descriptions, examples, and other information to help readers +understand the behavior of the configurations. + +### `Elem_a` + +Use this space to thoroughly, but succinctly, document the configuration +item. This format is intended to allow you to create complete documentation, +however, _stay within the scope of the reference_. If the description +deviates from the reference material, create a new Concept topic or add the +information to an existing Concept. + +#### Values + +- Default: default value or none +- This field is required. . Click on a property name +to view additional details, including default values. + +- [`elem_a`](#elema): data type | default +- [`elem_b`](#elemb): data type | default +- [`spec`](#elemb): data type | default +- [`elem_ba`](#elembelemba): data type | default +- [`elem_baa`](#elembelembaelembaa): data type | default +- [`elem_baaa`](#elembelembaelembaa): data type | default +- [`elem_baab`](#elembelembaelembaa): data type | default +- [`elem_baac`](#elembelembaelembaa): data type | default +- [`element_bab`](#elembelembaelembab): data type | default + +## Complete configuration + +The complete configuration follows the configuration model. Use tabs for +each markup language you expect pracitioners to use. + +```yaml +element_a: +element_b: +element_bb: +element_bbb: +element_bbba: +element_bbbb: +element_bbbc: +- +element_bbbd: +``` +## Specification + +The specification block contains the details about each configuration. It +is a flattened representation of the configuration model block that allows +for extended descriptions, examples, and other information to help readers +understand the behavior of the configurations. + +### `Elem_a` + +Use this space to thoroughly, but succinctly, document the configuration +item. This format is intended to allow you to create complete documentation, +however, _stay within the scope of the reference_. If the description +deviates from the reference material, create a new Concept topic or add the +information to an existing Concept. + +#### Values + +- Default: default value or none +- This field is required. . Click on a property name +to view additional details, including default values. + +- [`elem_a`](#elema): data type | default +- [`elem_b`](#elemb): data type | default +- [`spec`](#elemb): data type | default +- [`elem_ba`](#elembelemba): data type | default +- [`elem_baa`](#elembelembaelembaa): data type | default +- [`elem_baaa`](#elembelembaelembaa): data type | default +- [`elem_baab`](#elembelembaelembaa): data type | default +- [`elem_baac`](#elembelembaelembaa): data type | default +- [`element_bab`](#elembelembaelembab): data type | default + +## Complete configuration + +The complete configuration follows the configuration model. Use tabs for +each markup language you expect pracitioners to use. + +```yaml +apiVersion: auth.consul.hashicorp.com/v2beta1 # required +kind: TrafficPermissions # required +metadata: + name: + namespace: +spec: + destination: + identityName: + action: allow + permissions: + - sources: + - namespace: + identityName: + destinationRules: + - pathExact: + methods: ["GET", "POST"] + portNames: [""] +``` +## Specification + +The specification block contains the details about each configuration. It +is a flattened representation of the configuration model block that allows +for extended descriptions, examples, and other information to help readers +understand the behavior of the configurations. + +### `Elem_a` + +Use this space to thoroughly, but succinctly, document the configuration +item. This format is intended to allow you to create complete documentation, +however, _stay within the scope of the reference_. If the description +deviates from the reference material, create a new Concept topic or add the +information to an existing Concept. + +#### Values + +- Default: default value or none +- This field is required. Date: Wed, 25 Oct 2023 15:25:20 -0700 Subject: [PATCH 07/57] nav fix --- website/data/docs-nav-data.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 71b3ceddf723..e2d6255f4a24 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -1555,7 +1555,7 @@ }, { "title": "ProxyConfiguration resource", - "path": "k8s/multiport/reference/grpcroute" + "path": "k8s/multiport/reference/proxyconfiguration" }, { "title": "TCPRoute resource", From 9c1e4cdea0c3d4113b6b0c96826e9433f96a140d Mon Sep 17 00:00:00 2001 From: boruszak Date: Wed, 25 Oct 2023 15:54:29 -0700 Subject: [PATCH 08/57] resource info --- .../k8s/multiport/reference/grpcroute.mdx | 145 +++++++++++++++--- .../k8s/multiport/reference/httproute.mdx | 29 ++-- .../docs/k8s/multiport/reference/tcproute.mdx | 63 ++++++-- 3 files changed, 190 insertions(+), 47 deletions(-) diff --git a/website/content/docs/k8s/multiport/reference/grpcroute.mdx b/website/content/docs/k8s/multiport/reference/grpcroute.mdx index 2595602140ec..abfd980a66ed 100644 --- a/website/content/docs/k8s/multiport/reference/grpcroute.mdx +++ b/website/content/docs/k8s/multiport/reference/grpcroute.mdx @@ -1,20 +1,18 @@ --- layout: docs -page_title: Reference topic for structured information -description: Front-load meta descriptions with keywords and keyword -phrases to help readers find the information they are searching for. +page_title: GRPCRoute resource configuration reference +description: The GRPCRoute resource CRD configures L7 GRPC traffic behavior within the service mesh. GRPCRoute is a GAMMA resource that requires the v2 catalog API. Learn how to configure the GRPCRoute CRD with specifications and example configurations. --- -# GRPCRoute configuration reference +# GRPCRoute resource configuration reference -This sample page template shows how to format high structured reference -information. +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 GAMMA resource that requires the [v2 catalog API](/consul/docs/architecture/catalog/v2). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog/v1). 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 . Click on a property name -to view additional details, including default values. +The following list outlines field hierarchy, language-specific data types, and requirements in a GRPCRoute CRD. Click on a property name to view additional details, including default values. - [`elem_a`](#elema): data type | default - [`elem_b`](#elemb): data type | default @@ -28,26 +26,125 @@ to view additional details, including default values. ## Complete configuration -The complete configuration follows the configuration model. Use tabs for -each markup language you expect pracitioners to use. +When every field is defined, a GRPCRoute CRD has the following form: ```yaml -element_a: -element_b: -element_bb: -element_bbb: -element_bbba: -element_bbbb: -element_bbbc: -- -element_bbbd: +apiVersion: mesh.consul.hashicorp.com/v2beta1 +kind: HTTPRoute +metadata: +hostnames: +spec: + parentRefs: + port: + ref: + name: + section: + tenancy: + namespace: + partition: + peerName: + type: + group: + groupVersion: + kind: + rules: + backendRefs: + backendRef: + datacenter: + port: + ref: + name: + tenancy: + namespace: + partition: + peerName: + type: + group: + groupVersion: + kind: + filters: + requestHeaderModifier: + add: + name: + value: + remove: + name: + value: + set: + name: + value: + responseHeaderModifier: + add: + name: + value: + remove: + name: + value: + set: + name: + value: + urlRewrite: + pathPrefix: + weight: + filters: + requestHeaderModifier: + add: + name: + value: + remove: + name: + value: + set: + name: + value: + responseHeaderModifier: + add: + name: + value: + remove: + name: + value: + set: + name: + value: + urlRewrite: + pathPrefix: + matches: + headers: + invert: + name: + type: + method: + path: + type: + queryParams: + name: + type: + retries: + number: + onConditions: + onConnectFailure: + onStatusCodes: + timeouts: + idle: + nanos: + seconds: + request: + nanos: + seconds: + status: + conditions: + lastTransitionTime: + message: + reason: + status: + type: + lastSyncedTime: ``` + ## Specification -The specification block contains the details about each configuration. It -is a flattened representation of the configuration model block that allows -for extended descriptions, examples, and other information to help readers -understand the behavior of the configurations. +This section provides details about the fields you can configure in the GRPCRoute CRD. ### `Elem_a` diff --git a/website/content/docs/k8s/multiport/reference/httproute.mdx b/website/content/docs/k8s/multiport/reference/httproute.mdx index b9491da452d5..64390d994ae3 100644 --- a/website/content/docs/k8s/multiport/reference/httproute.mdx +++ b/website/content/docs/k8s/multiport/reference/httproute.mdx @@ -1,20 +1,18 @@ --- layout: docs -page_title: Reference topic for structured information -description: Front-load meta descriptions with keywords and keyword -phrases to help readers find the information they are searching for. +page_title: HTTPRoute resource configuration reference +description: The HTTPRoute resource CRD configures L7 GRPC traffic behavior within the service mesh. GRPCRoute is a GAMMA resource that requires the v2 catalog API. Learn how to configure the HTTPRoute CRD with specifications and example configurations. --- -# HTTPRoute configuration reference +# HTTPRoute resource configuration reference -This sample page template shows how to format high structured reference -information. +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 GAMMA resource that requires the [v2 catalog API](/consul/docs/architecture/catalog/v2). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog/v1). 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 . Click on a property name -to view additional details, including default values. +The following list outlines field hierarchy, language-specific data types, and requirements in an HTTPRoute CRD. Click on a property name to view additional details, including default values. - [`apiVersion`](#apiversion): string | required - [`kind`](#kind): string | required @@ -25,7 +23,7 @@ to view additional details, including default values. - [`parentRefs`](#spec-parentrefs): - [`ref`](#spec-parentrefs-ref): - [`type`](#spec-parentrefs-ref-type): -- [`group`] +- [`group`] - [`groupVersion`] - [`kind`] - [`name`] @@ -51,17 +49,19 @@ to view additional details, including default values. - [`peerName`] - [`datacenter`] - [`port`] - - [`weight`] +- [`weight`] ## Complete configuration -The complete configuration follows the configuration model. Use tabs for -each markup language you expect pracitioners to use. +When every field is defined, an HTTPRoute CRD has the following form: ```yaml -apiVersion: +apiVersion: mesh.consul.hashicorp.com/v2beta1 kind: HTTPRoute metadata: + name: + namespace: +hostnames: spec: parentRefs: port: @@ -170,6 +170,7 @@ spec: type: lastSyncedTime: ``` + ## Specification The specification block contains the details about each configuration. It diff --git a/website/content/docs/k8s/multiport/reference/tcproute.mdx b/website/content/docs/k8s/multiport/reference/tcproute.mdx index 11ec27935224..476aed4d3948 100644 --- a/website/content/docs/k8s/multiport/reference/tcproute.mdx +++ b/website/content/docs/k8s/multiport/reference/tcproute.mdx @@ -32,16 +32,61 @@ The complete configuration follows the configuration model. Use tabs for each markup language you expect pracitioners to use. ```yaml -element_a: -element_b: -element_bb: -element_bbb: -element_bbba: -element_bbbb: -element_bbbc: -- -element_bbbd: +apiVersion: mesh.consul.hashicorp.com/v2beta1 +kind: HTTPRoute +metadata: +hostnames: +spec: + parentRefs: + port: + ref: + name: + section: + tenancy: + namespace: + partition: + peerName: + type: + group: + groupVersion: + kind: + rules: + backendRefs: + backendRef: + datacenter: + port: + ref: + name: + tenancy: + namespace: + partition: + peerName: + type: + group: + groupVersion: + kind: + retries: + number: + onConditions: + onConnectFailure: + onStatusCodes: + timeouts: + idle: + nanos: + seconds: + request: + nanos: + seconds: + status: + conditions: + lastTransitionTime: + message: + reason: + status: + type: + lastSyncedTime: ``` + ## Specification The specification block contains the details about each configuration. It From bf25be6df6ffe889f183d33e664b83ca0cca5711 Mon Sep 17 00:00:00 2001 From: boruszak Date: Wed, 25 Oct 2023 16:09:24 -0700 Subject: [PATCH 09/57] specs start --- .../k8s/multiport/reference/grpcroute.mdx | 102 ++++++++++++++---- 1 file changed, 83 insertions(+), 19 deletions(-) diff --git a/website/content/docs/k8s/multiport/reference/grpcroute.mdx b/website/content/docs/k8s/multiport/reference/grpcroute.mdx index abfd980a66ed..c58db7666b47 100644 --- a/website/content/docs/k8s/multiport/reference/grpcroute.mdx +++ b/website/content/docs/k8s/multiport/reference/grpcroute.mdx @@ -29,8 +29,8 @@ The following list outlines field hierarchy, language-specific data types, and r When every field is defined, a GRPCRoute CRD has the following form: ```yaml -apiVersion: mesh.consul.hashicorp.com/v2beta1 -kind: HTTPRoute +apiVersion: mesh.consul.hashicorp.com/v2beta1 # required +kind: HTTPRoute # required metadata: hostnames: spec: @@ -146,34 +146,98 @@ spec: This section provides details about the fields you can configure in the GRPCRoute CRD. -### `Elem_a` +### `apiVersion` -Use this space to thoroughly, but succinctly, document the configuration -item. This format is intended to allow you to create complete documentation, -however, _stay within the scope of the reference_. If the description -deviates from the reference material, create a new Concept topic or add the -information to an existing Concept. +Specifies the version of the Consul API for integrating with Kubernetes. The value must be `mesh.consul.hashicorp.com/v2beta1`. #### Values -- Default: default value or none -- This field is required. + +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 must align with GAMMAs resource. Refer to [GRPCRoute in the Kubernetes documentation](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1alpha2.GRPCRoute). #### Values -- Default: default value or none -- This field is required. Date: Thu, 26 Oct 2023 11:40:18 -0700 Subject: [PATCH 10/57] GRPCRoute specs and structure --- .../k8s/multiport/reference/grpcroute.mdx | 615 ++++++++++++++---- 1 file changed, 505 insertions(+), 110 deletions(-) diff --git a/website/content/docs/k8s/multiport/reference/grpcroute.mdx b/website/content/docs/k8s/multiport/reference/grpcroute.mdx index c58db7666b47..c4c981d0af0b 100644 --- a/website/content/docs/k8s/multiport/reference/grpcroute.mdx +++ b/website/content/docs/k8s/multiport/reference/grpcroute.mdx @@ -26,13 +26,14 @@ The following list outlines field hierarchy, language-specific data types, and r ## Complete configuration -When every field is defined, a GRPCRoute CRD has the following form: +When every field is defined, a GRPCRoute resource CRD has the following form: ```yaml apiVersion: mesh.consul.hashicorp.com/v2beta1 # required -kind: HTTPRoute # required +kind: GRPCRoute # required metadata: -hostnames: + name: + namespace: spec: parentRefs: port: @@ -43,104 +44,56 @@ spec: namespace: partition: peerName: - type: - group: - groupVersion: - kind: - rules: - backendRefs: - backendRef: - datacenter: - port: - ref: - name: - tenancy: - namespace: - partition: - peerName: - type: - group: - groupVersion: - kind: - filters: - requestHeaderModifier: - add: - name: - value: - remove: - name: - value: - set: - name: - value: - responseHeaderModifier: - add: - name: - value: - remove: - name: - value: - set: - name: - value: - urlRewrite: - pathPrefix: - weight: + rules: + backendRefs: + backendRef: + datacenter: + port: + ref: + name: + section: + tenancy: + namespace: + partition: + peerName: + type: + group: + groupVersion: + kind: filters: requestHeaderModifier: - add: - name: - value: - remove: - name: - value: - set: - name: - value: responseHeaderModifier: - add: - name: - value: - remove: - name: - value: - set: - name: - value: urlRewrite: pathPrefix: - matches: - headers: - invert: - name: - type: - method: - path: - type: - queryParams: - name: - type: - retries: - number: - onConditions: - onConnectFailure: - onStatusCodes: - timeouts: - idle: - nanos: - seconds: - request: - nanos: - seconds: - status: - conditions: - lastTransitionTime: - message: - reason: - status: - type: - lastSyncedTime: -``` + weight: + filters: + requestHeaderModifier: + responseHeaderModifier: + urlRewrite: + pathPrefix: + matches: + headers: + name: + type: + value: + method: + method: + service: + type: + retries: + number: + value: + onConditions: + onConnectFailure: false + onStatusCodes: [400, 404] + timeouts: + idle: + nanos: + seconds: + request: + nanos: + seconds: +``` ## Specification @@ -158,13 +111,13 @@ Specifies the version of the Consul API for integrating with Kubernetes. The val ### `kind` -Specifies the type of CRD to implement. Must be set to `HTTPRoute`. +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 `HTTPRoute`. +- Data type: String value that must be set to `GRPCRoute`. ## `metadata` @@ -221,8 +174,7 @@ References the resources (usually Services) ### `spec.parentRefs.port` -For east/west this is the name of the Consul Service - port to direct traffic to or empty to imply all. +For east/west this is the name of the Consul Service port to direct traffic to or empty to imply all. #### Values @@ -231,26 +183,469 @@ For east/west this is the name of the Consul Service ### `spec.parentRefs.ref` -For east/west configuration, this should point - to a Service. +For east/west configuration, this should point to a Service. #### Values - Default: None - Data type: Map -## Examples +### `spec.parentRefs.ref.name` + +Name is the user-given name of the resource + (e.g. the "billing" service). + +#### Values + +- Default: None +- Data type: String + +### `spec.parentRefs.ref.section` + +Section identifies which part of the resource the condition relates to. + +#### Values + +- Default: None +- Data type: String + +### `spec.parentRefs.ref.tenancy` + +Tenancy identifies the tenancy units (i.e. partition, namespace) in which the resource resides. + +#### Values + +- Default: None +- Data type: Map containing the following parameters: + + | Parameter | Description | Data type | Default | + | :------------ | :------------------------------------------------------------------- | :-------- | :------- | + | `namespace` | Identifies the namespace where the resource applies. | String | None | + | `partition` | Identifies the admin partition where the resource applies. | String | None | + | `peerName` | Identifies the name of a cluster peer the resource is imported from. | String | None | + +### `spec.rules` + +Rules are a list of GRPC matchers, filters and actions. + +#### Values + +- Default: None +- Data type: Map -If you have more than one example to show, create an Examples section -(general block) and introduce the examples per the style guide. +### `spec.rules.backendRefs` + +BackendRefs defines the backend(s) where matching requests should be sent. Failure behavior here depends on how many BackendRefs are specified and how many are invalid. If all entries in BackendRefs are invalid, and there are also no filters specified in this route rule, all traffic which matches this rule MUST receive a 500 status code. See the GRPCBackendRef definition for the rules about what makes a single GRPCBackendRef invalid. When a GRPCBackendRef is invalid, 500 status codes MUST be returned for requests that would have otherwise been routed to an invalid backend. + +If multiple backends are specified, and some are invalid, the proportion of requests that would otherwise have been routed to an invalid backend MUST receive a 500 status code. For example, if two backends are specified with equal weights, and one is invalid, 50 percent of traffic must receive a 500. Implementations may choose how that 50 percent is determined. + +#### Values + +- Default: None +- Data type: Map + +### `spec.rules.backendRefs.backendRef` + +Defines an individual backend where matching requests should be sent. + +#### Values + +- Default: None +- Data type: Map + +### `spec.rules.backendRefs.backendRef.datacenter` + +Specifies the name of the datacenter + +#### Values + +- Default: None +- Data type: String + +### `spec.rules.backendRefs.backendRef.port` + +For east/west this is the name of the Consul Service port to direct traffic to or empty to imply using the same value as the parent ref. + +#### Values + +- Default: None +- Data type: String + +### `spec.rules.backendRefs.backendRef.ref` + +For east/west configuration, this should point to a Service. + +#### Values + +- Default: None +- Data type: Map + +### `spec.rules.backendRefs.backendRef.ref.name` + +Name is the user-given name of the resource(e.g. the "billing" service). + +#### Values + +- Default: None +- Data type: String + +### `spec.rules.backendRefs.backendRef.ref.section` + +Section identifies which part of the resource the condition relates to. + +#### Values + +- Default: None +- Data type: String + +### `spec.rules.backendRefs.backendRef.ref.tenancy` + +Tenancy identifies the tenancy units (i.e. partition, namespace) where the rule applies. + +#### Values + +- Default: None +- Data type: Map containing the following parameters: + + | Parameter | Description | Data type | Default | + | :------------ | :------------------------------------------------------------------- | :-------- | :------- | + | `namespace` | Identifies the namespace where the resource applies. | String | None | + | `partition` | Identifies the admin partition where the resource applies. | String | None | + | `peerName` | Identifies the name of a cluster peer the resource is imported from. | String | None | + +### `spec.rules.backendRefs.backendRef.ref.type` + +Type identifies the resource's type. + +#### Values + +- Default: None +- Data type: Map containing the following parameters: + + | Parameter | Description | Data type | Default | + | :------------ | :------------------------------------------------------------------- | :-------- | :------- | + | `group` | Describes the area of functionality to which this resource type relates. | String | None | + | `groupVersion` | Increments when sweeping or backward-incompatible changes are made to the group's resource types. | String (in code, should be int based on desc.) | None | + | `kind` | Iidentifies the specific resource type within the group. | String | None | + +### `spec.rules.backendRefs.filters` + +Filters defined at this level should be executed if and only if the request is being forwarded to the backend defined here. + +#### Values + +- Default: None +- Data type: Map + +### `spec.rules.backendRefs.filters.requestHeaderModifier` + +Specifies a set of HTTP-specific header modification rules applied to requests routed with the GRPCRoute 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 | + +### `spec.rules.backendRefs.filters.responseHeaderModifier` + +Specifies a set of HTTP-specific header modification rules applied to responses routed with the GRPCRoute 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 | + +### `spec.rules.backendRefs.filters.urlRewrite` + +URLRewrite defines a schema for a filter that modifies a request during forwarding. + +#### Values + +- Default: None +- Data type: Map containing the following parameter: + + | Parameter | Description | Data type | Default | + | :------------ | :------------------------------------------------------------------------------------------------- | --------- | ------- | + | `pathPrefix` | Specifies the number of random healthy hosts from which to select the one with the least requests. | String | None | + +### `spec.rules.backendRefs.weight` + +Weight specifies the proportion of requests forwarded to the referenced backend. This is computed as weight/(sum of all weights in this BackendRefs list). For non-zero values, there may be some epsilon from the exact proportion defined here depending on the precision an implementation supports. Weight is not a percentage and the sum of weights does not need to equal 100. If only one backend is specified and it has a weight greater than 0, 100% of the traffic is forwarded to that backend. If weight is set to 0, no traffic should be forwarded for this entry. If unspecified, weight defaults to 1. + +#### Values + +- Default: `1` +- Data type: Integer + +### `spec.rules.filters` + +Weight specifies the proportion of requests forwarded to the referenced backend. This is computed as weight/(sum of all weights in this BackendRefs list). For non-zero values, there may be some epsilon from the exact proportion defined here depending on the precision an implementation supports. Weight is not a percentage and the sum of weights does not need to equal 100. If only one backend is specified and it has a weight greater than 0, 100% of the traffic is forwarded to that backend. If weight is set to 0, no traffic should be forwarded for this entry. If unspecified, weight defaults to 1. + +#### Values + +- Default: None +- Data type: Map + +### `spec.rules.filters.requestHeaderModifier` + +Specifies a set of HTTP-specific header modification rules applied to requests routed with the GRPCRoute 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 | + +### `spec.rules.filters.responseHeaderModifier` + +Specifies a set of HTTP-specific header modification rules applied to responses routed with the GRPCRoute 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 | + +### `spec.rules.filters.urlRewrite` + +URLRewrite defines a schema for a filter that modifies a request during forwarding. + +#### Values + +- Default: None +- Data type: Map containing the following parameter: + + | Parameter | Description | Data type | Default | + | :------------ | :------------------------------------------------------------------------------------------------- | --------- | ------- | + | `pathPrefix` | Specifies the number of random healthy hosts from which to select the one with the least requests. | String | None | + +### `spec.rules.matches` + +Specifies matching rules + +#### Values + +- Default: None +- Data type: Map + +### `spec.rules.matches.headers` + +Headers specifies gRPC request header matchers. Multiple match values are ANDed together, meaning, a request MUST match all the specified headers to select the route. + +#### Values + +- Default: None +- Data type: Map + +### `spec.rules.matches.headers.name` + +Name of the header to match on. + +#### Values + +- Default: None +- Data type: String + +### `spec.rules.matches.headers.type` + +HeaderMatchType specifies the semantics of how HTTP header values should be compared. Valid HeaderMatchType values, along with their conformance levels, are: \n Note that values may be added to this enum, implementations must ensure that unknown values will not cause a crash. Unknown values here must result in the implementation setting the Accepted Condition for the Route to status: False, with a Reason of UnsupportedValue. + +#### 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 header to match. + +#### Values + +- Default: None +- Data type: String + +### `spec.rules.matches.method` + +Specifies a gRPC request service/method matcher. If this field is not specified, all services and methods will match. + +#### Values + +- Default: None +- Data type: Map + +### `spec.rules.matches.method.method` + +Value of the method to match against. If left empty or omitted, will match all services. At least one of Service and Method MUST be a non-empty string. + +#### Values + +- Default: None +- Data type: String + +### `spec.rules.matches.method.service` + +Value of the service to match against. If left empty or omitted, will match any service. At least one of Service and Method MUST be a non-empty string. + +#### Values + +- Default: None +- Data type: String + +### `spec.rules.matches.method.type` + +Type specifies how to match against the service and/or method. + +#### 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 the resource. + +#### Values + +- Default: None +- Data type: Map + +### `spec.rules.retries.number` + +Specifies retry logic for the resource. + +#### 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` + +RetryOn allows setting envoy specific conditions when a request should be automatically retried. + +#### Values + +- Default: None +- Data type: Array of strings + +### `spec.rules.retries.onConnnectFailure` + +Allows for connection failure errors to trigger a retry. + +#### Values + +- Default: `false` +- Data type: Boolean + +### `spec.rules.retries.onStatusCodes` + +Flat list of http response status codes that are eligible for retry. This again should be feasible in any reasonable proxy. + +#### Values + +- Default: None +- Data type: Array of integers + +### `spec.rules.timeouts` + +Specifies timeout logic for the resource. + +#### Values + +- Default: None +- Data type: Map + +### `spec.rules.timeouts.idle` + +Specifies the total amount of time permitted for the request stream to be idle. + +#### Values + +- Default: None +- Data type: Map that can contain the following parameters: + + | Parameter | Description | Data type | Default | + | :-------- | :--------------------------------------------------------------- | --------- | ------- | + | `nanos` | Specifies the number of nanoseconds before triggering a timeout. | Integer | None | + | `seconds` | Specifies the number of seconds before triggering a timeout. | Integer | None | + +### `spec.rules.timeouts.request` + +Specifies the total amount of time permitted for the entire downstream request and retries to be processed before triggering a timeout. + +#### Values + +- Default: None +- Data type: Map that can contain the following parameters: + + | Parameter | Description | Data type | Default | + | :-------- | :--------------------------------------------------------------- | --------- | ------- | + | `nanos` | Specifies the number of nanoseconds before triggering a timeout. | Integer | None | + | `seconds` | Specifies the number of seconds before triggering a timeout. | Integer | None | + +## Examples -### Specific use case +If you have more than one example to show, create an Examples section (general block) and introduce the examples per the style guide. -Introduce examples clearly and help readers understand the connections -between the example snippet and the configuration element you are trying to -explain. Use phrases such as "In the following example, the `elem` performs -some action on a service named `service-name`". +### Split service traffic between two ports +The following configuration 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 From 87a1fc24aef0753f0462b806585ea88be1cfdc1a Mon Sep 17 00:00:00 2001 From: boruszak Date: Thu, 26 Oct 2023 13:11:06 -0700 Subject: [PATCH 11/57] GRPCRoute configuration model --- .../k8s/multiport/reference/grpcroute.mdx | 107 +++++++++++++++--- 1 file changed, 93 insertions(+), 14 deletions(-) diff --git a/website/content/docs/k8s/multiport/reference/grpcroute.mdx b/website/content/docs/k8s/multiport/reference/grpcroute.mdx index c4c981d0af0b..e8d426232aed 100644 --- a/website/content/docs/k8s/multiport/reference/grpcroute.mdx +++ b/website/content/docs/k8s/multiport/reference/grpcroute.mdx @@ -14,15 +14,82 @@ This custom resource definition (CRD) describes a GAMMA resource that requires t The following list outlines field hierarchy, language-specific data types, and requirements in a GRPCRoute CRD. Click on a property name to view additional details, including default values. -- [`elem_a`](#elema): data type | default -- [`elem_b`](#elemb): data type | default -- [`spec`](#elemb): data type | default -- [`elem_ba`](#elembelemba): data type | default -- [`elem_baa`](#elembelembaelembaa): data type | default -- [`elem_baaa`](#elembelembaelembaa): data type | default -- [`elem_baab`](#elembelembaelembaa): data type | default -- [`elem_baac`](#elembelembaelembaa): data type | default -- [`element_bab`](#elembelembaelembab): data type | default +- [`apiVersion`](#apiversion): string | required +- [`kind`](#kind): string | required +- [`metadata`](#metadata): object | required + - [`name`](#metadata-name): string | required + - [`namespace`](#metadata-namespace): string | optional +- [`spec`](#spec): object | required + - [`parentRefs`](#spec-parentrefs): + - [`port`](#spec-parentrefs-port): + - [`ref`](#spec-parentrefs-ref): + - [`name`](#spec-parentrefs-ref-name): + - [`section`](#spec-parentrefs-ref-section): + - [`tenancy`](#spec-parentrefs-ref-tenancy): + - [`namespace`](#spec-parentrefs-ref-tenancy): + - [`partition`](#spec-parentrefs-ref-tenancy): + - [`peerName`](#spec-parentrefs-ref-tenancy): + - [`rules`](#spec-rules): + - [`backendRefs`](#spec-rules-backendrefs): + - [`backendRef`](#spec-rules-backendrefs-backendref): + - [`datacenter`](#spec-rules-backendrefs-backendref-datacenter): + - [`port`](#spec-rules-backendrefs-backendref-port): + - [`ref`](#spec-rules-backendrefs-backendref-ref): + - [`name`](#spec-rules-backendrefs-backendref-ref-name): + - [`section`](#spec-rules-backendrefs-backendref-ref-section): + - [`tenancy`](#spec-rules-backendrefs-backendref-ref-tenancy): + - [`namespace`](#spec-rules-backendrefs-backendref-ref-tenancy): + - [`partition`](#spec-rules-backendrefs-backendref-ref-tenancy): + - [`peerName`](#spec-rules-backendrefs-backendref-ref-tenancy): + - [`type`](#spec-rules-backendrefs-backendref-ref-type): + - [`group`](#spec-rules-backendrefs-backendref-ref-type): + - [`groupVersion`](#spec-rules-backendrefs-backendref-ref-type): + - [`kind`](#spec-rules-backendrefs-backendref-ref-type): + - [`filters`](#spec-rules-backendrefs-filters): + - [`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): + - [`pathPrefix`](#spec-rules-backendrefs-filters-urlrewrite): + - [`weight`](#spec-rules-backendrefs-weight): + - [`filters`](#spec-rules-filters): + - [`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): + - [`pathPrefix`](#spec-rules-filters-urlrewrite): + - [`matches`](#spec-rules-matches): + - [`headers`](#spec-rules-matches-headers): + - [`name`](#spec-rules-matches-headers-name): + - [`type`](#spec-rules-matches-headers-type): + - [`value`](#spec-rules-matches-headers-value): + - [`method`](#spec-rules-matches-method): + - [`method`](#spec-rules-matches-method-method): + - [`service`](#spec-rules-matches-method-service): + - [`type`](#spec-rules-matches-method-type): + - [`retries`](#spec-rules-retries): + - [`number`](#spec-rules-retries-number): + - [`value`](#spec-rules-retries-number): + - [`onConditions`](#spec-rules-retries-onconditions): + - [`onConnectFailure`](#spec-rules-retries-onconnectfailure): boolean | `false` + - [`onStatusCodes`](#spec-rules-retries-onconditions): array of integers + - [`timeouts`](#spec-rules-timeouts): + - [`idle`](#spec-rules-timeouts-idle): + - [`nanos`](#spec-rules-timeouts-idle): + - [`seconds`](#spec-rules-timeouts-idle): + - [`request`](#spec-rules-timeouts-request): + - [`nanos`](#spec-rules-timeouts-request): + - [`seconds`](#spec-rules-timeouts-request): ## Complete configuration @@ -62,13 +129,25 @@ spec: kind: filters: requestHeaderModifier: + add: + set: + remove: responseHeaderModifier: + add: + set: + remove: urlRewrite: pathPrefix: weight: filters: requestHeaderModifier: - responseHeaderModifier: + add: + set: + remove: + responseHeaderModifier: + add: + set: + remove: urlRewrite: pathPrefix: matches: @@ -76,10 +155,10 @@ spec: name: type: value: - method: method: - service: - type: + method: + service: + type: retries: number: value: @@ -97,7 +176,7 @@ spec: ## Specification -This section provides details about the fields you can configure in the GRPCRoute CRD. +This section provides details about the fields you can configure in the GRPCRoute custom resource definition (CRD). ### `apiVersion` From 7290e9d45831beeb473092cf33861791bf3f8521 Mon Sep 17 00:00:00 2001 From: boruszak Date: Thu, 26 Oct 2023 15:18:19 -0700 Subject: [PATCH 12/57] gRPCRoute models and examples --- .../k8s/multiport/reference/grpcroute.mdx | 441 +++++++++++------- 1 file changed, 272 insertions(+), 169 deletions(-) diff --git a/website/content/docs/k8s/multiport/reference/grpcroute.mdx b/website/content/docs/k8s/multiport/reference/grpcroute.mdx index e8d426232aed..7176f4f42def 100644 --- a/website/content/docs/k8s/multiport/reference/grpcroute.mdx +++ b/website/content/docs/k8s/multiport/reference/grpcroute.mdx @@ -14,50 +14,54 @@ This custom resource definition (CRD) describes a GAMMA resource that requires t The following list outlines field hierarchy, language-specific data types, and requirements in a GRPCRoute CRD. Click on a property name to view additional details, including default values. -- [`apiVersion`](#apiversion): string | required -- [`kind`](#kind): string | required +- [`apiVersion`](#apiversion): string | required | must be set to `mesh.consul.hashicorp.com/v2beta1` +- [`kind`](#kind): string | required | must be set to `GRPCRoute` - [`metadata`](#metadata): object | required - [`name`](#metadata-name): string | required - [`namespace`](#metadata-namespace): string | optional - [`spec`](#spec): object | required - - [`parentRefs`](#spec-parentrefs): - - [`port`](#spec-parentrefs-port): - - [`ref`](#spec-parentrefs-ref): - - [`name`](#spec-parentrefs-ref-name): - - [`section`](#spec-parentrefs-ref-section): - - [`tenancy`](#spec-parentrefs-ref-tenancy): - - [`namespace`](#spec-parentrefs-ref-tenancy): - - [`partition`](#spec-parentrefs-ref-tenancy): - - [`peerName`](#spec-parentrefs-ref-tenancy): - - [`rules`](#spec-rules): - - [`backendRefs`](#spec-rules-backendrefs): - - [`backendRef`](#spec-rules-backendrefs-backendref): - - [`datacenter`](#spec-rules-backendrefs-backendref-datacenter): - - [`port`](#spec-rules-backendrefs-backendref-port): - - [`ref`](#spec-rules-backendrefs-backendref-ref): - - [`name`](#spec-rules-backendrefs-backendref-ref-name): - - [`section`](#spec-rules-backendrefs-backendref-ref-section): - - [`tenancy`](#spec-rules-backendrefs-backendref-ref-tenancy): - - [`namespace`](#spec-rules-backendrefs-backendref-ref-tenancy): - - [`partition`](#spec-rules-backendrefs-backendref-ref-tenancy): - - [`peerName`](#spec-rules-backendrefs-backendref-ref-tenancy): - - [`type`](#spec-rules-backendrefs-backendref-ref-type): - - [`group`](#spec-rules-backendrefs-backendref-ref-type): - - [`groupVersion`](#spec-rules-backendrefs-backendref-ref-type): - - [`kind`](#spec-rules-backendrefs-backendref-ref-type): - - [`filters`](#spec-rules-backendrefs-filters): - - [`requestHeaderModifier`](#spec-rules-backendrefs-filters-requestheadermodifier): map + - [`parentRefs`](#spec-parentrefs): map | required + - [`port`](#spec-parentrefs-port): string + - [`ref`](#spec-parentrefs-ref): string | required + - [`name`](#spec-parentrefs-ref-name): string + - [`section`](#spec-parentrefs-ref-section): string + - [`tenancy`](#spec-parentrefs-ref-tenancy): string + - [`namespace`](#spec-parentrefs-ref-tenancy): string + - [`partition`](#spec-parentrefs-ref-tenancy): string + - [`peerName`](#spec-parentrefs-ref-tenancy): 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 + - [`section`](#spec-rules-backendrefs-backendref-ref-section): string + - [`tenancy`](#spec-rules-backendrefs-backendref-ref-tenancy): map + - [`namespace`](#spec-rules-backendrefs-backendref-ref-tenancy): string + - [`partition`](#spec-rules-backendrefs-backendref-ref-tenancy): string + - [`peerName`](#spec-rules-backendrefs-backendref-ref-tenancy): 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`]: map(#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 + - [`responseHeaderModifier`]: map(#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): - - [`pathPrefix`](#spec-rules-backendrefs-filters-urlrewrite): - - [`weight`](#spec-rules-backendrefs-weight): - - [`filters`](#spec-rules-filters): + - [`urlRewrite`](#spec-rules-backendrefs-filters-urlrewrite): map + - [`pathPrefix`](#spec-rules-backendrefs-filters-urlrewrite): string + - [`weight`](#spec-rules-backendrefs-weight): integer + - [`filters`](#spec-rules-filters): map - [`requestHeaderModifier`](#spec-rules-filters-requestheadermodifier): map - [`add`](#spec-rules-filters-requestheadermodifier): map - [`set`](#spec-rules-filters-requestheadermodifier): map @@ -66,112 +70,116 @@ The following list outlines field hierarchy, language-specific data types, and r - [`add`](#spec-rules-filters-responseheadermodifier): map - [`set`](#spec-rules-filters-responseheadermodifier): map - [`remove`](#spec-rules-filters-responseheadermodifier): map - - [`urlRewrite`](#spec-rules-filters-urlrewrite): - - [`pathPrefix`](#spec-rules-filters-urlrewrite): - - [`matches`](#spec-rules-matches): - - [`headers`](#spec-rules-matches-headers): - - [`name`](#spec-rules-matches-headers-name): - - [`type`](#spec-rules-matches-headers-type): - - [`value`](#spec-rules-matches-headers-value): - - [`method`](#spec-rules-matches-method): - - [`method`](#spec-rules-matches-method-method): - - [`service`](#spec-rules-matches-method-service): - - [`type`](#spec-rules-matches-method-type): - - [`retries`](#spec-rules-retries): - - [`number`](#spec-rules-retries-number): - - [`value`](#spec-rules-retries-number): - - [`onConditions`](#spec-rules-retries-onconditions): + - [`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): integer + - [`onConditions`](#spec-rules-retries-onconditions): map of strings - [`onConnectFailure`](#spec-rules-retries-onconnectfailure): boolean | `false` - - [`onStatusCodes`](#spec-rules-retries-onconditions): array of integers - - [`timeouts`](#spec-rules-timeouts): - - [`idle`](#spec-rules-timeouts-idle): - - [`nanos`](#spec-rules-timeouts-idle): - - [`seconds`](#spec-rules-timeouts-idle): - - [`request`](#spec-rules-timeouts-request): - - [`nanos`](#spec-rules-timeouts-request): - - [`seconds`](#spec-rules-timeouts-request): + - [`onStatusCodes`](#spec-rules-retries-onconditions): map of integers + - [`timeouts`](#spec-rules-timeouts): map + - [`idle`](#spec-rules-timeouts-idle): map + - [`nanos`](#spec-rules-timeouts-idle): integer + - [`seconds`](#spec-rules-timeouts-idle): integer + - [`request`](#spec-rules-timeouts-request): map + - [`nanos`](#spec-rules-timeouts-request): integer + - [`seconds`](#spec-rules-timeouts-request): integer ## Complete configuration When every field is defined, a GRPCRoute resource CRD has the following form: ```yaml -apiVersion: mesh.consul.hashicorp.com/v2beta1 # required +apiVersion: mesh.consul.hashicorp.com/v2beta1 # required kind: GRPCRoute # required metadata: - name: - namespace: + name: + namespace: spec: parentRefs: - port: - ref: - name: - section: + port: "" + - ref: + name: + section: tenancy: - namespace: - partition: - peerName: + namespace: + partition: + peerName: + type: + group: + groupVersion: + kind: rules: - backendRefs: - backendRef: - datacenter: - port: + - backendRefs: + - backendRef: + datacenter: + port: "" ref: - name: - section: + name: + section: tenancy: - namespace: - partition: - peerName: + namespace: + partition: + peerName: type: - group: - groupVersion: - kind: + group: + groupVersion: + kind: filters: - requestHeaderModifier: - add: - set: - remove: - responseHeaderModifier: + - requestHeaderModifier: add: + name: "" + value: "" + - responseHeaderModifier: set: - remove: + name: "" + value: "" urlRewrite: - pathPrefix: - weight: + pathPrefix: + weight: 1 filters: requestHeaderModifier: - add: - set: remove: + name: "" + value: "" responseHeaderModifier: add: - set: - remove: + name: "" + value: "" urlRewrite: - pathPrefix: + pathPrefix: matches: headers: - name: - type: - value: + name: + type: + value: method: - method: - service: - type: + method: + service: + type: retries: number: - value: - onConditions: + value: 1 + onConditions: ["cancelled", "unavailable"] onConnectFailure: false onStatusCodes: [400, 404] timeouts: idle: - nanos: - seconds: + nanos: 15 + seconds: 1 request: - nanos: - seconds: + nanos: 10 + seconds: 1 ``` ## Specification @@ -240,10 +248,7 @@ When using this CRD, the `spec` field must align with GAMMAs resource. Refer to ### `spec.parentRefs` -References the resources (usually Services) - that a Route wants to be attached to. \n It is invalid to reference - an identical parent more than once. It is valid to reference multiple - distinct sections within the same parent resource. +Specifies the resources to attach the route to. Usually these are services. You cannot reference the same `parentsRefs` multiple times. Instead, specify each [`spec.parentRefs.ref`](#spec-parentrefs-ref) in the same block. #### Values @@ -253,7 +258,7 @@ References the resources (usually Services) ### `spec.parentRefs.port` -For east/west this is the name of the Consul Service port to direct traffic to or empty to imply all. +Specifies the name of the Consul service's port that the configuration applies to. #### Values @@ -262,7 +267,7 @@ For east/west this is the name of the Consul Service port to direct traffic to o ### `spec.parentRefs.ref` -For east/west configuration, this should point to a Service. +Specifies the resource that the configuration applies to. #### Values @@ -271,8 +276,7 @@ For east/west configuration, this should point to a Service. ### `spec.parentRefs.ref.name` -Name is the user-given name of the resource - (e.g. the "billing" service). +Specifies the user-defined name of the resource that the configuration applies to. #### Values @@ -281,7 +285,7 @@ Name is the user-given name of the resource ### `spec.parentRefs.ref.section` -Section identifies which part of the resource the condition relates to. +Specifies the section of the resource that the configuration applies to. #### Values @@ -290,7 +294,7 @@ Section identifies which part of the resource the condition relates to. ### `spec.parentRefs.ref.tenancy` -Tenancy identifies the tenancy units (i.e. partition, namespace) in which the resource resides. +Specifies the user-defined namespace, partition, or cluster peer of the resource that the configuration applies to. #### Values @@ -299,13 +303,28 @@ Tenancy identifies the tenancy units (i.e. partition, namespace) in which the re | Parameter | Description | Data type | Default | | :------------ | :------------------------------------------------------------------- | :-------- | :------- | - | `namespace` | Identifies the namespace where the resource applies. | String | None | - | `partition` | Identifies the admin partition where the resource applies. | String | None | - | `peerName` | Identifies the name of a cluster peer the resource is imported from. | String | None | + | `namespace` | Identifies the namespace of the resource the configuration applies to. | String | None | + | `partition` | Identifies the admin partition of the resource the configuration applies to. | String | None | + | `peerName` | Identifies the name of a cluster peer the resource is imported from that the configuration applies to. | String | None | + +### `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 Kubenretes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String (in code, should be int based on desc.) | 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` -Rules are a list of GRPC matchers, filters and actions. +Specifies rules for sidecar proxies to direct a service's GRPC traffic within the service mesh, including filtering, retry, and timeout behavior. #### Values @@ -314,9 +333,11 @@ Rules are a list of GRPC matchers, filters and actions. ### `spec.rules.backendRefs` -BackendRefs defines the backend(s) where matching requests should be sent. Failure behavior here depends on how many BackendRefs are specified and how many are invalid. If all entries in BackendRefs are invalid, and there are also no filters specified in this route rule, all traffic which matches this rule MUST receive a 500 status code. See the GRPCBackendRef definition for the rules about what makes a single GRPCBackendRef invalid. When a GRPCBackendRef is invalid, 500 status codes MUST be returned for requests that would have otherwise been routed to an invalid backend. +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. -If multiple backends are specified, and some are invalid, the proportion of requests that would otherwise have been routed to an invalid backend MUST receive a 500 status code. For example, if two backends are specified with equal weights, and one is invalid, 50 percent of traffic must receive a 500. Implementations may choose how that 50 percent is determined. +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 is invalid, the relative weights are maintained and traffic is not redirected automatically. 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 @@ -325,7 +346,7 @@ If multiple backends are specified, and some are invalid, the proportion of requ ### `spec.rules.backendRefs.backendRef` -Defines an individual backend where matching requests should be sent. +Specifies an individual Service backend where matching requests should be sent. #### Values @@ -334,7 +355,7 @@ Defines an individual backend where matching requests should be sent. ### `spec.rules.backendRefs.backendRef.datacenter` -Specifies the name of the datacenter +Specifies the name of the Consul datacenter that registered the Service backend that the configuration routes traffic to. #### Values @@ -343,7 +364,7 @@ Specifies the name of the datacenter ### `spec.rules.backendRefs.backendRef.port` -For east/west this is the name of the Consul Service port to direct traffic to or empty to imply using the same value as the parent ref. +Specifies the name of the port for the Consul service that the configuration routes traffic to. #### Values @@ -352,7 +373,7 @@ For east/west this is the name of the Consul Service port to direct traffic to o ### `spec.rules.backendRefs.backendRef.ref` -For east/west configuration, this should point to a Service. +The Consul service that the configuration routes traffic to. #### Values @@ -361,7 +382,7 @@ For east/west configuration, this should point to a Service. ### `spec.rules.backendRefs.backendRef.ref.name` -Name is the user-given name of the resource(e.g. the "billing" service). +Specifies the user-defined name of the resource that the configuration routes traffic to. #### Values @@ -370,7 +391,7 @@ Name is the user-given name of the resource(e.g. the "billing" service). ### `spec.rules.backendRefs.backendRef.ref.section` -Section identifies which part of the resource the condition relates to. +Specifies the section the resource that the configuration routes traffic to. #### Values @@ -379,7 +400,7 @@ Section identifies which part of the resource the condition relates to. ### `spec.rules.backendRefs.backendRef.ref.tenancy` -Tenancy identifies the tenancy units (i.e. partition, namespace) where the rule applies. +Specifies the user-defined namespace, partition, or cluster peer of the resource that the configuration routes to. #### Values @@ -388,13 +409,13 @@ Tenancy identifies the tenancy units (i.e. partition, namespace) where the rule | Parameter | Description | Data type | Default | | :------------ | :------------------------------------------------------------------- | :-------- | :------- | - | `namespace` | Identifies the namespace where the resource applies. | String | None | - | `partition` | Identifies the admin partition where the resource applies. | String | None | - | `peerName` | Identifies the name of a cluster peer the resource is imported from. | String | None | + | `namespace` | Identifies the namespace of the resource the configuration routes traffic to. | String | None | + | `partition` | Identifies the admin partition of the resource the configuration routes traffic to. | String | None | + | `peerName` | Identifies the name of a cluster peer the resource is imported from that the configuration routes traffic to. | String | None | ### `spec.rules.backendRefs.backendRef.ref.type` -Type identifies the resource's 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 @@ -402,14 +423,13 @@ Type identifies the resource's type. - Data type: Map containing the following parameters: | Parameter | Description | Data type | Default | - | :------------ | :------------------------------------------------------------------- | :-------- | :------- | - | `group` | Describes the area of functionality to which this resource type relates. | String | None | - | `groupVersion` | Increments when sweeping or backward-incompatible changes are made to the group's resource types. | String (in code, should be int based on desc.) | None | - | `kind` | Iidentifies the specific resource type within the group. | String | None | + | `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 Kubenretes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String (in code, should be int based on desc.) | 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` -Filters defined at this level should be executed if and only if the request is being forwarded to the backend defined here. +Specifies filtering behavior for services configured in the same [`spec.rules.backendRefs`](#spec-rules-backendrefs) block. #### Values @@ -418,7 +438,7 @@ Filters defined at this level should be executed if and only if the request is b ### `spec.rules.backendRefs.filters.requestHeaderModifier` -Specifies a set of HTTP-specific header modification rules applied to requests routed with the GRPCRoute resource. +Specifies a set of header modification rules applied to requests routed with the GRPCRoute resource. #### Values @@ -438,7 +458,7 @@ The following table describes how to configure values for request headers: ### `spec.rules.backendRefs.filters.responseHeaderModifier` -Specifies a set of HTTP-specific header modification rules applied to responses routed with the GRPCRoute resource. +Specifies a set of header modification rules applied to responses routed with the GRPCRoute resource. #### Values @@ -458,7 +478,7 @@ The following table describes how to configure values for request headers: ### `spec.rules.backendRefs.filters.urlRewrite` -URLRewrite defines a schema for a filter that modifies a request during forwarding. +Specifies a path to modify the URL with when a request is forwarded. #### Values @@ -467,11 +487,15 @@ URLRewrite defines a schema for a filter that modifies a request during forwardi | Parameter | Description | Data type | Default | | :------------ | :------------------------------------------------------------------------------------------------- | --------- | ------- | - | `pathPrefix` | Specifies the number of random healthy hosts from which to select the one with the least requests. | String | None | + | `pathPrefix` | Specifies the path that is prepended to the URL. | String | None | ### `spec.rules.backendRefs.weight` -Weight specifies the proportion of requests forwarded to the referenced backend. This is computed as weight/(sum of all weights in this BackendRefs list). For non-zero values, there may be some epsilon from the exact proportion defined here depending on the precision an implementation supports. Weight is not a percentage and the sum of weights does not need to equal 100. If only one backend is specified and it has a weight greater than 0, 100% of the traffic is forwarded to that backend. If weight is set to 0, no traffic should be forwarded for this entry. If unspecified, weight defaults to 1. +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, 100% of traffic is forwarded. + +When this parameter is not specified, it assumes the default value `1`. #### Values @@ -480,7 +504,7 @@ Weight specifies the proportion of requests forwarded to the referenced backend. ### `spec.rules.filters` -Weight specifies the proportion of requests forwarded to the referenced backend. This is computed as weight/(sum of all weights in this BackendRefs list). For non-zero values, there may be some epsilon from the exact proportion defined here depending on the precision an implementation supports. Weight is not a percentage and the sum of weights does not need to equal 100. If only one backend is specified and it has a weight greater than 0, 100% of the traffic is forwarded to that backend. If weight is set to 0, no traffic should be forwarded for this entry. If unspecified, weight defaults to 1. +Specifies filtering behavior for all requests that match the service defined in [`spec.parentRefs`](#spec-parent-refs). #### Values @@ -489,7 +513,7 @@ Weight specifies the proportion of requests forwarded to the referenced backend. ### `spec.rules.filters.requestHeaderModifier` -Specifies a set of HTTP-specific header modification rules applied to requests routed with the GRPCRoute resource. +Specifies a set of header modification rules applied to requests that match the service defined in [`spec.parentRefs`](#spec-parent-refs). #### Values @@ -509,7 +533,7 @@ The following table describes how to configure values for request headers: ### `spec.rules.filters.responseHeaderModifier` -Specifies a set of HTTP-specific header modification rules applied to responses routed with the GRPCRoute resource. +Specifies a set of header modification rules applied to responses from services matching [`spec.parentRefs`](#spec-parent-refs). #### Values @@ -529,7 +553,7 @@ The following table describes how to configure values for request headers: ### `spec.rules.filters.urlRewrite` -URLRewrite defines a schema for a filter that modifies a request during forwarding. +Specifies a path to modify the URL with when a request matching [`spec.parentRefs`](#spec-parent-refs) is forwarded. #### Values @@ -538,11 +562,11 @@ URLRewrite defines a schema for a filter that modifies a request during forwardi | Parameter | Description | Data type | Default | | :------------ | :------------------------------------------------------------------------------------------------- | --------- | ------- | - | `pathPrefix` | Specifies the number of random healthy hosts from which to select the one with the least requests. | String | None | + | `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 matching rules +Specifies rules for matching services described in [`spec.parentRefs`](#spec-parent-refs) according to the request header or method. #### Values @@ -551,7 +575,9 @@ Specifies matching rules ### `spec.rules.matches.headers` -Headers specifies gRPC request header matchers. Multiple match values are ANDed together, meaning, a request MUST match all the specified headers to select the route. +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 @@ -560,7 +586,7 @@ Headers specifies gRPC request header matchers. Multiple match values are ANDed ### `spec.rules.matches.headers.name` -Name of the header to match on. +Specifies the name of a gRPC request header to match on. #### Values @@ -569,7 +595,7 @@ Name of the header to match on. ### `spec.rules.matches.headers.type` -HeaderMatchType specifies the semantics of how HTTP header values should be compared. Valid HeaderMatchType values, along with their conformance levels, are: \n Note that values may be added to this enum, implementations must ensure that unknown values will not cause a crash. Unknown values here must result in the implementation setting the Accepted Condition for the Route to status: False, with a Reason of UnsupportedValue. +Specifies a type of match to perform on the gRPC request header. Supported match types include: unspecified, exact, regex, present, prefix, and suffix. #### Values @@ -585,7 +611,7 @@ HeaderMatchType specifies the semantics of how HTTP header values should be comp ### `spec.rules.matches.headers.value` -Specifies the value of the header to match. +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 @@ -594,7 +620,7 @@ Specifies the value of the header to match. ### `spec.rules.matches.method` -Specifies a gRPC request service/method matcher. If this field is not specified, all services and methods will match. +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 @@ -603,7 +629,7 @@ Specifies a gRPC request service/method matcher. If this field is not specified, ### `spec.rules.matches.method.method` -Value of the method to match against. If left empty or omitted, will match all services. At least one of Service and Method MUST be a non-empty string. +Specifies the value of the method to match. When empty or omitted, all methods match. #### Values @@ -612,7 +638,7 @@ Value of the method to match against. If left empty or omitted, will match all s ### `spec.rules.matches.method.service` -Value of the service to match against. If left empty or omitted, will match any service. At least one of Service and Method MUST be a non-empty string. +Specifies the value of the service to match. When empty or omitted, all services match. #### Values @@ -621,7 +647,7 @@ Value of the service to match against. If left empty or omitted, will match any ### `spec.rules.matches.method.type` -Type specifies how to match against the service and/or method. +Specifies a type of match to perform on the gRPC request method. Supported match types include: unspecified, exact, and regex. #### Values @@ -634,7 +660,7 @@ Type specifies how to match against the service and/or method. ### `spec.rules.retries` -Specifies retry logic for the resource. +Specifies retry logic for routing gRPC traffic. #### Values @@ -643,7 +669,7 @@ Specifies retry logic for the resource. ### `spec.rules.retries.number` -Specifies retry logic for the resource. +Specifies the number of retries to attempt when a request fails. #### Values @@ -656,16 +682,16 @@ Specifies retry logic for the resource. ### `spec.rules.retries.onConditions` -RetryOn allows setting envoy specific conditions when a request should be automatically retried. +Specifies Envoy conditions that cause an automatic retry attempt. #### Values - Default: None -- Data type: Array of strings +- Data type: Map of strings ### `spec.rules.retries.onConnnectFailure` -Allows for connection failure errors to trigger a retry. +Enables an automatic retry attempt when a connection failure error occurs. #### Values @@ -674,16 +700,16 @@ Allows for connection failure errors to trigger a retry. ### `spec.rules.retries.onStatusCodes` -Flat list of http response status codes that are eligible for retry. This again should be feasible in any reasonable proxy. +Specifies the response status codes that are eligible for retry attempts. #### Values - Default: None -- Data type: Array of integers +- Data type: Map of integers ### `spec.rules.timeouts` -Specifies timeout logic for the resource. +Specifies timeout logic when routing gRPC traffic #### Values @@ -692,7 +718,7 @@ Specifies timeout logic for the resource. ### `spec.rules.timeouts.idle` -Specifies the total amount of time permitted for the request stream to be idle. +Specifies the total amount of time permitted for the request stream to be idle before a timeout occurs. #### Values @@ -706,7 +732,7 @@ Specifies the total amount of time permitted for the request stream to be idle. ### `spec.rules.timeouts.request` -Specifies the total amount of time permitted for the entire downstream request and retries to be processed before triggering a timeout. +Specifies the total amount of time spent processing the entire downstream request, including retries, before triggering a timeout. #### Values @@ -722,7 +748,7 @@ Specifies the total amount of time permitted for the entire downstream request a If you have more than one example to show, create an Examples section (general block) and introduce the examples per the style guide. -### Split service traffic between two ports +### Split gRPC traffic between two ports The following configuration 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. @@ -741,7 +767,7 @@ spec: kind: Service name: api # Note that right now, we must target the workload port, - # not the service port. This is likely to change in 1.18+. + # not the service port. port: "api-workload" rules: - backendRefs: @@ -753,7 +779,7 @@ spec: kind: Service name: api # Note that right now, we must target the workload port, - # not the service port. This is likely to change in 1.18+. + # not the service port. port: "api-workload" weight: 50 - backendRef: @@ -764,7 +790,84 @@ spec: kind: Service name: api # Note that right now, we must target the workload port, - # not the service port. This is likely to change in 1.18+. + # not the service port. port: "admin-workload" weight: 50 ``` + +### Route traffic by matching header + +The following configuration 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: + +- Traffic with a header that contains a `x-debug` value of exactly `1` has their response and request headers modified and is routed to the service with the `api` workload identity. +- Traffic with a header that contains a `x-debug` value of exactly `2` has their response and request headers modified and is routed to the service with the `api-admin` workload identity. + +```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 + # Note that right now, we must target the workload port, + # not the service port. + port: "api-workload" + 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 + # Note that right now, we must target the workload port, + # not the service port. + port: "api-workload" + - 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 + # Note that right now, we must target the workload port, + # not the service port. + port: "admin-workload" +``` \ No newline at end of file From 8009aa0791165cab0b7502c21a476c19c8f95133 Mon Sep 17 00:00:00 2001 From: boruszak Date: Thu, 26 Oct 2023 15:46:01 -0700 Subject: [PATCH 13/57] HTTP copy --- .../k8s/multiport/reference/grpcroute.mdx | 6 +- .../k8s/multiport/reference/httproute.mdx | 956 ++++++++++++++---- 2 files changed, 786 insertions(+), 176 deletions(-) diff --git a/website/content/docs/k8s/multiport/reference/grpcroute.mdx b/website/content/docs/k8s/multiport/reference/grpcroute.mdx index 7176f4f42def..9b991129afe3 100644 --- a/website/content/docs/k8s/multiport/reference/grpcroute.mdx +++ b/website/content/docs/k8s/multiport/reference/grpcroute.mdx @@ -746,11 +746,11 @@ Specifies the total amount of time spent processing the entire downstream reques ## Examples -If you have more than one example to show, create an Examples section (general block) and introduce the examples per the style guide. +The following examples demonstrate common GRPCRoute CRD configuration patterns for specific use cases. ### Split gRPC traffic between two ports -The following configuration 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. +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 @@ -797,7 +797,7 @@ spec: ### Route traffic by matching header -The following configuration 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: +The following examples 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: - Traffic with a header that contains a `x-debug` value of exactly `1` has their response and request headers modified and is routed to the service with the `api` workload identity. - Traffic with a header that contains a `x-debug` value of exactly `2` has their response and request headers modified and is routed to the service with the `api-admin` workload identity. diff --git a/website/content/docs/k8s/multiport/reference/httproute.mdx b/website/content/docs/k8s/multiport/reference/httproute.mdx index 64390d994ae3..6103046b5e28 100644 --- a/website/content/docs/k8s/multiport/reference/httproute.mdx +++ b/website/content/docs/k8s/multiport/reference/httproute.mdx @@ -1,12 +1,12 @@ --- layout: docs page_title: HTTPRoute resource configuration reference -description: The HTTPRoute resource CRD configures L7 GRPC traffic behavior within the service mesh. GRPCRoute is a GAMMA resource that requires the v2 catalog API. Learn how to configure the HTTPRoute CRD with specifications and example configurations. +description: The HTTPRoute resource CRD configures L7 HTTP traffic behavior within the service mesh. GRPCRoute 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 GRPCRoute resource, which defines L7 GRPC traffic within the service mesh. +This page provides reference information for the GRPCRoute resource, which defines L7 HTTP traffic within the service mesh. This custom resource definition (CRD) describes a GAMMA resource that requires the [v2 catalog API](/consul/docs/architecture/catalog/v2). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog/v1). For more information about GAMMA resources, refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/gamma/). @@ -14,211 +14,744 @@ This custom resource definition (CRD) describes a GAMMA resource that requires t The following list outlines field hierarchy, language-specific data types, and requirements in an HTTPRoute CRD. Click on a property name to view additional details, including default values. -- [`apiVersion`](#apiversion): string | required -- [`kind`](#kind): string | required +The following list outlines field hierarchy, language-specific data types, and requirements in a GRPCRoute 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): object | required - - [`name`](#metadata-name): string | required - - [`namespace`](#metadata-namespace): string | optional + - [`name`](#metadata-name): string | required + - [`namespace`](#metadata-namespace): string | optional - [`spec`](#spec): object | required - - [`parentRefs`](#spec-parentrefs): - - [`ref`](#spec-parentrefs-ref): - - [`type`](#spec-parentrefs-ref-type): -- [`group`] -- [`groupVersion`] -- [`kind`] -- [`name`] -- [`section`] -- [`tenancy`] - - [`namespace`] - - [`partition`] - - [`peerName`] - - [‘port’] - - [`rules`](#spec-rules): - - [`backendRefs`] - - [`backendRef`] - - [`ref`] - - [`type`] - - [`group`] - - [`groupVersion`] - - [`kind`] - - [`name`] - - [`section`] - - [`tenancy`] - - [`namespace`] - - [`partition`] - - [`peerName`] - - [`datacenter`] -- [`port`] -- [`weight`] + - [`parentRefs`](#spec-parentrefs): map | required + - [`port`](#spec-parentrefs-port): string + - [`ref`](#spec-parentrefs-ref): string | required + - [`name`](#spec-parentrefs-ref-name): string + - [`section`](#spec-parentrefs-ref-section): string + - [`tenancy`](#spec-parentrefs-ref-tenancy): string + - [`namespace`](#spec-parentrefs-ref-tenancy): string + - [`partition`](#spec-parentrefs-ref-tenancy): string + - [`peerName`](#spec-parentrefs-ref-tenancy): 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 + - [`section`](#spec-rules-backendrefs-backendref-ref-section): string + - [`tenancy`](#spec-rules-backendrefs-backendref-ref-tenancy): map + - [`namespace`](#spec-rules-backendrefs-backendref-ref-tenancy): string + - [`partition`](#spec-rules-backendrefs-backendref-ref-tenancy): string + - [`peerName`](#spec-rules-backendrefs-backendref-ref-tenancy): 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`]: map(#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`]: map(#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): integer + - [`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): integer + - [`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): map + - [`nanos`](#spec-rules-timeouts-idle): integer + - [`seconds`](#spec-rules-timeouts-idle): integer + - [`request`](#spec-rules-timeouts-request): map + - [`nanos`](#spec-rules-timeouts-request): integer + - [`seconds`](#spec-rules-timeouts-request): integer ## Complete configuration When every field is defined, an HTTPRoute CRD has the following form: ```yaml -apiVersion: mesh.consul.hashicorp.com/v2beta1 -kind: HTTPRoute +apiVersion: mesh.consul.hashicorp.com/v2beta1 # required +kind: GRPCRoute # required metadata: - name: + name: namespace: -hostnames: spec: parentRefs: - port: - ref: - name: - section: + port: "" + - ref: + name: + section: tenancy: - namespace: - partition: - peerName: - type: - group: - groupVersion: - kind: - rules: - backendRefs: - backendRef: - datacenter: - port: - ref: - name: - tenancy: - namespace: - partition: - peerName: - type: - group: - groupVersion: - kind: - filters: - requestHeaderModifier: - add: - name: - value: - remove: - name: - value: - set: - name: - value: - responseHeaderModifier: - add: - name: - value: - remove: - name: - value: - set: - name: - value: - urlRewrite: - pathPrefix: - weight: + namespace: + partition: + peerName: + type: + group: + groupVersion: + kind: + rules: + - backendRefs: + - backendRef: + datacenter: + port: "" + ref: + name: + section: + tenancy: + namespace: + partition: + peerName: + type: + group: + groupVersion: + kind: filters: - requestHeaderModifier: - add: - name: - value: - remove: - name: - value: - set: - name: - value: - responseHeaderModifier: + - requestHeaderModifier: add: - name: - value: - remove: - name: - value: + name: "" + value: "" + - responseHeaderModifier: set: - name: - value: + name: "" + value: "" urlRewrite: - pathPrefix: - matches: - headers: - invert: - name: - type: - method: - path: - type: - queryParams: - name: - type: - retries: - number: - onConditions: - onConnectFailure: - onStatusCodes: - timeouts: - idle: - nanos: - seconds: - request: - nanos: - seconds: - status: - conditions: - lastTransitionTime: - message: - reason: - status: - type: - lastSyncedTime: -``` + pathPrefix: + weight: 1 + filters: + requestHeaderModifier: + remove: + name: "" + value: "" + responseHeaderModifier: + add: + name: "" + value: "" + urlRewrite: + pathPrefix: + matches: + headers: + name: + type: + value: + method: + method: + service: + type: + retries: + number: + value: 1 + onConditions: ["cancelled", "unavailable"] + onConnectFailure: false + onStatusCodes: [400, 404] + timeouts: + idle: + nanos: 15 + seconds: 1 + request: + nanos: 10 + seconds: 1 +``` ## Specification +This section provides details about the fields you can configure in the GRPCRoute custom resource definition (CRD). + +### `apiVersion` -The specification block contains the details about each configuration. It -is a flattened representation of the configuration model block that allows -for extended descriptions, examples, and other information to help readers -understand the behavior of the configurations. +Specifies the version of the Consul API for integrating with Kubernetes. The value must be `mesh.consul.hashicorp.com/v2beta1`. -### `Elem_a` +#### Values + +- Default: None +- This field is required. +- String value that must be set to `mesh.consul.hashicorp.com/v2beta1`. + +### `kind` -Use this space to thoroughly, but succinctly, document the configuration -item. This format is intended to allow you to create complete documentation, -however, _stay within the scope of the reference_. If the description -deviates from the reference material, create a new Concept topic or add the -information to an existing Concept. +Specifies the type of CRD to implement. Must be set to `GRPCRoute`. #### Values -- Default: default value or none -- This field is required. -## Examples +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 must align with GAMMAs 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 resources to attach the route to. Usually these are services. You cannot reference the same `parentsRefs` multiple times. Instead, specify each [`spec.parentRefs.ref`](#spec-parentrefs-ref) in the same block. + +#### Values + +- Default: None +- This field is required. +- Data type: Map + +### `spec.parentRefs.port` + +Specifies the name of the Consul service's port that the configuration applies to. + +#### Values + +- Default: None +- Data type: String + +### `spec.parentRefs.ref` + +Specifies the resource that the configuration applies 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.section` + +Specifies the section of the resource that the configuration applies to. + +#### Values + +- Default: None +- Data type: String + +### `spec.parentRefs.ref.tenancy` + +Specifies the user-defined namespace, partition, or cluster peer of the resource that the configuration applies to. + +#### Values + +- Default: None +- Data type: Map containing the following parameters: + + | Parameter | Description | Data type | Default | + | :------------ | :------------------------------------------------------------------- | :-------- | :------- | + | `namespace` | Identifies the namespace of the resource the configuration applies to. | String | None | + | `partition` | Identifies the admin partition of the resource the configuration applies to. | String | None | + | `peerName` | Identifies the name of a cluster peer the resource is imported from that the configuration applies to. | String | None | + +### `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 Kubenretes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String (in code, should be int based on desc.) | 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 is invalid, the relative weights are maintained and traffic is not redirected automatically. 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. + +#### 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.section` + +Specifies the section the resource that the configuration routes traffic to. + +#### Values + +- Default: None +- Data type: String + +### `spec.rules.backendRefs.backendRef.ref.tenancy` + +Specifies the user-defined namespace, partition, or cluster peer of the resource that the configuration routes to. + +#### Values + +- Default: None +- Data type: Map containing the following parameters: + + | Parameter | Description | Data type | Default | + | :------------ | :------------------------------------------------------------------- | :-------- | :------- | + | `namespace` | Identifies the namespace of the resource the configuration routes traffic to. | String | None | + | `partition` | Identifies the admin partition of the resource the configuration routes traffic to. | String | None | + | `peerName` | Identifies the name of a cluster peer the resource is imported from that the configuration routes traffic to. | String | None | + +### `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 Kubenretes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String (in code, should be int based on desc.) | 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 GRPCRoute 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 | + +### `spec.rules.backendRefs.filters.responseHeaderModifier` + +Specifies a set of header modification rules applied to responses routed with the GRPCRoute 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 | + +### `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, 100% of traffic is forwarded. + +When this parameter is not specified, it assumes the default value `1`. + +#### Values -If you have more than one example to show, create an Examples section -(general block) and introduce the examples per the style guide. +- Default: `1` +- Data type: Integer -### Specific use case +### `spec.rules.filters` -Introduce examples clearly and help readers understand the connections -between the example snippet and the configuration element you are trying to -explain. Use phrases such as "In the following example, the `elem` performs -some action on a service named `service-name`". +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 | + +### `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 | + +### `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 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 criteria for matching a service and a HTTP 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 HTTP 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 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.onConnnectFailure` + +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. + +#### Values + +- Default: None +- Data type: Map that can contain the following parameters: + + | Parameter | Description | Data type | Default | + | :-------- | :--------------------------------------------------------------- | --------- | ------- | + | `nanos` | Specifies the number of nanoseconds before triggering a timeout. | Integer | None | + | `seconds` | Specifies the number of seconds before triggering a timeout. | Integer | None | + +### `spec.rules.timeouts.request` + +Specifies the total amount of time spent processing the entire downstream request, including retries, before triggering a timeout. + +#### Values + +- Default: None +- Data type: Map that can contain the following parameters: + + | Parameter | Description | Data type | Default | + | :-------- | :--------------------------------------------------------------- | --------- | ------- | + | `nanos` | Specifies the number of nanoseconds before triggering a timeout. | Integer | None | + | `seconds` | Specifies the number of seconds before triggering a timeout. | Integer | None | + +## Examples + +The following examples demonstrate common GRPCRoute 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-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 @@ -235,7 +768,7 @@ spec: kind: Service name: api # Note that right now, we must target the workload port, - # not the service port. This is likely to change in 1.18+. + # not the service port. port: "api-workload" rules: - backendRefs: @@ -247,7 +780,7 @@ spec: kind: Service name: api # Note that right now, we must target the workload port, - # not the service port. This is likely to change in 1.18+. + # not the service port. port: "api-workload" weight: 50 - backendRef: @@ -258,7 +791,84 @@ spec: kind: Service name: api # Note that right now, we must target the workload port, - # not the service port. This is likely to change in 1.18+. + # not the service port. port: "admin-workload" 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: + +- Traffic with a header that contains a `x-debug` value of exactly `1` has their response and request headers modified and is routed to the service with the `api` workload identity. +- Traffic with a header that contains a `x-debug` value of exactly `2` has their response and request headers modified and is routed to the service with the `api-admin` workload identity. + +```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 + # Note that right now, we must target the workload port, + # not the service port. + port: "api-workload" + 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 + # Note that right now, we must target the workload port, + # not the service port. + port: "api-workload" + - 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 + # Note that right now, we must target the workload port, + # not the service port. + port: "admin-workload" +``` \ No newline at end of file From 28dd84c1e80b6a4afa49354ec60727916cbce937 Mon Sep 17 00:00:00 2001 From: boruszak Date: Thu, 26 Oct 2023 16:05:04 -0700 Subject: [PATCH 14/57] Resource configuration alignment --- .../k8s/multiport/reference/grpcroute.mdx | 20 +- .../k8s/multiport/reference/httproute.mdx | 45 +- .../reference/proxyconfiguration.mdx | 8 +- .../docs/k8s/multiport/reference/tcproute.mdx | 718 +++++++++++++++--- .../reference/trafficpermissions.mdx | 10 +- 5 files changed, 673 insertions(+), 128 deletions(-) diff --git a/website/content/docs/k8s/multiport/reference/grpcroute.mdx b/website/content/docs/k8s/multiport/reference/grpcroute.mdx index 9b991129afe3..bb73e2357cd0 100644 --- a/website/content/docs/k8s/multiport/reference/grpcroute.mdx +++ b/website/content/docs/k8s/multiport/reference/grpcroute.mdx @@ -14,6 +14,10 @@ This custom resource definition (CRD) describes a GAMMA resource that requires t The following list outlines field hierarchy, language-specific data types, and requirements in a GRPCRoute 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): object | required @@ -50,11 +54,11 @@ The following list outlines field hierarchy, language-specific data types, and r - [`groupVersion`](#spec-rules-backendrefs-backendref-ref-type): string - [`kind`](#spec-rules-backendrefs-backendref-ref-type): string - [`filters`](#spec-rules-backendrefs-filters): map - - [`requestHeaderModifier`]: map(#spec-rules-backendrefs-filters-requestheadermodifier): 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`]: map(#spec-rules-backendrefs-filters-responseheadermodifier): 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 @@ -95,10 +99,17 @@ The following list outlines field hierarchy, language-specific data types, and r - [`nanos`](#spec-rules-timeouts-request): integer - [`seconds`](#spec-rules-timeouts-request): integer + + + ## Complete configuration When every field is defined, a GRPCRoute resource CRD has the following form: + + + + ```yaml apiVersion: mesh.consul.hashicorp.com/v2beta1 # required kind: GRPCRoute # required @@ -182,6 +193,9 @@ spec: seconds: 1 ``` + + + ## Specification This section provides details about the fields you can configure in the GRPCRoute custom resource definition (CRD). @@ -206,7 +220,7 @@ Specifies the type of CRD to implement. Must be set to `GRPCRoute`. - This field is required. - Data type: String value that must be set to `GRPCRoute`. -## `metadata` +### `metadata` Map that contains an arbitrary name for the CRD and the namespace it applies to. diff --git a/website/content/docs/k8s/multiport/reference/httproute.mdx b/website/content/docs/k8s/multiport/reference/httproute.mdx index 6103046b5e28..b6ed04bd51d2 100644 --- a/website/content/docs/k8s/multiport/reference/httproute.mdx +++ b/website/content/docs/k8s/multiport/reference/httproute.mdx @@ -1,12 +1,12 @@ --- layout: docs page_title: HTTPRoute resource configuration reference -description: The HTTPRoute resource CRD configures L7 HTTP traffic behavior within the service mesh. GRPCRoute is a GAMMA resource that requires the v2 catalog API. Learn how to configure the HTTPRoute CRD with specifications and example configurations. +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 GRPCRoute resource, which defines L7 HTTP traffic within the service mesh. +This page provides reference information for the HTTPRoute resource, which defines L7 HTTP traffic within the service mesh. This custom resource definition (CRD) describes a GAMMA resource that requires the [v2 catalog API](/consul/docs/architecture/catalog/v2). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog/v1). For more information about GAMMA resources, refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/gamma/). @@ -14,10 +14,12 @@ This custom resource definition (CRD) describes a GAMMA resource that requires t The following list outlines field hierarchy, language-specific data types, and requirements in an HTTPRoute CRD. Click on a property name to view additional details, including default values. -The following list outlines field hierarchy, language-specific data types, and requirements in a GRPCRoute 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` +- [`kind`](#kind): string | required | must be set to `HTTPRoute` - [`metadata`](#metadata): object | required - [`name`](#metadata-name): string | required - [`namespace`](#metadata-namespace): string | optional @@ -52,11 +54,11 @@ The following list outlines field hierarchy, language-specific data types, and r - [`groupVersion`](#spec-rules-backendrefs-backendref-ref-type): string - [`kind`](#spec-rules-backendrefs-backendref-ref-type): string - [`filters`](#spec-rules-backendrefs-filters): map - - [`requestHeaderModifier`]: map(#spec-rules-backendrefs-filters-requestheadermodifier): 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`]: map(#spec-rules-backendrefs-filters-responseheadermodifier): 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 @@ -97,13 +99,20 @@ The following list outlines field hierarchy, language-specific data types, and r - [`nanos`](#spec-rules-timeouts-request): integer - [`seconds`](#spec-rules-timeouts-request): integer + + + ## Complete configuration When every field is defined, an HTTPRoute CRD has the following form: + + + + ```yaml apiVersion: mesh.consul.hashicorp.com/v2beta1 # required -kind: GRPCRoute # required +kind: HTTPRoute # required metadata: name: namespace: @@ -184,8 +193,12 @@ spec: seconds: 1 ``` + + + ## Specification -This section provides details about the fields you can configure in the GRPCRoute custom resource definition (CRD). + +This section provides details about the fields you can configure in the HTTPRoute custom resource definition (CRD). ### `apiVersion` @@ -199,15 +212,15 @@ Specifies the version of the Consul API for integrating with Kubernetes. The val ### `kind` -Specifies the type of CRD to implement. Must be set to `GRPCRoute`. +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 `GRPCRoute`. +- Data type: String value that must be set to `HTTPRoute`. -## `metadata` +### `metadata` Map that contains an arbitrary name for the CRD and the namespace it applies to. @@ -237,9 +250,9 @@ Specifies the namespace that the service resolver applies to. Refer to [namespac ### `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. +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 must align with GAMMAs resource. Refer to [GRPCRoute in the Kubernetes documentation](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1alpha2.GRPCRoute). +When using this CRD, the `spec` field must align with GAMMAs resource. Refer to [HTTPRoute in the Kubernetes documentation](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRoute). #### Values @@ -439,7 +452,7 @@ Specifies filtering behavior for services configured in the same [`spec.rules.ba ### `spec.rules.backendRefs.filters.requestHeaderModifier` -Specifies a set of header modification rules applied to requests routed with the GRPCRoute resource. +Specifies a set of header modification rules applied to requests routed with the HTTPRoute resource. #### Values @@ -459,7 +472,7 @@ The following table describes how to configure values for request headers: ### `spec.rules.backendRefs.filters.responseHeaderModifier` -Specifies a set of header modification rules applied to responses routed with the GRPCRoute resource. +Specifies a set of header modification rules applied to responses routed with the HTTPRoute resource. #### Values @@ -747,7 +760,7 @@ Specifies the total amount of time spent processing the entire downstream reques ## Examples -The following examples demonstrate common GRPCRoute CRD configuration patterns for specific use cases. +The following examples demonstrate common HTTPRoute CRD configuration patterns for specific use cases. ### Split HTTP traffic between two ports diff --git a/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx b/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx index 3d1fd48db06b..2509cca1316b 100644 --- a/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx +++ b/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx @@ -13,7 +13,7 @@ information. ## Configuration model The following list outlines field hierarchy, language-specific data types, -and requirements in . Click on a property name +and requirements in this configuration entry. Click on a property name to view additional details, including default values. - [`elem_a`](#elema): data type | default @@ -39,9 +39,9 @@ element_bbb: element_bbba: element_bbbb: element_bbbc: -- element_bbbd: ``` + ## Specification The specification block contains the details about each configuration. It @@ -60,7 +60,7 @@ information to an existing Concept. #### Values - Default: default value or none -- This field is required. . Click on a property name -to view additional details, including default values. +The following list outlines field hierarchy, language-specific data types, and requirements in an TCPRoute 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 `TCPRoute` +- [`metadata`](#metadata): object | required + - [`name`](#metadata-name): string | required + - [`namespace`](#metadata-namespace): string | optional +- [`spec`](#spec): object | required + - [`parentRefs`](#spec-parentrefs): map | required + - [`port`](#spec-parentrefs-port): string + - [`ref`](#spec-parentrefs-ref): string | required + - [`name`](#spec-parentrefs-ref-name): string + - [`section`](#spec-parentrefs-ref-section): string + - [`tenancy`](#spec-parentrefs-ref-tenancy): string + - [`namespace`](#spec-parentrefs-ref-tenancy): string + - [`partition`](#spec-parentrefs-ref-tenancy): string + - [`peerName`](#spec-parentrefs-ref-tenancy): 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 + - [`section`](#spec-rules-backendrefs-backendref-ref-section): string + - [`tenancy`](#spec-rules-backendrefs-backendref-ref-tenancy): map + - [`namespace`](#spec-rules-backendrefs-backendref-ref-tenancy): string + - [`partition`](#spec-rules-backendrefs-backendref-ref-tenancy): string + - [`peerName`](#spec-rules-backendrefs-backendref-ref-tenancy): 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): integer + - [`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 + - [`retries`](#spec-rules-retries): map + - [`number`](#spec-rules-retries-number): map + - [`value`](#spec-rules-retries-number): integer + - [`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): map + - [`nanos`](#spec-rules-timeouts-idle): integer + - [`seconds`](#spec-rules-timeouts-idle): integer + - [`request`](#spec-rules-timeouts-request): map + - [`nanos`](#spec-rules-timeouts-request): integer + - [`seconds`](#spec-rules-timeouts-request): integer -- [`elem_a`](#elema): data type | default -- [`elem_b`](#elemb): data type | default -- [`spec`](#elemb): data type | default -- [`elem_ba`](#elembelemba): data type | default -- [`elem_baa`](#elembelembaelembaa): data type | default -- [`elem_baaa`](#elembelembaelembaa): data type | default -- [`elem_baab`](#elembelembaelembaa): data type | default -- [`elem_baac`](#elembelembaelembaa): data type | default -- [`element_bab`](#elembelembaelembab): data type | default + + ## Complete configuration -The complete configuration follows the configuration model. Use tabs for -each markup language you expect pracitioners to use. +When every field is defined, a TCPRoute CRD has the following form: + + + + ```yaml -apiVersion: mesh.consul.hashicorp.com/v2beta1 -kind: HTTPRoute +apiVersion: mesh.consul.hashicorp.com/v2beta1 # required +kind: TCPRoute # required metadata: -hostnames: + name: + namespace: spec: parentRefs: - port: - ref: - name: - section: + port: "" + - ref: + name: + section: tenancy: - namespace: - partition: - peerName: - type: - group: - groupVersion: - kind: - rules: - backendRefs: - backendRef: - datacenter: - port: - ref: - name: - tenancy: - namespace: - partition: - peerName: - type: - group: - groupVersion: - kind: - retries: - number: - onConditions: - onConnectFailure: - onStatusCodes: - timeouts: - idle: - nanos: - seconds: - request: - nanos: - seconds: - status: - conditions: - lastTransitionTime: - message: - reason: - status: - type: - lastSyncedTime: -``` + namespace: + partition: + peerName: + type: + group: + groupVersion: + kind: + rules: + - backendRefs: + - backendRef: + datacenter: + port: "" + ref: + name: + section: + tenancy: + namespace: + partition: + peerName: + type: + group: + groupVersion: + kind: + filters: + - requestHeaderModifier: + add: + name: "" + value: "" + - responseHeaderModifier: + set: + name: "" + value: "" + urlRewrite: + pathPrefix: + weight: 1 + filters: + requestHeaderModifier: + remove: + name: "" + value: "" + responseHeaderModifier: + add: + name: "" + value: "" + urlRewrite: + pathPrefix: + retries: + number: + value: 1 + onConditions: ["cancelled", "unavailable"] + onConnectFailure: false + onStatusCodes: [400, 404] + timeouts: + idle: + nanos: 15 + seconds: 1 + request: + nanos: 10 + seconds: 1 +``` + + + ## Specification -The specification block contains the details about each configuration. It -is a flattened representation of the configuration model block that allows -for extended descriptions, examples, and other information to help readers -understand the behavior of the configurations. +This section provides details about the fields you can configure in the TCPRoute custom resource definition (CRD). -### `Elem_a` +### `apiVersion` -Use this space to thoroughly, but succinctly, document the configuration -item. This format is intended to allow you to create complete documentation, -however, _stay within the scope of the reference_. If the description -deviates from the reference material, create a new Concept topic or add the -information to an existing Concept. +Specifies the version of the Consul API for integrating with Kubernetes. The value must be `mesh.consul.hashicorp.com/v2beta1`. #### Values -- Default: default value or none -- This field is required. + +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 must align with GAMMAs 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 resources to attach the route to. Usually these are services. You cannot reference the same `parentsRefs` multiple times. Instead, specify each [`spec.parentRefs.ref`](#spec-parentrefs-ref) in the same block. + +#### Values + +- Default: None +- This field is required. +- Data type: Map + +### `spec.parentRefs.port` + +Specifies the name of the Consul service's port that the configuration applies to. + +#### Values + +- Default: None +- Data type: String + +### `spec.parentRefs.ref` + +Specifies the resource that the configuration applies 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.section` + +Specifies the section of the resource that the configuration applies to. + +#### Values + +- Default: None +- Data type: String -If you have more than one example to show, create an Examples section -(general block) and introduce the examples per the style guide. +### `spec.parentRefs.ref.tenancy` -### Specific use case +Specifies the user-defined namespace, partition, or cluster peer of the resource that the configuration applies to. + +#### Values + +- Default: None +- Data type: Map containing the following parameters: + + | Parameter | Description | Data type | Default | + | :------------ | :------------------------------------------------------------------- | :-------- | :------- | + | `namespace` | Identifies the namespace of the resource the configuration applies to. | String | None | + | `partition` | Identifies the admin partition of the resource the configuration applies to. | String | None | + | `peerName` | Identifies the name of a cluster peer the resource is imported from that the configuration applies to. | String | None | + +### `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 Kubenretes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String (in code, should be int based on desc.) | 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, including filtering, retry, and timeout behavior. + +#### 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 is invalid, the relative weights are maintained and traffic is not redirected automatically. 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. + +#### 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.section` + +Specifies the section the resource that the configuration routes traffic to. + +#### Values + +- Default: None +- Data type: String + +### `spec.rules.backendRefs.backendRef.ref.tenancy` + +Specifies the user-defined namespace, partition, or cluster peer of the resource that the configuration routes to. + +#### Values -Introduce examples clearly and help readers understand the connections -between the example snippet and the configuration element you are trying to -explain. Use phrases such as "In the following example, the `elem` performs -some action on a service named `service-name`". +- Default: None +- Data type: Map containing the following parameters: + | Parameter | Description | Data type | Default | + | :------------ | :------------------------------------------------------------------- | :-------- | :------- | + | `namespace` | Identifies the namespace of the resource the configuration routes traffic to. | String | None | + | `partition` | Identifies the admin partition of the resource the configuration routes traffic to. | String | None | + | `peerName` | Identifies the name of a cluster peer the resource is imported from that the configuration routes traffic to. | String | None | + +### `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 Kubenretes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String (in code, should be int based on desc.) | 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 TCPRoute 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 | + +### `spec.rules.backendRefs.filters.responseHeaderModifier` + +Specifies a set of header modification rules applied to responses routed with the TCPRoute 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 | + +### `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, 100% of traffic is forwarded. + +When this parameter is not specified, it assumes the default value `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 | + +### `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 | + +### `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.retries` + +Specifies retry logic for routing TCP 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.onConnnectFailure` + +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 TCP 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. + +#### Values + +- Default: None +- Data type: Map that can contain the following parameters: + + | Parameter | Description | Data type | Default | + | :-------- | :--------------------------------------------------------------- | --------- | ------- | + | `nanos` | Specifies the number of nanoseconds before triggering a timeout. | Integer | None | + | `seconds` | Specifies the number of seconds before triggering a timeout. | Integer | None | + +### `spec.rules.timeouts.request` + +Specifies the total amount of time spent processing the entire downstream request, including retries, before triggering a timeout. + +#### Values + +- Default: None +- Data type: Map that can contain the following parameters: + + | Parameter | Description | Data type | Default | + | :-------- | :--------------------------------------------------------------- | --------- | ------- | + | `nanos` | Specifies the number of nanoseconds before triggering a timeout. | Integer | None | + | `seconds` | Specifies the number of seconds before triggering a timeout. | Integer | None | + +## 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 @@ -177,4 +695,4 @@ spec: # not the service port. This is likely to change in 1.18+. port: "admin-workload" weight: 50 -``` +``` \ No newline at end of file diff --git a/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx b/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx index 542b74eb81cf..c79c48c6d8f6 100644 --- a/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx +++ b/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx @@ -13,7 +13,7 @@ information. ## Configuration model The following list outlines field hierarchy, language-specific data types, -and requirements in . Click on a property name +and requirements in this configuration entry. Click on a property name to view additional details, including default values. - [`elem_a`](#elema): data type | default @@ -50,6 +50,7 @@ spec: methods: ["GET", "POST"] portNames: [""] ``` + ## Specification The specification block contains the details about each configuration. It @@ -68,10 +69,10 @@ information to an existing Concept. #### Values - Default: default value or none -- This field is required. Date: Thu, 26 Oct 2023 16:35:19 -0700 Subject: [PATCH 15/57] Catalogs --- .../content/docs/architecture/catalog/v1.mdx | 53 +++--------- .../content/docs/architecture/catalog/v2.mdx | 85 ++++--------------- 2 files changed, 32 insertions(+), 106 deletions(-) diff --git a/website/content/docs/architecture/catalog/v1.mdx b/website/content/docs/architecture/catalog/v1.mdx index db56d13bda4b..28d4bc70db37 100644 --- a/website/content/docs/architecture/catalog/v1.mdx +++ b/website/content/docs/architecture/catalog/v1.mdx @@ -1,7 +1,7 @@ --- layout: docs page_title: v1 Catalog API -description: +description: Learn about version 1 of the Consul catalog, including what Consul servers record when they register a service. --- # v1 Catalog API @@ -20,43 +20,18 @@ Consul uses v1 of the Catalog API by default. Consul v1.17.0 introduces a second When Consul registers a service instance using the v1 catalog API, it records the following information about each instance: -v1 Catalog field -Description -User-defined or Consul-computed? -ID -A unique identifier for a service instance. -Consul -Node - -Consul -Address -The address of the node where the service instance is running. -Consul -Tagged Addresses - - -User -NodeMeta - - -User -Datacenter -The name of the datacenter the service is registered in. -User -Service -The name of the service Consul registers the service instance under. -User -Agent Check -The health status of service last reported by the Consul agent. -Consul -Health Checks -The health checks defined for the service. Refer to [define health checks](/consul/docs/services/usage/checks) for more information. -User -Partition -The name of the admin partition the service is registered in. Refer to [admin partitions](/consul/docs/enterprise/admin-partitions) for more information. -User -Locality -Refer to [`locality`](/consul/docs/agent/config/config-files#locality) for more information. -User +| v1 Catalog field | Description | Source | +| :--------------- | :---------- | :----- | +| ID | A unique identifier for a service instance. | Computed by Consul | +| Node | The connection point where the service is available. | Computed by Consul | +| Address | The address of the node where the service instance is running. | Computed by Consul | +| Tagged Addresses | User-defined metadata about addresses. | Defined by user | +| NodeMeta | User-defined metadata about the node. | Defined by user | +| Datacenter | The name of the datacenter the service is registered in. | Defined by user | +| Service | The name of the service Consul registers the service instance under. | Defined by user | +| Agent Check | The health status of service last reported by the Consul agent. | Computed by Consul | +| Health Checks | The health checks defined for the service. Refer to [define health checks](/consul/docs/services/usage/checks) for more information. | Defined by user | +| Partition | The name of the admin partition the service is registered in. Refer to [admin partitions](/consul/docs/enterprise/admin-partitions) for more information. | Defined by user | +| Locality | Region and availability zone of the service. Refer to [`locality`](/consul/docs/agent/config/config-files#locality) for more information. | Defined by user | Depending on the configuration entries or custom resource definitions you apply to your Consul installation, additional information such as [proxy default behavior](/consul/docs/connect/config-entries/proxy-defaults) is automatically recorded to the catalog for services. You can return this information using the [`/catalog` HTTP API endpoint](/consul/api-docs/catalog). diff --git a/website/content/docs/architecture/catalog/v2.mdx b/website/content/docs/architecture/catalog/v2.mdx index 4997154d546b..c8d8df6e91e5 100644 --- a/website/content/docs/architecture/catalog/v2.mdx +++ b/website/content/docs/architecture/catalog/v2.mdx @@ -1,13 +1,13 @@ --- layout: docs page_title: v2 Catalog API -description: +description: Learn about version 2 of the Consul catalog, which uses GAMMA specified resources. Learn how the v2 catalog corresponds to the v1 catalog and Kubernetes resources.. --- # v2 Catalog API -The v2 catalog API is in a beta release for testing and development purposes. Do not use the v2 catalog or multi-port services in secure production environments. +The v2 catalog API is in a beta release for testing and development purposes. Do not use the v2 catalog or multi-port services in secure production environments. This topic provides conceptual information about version 2 of the Consul Catalog API. The catalog tracks registered services and their locations for both service discovery and service mesh use cases. @@ -36,67 +36,18 @@ Consul v1.17 introduces a new version of the catalog API designed to bridge diff The following table describes resources in the v2 catalog and compares them to the v1 catalog and Kubernetes resources. It also states whether these resources are defined by the user or computed by Consul when it registers a service. - -V2 Catalog resource -Description -Catalog v1 resource analogue -Kubernetes resource analogue -User-defined or Consul-computed -Service -The name of the service Consul registers a workload under -Service -X -User -Node -The address of the node where the workload runs. -Node -Node -Consul -Workload -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 Workloads -User -Workload identities -Provides a distinct identity for a Kubernetes Workload to assume in a Kubernetes cluster. -Service instance -Kubernetes Service Accounts -User -Service endpoints -Maps services to workload addresses and endpoints. - - - - -Consul -Health status -A resource for reporting the health status of a workload -Agent check -X -Consul -Health check -A resource for defining the health checks for a workload. -Health check - - -User -Proxy configuration -Represents a configuration for a sidecar or gateway proxy. -`Proxy` field in service definition - - -User -Destinations -Represents explicit service upstreams -Upstream service annotations -X -User -Traffic permissions -Enables L4 traffic authorization according to workload identity instead of service identity -Service intentions -X -User - +| v2 Catalog resource | Description | Catalog v1 resource analogue | Kubernetes resource analogue | Source | +| :------------------ | :---------- | :--------------------------- | :--------------------------- | :----- | +| Service | The name of the service Consul registers a workload under | Service | None | Defined by user in Kubernetes | +| Node | The address of the node where the workload runs. | Node | Node | Computed by Consul | +| Workload | 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 Workloads | Defined by user in Kubernetes | +| Workload identities | Provides a distinct identity for a Kubernetes Workload to assume in a Kubernetes cluster. | Service instance | Kubernetes Service Accounts | Defin by user in Kubernetes | +| Service endpoints | Maps services to workload addresses and endpoints. | None | Service backend | Computed by Consul | +| Health status | A resource for reporting the health status of a workload | Agent check | None | Computed by Consul | +| Health check | A resource for defining the health checks for a workload. | Health check | Liveness, Readiness, and Startup Probes | Defined by user in Kubernetes | +| Proxy configuration | Represents a configuration for a sidecar or gateway proxy. | `Proxy` field in service definition | None | Defined by user in Consul | +| Destinations | Represents explicit service upstreams | None | Upstream Service annotation | Defined by user in Kubernetes | +| Traffic permissions | Enables L4 traffic authorization according to workload identity instead of service identity. | Service intentions | None | Defined by user in Consul | Refer to [`consul resource`](/consul/docs/k8s/multiport/reference/resource-command) for more information about using the Consul CLI to interact with the v2 catalog. @@ -110,14 +61,14 @@ The most significant change to Consul’s architecture and operations when using For more information about this resource, including example configurations, refer to [TrafficPermissions configuration reference](/consul/docs/k8s/multiport/reference/trafficpermissions). -### HTTP route resource for L7 traffic management +### HTTPRoute and GRPCRoute resources for L7 traffic management -You can configure L7 traffic management behavior, such as service splitting, in an `HTTPRoute` 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). +You can configure L7 traffic management behavior, such as service splitting, in an `HTTPRoute` or a `GRPCRoute` 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 this resource, including example configurations, refer to [HTTPRoute configuration reference](/consul/docs/k8s/multiport/reference/httproute). +For more information about these resource, including specifications and example configurations, refer to [HTTPRoute resource configuration reference](/consul/docs/k8s/multiport/reference/httproute) and [GRPCRoute resource configuration reference](/consul/docs/k8s/multiport/reference/grpcroute). ### 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). -The v2 catalog introduces the `ProxyConfiguration` resource, enabling the automatic configuration of sidecar proxy behavior according to Consul workload identity. Refer to [ProxyConfiguration configuration reference](/consul/docs/k8s/multiport/reference/proxyconfiguration) for more information. +The v2 catalog introduces the `ProxyConfiguration` resource, enabling the automatic configuration of sidecar proxy behavior according to Consul workload identity. Refer to [ProxyConfiguration resource configuration reference](/consul/docs/k8s/multiport/reference/proxyconfiguration) for more information. From 4303eafa0fa5c6bf77674f94ea14cf80b3ce69ee Mon Sep 17 00:00:00 2001 From: boruszak Date: Thu, 26 Oct 2023 16:46:05 -0700 Subject: [PATCH 16/57] Deployment error fix --- .../docs/k8s/multiport/reference/proxyconfiguration.mdx | 7 +++---- .../docs/k8s/multiport/reference/trafficpermissions.mdx | 5 ++--- 2 files changed, 5 insertions(+), 7 deletions(-) diff --git a/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx b/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx index 2509cca1316b..14d2bb8b8f82 100644 --- a/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx +++ b/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx @@ -1,11 +1,10 @@ --- layout: docs -page_title: Reference topic for structured information -description: Front-load meta descriptions with keywords and keyword -phrases to help readers find the information they are searching for. +page_title: ProxyConfiguration resource configuration reference +description: Front-load meta descriptions with keywords and keyword phrases to help readers find the information they are searching for. --- -# ProxyConfiguration configuration reference +# ProxyConfiguration resource configuration reference This sample page template shows how to format high structured reference information. diff --git a/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx b/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx index c79c48c6d8f6..80bea577e013 100644 --- a/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx +++ b/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx @@ -1,8 +1,7 @@ --- layout: docs -page_title: Reference topic for structured information -description: Front-load meta descriptions with keywords and keyword -phrases to help readers find the information they are searching for. +page_title: TrafficPermissions resource configuration reference +description: Front-load meta descriptions with keywords and keyword phrases to help readers find the information they are searching for. --- # TrafficPermissions configuration reference From cf1201cd23ff70bfe096674276694e7825ba811f Mon Sep 17 00:00:00 2001 From: boruszak Date: Fri, 27 Oct 2023 10:12:57 -0700 Subject: [PATCH 17/57] HTTPRoute specs --- .../k8s/multiport/reference/grpcroute.mdx | 2 +- .../k8s/multiport/reference/httproute.mdx | 102 +++++++++++++----- 2 files changed, 79 insertions(+), 25 deletions(-) diff --git a/website/content/docs/k8s/multiport/reference/grpcroute.mdx b/website/content/docs/k8s/multiport/reference/grpcroute.mdx index bb73e2357cd0..c52e1a4027bc 100644 --- a/website/content/docs/k8s/multiport/reference/grpcroute.mdx +++ b/website/content/docs/k8s/multiport/reference/grpcroute.mdx @@ -64,7 +64,7 @@ The following list outlines field hierarchy, language-specific data types, and r - [`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): integer + - [`weight`](#spec-rules-backendrefs-weight): integer | `1` - [`filters`](#spec-rules-filters): map - [`requestHeaderModifier`](#spec-rules-filters-requestheadermodifier): map - [`add`](#spec-rules-filters-requestheadermodifier): map diff --git a/website/content/docs/k8s/multiport/reference/httproute.mdx b/website/content/docs/k8s/multiport/reference/httproute.mdx index b6ed04bd51d2..3673fce2381b 100644 --- a/website/content/docs/k8s/multiport/reference/httproute.mdx +++ b/website/content/docs/k8s/multiport/reference/httproute.mdx @@ -6,7 +6,7 @@ description: The HTTPRoute resource CRD configures L7 HTTP traffic behavior with # HTTPRoute resource configuration reference -This page provides reference information for the HTTPRoute resource, which defines L7 HTTP traffic within the service mesh. +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 GAMMA resource that requires the [v2 catalog API](/consul/docs/architecture/catalog/v2). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog/v1). For more information about GAMMA resources, refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/gamma/). @@ -64,7 +64,7 @@ The following list outlines field hierarchy, language-specific data types, and r - [`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): integer + - [`weight`](#spec-rules-backendrefs-weight): integer | `1` - [`filters`](#spec-rules-filters): map - [`requestHeaderModifier`](#spec-rules-filters-requestheadermodifier): map - [`add`](#spec-rules-filters-requestheadermodifier): map @@ -81,10 +81,14 @@ The following list outlines field hierarchy, language-specific data types, and r - [`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 + - [`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): integer @@ -114,7 +118,7 @@ When every field is defined, an HTTPRoute CRD has the following form: apiVersion: mesh.consul.hashicorp.com/v2beta1 # required kind: HTTPRoute # required metadata: - name: + name: namespace: spec: parentRefs: @@ -172,12 +176,16 @@ spec: matches: headers: name: - type: + type: + value: + method: + path: + type: + value: / + queryParams: + name: + type: value: - method: - method: - service: - type: retries: number: value: 1 @@ -634,43 +642,89 @@ Specifies the value of the HTTP request header to match. When this field is spec ### `spec.rules.matches.method` -Specifies criteria for matching a service and a HTTP 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. +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.method.method` +### `spec.rules.matches.path.type` -Specifies the value of the method to match. When empty or omitted, all methods match. +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 +- 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. -### `spec.rules.matches.method.service` +#### Values + +- Default: None +- Data type: Map + +### `spec.rules.matches.queryParams.name` -Specifies the value of the service to match. When empty or omitted, all services match. +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.method.type` +### `spec.rules.matches.queryParams.type` -Specifies a type of match to perform on the HTTP request method. Supported match types include: unspecified, exact, and regex. +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: +- 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` + - `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` From 42eea7cb431de2d47c3cfba459f52cfaf76e0aa9 Mon Sep 17 00:00:00 2001 From: boruszak Date: Fri, 27 Oct 2023 10:34:19 -0700 Subject: [PATCH 18/57] TCP Route specifications --- .../docs/k8s/multiport/reference/tcproute.mdx | 292 +----------------- 1 file changed, 6 insertions(+), 286 deletions(-) diff --git a/website/content/docs/k8s/multiport/reference/tcproute.mdx b/website/content/docs/k8s/multiport/reference/tcproute.mdx index 6544b989422d..d0761f98869e 100644 --- a/website/content/docs/k8s/multiport/reference/tcproute.mdx +++ b/website/content/docs/k8s/multiport/reference/tcproute.mdx @@ -53,42 +53,7 @@ The following list outlines field hierarchy, language-specific data types, and r - [`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): integer - - [`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 - - [`retries`](#spec-rules-retries): map - - [`number`](#spec-rules-retries-number): map - - [`value`](#spec-rules-retries-number): integer - - [`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): map - - [`nanos`](#spec-rules-timeouts-idle): integer - - [`seconds`](#spec-rules-timeouts-idle): integer - - [`request`](#spec-rules-timeouts-request): map - - [`nanos`](#spec-rules-timeouts-request): integer - - [`seconds`](#spec-rules-timeouts-request): integer @@ -105,7 +70,7 @@ When every field is defined, a TCPRoute CRD has the following form: apiVersion: mesh.consul.hashicorp.com/v2beta1 # required kind: TCPRoute # required metadata: - name: + name: namespace: spec: parentRefs: @@ -137,42 +102,7 @@ spec: group: groupVersion: kind: - filters: - - requestHeaderModifier: - add: - name: "" - value: "" - - responseHeaderModifier: - set: - name: "" - value: "" - urlRewrite: - pathPrefix: weight: 1 - filters: - requestHeaderModifier: - remove: - name: "" - value: "" - responseHeaderModifier: - add: - name: "" - value: "" - urlRewrite: - pathPrefix: - retries: - number: - value: 1 - onConditions: ["cancelled", "unavailable"] - onConnectFailure: false - onStatusCodes: [400, 404] - timeouts: - idle: - nanos: 15 - seconds: 1 - request: - nanos: 10 - seconds: 1 ``` @@ -320,7 +250,7 @@ Specifies the type of resource that the configuration applies to. To reference a ### `spec.rules` -Specifies rules for sidecar proxies to direct a service's TCP traffic within the service mesh, including filtering, retry, and timeout behavior. +Specifies rules for sidecar proxies to direct a service's TCP traffic within the service mesh. #### Values @@ -333,7 +263,7 @@ Specifies the Kubernetes Service backend to direct TCP traffic to when a request 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 is invalid, the relative weights are maintained and traffic is not redirected automatically. 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. +When different Service backends are specified with [`spec.rules.backendRefs.weight`](#spec-rules-backendrefs-weight) and one is invalid, the relative weights are maintained and traffic is not adjusted automatically. 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 @@ -423,68 +353,6 @@ Specifies the type of resource that the configuration routes traffic to. To refe | `groupVersion` | Specifies a groupVersion for the resource type within the Kubenretes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String (in code, should be int based on desc.) | 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 TCPRoute 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 | - -### `spec.rules.backendRefs.filters.responseHeaderModifier` - -Specifies a set of header modification rules applied to responses routed with the TCPRoute 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 | - -### `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. @@ -498,154 +366,6 @@ When this parameter is not specified, it assumes the default value `1`. - 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 | - -### `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 | - -### `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.retries` - -Specifies retry logic for routing TCP 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.onConnnectFailure` - -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 TCP 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. - -#### Values - -- Default: None -- Data type: Map that can contain the following parameters: - - | Parameter | Description | Data type | Default | - | :-------- | :--------------------------------------------------------------- | --------- | ------- | - | `nanos` | Specifies the number of nanoseconds before triggering a timeout. | Integer | None | - | `seconds` | Specifies the number of seconds before triggering a timeout. | Integer | None | - -### `spec.rules.timeouts.request` - -Specifies the total amount of time spent processing the entire downstream request, including retries, before triggering a timeout. - -#### Values - -- Default: None -- Data type: Map that can contain the following parameters: - - | Parameter | Description | Data type | Default | - | :-------- | :--------------------------------------------------------------- | --------- | ------- | - | `nanos` | Specifies the number of nanoseconds before triggering a timeout. | Integer | None | - | `seconds` | Specifies the number of seconds before triggering a timeout. | Integer | None | - ## Examples The following examples demonstrate common TCPRoute CRD configuration patterns for specific use cases. @@ -669,7 +389,7 @@ spec: kind: Service name: api # Note that right now, we must target the workload port, - # not the service port. This is likely to change in 1.18+. + # not the service port. port: "api-workload" rules: - backendRefs: @@ -681,7 +401,7 @@ spec: kind: Service name: api # Note that right now, we must target the workload port, - # not the service port. This is likely to change in 1.18+. + # not the service port. port: "api-workload" weight: 50 - backendRef: @@ -692,7 +412,7 @@ spec: kind: Service name: api # Note that right now, we must target the workload port, - # not the service port. This is likely to change in 1.18+. + # not the service port. port: "admin-workload" weight: 50 ``` \ No newline at end of file From 3c57d1680ad146dcb3db18f014294ee7f5a2cf02 Mon Sep 17 00:00:00 2001 From: boruszak Date: Fri, 27 Oct 2023 11:52:45 -0700 Subject: [PATCH 19/57] proxy configuration model --- .../reference/proxyconfiguration.mdx | 170 ++++++++++++++---- 1 file changed, 133 insertions(+), 37 deletions(-) diff --git a/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx b/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx index 14d2bb8b8f82..0dda551c450c 100644 --- a/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx +++ b/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx @@ -1,29 +1,90 @@ --- layout: docs page_title: ProxyConfiguration resource configuration reference -description: Front-load meta descriptions with keywords and keyword phrases to help readers find the information they are searching for. +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 sample page template shows how to format high structured reference -information. +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. -## Configuration model +This custom resource definition (CRD) describes a GAMMA resource that requires the [v2 catalog API](/consul/docs/architecture/catalog/v2). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog/v1). For more information about GAMMA resources, refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/gamma/). -The following list outlines field hierarchy, language-specific data types, -and requirements in this configuration entry. Click on a property name -to view additional details, including default values. +## Configuration model -- [`elem_a`](#elema): data type | default -- [`elem_b`](#elemb): data type | default -- [`spec`](#elemb): data type | default -- [`elem_ba`](#elembelemba): data type | default -- [`elem_baa`](#elembelembaelembaa): data type | default -- [`elem_baaa`](#elembelembaelembaa): data type | default -- [`elem_baab`](#elembelembaelembaa): data type | default -- [`elem_baac`](#elembelembaelembaa): data type | default -- [`element_bab`](#elembelembaelembab): data type | default +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): object | required + - [`name`](#metadata-name): string | required + - [`namespace`](#metadata-namespace): string | optional +- [`spec`](#spec): object | required + - [`workloads`](#spec-workloads): map + - [`filter`](#spec-workloads): string + - [`names`](#spec-workloads): list 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 + - [`envoyExtensions`](#spec-dynamicconfig-envoyextensions): map + - [`arguments`](#spec-dynamicconfig-envoyextensions-arguments): map + - [`consulVersion`](#spec-dynamicconfig-envoyextensions-consulVersion): string + - [`envoyVersion`](#spec-dynamicconfig-envoyextensions-envoyVersion): string + - [`name`](#spec-dynamicconfig-envoyextensions-name): string + - [`required`](#spec-dynamicconfig-envoyextensions-required): boolean | `false` + - [`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): map + - [`nanos`](#spec-dynamicconfig-localconnection-connecttimeout): integer + - [`seconds`](#spec-dynamicconfig-localconnection-connecttimeout): integer + - [`requestTimeout`](#spec-dynamicconfig-localconnection-requesttimeout): map + - [`nanos`](#spec-dynamicconfig-localconnection-requesttimeout): integer + - [`seconds`](#spec-dynamicconfig-localconnection-requesttimeout): integer + - [`meshGatewayMode`](#spec-dynamicconfig-meshgatewaymode): string + - [`mode`](#spec-dynamicconfig-mode): string + - [`mutualTLSMode`](#spec-dynamicconfig-mutualtlsmode): 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 @@ -43,39 +104,74 @@ element_bbbd: ## Specification -The specification block contains the details about each configuration. It -is a flattened representation of the configuration model block that allows -for extended descriptions, examples, and other information to help readers -understand the behavior of the configurations. +This section provides details about the fields you can configure in the ProxyConfiguration custom resource definition (CRD). -### `Elem_a` +### `apiVersion` -Use this space to thoroughly, but succinctly, document the configuration -item. This format is intended to allow you to create complete documentation, -however, _stay within the scope of the reference_. If the description -deviates from the reference material, create a new Concept topic or add the -information to an existing Concept. +Specifies the version of the Consul API for integrating with Kubernetes. The value must be `mesh.consul.hashicorp.com/v2beta1`. #### Values -- Default: default value or none -- This field is required. -- Data type: data type +- Default: None +- This field is required. +- String value that must be set to `mesh.consul.hashicorp.com/v2beta1`. -Specify any additional information about the values that you can specify. +### `kind` -### `Elem_b` +Specifies the type of CRD to implement. Must be set to `ProxyConfiguration`. + +#### Values -Add your description. You can include example configurations and describe -any dependencies or cascading effects that the configuration may have. +- 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: default value or none -- This field is required. -- Data type: data type +- 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` + +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 `ProxyConfiguration` 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 must align with GAMMAs 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` + +#### Values -Specify any additional information about the values that you can specify. +- Default: None +- Data type: Map ## Examples From fa00cb7370079f9f603da9e8362665f718d40ac8 Mon Sep 17 00:00:00 2001 From: boruszak Date: Fri, 27 Oct 2023 16:47:11 -0700 Subject: [PATCH 20/57] ProxyConfiguration specifications --- .../reference/proxyconfiguration.mdx | 570 +++++++++++++++++- 1 file changed, 547 insertions(+), 23 deletions(-) diff --git a/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx b/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx index 0dda551c450c..d5d74b9ad2b8 100644 --- a/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx +++ b/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx @@ -26,7 +26,7 @@ The following list outlines field hierarchy, language-specific data types, and r - [`spec`](#spec): object | required - [`workloads`](#spec-workloads): map - [`filter`](#spec-workloads): string - - [`names`](#spec-workloads): list of strings + - [`names`](#spec-workloads): array of strings - [`prefixes`](#spec-workloads): array of strings - [`bootstrapConfig`](#spec-bootstrapconfig): map - [`dogstatsdUrl`](#spec-bootstrapconfig): string @@ -51,12 +51,6 @@ The following list outlines field hierarchy, language-specific data types, and r - [`path`](#spec-dynamicconfig-accesslogs-path): string - [`textFormat`](#spec-dynamicconfig-accesslogs-textformat): string - [`type`](#spec-dynamicconfig-accesslogs-type): string - - [`envoyExtensions`](#spec-dynamicconfig-envoyextensions): map - - [`arguments`](#spec-dynamicconfig-envoyextensions-arguments): map - - [`consulVersion`](#spec-dynamicconfig-envoyextensions-consulVersion): string - - [`envoyVersion`](#spec-dynamicconfig-envoyextensions-envoyVersion): string - - [`name`](#spec-dynamicconfig-envoyextensions-name): string - - [`required`](#spec-dynamicconfig-envoyextensions-required): boolean | `false` - [`exposeConfig`](#spec-dynamicconfig-exposeconfig): map - [`exposePaths`](#spec-dynamicconfig-exposeconfig-exposepaths): map - [`listenerPort`](#spec-dynamicconfig-exposeconfig-exposepaths-listenerport): integer @@ -77,7 +71,6 @@ The following list outlines field hierarchy, language-specific data types, and r - [`seconds`](#spec-dynamicconfig-localconnection-requesttimeout): integer - [`meshGatewayMode`](#spec-dynamicconfig-meshgatewaymode): string - [`mode`](#spec-dynamicconfig-mode): string - - [`mutualTLSMode`](#spec-dynamicconfig-mutualtlsmode): string - [`publicListenerJson`](#spec-dynamicconfig-publiclistenerjson): string - [`transparentProxy`](#spec-dynamicconfig-transparentproxy): map - [`dialedDirectly`](#spec-dynamicconfig-transparentproxy-dialeddirectly): boolean | `false` @@ -88,19 +81,79 @@ The following list outlines field hierarchy, language-specific data types, and r ## Complete configuration -The complete configuration follows the configuration model. Use tabs for -each markup language you expect pracitioners to use. +When every field is defined, an ProxyCOnfigurations CRD has the following form: + + + + + + ```yaml -element_a: -element_b: -element_bb: -element_bbb: -element_bbba: -element_bbbb: -element_bbbc: -element_bbbd: -``` +apiVersion: mesh.consul.hashicorp.com/v2beta1 # required +kind: ProxyConfiguration # required +metadata: + name: + namespace: +spec: + workloads: # required + filter: "Service.Meta.version == v1" + names: ["api", "admin"] + prefixes: ["
", ""]
+  bootstrapConfig: 
+    dogstatsdUrl: 
+    overrideJsonTpl: 
+    prometheusBindAddr:
+    readyBindAddr: 
+    staticClustersJson:
+    staticListenersJson:
+    statsBindAddr:
+    statsConfigJson:
+    statsFlushInterval:
+    statsSinkJson:
+    statsTags:
+      - string
+    statsdUrl:
+    telemetryCollectorBindSocketDir:
+    tracingConfigJson:
+  dynamicConfig:
+    accessLogs:
+      enabled: false
+      disableListenerLogs: false
+      jsonFormat: 
+      path: 
+      textFormat: 
+      type: 
+    exposeConfig:
+      exposePaths:
+        listenerPort: <42>
+        localPathPort: <4242>
+        path: 
+        protocol: 
+      inboundConnections:
+        balanceInboundConnections:
+        maxInboundConnections:
+    listenerTracingJson:
+    localClusterJson:
+    localConnection:
+      connectTimeout:
+        nanos: 
+        seconds: 
+      requestTimeout:
+        nanos:
+        seconds:
+    meshGatewayMode:
+    mode:
+    publicListenerJson:
+    transparentProxy:
+      dialedDirectly: false
+      outboundListenerPort: 15001
+```
+
+
+
+
+
 
 ## Specification
 
@@ -158,25 +211,496 @@ Specifies the namespace that the service resolver applies to. Refer to [namespac
 
 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.
 
-When using this CRD, the `spec` field must align with GAMMAs 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.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`
+### `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. Currently, 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`
+
+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 bootstrap via [`consul connect envoy` command](/consul/commands/connect/envoy). The variables that are available to be interpolated are [documented in `bootstrap_tpl.go`](https://github.com/hashicorp/consul/blob/71d45a34601423abdfc0a64d44c6a55cf88fa2fc/command/connect/envoy/bootstrap_tpl.go#L5).
+
+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.
+
+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`
+
+Specifies that the proxy should expose a Prometheus metrics endpoint to the _public_ network. It must be supplied in the form `ip:port` and port and 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.readyBindAddr`
+
+ Specifies the location to confiugure the proxy's readiness probe, specified 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 config.
+
+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-boostrapconfig-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-boostrapconfig-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. Currently, 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`
+
+#### Values
+
+- Default: None
+- Data type: String
+
+### `spec.dynamicConfig.exposeConfig`
+
+Specifies configurations to expose 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 a 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. This field enables customization of 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.
+
+#### Values
+
+- Default: None
+- Data type: Map that can contain the following parameters:
+
+  | Parameter | Description                                                      | Data type | Default |
+  | :-------- | :--------------------------------------------------------------- | --------- | ------- |
+  | `nanos`   | Specifies the number of nanoseconds before triggering a timeout. | Integer   | None    |
+  | `seconds` | Specifies the number of seconds before triggering a timeout.     | Integer   | None    |
+
+### `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.
+
+#### Values
+
+- Default: None
+- Data type: Map that can contain the following parameters:
+
+  | Parameter | Description                                                      | Data type | Default |
+  | :-------- | :--------------------------------------------------------------- | --------- | ------- |
+  | `nanos`   | Specifies the number of nanoseconds before triggering a timeout. | Integer   | None    |
+  | `seconds` | Specifies the number of seconds before triggering a timeout.     | Integer   | None    |
+
+### `spec.dynamicConfig.meshGatewayMode`
+
+Specifies the mode of operation for how upstreams with a remote destination datacenter are resolved. 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`
+
+Specifies the mode the proxy operates in: default, transparent, or direct. 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 to be delivered in place of the main public listener that the proxy used 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 the transparent proxy. 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
 
-If you have more than one example to show, create an Examples section 
-(general block) and introduce the examples per the style guide.
+The following examples demonstrate common ProxyConfiguration CRD configuration patterns for specific use cases.
 
 ### Specific use case 
 

From ee7e4a80fa9bbeb0873889a5b9be841fe5ab2066 Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Fri, 27 Oct 2023 16:56:17 -0700
Subject: [PATCH 21/57] Example

---
 .../multiport/reference/proxyconfiguration.mdx  | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx b/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx
index d5d74b9ad2b8..14b2b416d0df 100644
--- a/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx
+++ b/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx
@@ -711,5 +711,20 @@ some action on a service named `service-name`".
 
 
 ```yaml
-[Example goes here]
+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"
 ```

From 12c7212894922588172efeb953078133318fec2e Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Mon, 30 Oct 2023 10:00:52 -0700
Subject: [PATCH 22/57] basic traffic permissions info

---
 .../reference/proxyconfiguration.mdx          |   2 +-
 .../reference/trafficpermissions.mdx          | 136 +++++++++++-------
 2 files changed, 87 insertions(+), 51 deletions(-)

diff --git a/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx b/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx
index 14b2b416d0df..570996a2bd79 100644
--- a/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx
+++ b/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx
@@ -81,7 +81,7 @@ The following list outlines field hierarchy, language-specific data types, and r
 
 ## Complete configuration
 
-When every field is defined, an ProxyCOnfigurations CRD has the following form:
+When every field is defined, an ProxyConfigurations CRD has the following form:
 
 
 
diff --git a/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx b/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
index 80bea577e013..20886b86a63d 100644
--- a/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
+++ b/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
@@ -1,34 +1,49 @@
 ---
 layout: docs
 page_title: TrafficPermissions resource configuration reference
-description: Front-load meta descriptions with keywords and keyword phrases to help readers find the information they are searching for.
+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 sample page template shows how to format high structured reference 
-information.
+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/catalog/v2#changes-to-consul-s-existing-architecture) for more information.
 
-## Configuration model
+This custom resource definition (CRD) describes a GAMMA resource that requires the [v2 catalog API](/consul/docs/architecture/catalog/v2). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog/v1). For more information about GAMMA resources, refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/gamma/).
 
-The following list outlines field hierarchy, language-specific data types, 
-and requirements in this configuration entry. Click on a property name 
-to view additional details, including default values.
+## Configuration model
 
-- [`elem_a`](#elema): data type | default
-- [`elem_b`](#elemb): data type | default
-- [`spec`](#elemb): data type | default
-- [`elem_ba`](#elembelemba): data type | default
-- [`elem_baa`](#elembelembaelembaa): data type | default
-- [`elem_baaa`](#elembelembaelembaa): data type | default
-- [`elem_baab`](#elembelembaelembaa): data type | default
-- [`elem_baac`](#elembelembaelembaa): data type | default
-- [`element_bab`](#elembelembaelembab): data type | default
+The following list outlines field hierarchy, language-specific data types, and requirements in a TrafficPermissions 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 `TrafficPermissions`
+- [`metadata`](#metadata): object | required
+  - [`name`](#metadata-name): string | required
+  - [`namespace`](#metadata-namespace): string | optional 
+- [`spec`](#spec): object | required
+  - [`destination`](#spec-destination):
+    - [`identityName`](#spec-destination-identityname):
+  - [`action`](#spec-action):
+  - [`permissions`](#spec-permissions):
+    - [`sources`](#spec-permissions-sources):
+      - [`namespace`](#spec-permissions-sources):
+    - [`identityName`](#spec-permissions-identityname):
+      - [`destinationRules`](#spec-permissions-identityname-destinationrules):
+        - [`pathExact`](#spec-permissions-identityname-destinationrules):
+      - [`methods`](#spec-permissions-identityname-methods): array of strings
+    - [`portNames`](#spec-permissions-portnames): array of strings
+
+
+
 
 ## Complete configuration
 
-The complete configuration follows the configuration model. Use tabs for 
-each markup language you expect pracitioners to use.
+The [configuration model](#configuration-model) provides an overview of configurable fields and links to each field's specifications. The complete configuration provides the same basic structure, including field hierarchy and data types, in a code block that you can copy and paste into your preferred coding environment.
+
+When every field is defined, a TrafficPermissions CRD has the following form:
 
 ```yaml
 apiVersion: auth.consul.hashicorp.com/v2beta1    # required
@@ -45,58 +60,79 @@ spec:
         - namespace: 
     identityName: 
       destinationRules:
-        - pathExact:
-	    methods: ["GET", "POST"]
+        - pathExact: 
+      methods: ["GET", "POST"]
     portNames: [""]
-``` 
+```
 
 ## Specification
+This section provides details about the fields you can configure in the ProxyConfiguration custom resource definition (CRD).
+
+### `apiVersion`
 
-The specification block contains the details about each configuration. It 
-is a flattened representation of the configuration model block that allows 
-for extended descriptions, examples, and other information to help readers 
-understand the behavior of the configurations. 
+Specifies the version of the Consul API for integrating with Kubernetes. The value must be `mesh.consul.hashicorp.com/v2beta1`.
 
-### `Elem_a`
+#### Values
 
-Use this space to thoroughly, but succinctly, document the configuration 
-item. This format is intended to allow you to create complete documentation, 
-however, _stay within the scope of the reference_. If the description 
-deviates from the reference material, create a new Concept topic or add the 
-information to an existing Concept.
+- 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 `TrafficPermissions`.
 
 #### Values
 
-- Default: default value or none
-- This field is required. 
-- Data type: data type
+- Default: None
+- This field is required.
+- Data type: String value that must be set to `TrafficPermissions`.
+
+### `metadata`
 
-Specify any additional information about the values that you can specify.
+Map that contains an arbitrary name for the CRD and the namespace it applies to.
+
+#### Values
 
-### `Elem_b`
+- Default: None
+- Data type: Map
 
-Add your description. You can include example configurations and describe 
-any dependencies or cascading effects that the configuration may have.
+### `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` 
+
+Specifies the namespace that the service resolver applies to. Refer to [namespaces](/consul/docs/enterprise/namespaces) for more information.
 
 #### Values
 
-- Default: default value or none
-- This field is required. 
-- Data type: data type
+- 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
 
-Specify any additional information about the values that you can specify. 
+- Default: None
+- This field is required.
+- Data type: Map
 
 ## Examples
 
-If you have more than one example to show, create an Examples section 
-(general block) and introduce the examples per the style guide.
+The following examples demonstrate common TrafficPermissions CRD configuration patterns for specific use cases.
 
-### Specific use case 
+### Deny traffic between services
 
-Introduce examples clearly and help readers understand the connections 
-between the example snippet and the configuration element you are trying to 
-explain. Use phrases such as "In the following example, the `elem` performs 
-some action on a service named `service-name`". 
+The following example configures traffic permissions to deny traffic when the `web` service makes a request to the `api` service on the `admin` port.
 
 ```yaml
 apiVersion: auth.consul.hashicorp.com/v2beta1
@@ -111,5 +147,5 @@ spec:
     - sources:
         - identityName: web
       destinationRules:
-        - portNames: ["api"]
+        - portNames: ["admin"]
 ```

From 5e8f60279859b97305ed4c0c617c7a3a886f94e9 Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Mon, 30 Oct 2023 11:16:47 -0700
Subject: [PATCH 23/57] complete config structure

---
 .../reference/trafficpermissions.mdx          | 209 ++++++++++++++++--
 1 file changed, 192 insertions(+), 17 deletions(-)

diff --git a/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx b/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
index 20886b86a63d..60d1a06e1146 100644
--- a/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
+++ b/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
@@ -18,7 +18,7 @@ The following list outlines field hierarchy, language-specific data types, and r
 
 
 
-- [`apiVersion`](#apiversion): string | required | must be set to `mesh.consul.hashicorp.com/v2beta1`
+- [`apiVersion`](#apiversion): string | required | must be set to `auth.consul.hashicorp.com/v2beta1`
 - [`kind`](#kind): string | required | must be set to `TrafficPermissions`
 - [`metadata`](#metadata): object | required
   - [`name`](#metadata-name): string | required
@@ -26,22 +26,54 @@ The following list outlines field hierarchy, language-specific data types, and r
 - [`spec`](#spec): object | required
   - [`destination`](#spec-destination):
     - [`identityName`](#spec-destination-identityname):
-  - [`action`](#spec-action):
-  - [`permissions`](#spec-permissions):
+  - [`action`](#spec-action): string
+  - [`permissions`](#spec-permissions): list of maps
     - [`sources`](#spec-permissions-sources):
-      - [`namespace`](#spec-permissions-sources):
-    - [`identityName`](#spec-permissions-identityname):
-      - [`destinationRules`](#spec-permissions-identityname-destinationrules):
-        - [`pathExact`](#spec-permissions-identityname-destinationrules):
-      - [`methods`](#spec-permissions-identityname-methods): array of strings
-    - [`portNames`](#spec-permissions-portnames): array of strings
-
+      - [`identityName`](#spec-permissions-sources-identityname): string
+      - [`namespace`](#spec-permissions-sources-namespace): string
+      - [`partition`](#spec-permissions-sources-partition): string
+      - [`peer`](#spec-permissions-sources-peer): string
+      - [`samenessGroup`](#spec-permissions-sources-samenessgroup): string
+      - [`exclude`](#spec-permissions-sources-exclude): Map
+        - [`identityName`](#spec-permissions-sources-exclude): string
+        - [`namespace`](#spec-permissions-sources-exclude): string
+        - [`partition`](#spec-permissions-sources-exclude): string
+        - [`peer`](#spec-permissions-sources-exclude): string
+        - [`samenessGroup`](#spec-permissions-sources-exclude): string
+    - [`destinationRules`](#spec-permissions-destinationrules):
+      - [`header`](#spec-permissions-destinationrules-header): map
+        - [`exact`](#spec-permissions-destinationrules-header): string
+        - [`invert`](#spec-permissions-destinationrules-header): boolean | `false`
+        - [`name`](#spec-permissions-destinationrules-header): string
+        - [`prefix`](#spec-permissions-destinationrules-header): string
+        - [`present`](#spec-permissions-destinationrules-header): boolean | `false`
+        - [`regex`](#spec-permissions-destinationrules-header): string
+        - [`suffix`](#spec-permissions-destinationrules-header): string
+      - [`methods`](#spec-permissions-destinationrules-methods): array of strings
+      - [`pathExact`](#spec-permissions-destinationrules-pathexact): string
+      - [`pathPrefix`](#spec-permissions-destinationrules-pathprefix): string
+      - [`pathRegex`](#spec-permissions-destinationrules-pathregex): string
+      - [`portNames`](#spec-permissions-destinationrules-portNames): array of strings
+      - [`exclude`](#spec-permissions-destinationrules-exclude): map
+        - [`header`](#spec-permissions-destinationrules-exclude-header): map
+          - [`exact`](#spec-permissions-destinationrules-exclude-header): string
+          - [`invert`](#spec-permissions-destinationrules-exclude-header): boolean | `false`
+          - [`name`](#spec-permissions-destinationrules-exclude-header): string
+          - [`prefix`](#spec-permissions-destinationrules-exclude-header): string
+          - [`present`](#spec-permissions-destinationrules-exclude-header): boolean | `false`
+          - [`regex`](#spec-permissions-destinationrules-exclude-header): string
+          - [`suffix`](#spec-permissions-destinationrules-exclude-header): string
+        - [`methods`](#spec-permissions-destinationrules-exclude-methods): array of strings
+        - [`pathExact`](#spec-permissions-destinationrules-exclude-pathexact): string
+        - [`pathPrefix`](#spec-permissions-destinationrules-exclude-pathprefix): string
+        - [`pathRegex`](#spec-permissions-destinationrules-exclude-pathregex): string
+        - [`portNames`](#spec-permissions-destinationrules-exclude-portNames): array of strings
 
 
 
 ## Complete configuration
 
-The [configuration model](#configuration-model) provides an overview of configurable fields and links to each field's specifications. The complete configuration provides the same basic structure, including field hierarchy and data types, in a code block that you can copy and paste into your preferred coding environment.
+The previous section's [configuration model](#configuration-model) provides an overview of configurable fields and links directly to each field's specifications. The complete configuration provides the same basic structure, including field hierarchy and data types, in a code block that you can copy and paste into your preferred coding environment.
 
 When every field is defined, a TrafficPermissions CRD has the following form:
 
@@ -57,16 +89,48 @@ spec:
   action: allow
   permissions:
     - sources:
-        - namespace: 
-    identityName: 
-      destinationRules:
-        - pathExact: 
+      identityName:  
+      namespace: 
+      partition:
+      peer:
+      samenessGroup:
+      exclude:
+        identityName:
+        namespace:
+        partition:
+        peer:
+        samenessGroup:
+    destinationRules:
+      - header:
+        exact:
+        invert:
+        name:
+        prefix:
+        present:
+        regex:
+        suffix:
       methods: ["GET", "POST"]
-    portNames: [""]
+      pathExact: 
+      pathReges:
+      portNames: [""]
+      exclude:
+        - header:
+          exact:
+          invert:
+          name:
+          prefix:
+          present:
+          regex:
+          suffix:
+        methods:
+        pathExact:
+        pathPrefix:
+        pathRegex:
 ```
 
 ## Specification
-This section provides details about the fields you can configure in the ProxyConfiguration custom resource definition (CRD).
+
+This section provides details about the fields you can configure in the TrafficPermissions custom resource definition (CRD).
 
 ### `apiVersion`
 
@@ -126,6 +190,117 @@ Map that contains the details about the `TrafficPermissions` CRD. The `apiVersio
 - This field is required.
 - Data type: Map
 
+### `spec.destination`
+
+Destination is a configuration of the destination proxies
+                  where these traffic permissions should apply.
+
+#### Values
+
+- Default: None
+- Data type: Map
+
+### `spec.destination.identityName`
+
+
+
+#### Values
+
+- Default: None
+- Data type: String
+
+### `spec.action`
+
+"Action can be either allow or deny for the entire object.
+                  It will default to allow. \n If action is allow, we will allow the
+                  connection if one of the rules in Rules matches, in other words,
+                  we will deny all requests except for the ones that match Rules.
+                  If Consul is in default allow mode, then allow actions have no effect
+                  without a deny permission as everything is allowed by default. \n
+                  If action is deny, we will deny the connection if one of the rules
+                  in Rules match, in other words, we will allow all requests except
+                  for the ones that match Rules. If Consul is default deny mode, then
+                  deny permissions have no effect without an allow permission as everything
+                  is denied by default. \n Action unspecified is reserved for compatibility
+                  with the addition of future actions."
+
+#### Values
+
+- Default: None
+- Data type: String that must contain one of the following values:
+
+  - `ACTION_ALLOW`
+  - `ACTION_DENY`
+  - `ACTION_UNKNOWN`
+
+### `spec.permissions`
+
+Permissions is a list of permissions to match on. They
+                  are applied using OR semantics.
+
+#### Values
+
+- Default: None
+- Data type: List of maps
+
+### `spec.permissions.exclude`
+
+Permissions is a list of permissions to match on. They
+                  are applied using OR semantics.
+
+#### Values
+
+- Default: None
+- Data type: List of maps
+
+### `spec.permissions.sources`
+
+Sources is a list of sources in this traffic permission. Source represents the source identity. To specify
+                          any of the wildcard sources, the specific fields need to
+                          be omitted. For example, for a wildcard namespace, identity_name
+                          should be omitted.
+
+#### Values
+
+- Default: None
+- Data type: Map
+
+### `spec.permissions.identityName`
+
+
+
+#### Values
+
+- Default: None
+- Data type: Map
+
+### `spec.permissions.identityName.destinationRules`
+
+
+
+#### Values
+
+- Default: None
+- Data type: Map
+
+### `spec.permissions.identityName.methods`
+
+
+
+#### Values
+
+- Default: None
+- Data type: Map
+
+### `spec.permissions.portNames`
+
+
+
+#### Values
+
+- Default: None
+- Data type: Map
+
 ## Examples
 
 The following examples demonstrate common TrafficPermissions CRD configuration patterns for specific use cases.

From 556ecda8237a6194c924a8d319ee17fee6269dde Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Mon, 30 Oct 2023 11:33:13 -0700
Subject: [PATCH 24/57] tab spacing

---
 .../docs/k8s/multiport/reference/trafficpermissions.mdx   | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx b/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
index 60d1a06e1146..e442af7d2765 100644
--- a/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
+++ b/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
@@ -68,6 +68,7 @@ The following list outlines field hierarchy, language-specific data types, and r
         - [`pathPrefix`](#spec-permissions-destinationrules-exclude-pathprefix): string
         - [`pathRegex`](#spec-permissions-destinationrules-exclude-pathregex): string
         - [`portNames`](#spec-permissions-destinationrules-exclude-portNames): array of strings
+
 
 
 
@@ -77,6 +78,10 @@ The previous section's [configuration model](#configuration-model) provides an o
 
 When every field is defined, a TrafficPermissions CRD has the following form:
 
+
+
+
+
 ```yaml
 apiVersion: auth.consul.hashicorp.com/v2beta1    # required
 kind: TrafficPermissions                         # required
@@ -128,6 +133,9 @@ spec:
         pathRegex:
 ```
 
+
+
+
 ## Specification
 
 This section provides details about the fields you can configure in the TrafficPermissions custom resource definition (CRD).

From 5b24e3600c34bcec5cd711e0d7baca96f6ef1794 Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Mon, 30 Oct 2023 14:55:35 -0700
Subject: [PATCH 25/57] Traffic permission specifications

---
 .../reference/trafficpermissions.mdx          | 260 +++++++++++++++---
 1 file changed, 222 insertions(+), 38 deletions(-)

diff --git a/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx b/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
index e442af7d2765..b9221195c02e 100644
--- a/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
+++ b/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
@@ -42,13 +42,13 @@ The following list outlines field hierarchy, language-specific data types, and r
         - [`samenessGroup`](#spec-permissions-sources-exclude): string
     - [`destinationRules`](#spec-permissions-destinationrules):
       - [`header`](#spec-permissions-destinationrules-header): map
-        - [`exact`](#spec-permissions-destinationrules-header): string
-        - [`invert`](#spec-permissions-destinationrules-header): boolean | `false`
         - [`name`](#spec-permissions-destinationrules-header): string
-        - [`prefix`](#spec-permissions-destinationrules-header): string
         - [`present`](#spec-permissions-destinationrules-header): boolean | `false`
-        - [`regex`](#spec-permissions-destinationrules-header): string
+        - [`exact`](#spec-permissions-destinationrules-header): string
+        - [`prefix`](#spec-permissions-destinationrules-header): string
         - [`suffix`](#spec-permissions-destinationrules-header): string
+        - [`regex`](#spec-permissions-destinationrules-header): string
+        - [`invert`](#spec-permissions-destinationrules-header): boolean | `false`
       - [`methods`](#spec-permissions-destinationrules-methods): array of strings
       - [`pathExact`](#spec-permissions-destinationrules-pathexact): string
       - [`pathPrefix`](#spec-permissions-destinationrules-pathprefix): string
@@ -74,7 +74,7 @@ The following list outlines field hierarchy, language-specific data types, and r
 
 ## Complete configuration
 
-The previous section's [configuration model](#configuration-model) provides an overview of configurable fields and links directly to each field's specifications. The complete configuration provides the same basic structure, including field hierarchy and data types, in a code block that you can copy and paste into your preferred coding environment.
+The complete configuration provides the same basic information as the configuration model, including field hierarchy and data types. Instead of linking to specifications, it provides a code block that you can copy and paste into your preferred coding environment.
 
 When every field is defined, a TrafficPermissions CRD has the following form:
 
@@ -142,13 +142,13 @@ This section provides details about the fields you can configure in the TrafficP
 
 ### `apiVersion`
 
-Specifies the version of the Consul API for integrating with Kubernetes. The value must be `mesh.consul.hashicorp.com/v2beta1`.
+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 `mesh.consul.hashicorp.com/v2beta1`.
+- String value that must be set to `auth.consul.hashicorp.com/v2beta1`.
 
 ### `kind`
 
@@ -200,8 +200,7 @@ Map that contains the details about the `TrafficPermissions` CRD. The `apiVersio
 
 ### `spec.destination`
 
-Destination is a configuration of the destination proxies
-                  where these traffic permissions should apply.
+Specifies the proxies of the services where these traffic permissions apply.
 
 #### Values
 
@@ -210,7 +209,7 @@ Destination is a configuration of the destination proxies
 
 ### `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
 
@@ -219,18 +218,11 @@ Destination is a configuration of the destination proxies
 
 ### `spec.action`
 
-"Action can be either allow or deny for the entire object.
-                  It will default to allow. \n If action is allow, we will allow the
-                  connection if one of the rules in Rules matches, in other words,
-                  we will deny all requests except for the ones that match Rules.
-                  If Consul is in default allow mode, then allow actions have no effect
-                  without a deny permission as everything is allowed by default. \n
-                  If action is deny, we will deny the connection if one of the rules
-                  in Rules match, in other words, we will allow all requests except
-                  for the ones that match Rules. If Consul is default deny mode, then
-                  deny permissions have no effect without an allow permission as everything
-                  is denied by default. \n Action unspecified is reserved for compatibility
-                  with the addition of future actions."
+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).
+
+By default, Consul allows traffic between all services.
+
+The "Action unknown" value that this resource accepts is reserved for compatibility with future configurations. Do not invoke this value in the current release.
 
 #### Values
 
@@ -243,71 +235,263 @@ Destination is a configuration of the destination proxies
 
 ### `spec.permissions`
 
-Permissions is a list of permissions to match on. They
-                  are applied using OR semantics.
+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.exclude`
+### `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.
 
-Permissions is a list of permissions to match on. They
-                  are applied using OR semantics.
+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
+- Data type: Map
 
-### `spec.permissions.sources`
+### `spec.permissions.sources.identityName`
 
-Sources is a list of sources in this traffic permission. Source represents the source identity. To specify
-                          any of the wildcard sources, the specific fields need to
-                          be omitted. For example, for a wildcard namespace, identity_name
-                          should be omitted.
+Specifies the Workload identity for the service that originates the request.
 
 #### Values
 
 - Default: None
 - Data type: Map
 
-### `spec.permissions.identityName`
+### `spec.permissions.sources.namespace`
 
+Specifies the Consul namespace for the service that originates the request.
 
+#### Values
+
+- Default: None
+- Data type: Map
+
+### `spec.permissions.sources.partition`
+
+Specifies the Consul admin partition for the service that originates the request.
 
 #### Values
 
 - Default: None
 - Data type: Map
 
-### `spec.permissions.identityName.destinationRules`
+### `spec.permissions.sources.peer`
+
+Specifies the Consul cluster peer where the service that originates the request is scheduled.
+
+#### Values
+
+- Default: None
+- Data type: Map
 
+### `spec.permissions.sources.samenessGroup`
 
+Specifies the sameness group that includes the service that originates the request.
 
 #### Values
 
 - Default: None
 - Data type: Map
 
-### `spec.permissions.identityName.methods`
+### `spec.permissions.sources.exclude`
+
+Specifies sources to exclude from the defined source.
+
+#### Values
+
+- Default: None
+- Data type: Array of maps
 
+### `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: Map
 
-### `spec.permissions.portNames`
+### `spec.permissions.destinationRules.header`
+
+Specifies a set of criteria for matching HTTP request headers. The request header must match all specified criteria for the permission to apply.
+
+#### Values
+
+- Default: None
+- Data type: List of maps
+
+Each member of the header list is a map that contains a name field and at least one match criterion. The following table describes the parameters that each member of the header list may contain:
+
+| Parameter | Description | Data type | Required |
+| --- | --- | --- | --- |
+| `name` | Specifies the name of the header to match. | string | required |
+| `present` | Enables a match if the header configured in the `name` field appears in the request. Consul matches on any value as long as the header key appears in the request. Do not specify `present` if `exact`, `prefix`, `suffix`, or `regex` are configured in the same `header` configuration. | boolean | optional |
+| `exact` | Specifies a value for the header key set in the `name` field. If the request header value matches the `exact` value, Consul applies the permission.  Do not specify `exact` if `present`, `prefix`, `suffix`, or `regex` are configured in the same `header` configuration. | string | optional |
+| `prefix` | Specifies a prefix value for the header key set in the `name` field. If the request header value starts with the `prefix` value, Consul applies the permission.  Do not specify `prefix` if `present`, `exact`, `suffix`, or `regex` are configured in the same `header` configuration. | string | optional |
+| `suffix` | Specifies a suffix value for the header key set in the `name` field. If the request header value ends with the `suffix` value, Consul applies the permission.  Do not specify `suffix` if `present`, `exact`, `prefix`, or `regex` are configured in the same `header` configuration. | string | optional |
+| `regex` | Specifies a regular expression pattern as the value for the header key set in the `name` field. If the request header value matches the regex, Consul applies the permission. Do not specify `regex` if `present`, `exact`, `prefix`, or `suffix` are configured in the same `header` configuration. The regex syntax is proxy-specific. If using Envoy, refer to the [re2 documentation](https://github.com/google/re2/wiki/Syntax) for details. | string | optional |
+| `invert` | Inverts the matching logic configured in the `header`. Default is `false`. | boolean | optional |
 
+### `spec.permissions.destinationRules.methods`
 
+Specifies a list of HTTP methods. Consul applies the permission if the source sent the request using one of the specified methods. Refer to the [Mozilla documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) for details on supported request methods.
 
 #### Values
 
 - Default: None
-- Data type: Map
+- Data type: List of strings with one or more of the following values:
+
+  - `GET`
+  - `HEAD`
+  - `POST`
+  - `PUT`
+  - `DELETE`
+  - `CONNECT`
+  - `OPTIONS`
+  - `TRACE`
+  - `PATCH`
+
+Refer to the [Mozilla documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) for more information about each method.
+
+### `spec.permissions.destinationRules.pathExact`
+
+Specifies an exact path to match on the request path. Do not specify `pathExact` if `pathPrefix` or `pathRegex` are configured in the same destination rule.
+
+#### Values
+
+- Default: None
+- Data type: String
+
+### `spec.permissions.destinationRules.pathPrefix`
+
+Specifies a path prefix to match on the request path. Do not specify `pathPrefix` if `pathExact` or `pathRegex` are configured in the same destination rule.
+
+#### Values
+
+- Default: None
+- Data type: String
+
+### `spec.permissions.destinationRules.pathRegex`
+
+Defines a regular expression to match on the request path. Do not specify `pathRegex` if `pathExact` or `pathPrefix` are configured in the same destination rule. The regex syntax is proxy-specific. If using Envoy, refer to the [re2 documentation](https://github.com/google/re2/wiki/Syntax) for details.
+
+#### Values
+
+- Default: None
+- Data type: String
+
+### `spec.permissions.destinationRules.portNames`
+
+Specifies a port name that the Kubernetes Service exposes at the destination.
+
+#### Values
+
+- Default: None
+- Data type: String
+
+### `spec.permissions.destinationRules.exclude`
+
+Specifies a list of destination rules to exclude when evaluating an incoming connection.
+
+#### Values
+
+- Default: None
+- Data type: List of maps
+
+### `spec.permissions.destinationRules.exclude.header`
+
+Specifies a set of header information that qualify for an exclusion to the destination rules. When an incoming request contains matching header information, the request will not produce a match when evaluating the destination rule that is otherwise defined.
+
+When [`spec.action`](#spec-action) _allows traffic_, Consul denies permission to the exclusion.
+
+When [`spec.action`](#spec-action) _denies traffic_, Consul allows permission to the exclusion.
+
+The request header must match all specified criteria to be considered an exclusion.
+
+#### Values
+
+- Default: None
+- Data type: List of maps
+
+Each member of the header list is a map that contains a name field and at least one match criterion. The following table describes the parameters that each member of the header list may contain:
+
+| Parameter | Description | Data type | Required |
+| --- | --- | --- | --- |
+| `name` | Specifies the name of the header to match. | string | required |
+| `present` | Enables a match if the header configured in the `name` field appears in the request. Consul matches on any value as long as the header key appears in the request. Do not specify `present` if `exact`, `prefix`, `suffix`, or `regex` are configured in the same `exclude.header` configuration. | boolean | optional |
+| `exact` | Specifies a value for the header key set in the `name` field. If the request header value matches the `exact` value, Consul applies the permission.  Do not specify `exact` if `present`, `prefix`, `suffix`, or `regex` are configured in the same `exclude.header` configuration. | string | optional |
+| `prefix` | Specifies a prefix value for the header key set in the `name` field. If the request header value starts with the `prefix` value, Consul applies the permission.  Do not specify `prefix` if `present`, `exact`, `suffix`, or `regex` are configured in the same `exclude.header` configuration. | string | optional |
+| `suffix` | Specifies a suffix value for the header key set in the `name` field. If the request header value ends with the `suffix` value, Consul applies the permission.  Do not specify `suffix` if `present`, `exact`, `prefix`, or `regex` are configured in the same `exclude.header` configuration. | string | optional |
+| `regex` | Specifies a regular expression pattern as the value for the header key set in the `name` field. If the request header value matches the regex, Consul applies the permission. Do not specify `regex` if `present`, `exact`, `prefix`, or `suffix` are configured in the same `exclude.header` configuration. The regex syntax is proxy-specific. If using Envoy, refer to the [re2 documentation](https://github.com/google/re2/wiki/Syntax) for details. | string | optional |
+| `invert` | Inverts the matching logic configured in the `exclude.header`. Default is `false`. | boolean | optional |
+
+### `spec.permissions.destinationRules.exclude.methods`
+
+Specifies a set of HTTP methods that qualify a request for an exclusion to the destination rules. When an incoming request uses one of the specified methods, the request will not produce a match when evaluating the destination rule that is otherwise defined.
+
+Refer to the [Mozilla documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) for details on supported request methods.
+
+#### Values
+
+- Default: None
+- Data type: List of strings with one or more of the following values:
+
+  - `GET`
+  - `HEAD`
+  - `POST`
+  - `PUT`
+  - `DELETE`
+  - `CONNECT`
+  - `OPTIONS`
+  - `TRACE`
+  - `PATCH`
+
+Refer to the [Mozilla documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) for more information about each method.
+
+### `spec.permissions.destinationRules.exclude.pathExact`
+
+Specifies an exact path that causes a request to be considered an exclusion to the destination rules.
+
+#### Values
+
+- Default: None
+- Data type: String
+
+### `spec.permissions.destinationRules.exclude.pathPrefix`
+
+Specifies a path prefix that causes a request to be considered an exclusion to the destination rules.
+
+#### Values
+
+- Default: None
+- Data type: String
+
+### `spec.permissions.destinationRules.exclude.pathRegex`
+
+Defines a regular expression that causes a request to be considered an exclusion to the destination rules when it matches a request path. The regex syntax is proxy-specific. If using Envoy, refer to the [re2 documentation](https://github.com/google/re2/wiki/Syntax) for details.
+
+#### Values
+
+- Default: None
+- Data type: String
+
+### `spec.permissions.destinationRules.exclude.portNames`
+
+Specifies a port name that exposes a Kubernetes Service. An incoming requests addressed to the port is considered an exclusion to the destination rules.
+
+#### Values
+
+- Default: None
+- Data type: List of strings
 
 ## Examples
 

From 7b1b91aba86ee62a78fc29f4d52c59bcc60e6bcc Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Mon, 30 Oct 2023 15:02:01 -0700
Subject: [PATCH 26/57] Proxy config example description

---
 .../docs/k8s/multiport/reference/proxyconfiguration.mdx   | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)

diff --git a/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx b/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx
index 570996a2bd79..38126d49a4cf 100644
--- a/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx
+++ b/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx
@@ -702,13 +702,9 @@ Specifies the port the proxy listens on for outbound traffic to capture and redi
 
 The following examples demonstrate common ProxyConfiguration CRD configuration patterns for specific use cases.
 
-### Specific use case 
-
-Introduce examples clearly and help readers understand the connections 
-between the example snippet and the configuration element you are trying to 
-explain. Use phrases such as "In the following example, the `elem` performs 
-some action on a service named `service-name`". 
+### 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

From ead575270a44c51f32514e9ce1f2ca45e21c10be Mon Sep 17 00:00:00 2001
From: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
Date: Tue, 31 Oct 2023 10:04:04 -0700
Subject: [PATCH 27/57] Apply suggestions from code review

Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
Co-authored-by: Nitya Dhanushkodi 
---
 .../content/docs/architecture/catalog/v1.mdx  |  4 ++--
 .../content/docs/architecture/catalog/v2.mdx  | 22 +++++++++----------
 website/content/docs/k8s/multiport/index.mdx  |  2 +-
 .../multiport/reference/resource-command.mdx  | 10 +++------
 4 files changed, 17 insertions(+), 21 deletions(-)

diff --git a/website/content/docs/architecture/catalog/v1.mdx b/website/content/docs/architecture/catalog/v1.mdx
index 28d4bc70db37..5271ed013abb 100644
--- a/website/content/docs/architecture/catalog/v1.mdx
+++ b/website/content/docs/architecture/catalog/v1.mdx
@@ -14,7 +14,7 @@ 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 introduces a second version of the Catalog API for testing and development purposes. The catalog APIs cannot run concurrently in a Consul deployment. There is no migration path between catalog versions at this time. For more information, refer to [Consul v2 Catalog API](/consul/docs/architecture/catalog/v2).
+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 to be used 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/catalog/v2).
 
 ## Catalog structure
 
@@ -29,7 +29,7 @@ When Consul registers a service instance using the v1 catalog API, it records th
 | NodeMeta | User-defined metadata about the node. | Defined by user |
 | Datacenter | The name of the datacenter the service is registered in. | Defined by user |
 | Service | The name of the service Consul registers the service instance under. | Defined by user |
-| Agent Check | The health status of service last reported by the Consul agent. | Computed by Consul |
+| Agent Check | The health checks defined for a service instance managed by a Consul client agent. | Computed by Consul |
 | Health Checks | The health checks defined for the service. Refer to [define health checks](/consul/docs/services/usage/checks) for more information. | Defined by user |
 | Partition | The name of the admin partition the service is registered in. Refer to [admin partitions](/consul/docs/enterprise/admin-partitions) for more information. | Defined by user |
 | Locality | Region and availability zone of the service. Refer to [`locality`](/consul/docs/agent/config/config-files#locality) for more information. | Defined by user |
diff --git a/website/content/docs/architecture/catalog/v2.mdx b/website/content/docs/architecture/catalog/v2.mdx
index c8d8df6e91e5..905c97676545 100644
--- a/website/content/docs/architecture/catalog/v2.mdx
+++ b/website/content/docs/architecture/catalog/v2.mdx
@@ -10,7 +10,7 @@ description: Learn about version 2 of the Consul catalog, which uses GAMMA speci
 The v2 catalog API is in a beta release for testing and development purposes. Do not use the v2 catalog or multi-port services in secure production environments.
 
 
-This topic provides conceptual information about version 2 of the Consul Catalog API. The catalog tracks registered services and their locations for both service discovery and service mesh use cases.
+This topic provides conceptual information about version 2 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 on Kubernetes deployments only. For more information about Consul’s default catalog, refer to [v1 Catalog API](/consul/docs/architecture/catalog/v1).
 
@@ -26,7 +26,7 @@ This information enables Consul to associate service names with the individual i
 
 The [Consul v1 Catalog API](/consul/docs/architecture/catalog/v1) was designed prior to the introduction of Consul’s service mesh features. 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 service can represent a Kubernetes Workload in the v1 catalog.
 
-Since then, the cloud networking needs for applications have evolved and workarounds were developed. For example, [Kubernetes Pods with multiple ports](/consul/docs/k8s/connect#kubernetes-pods-with-multiple-ports) demonstrates how you can schedule a service with multiple ports so that Consul registers it in the catalog as distinct services with their own service instances. However, this workaround results in additional resource consumption because Consul requires that each service and port use their own proxy and Consul dataplane so that it can recognize them as distinct services.
+The v2 catalog API addresses limitations with the v1 catalog API, allowing functionality such as associating Kubernetes Pods with multiple Kubernetes Services, or allowing Services and Pods registered with Consul to have multiple ports. The v2 catalog APIs align more closely with upstream Kubernetes APIs and some concepts differ from the v1 APIs. These differences are described in the catalog structure section below.
 
 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.
 
@@ -36,15 +36,15 @@ Consul v1.17 introduces a new version of the catalog API designed to bridge diff
 
 The following table describes resources in the v2 catalog and compares them to the v1 catalog and Kubernetes resources. It also states whether these resources are defined by the user or computed by Consul when it registers a service.
 
-| v2 Catalog resource | Description | Catalog v1 resource analogue | Kubernetes resource analogue | Source |
+| Catalog v2 resource | Description | Catalog v1 resource analogue | Kubernetes resource analogue | Source |
 | :------------------ | :---------- | :--------------------------- | :--------------------------- | :----- |
-| Service | The name of the service Consul registers a workload under | Service | None  | Defined by user in Kubernetes |
-| Node | The address of the node where the workload runs. | Node | Node | Computed by Consul |
-| Workload | 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 Workloads | Defined by user in Kubernetes |
-| Workload identities | Provides a distinct identity for a Kubernetes Workload to assume in a Kubernetes cluster. | Service instance | Kubernetes Service Accounts | Defin by user in Kubernetes |
-| Service endpoints | Maps services to workload addresses and endpoints. | None  | Service backend | Computed by Consul |
+| Service | The name of the service Consul registers a workload under. | Service | None  | Defined by user in Kubernetes |
+| Node | The address of the node where the workload runs. | Node | Kubernetes Node | Computed by Consul |
+| Workload | 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 | Defined by user in Kubernetes |
+| Workload identities | Provides a distinct identity for a workload to assume and is used for Traffic Permissions. | Service instance | Kubernetes Service Accounts | Defined by user in Kubernetes |
+| Service endpoints | Maps services to workload addresses and endpoints. | None  | Kubernetes Endpoints | Computed by Consul |
 | Health status | A resource for reporting the health status of a workload | Agent check | None | Computed by Consul |
-| Health check | A resource for defining the health checks for a workload. | Health check | Liveness, Readiness, and Startup Probes | Defined by user in Kubernetes |
+| Health check | A resource for defining the health checks for a workload. | Service Instance Health check | Liveness, Readiness, and Startup Probes | Defined by user in Kubernetes |
 | Proxy configuration | Represents a configuration for a sidecar or gateway proxy. | `Proxy` field in service definition | None | Defined by user in Consul |
 | Destinations | Represents explicit service upstreams | None | Upstream Service annotation  | Defined by user in Kubernetes |
 | Traffic permissions | Enables L4 traffic authorization according to workload identity instead of service identity. | Service intentions | None | Defined by user in Consul |
@@ -57,9 +57,9 @@ The change in data models introduced by the v2 Catalog API impacts several aspec
 
 ### 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 TrafficPermissions resource. This resource replaces the service intentions configuration entry, and enables authorized service-to-service communication for both L4 and L7 applications.
+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 [TrafficPermissions configuration reference](/consul/docs/k8s/multiport/reference/trafficpermissions).
+For more information about this resource, including example configurations, refer to [Traffic permissions configuration reference](/consul/docs/k8s/multiport/reference/trafficpermissions).
 
 ### HTTPRoute and GRPCRoute resources for L7 traffic management
 
diff --git a/website/content/docs/k8s/multiport/index.mdx b/website/content/docs/k8s/multiport/index.mdx
index c411906d902a..04a0a930e74b 100644
--- a/website/content/docs/k8s/multiport/index.mdx
+++ b/website/content/docs/k8s/multiport/index.mdx
@@ -31,7 +31,7 @@ For an example configuration and instructions for each of the steps in this work
 
 Be aware of the following constraints and technical limitations on using multi-port services and the v2 catalog API:
 
-- Consul client agents do not support multi-port services or the v2 catalog API beta. Kubernetes deployments support multi-port services using [Consul dataplanes](/consul/docs/connect/dataplane) instead of client agents.
+- The v2 catalog API only supports using [Consul dataplanes](/consul/docs/connect/dataplane) instead of client agents. This is the default deployment mode in Kubernetes.
 - The v1 and v2 catalog APIs cannot run concurrently.
 - The Consul UI does not support multi-port services or the v2 catalog API in this release. You must disable the UI in the Helm chart in order to use the v2 catalog API.
 - HCP Consul does not support multi-port services or the v2 catalog API in this release. You cannot [link a self-managed cluster to HCP Consul](/hcp/docs/consul/self-managed) to access its UI or view observability metrics when it uses the v2 catalog.
diff --git a/website/content/docs/k8s/multiport/reference/resource-command.mdx b/website/content/docs/k8s/multiport/reference/resource-command.mdx
index 471d15d00376..593a6ceba725 100644
--- a/website/content/docs/k8s/multiport/reference/resource-command.mdx
+++ b/website/content/docs/k8s/multiport/reference/resource-command.mdx
@@ -35,11 +35,7 @@ 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 table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication).
-
-| ACL Required |
-| ------------ |
-| `operator:write`  |
+You must present a token with `operator:write` [ACL permissions](/consul/api-docs/api-structure#authentication) to use the `apply` command. 
 
 #### Command Options
 
@@ -47,7 +43,7 @@ The table below shows this command's [required ACLs](/consul/api-docs/api-struct
 
 #### Example usage
 
-The following command applies a TrafficPermissions resource to Consul that restricts service-to-service communication to authorized services only.
+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.yaml
@@ -69,7 +65,7 @@ The table below shows this command's [required ACLs](/consul/api-docs/api-struct
 
 #### Example usage
 
-The following command removes a TrafficPermissions resource from Consul that restricts service-to-service communication to authorized services only.
+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.yaml

From bb96ad8a83c2f7395685de70e9e51868522df277 Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Tue, 31 Oct 2023 11:23:16 -0700
Subject: [PATCH 28/57] v1 concept review updates

---
 website/content/docs/architecture/catalog/v1.mdx | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/website/content/docs/architecture/catalog/v1.mdx b/website/content/docs/architecture/catalog/v1.mdx
index 5271ed013abb..d55ea1fcd840 100644
--- a/website/content/docs/architecture/catalog/v1.mdx
+++ b/website/content/docs/architecture/catalog/v1.mdx
@@ -12,9 +12,9 @@ For more information about the information returned when querying the catalog, i
 
 ## Introduction
 
-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 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 to be used 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/catalog/v2).
+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/catalog/v2).
 
 ## Catalog structure
 
@@ -22,10 +22,10 @@ When Consul registers a service instance using the v1 catalog API, it records th
 
 | v1 Catalog field | Description | Source |
 | :--------------- | :---------- | :----- |
-| ID | A unique identifier for a service instance. | Computed by Consul |
-| Node | The connection point where the service is available. | Computed by Consul |
-| Address  | The address of the node where the service instance is running. | Computed by Consul |
-| Tagged Addresses | User-defined metadata about addresses. | Defined by user |
+| ID | A unique identifier for a service instance. | Defined by user in [service definition](/consul/docs/services/configuration/services-configuration-reference#id). |
+| Node | The connection point where the service is available.  | On VMs, defined by user. 

 On Kubernetes, computed by Consul according to [Kubernetes Nodes](https://kubernetes.io/docs/concepts/architecture/nodes/). |
+| Address  | The registered address of the service instance. | Defined by user in [service definition](/consul/docs/services/configuration/services-configuration-reference#address). |
+| Tagged Addresses | User-defined labels for addresses. | Defined by user in [service definition](/consul/docs/services/configuration/services-configuration-reference#tags). |
 | NodeMeta | User-defined metadata about the node. | Defined by user |
 | Datacenter | The name of the datacenter the service is registered in. | Defined by user |
 | Service | The name of the service Consul registers the service instance under. | Defined by user |

From e95f5900a1ec814c6830b10c33fb9b7f51e908ce Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Tue, 31 Oct 2023 11:48:31 -0700
Subject: [PATCH 29/57] v2 catalog code review updates

---
 .../content/docs/architecture/catalog/v2.mdx  | 32 +++++++++----------
 1 file changed, 16 insertions(+), 16 deletions(-)

diff --git a/website/content/docs/architecture/catalog/v2.mdx b/website/content/docs/architecture/catalog/v2.mdx
index 905c97676545..da16f59d125a 100644
--- a/website/content/docs/architecture/catalog/v2.mdx
+++ b/website/content/docs/architecture/catalog/v2.mdx
@@ -10,9 +10,9 @@ description: Learn about version 2 of the Consul catalog, which uses GAMMA speci
 The v2 catalog API is in a beta release for testing and development purposes. Do not use the v2 catalog or multi-port services in secure production environments.
 
 
-This topic provides conceptual information about version 2 of the Consul catalog API. The catalog tracks registered services and their locations for both service discovery and service mesh use cases.
+This topic provides conceptual 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 on Kubernetes deployments only. For more information about Consul’s default catalog, refer to [v1 Catalog API](/consul/docs/architecture/catalog/v1).
+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/v1).
 
 ## Introduction
 
@@ -24,9 +24,9 @@ When Consul registers services, it records [user-defined and Consul-assigned inf
 
 This information enables Consul to associate service names with the individual instances and their unique network addresses, and it is essential to Consul’s service discovery and service mesh operations.
 
-The [Consul v1 Catalog API](/consul/docs/architecture/catalog/v1) was designed prior to the introduction of Consul’s service mesh features. 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 service can represent a Kubernetes Workload in the v1 catalog.
+The [Consul v1 catalog API](/consul/docs/architecture/catalog/v1) was designed prior to the introduction of Consul’s service mesh features. 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 service can represent a service instance in the v1 catalog.
 
-The v2 catalog API addresses limitations with the v1 catalog API, allowing functionality such as associating Kubernetes Pods with multiple Kubernetes Services, or allowing Services and Pods registered with Consul to have multiple ports. The v2 catalog APIs align more closely with upstream Kubernetes APIs and some concepts differ from the v1 APIs. These differences are described in the catalog structure section below.
+The v2 catalog API aligns more closely with the [Kubernetes Gateway API's GAMMA initiative](https://gateway-api.sigs.k8s.io/concepts/gamma/), enabling functionality such as associating Kubernetes Pods with multiple Kubernetes Services and allowing Services and Pods registered with Consul to have multiple ports. For more information about how the differences between the catalog API impacts Consul operations, refer to [changes to Consul's existing architecture](#changes-to-consuls-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.
 
@@ -39,15 +39,15 @@ The following table describes resources in the v2 catalog and compares them to t
 | Catalog v2 resource | Description | Catalog v1 resource analogue | Kubernetes resource analogue | Source |
 | :------------------ | :---------- | :--------------------------- | :--------------------------- | :----- |
 | Service | The name of the service Consul registers a workload under. | Service | None  | Defined by user in Kubernetes |
-| Node | The address of the node where the workload runs. | Node | Kubernetes Node | Computed by Consul |
-| Workload | 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 | Defined by user in Kubernetes |
-| Workload identities | Provides a distinct identity for a workload to assume and is used for Traffic Permissions. | Service instance | Kubernetes Service Accounts | Defined by user in Kubernetes |
-| Service endpoints | Maps services to workload addresses and endpoints. | None  | Kubernetes Endpoints | Computed by Consul |
-| Health status | A resource for reporting the health status of a workload | Agent check | None | Computed by Consul |
-| Health check | A resource for defining the health checks for a workload. | Service Instance Health check | Liveness, Readiness, and Startup Probes | Defined by user in Kubernetes |
+| Node | The address of the node where the workload runs. | Node | [Kubernetes Node](https://kubernetes.io/docs/concepts/architecture/nodes/) | Computed by Consul |
+| Workload | 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/) | Defined by user in Kubernetes |
+| Workload identities | Provides a distinct identity for a workload to assume and is used for Traffic Permissions. | Service instance | [Kubernetes Service Accounts](https://kubernetes.io/docs/concepts/security/service-accounts/) | Defined by user in Kubernetes |
+| Service endpoints | 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 | A resource for reporting the health status of a workload. | Service instance health status | None | Computed by Consul |
+| Health check | 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) | Defined by user in Kubernetes |
 | Proxy configuration | Represents a configuration for a sidecar or gateway proxy. | `Proxy` field in service definition | None | Defined by user in Consul |
-| Destinations | Represents explicit service upstreams | None | Upstream Service annotation  | Defined by user in Kubernetes |
-| Traffic permissions | Enables L4 traffic authorization according to workload identity instead of service identity. | Service intentions | None | Defined by user in Consul |
+| Destinations | Represents explicit service upstreams. | [Proxy Configuration](/consul/docs/connect/proxies/envoy#envoy-proxy-configuration-for-service-mesh) | [Upstream Service annotation](/consul/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams)  | Defined by user in Kubernetes |
+| Traffic permissions | Enables L4 traffic authorization according to workload identity instead of service identity. | [Service intentions](/consul/docs/connect/intentions) | None | Defined by user in Consul |
 
 Refer to [`consul resource`](/consul/docs/k8s/multiport/reference/resource-command) for more information about using the Consul CLI to interact with the v2 catalog.
 
@@ -61,14 +61,14 @@ The most significant change to Consul’s architecture and operations when using
 
 For more information about this resource, including example configurations, refer to [Traffic permissions configuration reference](/consul/docs/k8s/multiport/reference/trafficpermissions).
 
-### HTTPRoute and GRPCRoute resources for L7 traffic management
+### HTTPRoute, GRPCRoute, and TCPRoute resources for traffic management
 
-You can configure L7 traffic management behavior, such as service splitting, in an `HTTPRoute` or a `GRPCRoute` 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).
+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) and [GRPCRoute resource configuration reference](/consul/docs/k8s/multiport/reference/grpcroute).
+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).
 
-The v2 catalog introduces the `ProxyConfiguration` resource, enabling the automatic configuration of sidecar proxy behavior according to Consul workload identity. Refer to [ProxyConfiguration resource configuration reference](/consul/docs/k8s/multiport/reference/proxyconfiguration) for more information.
+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.

From 3c005995c7b7259a1d93c7c2ecdd545394e0e8b6 Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Tue, 31 Oct 2023 11:59:16 -0700
Subject: [PATCH 30/57] V2 catalog contraints + guidance

---
 .../content/docs/architecture/catalog/v2.mdx  | 28 +++++++++++++++++++
 website/content/docs/k8s/multiport/index.mdx  |  8 +++---
 2 files changed, 32 insertions(+), 4 deletions(-)

diff --git a/website/content/docs/architecture/catalog/v2.mdx b/website/content/docs/architecture/catalog/v2.mdx
index da16f59d125a..c467c7b15990 100644
--- a/website/content/docs/architecture/catalog/v2.mdx
+++ b/website/content/docs/architecture/catalog/v2.mdx
@@ -72,3 +72,31 @@ For more information about these resource, including specifications and example
 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.
+- 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.
+- HCP Consul does not support the v2 catalog API in this release. You cannot [link a self-managed cluster to HCP Consul](/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
+
+- [Multi-port services overview](/consul/docs/k8s/multiport/configure)
+- [Configure multi-port services](/consul/docs/k8s/multiport/configure)
+
+### 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)
diff --git a/website/content/docs/k8s/multiport/index.mdx b/website/content/docs/k8s/multiport/index.mdx
index 04a0a930e74b..2524e7f8cd5c 100644
--- a/website/content/docs/k8s/multiport/index.mdx
+++ b/website/content/docs/k8s/multiport/index.mdx
@@ -31,10 +31,10 @@ For an example configuration and instructions for each of the steps in this work
 
 Be aware of the following constraints and technical limitations on using multi-port services and the v2 catalog API:
 
-- The v2 catalog API only supports using [Consul dataplanes](/consul/docs/connect/dataplane) instead of client agents. This is the default deployment mode in Kubernetes.
-- The v1 and v2 catalog APIs cannot run concurrently.
-- The Consul UI does not support multi-port services or the v2 catalog API in this release. You must disable the UI in the Helm chart in order to use the v2 catalog API.
-- HCP Consul does not support multi-port services or the v2 catalog API in this release. You cannot [link a self-managed cluster to HCP Consul](/hcp/docs/consul/self-managed) to access its UI or view observability metrics when it uses the v2 catalog.
+- 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.
+- 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 does not support multi-port services in this release. You cannot [link a self-managed cluster to HCP Consul](/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

From 068703b836ad40a73e64ff34f2b2beac53a624b7 Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Tue, 31 Oct 2023 14:11:42 -0700
Subject: [PATCH 31/57] Proxyconfiguration code review changes

---
 .../k8s/multiport/reference/grpcroute.mdx     | 48 +++++++-------
 .../k8s/multiport/reference/httproute.mdx     | 16 ++---
 .../reference/proxyconfiguration.mdx          | 62 +++++++------------
 .../docs/k8s/multiport/reference/tcproute.mdx |  6 +-
 4 files changed, 58 insertions(+), 74 deletions(-)

diff --git a/website/content/docs/k8s/multiport/reference/grpcroute.mdx b/website/content/docs/k8s/multiport/reference/grpcroute.mdx
index c52e1a4027bc..bd6f730ade9b 100644
--- a/website/content/docs/k8s/multiport/reference/grpcroute.mdx
+++ b/website/content/docs/k8s/multiport/reference/grpcroute.mdx
@@ -1,14 +1,14 @@
 ---
 layout: docs
 page_title: GRPCRoute resource configuration reference
-description: The GRPCRoute resource CRD configures L7 GRPC traffic behavior within the service mesh. GRPCRoute is a GAMMA resource that requires the v2 catalog API. Learn how to configure the GRPCRoute CRD with specifications and example configurations.
+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 page provides reference information for the gRPC route resource, which defines L7 gRPC traffic within the service mesh.
 
-This custom resource definition (CRD) describes a GAMMA resource that requires the [v2 catalog API](/consul/docs/architecture/catalog/v2). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog/v1). For more information about GAMMA resources, refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/gamma/).
+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/catalog/v2). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog/v1). For more information about GAMMA resources, refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/gamma/).
 
 ## Configuration model
 
@@ -20,10 +20,10 @@ The following list outlines field hierarchy, language-specific data types, and r
 
 - [`apiVersion`](#apiversion): string | required | must be set to `mesh.consul.hashicorp.com/v2beta1`
 - [`kind`](#kind): string | required | must be set to `GRPCRoute`
-- [`metadata`](#metadata): object | required
+- [`metadata`](#metadata): map | required
   - [`name`](#metadata-name): string | required
   - [`namespace`](#metadata-namespace): string | optional 
-- [`spec`](#spec): object | required
+- [`spec`](#spec): map | required
   - [`parentRefs`](#spec-parentrefs): map | required
     - [`port`](#spec-parentrefs-port): string
     - [`ref`](#spec-parentrefs-ref):  string | required
@@ -64,7 +64,7 @@ The following list outlines field hierarchy, language-specific data types, and r
           - [`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): integer | `1`
+      - [`weight`](#spec-rules-backendrefs-weight): number | `1`
     - [`filters`](#spec-rules-filters): map
       - [`requestHeaderModifier`](#spec-rules-filters-requestheadermodifier): map
         - [`add`](#spec-rules-filters-requestheadermodifier): map
@@ -87,24 +87,24 @@ The following list outlines field hierarchy, language-specific data types, and r
         - [`type`](#spec-rules-matches-method-type): string
     - [`retries`](#spec-rules-retries): map
       - [`number`](#spec-rules-retries-number): map
-        - [`value`](#spec-rules-retries-number): integer
+        - [`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
+      - [`onStatusCodes`](#spec-rules-retries-onconditions): map of numbers
     - [`timeouts`](#spec-rules-timeouts): map
       - [`idle`](#spec-rules-timeouts-idle): map
-        - [`nanos`](#spec-rules-timeouts-idle): integer
-        - [`seconds`](#spec-rules-timeouts-idle): integer
+        - [`nanos`](#spec-rules-timeouts-idle): number
+        - [`seconds`](#spec-rules-timeouts-idle): number
       - [`request`](#spec-rules-timeouts-request): map
-        - [`nanos`](#spec-rules-timeouts-request): integer
-        - [`seconds`](#spec-rules-timeouts-request): integer
+        - [`nanos`](#spec-rules-timeouts-request): numberer
+        - [`seconds`](#spec-rules-timeouts-request): number
 
 
 
 
 ## Complete configuration
 
-When every field is defined, a GRPCRoute resource CRD has the following form:
+When every field is defined, a gRPC route resource CRD has the following form:
 
 
 
@@ -118,7 +118,7 @@ metadata:
   namespace: 
 spec:
   parentRefs:
-    port: ""
+    port: 
     - ref:
       name: 
       section: 
@@ -149,24 +149,24 @@ spec:
       filters:
         - requestHeaderModifier:
           add:
-            name: ""
-            value: ""
+            name: 
+            value: 
         - responseHeaderModifier:
           set:
-            name: ""
-            value: ""
+            name: 
+            value: 
         urlRewrite:
           pathPrefix: 
       weight: 1
     filters:
       requestHeaderModifier:
           remove:
-            name: ""
-            value: ""
+            name: 
+            value: 
       responseHeaderModifier:      
           add:
-            name: ""
-            value: ""              
+            name: 
+            value: 
       urlRewrite:
         pathPrefix: 
     matches:
@@ -452,7 +452,7 @@ Specifies filtering behavior for services configured in the same [`spec.rules.ba
 
 ### `spec.rules.backendRefs.filters.requestHeaderModifier`
 
-Specifies a set of header modification rules applied to requests routed with the GRPCRoute resource.
+Specifies a set of header modification rules applied to requests routed with the gRPC route resource.
 
 #### Values
 
@@ -472,7 +472,7 @@ The following table describes how to configure values for request headers:
 
 ### `spec.rules.backendRefs.filters.responseHeaderModifier`
 
-Specifies a set of header modification rules applied to responses routed with the GRPCRoute resource.
+Specifies a set of header modification rules applied to responses routed with the gRPC route resource.
 
 #### Values
 
diff --git a/website/content/docs/k8s/multiport/reference/httproute.mdx b/website/content/docs/k8s/multiport/reference/httproute.mdx
index 3673fce2381b..b7c75c7714b2 100644
--- a/website/content/docs/k8s/multiport/reference/httproute.mdx
+++ b/website/content/docs/k8s/multiport/reference/httproute.mdx
@@ -20,10 +20,10 @@ The following list outlines field hierarchy, language-specific data types, and r
 
 - [`apiVersion`](#apiversion): string | required | must be set to `mesh.consul.hashicorp.com/v2beta1`
 - [`kind`](#kind): string | required | must be set to `HTTPRoute`
-- [`metadata`](#metadata): object | required
+- [`metadata`](#metadata): map  | required
   - [`name`](#metadata-name): string | required
   - [`namespace`](#metadata-namespace): string | optional 
-- [`spec`](#spec): object | required
+- [`spec`](#spec): map | required
   - [`parentRefs`](#spec-parentrefs): map | required
     - [`port`](#spec-parentrefs-port): string
     - [`ref`](#spec-parentrefs-ref):  string | required
@@ -64,7 +64,7 @@ The following list outlines field hierarchy, language-specific data types, and r
           - [`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): integer | `1`
+      - [`weight`](#spec-rules-backendrefs-weight): number | `1`
     - [`filters`](#spec-rules-filters): map
       - [`requestHeaderModifier`](#spec-rules-filters-requestheadermodifier): map
         - [`add`](#spec-rules-filters-requestheadermodifier): map
@@ -91,17 +91,17 @@ The following list outlines field hierarchy, language-specific data types, and r
         - [`value`](#spec-rules-matches-queryparams-value): string
     - [`retries`](#spec-rules-retries): map
       - [`number`](#spec-rules-retries-number): map
-        - [`value`](#spec-rules-retries-number): integer
+        - [`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): map
-        - [`nanos`](#spec-rules-timeouts-idle): integer
-        - [`seconds`](#spec-rules-timeouts-idle): integer
+        - [`nanos`](#spec-rules-timeouts-idle): number
+        - [`seconds`](#spec-rules-timeouts-idle): number
       - [`request`](#spec-rules-timeouts-request): map
-        - [`nanos`](#spec-rules-timeouts-request): integer
-        - [`seconds`](#spec-rules-timeouts-request): integer
+        - [`nanos`](#spec-rules-timeouts-request): number
+        - [`seconds`](#spec-rules-timeouts-request): number
 
 
 
diff --git a/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx b/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx
index 38126d49a4cf..6ca2493c18c7 100644
--- a/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx
+++ b/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx
@@ -6,7 +6,7 @@ description: The ProxyConfiguration resource CRD configures sidecar proxy behavi
 
 # 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 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 GAMMA resource that requires the [v2 catalog API](/consul/docs/architecture/catalog/v2). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog/v1). For more information about GAMMA resources, refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/gamma/).
 
@@ -14,16 +14,12 @@ This custom resource definition (CRD) describes a GAMMA resource that requires t
 
 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): object | required
+- [`metadata`](#metadata): map | required
   - [`name`](#metadata-name): string | required
   - [`namespace`](#metadata-namespace): string | optional 
-- [`spec`](#spec): object | required
+- [`spec`](#spec): map | required
   - [`workloads`](#spec-workloads): map
     - [`filter`](#spec-workloads): string
     - [`names`](#spec-workloads): array of strings
@@ -76,19 +72,10 @@ The following list outlines field hierarchy, language-specific data types, and r
       - [`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
@@ -150,11 +137,6 @@ spec:
       outboundListenerPort: 15001
 ```
 
-
-
-
-
-
 ## Specification
 
 This section provides details about the fields you can configure in the ProxyConfiguration custom resource definition (CRD).
@@ -200,7 +182,7 @@ Specifies a name for the CRD. The name is metadata that you can use to reference
 
 ### `metadata.namespace` 
 
-Specifies the namespace that the service resolver applies to. Refer to [namespaces](/consul/docs/enterprise/namespaces) for more information.
+Specifies the namespace that the proxy configuration applies to. Refer to [namespaces](/consul/docs/enterprise/namespaces) for more information.
 
 #### Values
 
@@ -246,7 +228,7 @@ Specifies initial bootstrap settings for the Envoy proxy, as well as proxy confi
 
 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. Currently, TCP is not supported.
+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.
 
@@ -259,9 +241,11 @@ For more information about configuring a UNIX domain socket with DogStatsD, refe
 
 ### `spec.bootstrapConfig.overrideJsonTpl`
 
-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 bootstrap via [`consul connect envoy` command](/consul/commands/connect/envoy). The variables that are available to be interpolated are [documented in `bootstrap_tpl.go`](https://github.com/hashicorp/consul/blob/71d45a34601423abdfc0a64d44c6a55cf88fa2fc/command/connect/envoy/bootstrap_tpl.go#L5).
-
+
 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.
+
+
+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.
 
@@ -281,9 +265,9 @@ Specifies that the proxy should expose a Prometheus metrics endpoint to the _pub
 
 ### `spec.bootstrapConfig.readyBindAddr`
 
- Specifies the location to confiugure the proxy's readiness probe, specified as `ip:port`. 
- 
- By default the proxy does not have a readiness probe configured on it.
+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
 
@@ -292,7 +276,7 @@ Specifies that the proxy should expose a Prometheus metrics endpoint to the _pub
 
 ### `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 config.
+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.
 
@@ -371,7 +355,7 @@ Specifies one or more static tags to add to all metrics produced by the proxy.
 
 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. Currently, TCP is not supported.
+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.
 
@@ -496,7 +480,7 @@ Refer to [expose paths configuration reference](/consul/docs/connect/proxies/pro
 
 ### `spec.dynamicConfig.exposeConfig.exposePaths`
 
-Specifies a configuration for exposing a HTTP path through the proxy.
+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.
 
@@ -569,7 +553,7 @@ Specifies the strategy for balancing inbound connections across Envoy worker thr
 
 ### `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`.
+Specifies the maximum number of concurrent inbound connections to the local application instance. If not specified, inherits the Envoy default of `1024`.
 
 #### Values
 
@@ -587,7 +571,7 @@ Specifies a tracing configuration to be inserted in the proxy's public and upstr
 
 ### `spec.dynamicConfig.localClusterJson`
 
-Specifies a complete Envoy cluster to be delivered in place of the local application cluster. This field enables customization of timeouts, rate limits, and load balancing strategy.
+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.
 
@@ -623,7 +607,7 @@ Specifies the length of time the proxy is allowed to attempt connections to the
 
 ### `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.
+Specifies the length of time the proxy is allowed to attempt HTTP requests to the local application instance. Applies to HTTP-based protocols only.
 
 #### Values
 
@@ -637,7 +621,7 @@ Specifies the length of time the proxy is allowed to attempt HTTP requests to th
 
 ### `spec.dynamicConfig.meshGatewayMode`
 
-Specifies the mode of operation for how upstreams with a remote destination datacenter are resolved. Refer to [Mesh gateway configuration reference](/consul/docs/connect/proxies/proxy-config-reference#mesh-gateway-configuration-reference) for more information.
+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
 
@@ -651,7 +635,7 @@ Specifies the mode of operation for how upstreams with a remote destination data
 
 ### `spec.dynamicConfig.mode`
 
-Specifies the mode the proxy operates in: default, transparent, or direct. Refer to [proxy modes](/consul/docs/connect/proxies/proxy-config-reference#proxy-modes) for more information.
+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
 
@@ -664,7 +648,7 @@ Specifies the mode the proxy operates in: default, transparent, or direct. Refer
 
 ### `spec.dynamicConfig.publicListenerJson`
 
-Specifies a complete Envoy listener to be delivered in place of the main public listener that the proxy used to accept inbound connections. Refer to [escape-hatch overrides](/consul/docs/connect/proxies/envoy#escape-hatch-overrides) for more information
+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
 
@@ -673,7 +657,7 @@ Specifies a complete Envoy listener to be delivered in place of the main public
 
 ### `spec.dynamicConfig.transparentProxy`
 
-Specifies additional configurations for the transparent proxy. Refer to [transparent proxy configuration reference](/consul/docs/connect/proxies/proxy-config-reference#transparent-proxy-configuration-reference) for more information.
+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
 
@@ -682,7 +666,7 @@ Specifies additional configurations for the transparent proxy. Refer to [transpa
 
 ### `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.
+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
 
diff --git a/website/content/docs/k8s/multiport/reference/tcproute.mdx b/website/content/docs/k8s/multiport/reference/tcproute.mdx
index d0761f98869e..4201f8b92fa0 100644
--- a/website/content/docs/k8s/multiport/reference/tcproute.mdx
+++ b/website/content/docs/k8s/multiport/reference/tcproute.mdx
@@ -20,10 +20,10 @@ The following list outlines field hierarchy, language-specific data types, and r
 
 - [`apiVersion`](#apiversion): string | required | must be set to `mesh.consul.hashicorp.com/v2beta1`
 - [`kind`](#kind): string | required | must be set to `TCPRoute`
-- [`metadata`](#metadata): object | required
+- [`metadata`](#metadata): map  | required
   - [`name`](#metadata-name): string | required
   - [`namespace`](#metadata-namespace): string | optional 
-- [`spec`](#spec): object | required
+- [`spec`](#spec): map | required
   - [`parentRefs`](#spec-parentrefs): map | required
     - [`port`](#spec-parentrefs-port): string
     - [`ref`](#spec-parentrefs-ref):  string | required
@@ -53,7 +53,7 @@ The following list outlines field hierarchy, language-specific data types, and r
             - [`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): integer
+      - [`weight`](#spec-rules-backendrefs-weight): number
 
 
 

From bd268acd2afca37b0e44c58c7e05f93986c7d55f Mon Sep 17 00:00:00 2001
From: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
Date: Tue, 31 Oct 2023 14:18:03 -0700
Subject: [PATCH 32/57] Apply suggestions from code review

Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
---
 .../reference/trafficpermissions.mdx          | 23 +++++++++----------
 1 file changed, 11 insertions(+), 12 deletions(-)

diff --git a/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx b/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
index b9221195c02e..e2a088a4ba57 100644
--- a/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
+++ b/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
@@ -6,7 +6,7 @@ description: The TrafficPermissions CRD defines rules for allowing and denying t
 
 # 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/catalog/v2#changes-to-consul-s-existing-architecture) for more information.
+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/catalog/v2#changes-to-consul-s-existing-architecture) for more information.
 
 This custom resource definition (CRD) describes a GAMMA resource that requires the [v2 catalog API](/consul/docs/architecture/catalog/v2). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog/v1). For more information about GAMMA resources, refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/gamma/).
 
@@ -20,21 +20,21 @@ The following list outlines field hierarchy, language-specific data types, and r
 
 - [`apiVersion`](#apiversion): string | required | must be set to `auth.consul.hashicorp.com/v2beta1`
 - [`kind`](#kind): string | required | must be set to `TrafficPermissions`
-- [`metadata`](#metadata): object | required
+- [`metadata`](#metadata): map | required
   - [`name`](#metadata-name): string | required
   - [`namespace`](#metadata-namespace): string | optional 
-- [`spec`](#spec): object | required
-  - [`destination`](#spec-destination):
-    - [`identityName`](#spec-destination-identityname):
+- [`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):
+    - [`sources`](#spec-permissions-sources): map
       - [`identityName`](#spec-permissions-sources-identityname): string
       - [`namespace`](#spec-permissions-sources-namespace): string
       - [`partition`](#spec-permissions-sources-partition): string
       - [`peer`](#spec-permissions-sources-peer): string
       - [`samenessGroup`](#spec-permissions-sources-samenessgroup): string
-      - [`exclude`](#spec-permissions-sources-exclude): Map
+      - [`exclude`](#spec-permissions-sources-exclude): map
         - [`identityName`](#spec-permissions-sources-exclude): string
         - [`namespace`](#spec-permissions-sources-exclude): string
         - [`partition`](#spec-permissions-sources-exclude): string
@@ -74,9 +74,8 @@ The following list outlines field hierarchy, language-specific data types, and r
 
 ## Complete configuration
 
-The complete configuration provides the same basic information as the configuration model, including field hierarchy and data types. Instead of linking to specifications, it provides a code block that you can copy and paste into your preferred coding environment.
 
-When every field is defined, a TrafficPermissions CRD has the following form:
+When every field is defined, a `TrafficPermissions` CRD has the following form:
 
 
 
@@ -138,7 +137,7 @@ spec:
 
 ## Specification
 
-This section provides details about the fields you can configure in the TrafficPermissions custom resource definition (CRD).
+This section provides details about the fields you can configure in the `TrafficPermissions` custom resource definition (CRD).
 
 ### `apiVersion`
 
@@ -209,7 +208,7 @@ Specifies the proxies of the services where these traffic permissions apply.
 
 ### `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.
+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
 
@@ -222,7 +221,7 @@ Specifies whether the proxy should _allow traffic_ or _deny traffic_ between the
 
 By default, Consul allows traffic between all services.
 
-The "Action unknown" value that this resource accepts is reserved for compatibility with future configurations. Do not invoke this value in the current release.
+The `ACTION_UNKNOWN` value is a reserved value that enables compatibility with future configurations. Do not specify this value in the current release.
 
 #### Values
 

From 89addfa93ea587402272eac8c7c34ffffc9f61ef Mon Sep 17 00:00:00 2001
From: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
Date: Tue, 31 Oct 2023 14:30:21 -0700
Subject: [PATCH 33/57] Apply suggestions from code review

Co-authored-by: Nitya Dhanushkodi 
Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
---
 .../k8s/multiport/reference/grpcroute.mdx     | 35 ++++++++++---------
 1 file changed, 19 insertions(+), 16 deletions(-)

diff --git a/website/content/docs/k8s/multiport/reference/grpcroute.mdx b/website/content/docs/k8s/multiport/reference/grpcroute.mdx
index bd6f730ade9b..52e5da3d01cf 100644
--- a/website/content/docs/k8s/multiport/reference/grpcroute.mdx
+++ b/website/content/docs/k8s/multiport/reference/grpcroute.mdx
@@ -252,7 +252,7 @@ Specifies the namespace that the service resolver applies to. Refer to [namespac
 
 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 must align with GAMMAs resource. Refer to [GRPCRoute in the Kubernetes documentation](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1alpha2.GRPCRoute).
+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
 
@@ -262,7 +262,7 @@ When using this CRD, the `spec` field must align with GAMMAs resource. Refer to
 
 ### `spec.parentRefs`
 
-Specifies the resources to attach the route to. Usually these are services. You cannot reference the same `parentsRefs` multiple times. Instead, specify each [`spec.parentRefs.ref`](#spec-parentrefs-ref) in the same block.
+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
 
@@ -281,7 +281,7 @@ Specifies the name of the Consul service's port that the configuration applies t
 
 ### `spec.parentRefs.ref`
 
-Specifies the resource that the configuration applies to.
+Specifies the resource that the route attaches to.
 
 #### Values
 
@@ -333,12 +333,12 @@ Specifies the type of resource that the configuration applies to. To reference a
   | 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 Kubenretes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String (in code, should be int based on desc.)   | None     |
+  | `groupVersion` | Specifies a groupVersion for the resource type within the Kubenretes 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.
+Specifies rules for sidecar proxies to direct a service's gRPC traffic within the service mesh, including filtering, retry, and timeout behavior.
 
 #### Values
 
@@ -351,7 +351,7 @@ Specifies the Kubernetes Service backend to direct GRPC traffic to when a reques
 
 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 is invalid, the relative weights are maintained and traffic is not redirected automatically. 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.
+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
 
@@ -469,7 +469,9 @@ The following table describes how to configure values for request headers:
 | `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%` in your configuration entry 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.
@@ -507,9 +509,9 @@ Specifies a path to modify the URL with when a request is forwarded.
 
 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, 100% of traffic is forwarded. 
+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, it assumes the default value `1`.
+When this parameter is not specified, Consul defaults to `1`.
 
 #### Values
 
@@ -580,7 +582,7 @@ Specifies a path to modify the URL with when a request matching [`spec.parentRef
 
 ### `spec.rules.matches`
 
-Specifies rules for matching services described in [`spec.parentRefs`](#spec-parent-refs) according to the request header or method.
+Specifies rules for matching traffic to services described in [`spec.parentRefs`](#spec-parent-refs) according to the request header or method.
 
 #### Values
 
@@ -780,7 +782,7 @@ spec:
           groupVersion: v2beta1
           kind: Service
         name: api
-      # Note that right now, we must target the workload port,
+      # The configuration targets the workload port,
       # not the service port. 
       port: "api-workload"
   rules:
@@ -792,7 +794,7 @@ spec:
               groupVersion: v2beta1
               kind: Service
             name: api
-          # Note that right now, we must target the workload port,
+          # The configuration targets the workload port,
           # not the service port.
           port: "api-workload"
         weight: 50
@@ -803,7 +805,7 @@ spec:
               groupVersion: v2beta1
               kind: Service
             name: api
-          # Note that right now, we must target the workload port,
+          # The configuration targets the workload port,
           # not the service port. 
           port: "admin-workload"
         weight: 50
@@ -811,11 +813,12 @@ spec:
 
 ### Route traffic by matching header
 
-The following examples 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:
+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:
 
 - Traffic with a header that contains a `x-debug` value of exactly `1` has their response and request headers modified and is routed to the service with the `api` workload identity.
 - Traffic with a header that contains a `x-debug` value of exactly `2` has their response and request headers modified and is routed to the service with the `api-admin` workload identity.
 
+This example also includes how to include filters that modify request or response headers.
 ```yaml
 apiVersion: mesh.consul.hashicorp.com/v2beta1
 kind: GRPCRoute
@@ -830,7 +833,7 @@ spec:
           groupVersion: v2beta1
           kind: Service
         name: api
-      # Note that right now, we must target the workload port,
+      # The configuration targets the workload port,
       # not the service port.
       port: "api-workload"
   rules:
@@ -856,7 +859,7 @@ spec:
               groupVersion: v2beta1
               kind: Service
             name: api
-          # Note that right now, we must target the workload port,
+          # The configuration targets the workload port,
           # not the service port.
           port: "api-workload"
     - matches:
@@ -881,7 +884,7 @@ spec:
               groupVersion: v2beta1
               kind: Service
             name: api-admin
-          # Note that right now, we must target the workload port,
+          # The configuration targets the workload port,
           # not the service port.
           port: "admin-workload"
 ```
\ No newline at end of file

From 7d438a3d5271caa87f3577711bb969666f52bee4 Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Tue, 31 Oct 2023 16:01:20 -0700
Subject: [PATCH 34/57] Cross-apply suggestions to reference pages

---
 .../k8s/multiport/reference/grpcroute.mdx     |  65 +++++------
 .../k8s/multiport/reference/httproute.mdx     | 106 +++++++++---------
 .../docs/k8s/multiport/reference/tcproute.mdx |  48 ++++----
 .../reference/trafficpermissions.mdx          |  76 +++++--------
 4 files changed, 128 insertions(+), 167 deletions(-)

diff --git a/website/content/docs/k8s/multiport/reference/grpcroute.mdx b/website/content/docs/k8s/multiport/reference/grpcroute.mdx
index 52e5da3d01cf..752c2878d9d3 100644
--- a/website/content/docs/k8s/multiport/reference/grpcroute.mdx
+++ b/website/content/docs/k8s/multiport/reference/grpcroute.mdx
@@ -6,17 +6,13 @@ description: The GRPCRoute resource CRD configures L7 gRPC traffic behavior with
 
 # GRPCRoute resource configuration reference
 
-This page provides reference information for the gRPC route resource, which defines L7 gRPC traffic within the service mesh.
+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/catalog/v2). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog/v1). 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 GRPCRoute CRD. Click on a property name to view additional details, including default values.
-
-
-
-
+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`
@@ -99,17 +95,10 @@ The following list outlines field hierarchy, language-specific data types, and r
         - [`nanos`](#spec-rules-timeouts-request): numberer
         - [`seconds`](#spec-rules-timeouts-request): number
 
-
-
-
 ## 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
@@ -193,12 +182,9 @@ spec:
         seconds: 1
 ```
 
-
-
-
 ## Specification
 
-This section provides details about the fields you can configure in the GRPCRoute custom resource definition (CRD).
+This section provides details about the fields you can configure in the `GRPCRoute` custom resource definition (CRD).
 
 ### `apiVersion`
 
@@ -262,7 +248,7 @@ When using this CRD, the `spec` field closely resembles the `GRPCRoute` GAMMA re
 
 ### `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. 
+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
 
@@ -272,7 +258,7 @@ Specifies the services and other resources to attach the route to. You can only
 
 ### `spec.parentRefs.port`
 
-Specifies the name of the Consul service's port that the configuration applies to.
+Specifies the name of the port that the configuration applies to.
 
 #### Values
 
@@ -438,7 +424,7 @@ Specifies the type of resource that the configuration routes traffic to. To refe
 
   | 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 Kubenretes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String (in code, should be int based on desc.)   | None     |
+  | `groupVersion` | Specifies a groupVersion for the resource type within the Kubenretes 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`
@@ -469,9 +455,11 @@ The following table describes how to configure values for request headers:
 | `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%` in your configuration entry allows you to pass a value that is generated when the split occurs.
+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.
@@ -492,6 +480,10 @@ The following table describes how to configure values for request headers:
 | `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.
@@ -547,6 +539,10 @@ The following table describes how to configure values for request headers:
 | `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).
@@ -567,6 +563,10 @@ The following table describes how to configure values for request headers:
 | `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.
@@ -782,8 +782,7 @@ spec:
           groupVersion: v2beta1
           kind: Service
         name: api
-      # The configuration targets the workload port,
-      # not the service port. 
+      # The configuration targets the workload port, not the service port.
       port: "api-workload"
   rules:
     - backendRefs:
@@ -794,8 +793,7 @@ spec:
               groupVersion: v2beta1
               kind: Service
             name: api
-          # The configuration targets the workload port,
-          # not the service port.
+          # The configuration targets the workload port, not the service port.
           port: "api-workload"
         weight: 50
       - backendRef:
@@ -805,8 +803,7 @@ spec:
               groupVersion: v2beta1
               kind: Service
             name: api
-          # The configuration targets the workload port,
-          # not the service port. 
+          # The configuration targets the workload port, not the service port.
           port: "admin-workload"
         weight: 50
 ```
@@ -815,10 +812,11 @@ spec:
 
 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:
 
-- Traffic with a header that contains a `x-debug` value of exactly `1` has their response and request headers modified and is routed to the service with the `api` workload identity.
-- Traffic with a header that contains a `x-debug` value of exactly `2` has their response and request headers modified and is routed to the service with the `api-admin` workload identity.
+- 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
@@ -833,8 +831,7 @@ spec:
           groupVersion: v2beta1
           kind: Service
         name: api
-      # The configuration targets the workload port,
-      # not the service port.
+      # The configuration targets the workload port, not the service port.
       port: "api-workload"
   rules:
     - matches:
@@ -859,8 +856,7 @@ spec:
               groupVersion: v2beta1
               kind: Service
             name: api
-          # The configuration targets the workload port,
-          # not the service port.
+          # The configuration targets the workload port, not the service port.
           port: "api-workload"
     - matches:
       - headers:
@@ -884,7 +880,6 @@ spec:
               groupVersion: v2beta1
               kind: Service
             name: api-admin
-          # The configuration targets the workload port,
-          # not the service port.
+          # The configuration targets the workload port, not the service port.
           port: "admin-workload"
 ```
\ No newline at end of file
diff --git a/website/content/docs/k8s/multiport/reference/httproute.mdx b/website/content/docs/k8s/multiport/reference/httproute.mdx
index b7c75c7714b2..b7bfc8f0f48c 100644
--- a/website/content/docs/k8s/multiport/reference/httproute.mdx
+++ b/website/content/docs/k8s/multiport/reference/httproute.mdx
@@ -6,17 +6,13 @@ description: The HTTPRoute resource CRD configures L7 HTTP traffic behavior with
 
 # 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 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 GAMMA resource that requires the [v2 catalog API](/consul/docs/architecture/catalog/v2). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog/v1). For more information about GAMMA resources, refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/gamma/).
+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/catalog/v2). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog/v1). 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 HTTPRoute CRD. Click on a property name to view additional details, including default values.
-
-
-
-
+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`
@@ -103,16 +99,9 @@ The following list outlines field hierarchy, language-specific data types, and r
         - [`nanos`](#spec-rules-timeouts-request): number
         - [`seconds`](#spec-rules-timeouts-request): number
 
-
-
-
 ## Complete configuration
 
-When every field is defined, an HTTPRoute CRD has the following form:
-
-
-
-
+When every field is defined, an HTTP route CRD has the following form:
 
 ```yaml
 apiVersion: mesh.consul.hashicorp.com/v2beta1        # required 
@@ -122,7 +111,7 @@ metadata:
   namespace: 
 spec:
   parentRefs:
-    port: ""
+    port: 
     - ref:
       name: 
       section: 
@@ -138,7 +127,7 @@ spec:
     - backendRefs:
       - backendRef:
         datacenter: 
-        port: ""
+        port: 
         ref:
           name: 
           section: 
@@ -153,24 +142,24 @@ spec:
       filters:
         - requestHeaderModifier:
           add:
-            name: ""
-            value: ""
+            name: 
+            value: 
         - responseHeaderModifier:
           set:
-            name: ""
-            value: ""
+            name: 
+            value: 
         urlRewrite:
           pathPrefix: 
       weight: 1
     filters:
       requestHeaderModifier:
           remove:
-            name: ""
-            value: ""
+            name: 
+            value: 
       responseHeaderModifier:      
           add:
-            name: ""
-            value: ""              
+            name: 
+            value:          
       urlRewrite:
         pathPrefix: 
     matches:
@@ -201,12 +190,9 @@ spec:
         seconds: 1
 ```
 
-
-
-
 ## Specification
 
-This section provides details about the fields you can configure in the HTTPRoute custom resource definition (CRD).
+This section provides details about the fields you can configure in the `HTTPRoute` custom resource definition (CRD).
 
 ### `apiVersion`
 
@@ -260,7 +246,7 @@ Specifies the namespace that the service resolver applies to. Refer to [namespac
 
 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 must align with GAMMAs resource. Refer to [HTTPRoute in the Kubernetes documentation](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRoute).
+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
 
@@ -270,7 +256,7 @@ When using this CRD, the `spec` field must align with GAMMAs resource. Refer to
 
 ### `spec.parentRefs`
 
-Specifies the resources to attach the route to. Usually these are services. You cannot reference the same `parentsRefs` multiple times. Instead, specify each [`spec.parentRefs.ref`](#spec-parentrefs-ref) in the same block.
+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
 
@@ -280,7 +266,7 @@ Specifies the resources to attach the route to. Usually these are services. You
 
 ### `spec.parentRefs.port`
 
-Specifies the name of the Consul service's port that the configuration applies to.
+Specifies the name of the port that the configuration applies to.
 
 #### Values
 
@@ -289,7 +275,7 @@ Specifies the name of the Consul service's port that the configuration applies t
 
 ### `spec.parentRefs.ref`
 
-Specifies the resource that the configuration applies to.
+Specifies the resource that the route attaches to.
 
 #### Values
 
@@ -341,7 +327,7 @@ Specifies the type of resource that the configuration applies to. To reference a
   | 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 Kubenretes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String (in code, should be int based on desc.)   | None     |
+  | `groupVersion` | Specifies a groupVersion for the resource type within the Kubenretes 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`
@@ -359,7 +345,7 @@ Specifies the Kubernetes Service backend to direct HTTP traffic to when a reques
 
 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 is invalid, the relative weights are maintained and traffic is not redirected automatically. 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.
+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
 
@@ -446,7 +432,7 @@ Specifies the type of resource that the configuration routes traffic to. To refe
 
   | 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 Kubenretes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String (in code, should be int based on desc.)   | None     |
+  | `groupVersion` | Specifies a groupVersion for the resource type within the Kubenretes 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`
@@ -478,6 +464,10 @@ The following table describes how to configure values for request headers:
 | `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.
@@ -498,6 +488,10 @@ The following table describes how to configure values for request headers:
 | `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.
@@ -515,9 +509,9 @@ Specifies a path to modify the URL with when a request is forwarded.
 
 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, 100% of traffic is forwarded. 
+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, it assumes the default value `1`.
+When this parameter is not specified, Consul defaults to `1`.
 
 #### Values
 
@@ -553,6 +547,10 @@ The following table describes how to configure values for request headers:
 | `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).
@@ -573,6 +571,10 @@ The following table describes how to configure values for request headers:
 | `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.
@@ -588,7 +590,7 @@ Specifies a path to modify the URL with when a request matching [`spec.parentRef
 
 ### `spec.rules.matches`
 
-Specifies rules for matching services described in [`spec.parentRefs`](#spec-parent-refs) according to the request header or method.
+Specifies rules for matching traffic to services described in [`spec.parentRefs`](#spec-parent-refs) according to the request header or method.
 
 #### Values
 
@@ -814,7 +816,7 @@ Specifies the total amount of time spent processing the entire downstream reques
 
 ## Examples
 
-The following examples demonstrate common HTTPRoute CRD configuration patterns for specific use cases.
+The following examples demonstrate common HTTP route CRD configuration patterns for specific use cases.
 
 ### Split HTTP traffic between two ports
 
@@ -834,8 +836,7 @@ spec:
           groupVersion: v2beta1
           kind: Service
         name: api
-      # Note that right now, we must target the workload port,
-      # not the service port. 
+      # The configuration targets the workload port, not the service port.
       port: "api-workload"
   rules:
     - backendRefs:
@@ -846,8 +847,7 @@ spec:
               groupVersion: v2beta1
               kind: Service
             name: api
-          # Note that right now, we must target the workload port,
-          # not the service port. 
+          # The configuration targets the workload port, not the service port.
           port: "api-workload"
         weight: 50
       - backendRef:
@@ -857,8 +857,7 @@ spec:
               groupVersion: v2beta1
               kind: Service
             name: api
-          # Note that right now, we must target the workload port,
-          # not the service port.
+          # The configuration targets the workload port, not the service port.
           port: "admin-workload"
         weight: 50
 ```
@@ -867,8 +866,10 @@ spec:
 
 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:
 
-- Traffic with a header that contains a `x-debug` value of exactly `1` has their response and request headers modified and is routed to the service with the `api` workload identity.
-- Traffic with a header that contains a `x-debug` value of exactly `2` has their response and request headers modified and is routed to the service with the `api-admin` workload identity.
+- 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
@@ -884,8 +885,7 @@ spec:
           groupVersion: v2beta1
           kind: Service
         name: api
-      # Note that right now, we must target the workload port,
-      # not the service port. 
+      # The configuration targets the workload port, not the service port.
       port: "api-workload"
   rules:
     - matches:
@@ -910,8 +910,7 @@ spec:
               groupVersion: v2beta1
               kind: Service
             name: api
-          # Note that right now, we must target the workload port,
-          # not the service port.
+          # The configuration targets the workload port, not the service port.
           port: "api-workload"
     - matches:
       - headers:
@@ -935,7 +934,6 @@ spec:
               groupVersion: v2beta1
               kind: Service
             name: api-admin
-          # Note that right now, we must target the workload port,
-          # not the service port. 
+          # The configuration targets the workload port, not the service port.
           port: "admin-workload"
 ```
\ No newline at end of file
diff --git a/website/content/docs/k8s/multiport/reference/tcproute.mdx b/website/content/docs/k8s/multiport/reference/tcproute.mdx
index 4201f8b92fa0..6af82963a713 100644
--- a/website/content/docs/k8s/multiport/reference/tcproute.mdx
+++ b/website/content/docs/k8s/multiport/reference/tcproute.mdx
@@ -6,13 +6,13 @@ description: The TCPRoute resource CRD configures L4 TCP behavior within the ser
 
 # TCPRoute resource configuration reference
 
-This page provides reference information for the TCPRoute resource, which defines L7 TCP traffic within the service mesh.
+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 GAMMA resource that requires the [v2 catalog API](/consul/docs/architecture/catalog/v2). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog/v1). For more information about GAMMA resources, refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/gamma/).
+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/catalog/v2). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog/v1). 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 TCPRoute CRD. Click on a property name to view additional details, including default values.
+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.
 
 
 
@@ -60,11 +60,7 @@ The following list outlines field hierarchy, language-specific data types, and r
 
 ## Complete configuration
 
-When every field is defined, a TCPRoute CRD has the following form:
-
-
-
-
+When every field is defined, a TCP route CRD has the following form:
 
 ```yaml
 apiVersion: mesh.consul.hashicorp.com/v2beta1        # required 
@@ -74,7 +70,7 @@ metadata:
   namespace: 
 spec:
   parentRefs:
-    port: ""
+    port: 
     - ref:
       name: 
       section: 
@@ -90,7 +86,7 @@ spec:
     - backendRefs:
       - backendRef:
         datacenter: 
-        port: ""
+        port: 
         ref:
           name: 
           section: 
@@ -105,12 +101,9 @@ spec:
       weight: 1
 ```
 
-
-
-
 ## Specification
 
-This section provides details about the fields you can configure in the TCPRoute custom resource definition (CRD).
+This section provides details about the fields you can configure in the `TCPRoute` custom resource definition (CRD).
 
 ### `apiVersion`
 
@@ -164,7 +157,7 @@ Specifies the namespace that the service resolver applies to. Refer to [namespac
 
 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 must align with GAMMAs resource. Refer to [TCPRoute in the Kubernetes documentation](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1alpha2.TCPRoute).
+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
 
@@ -174,7 +167,7 @@ When using this CRD, the `spec` field must align with GAMMAs resource. Refer to
 
 ### `spec.parentRefs`
 
-Specifies the resources to attach the route to. Usually these are services. You cannot reference the same `parentsRefs` multiple times. Instead, specify each [`spec.parentRefs.ref`](#spec-parentrefs-ref) in the same block.
+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
 
@@ -184,7 +177,7 @@ Specifies the resources to attach the route to. Usually these are services. You
 
 ### `spec.parentRefs.port`
 
-Specifies the name of the Consul service's port that the configuration applies to.
+Specifies the name of the port that the configuration applies to.
 
 #### Values
 
@@ -193,7 +186,7 @@ Specifies the name of the Consul service's port that the configuration applies t
 
 ### `spec.parentRefs.ref`
 
-Specifies the resource that the configuration applies to.
+Specifies the resource that the route attaches to.
 
 #### Values
 
@@ -245,7 +238,7 @@ Specifies the type of resource that the configuration applies to. To reference a
   | 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 Kubenretes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String (in code, should be int based on desc.)   | None     |
+  | `groupVersion` | Specifies a groupVersion for the resource type within the Kubenretes 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`
@@ -263,7 +256,7 @@ Specifies the Kubernetes Service backend to direct TCP traffic to when a request
 
 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 with [`spec.rules.backendRefs.weight`](#spec-rules-backendrefs-weight) and one is invalid, the relative weights are maintained and traffic is not adjusted automatically. 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.
+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
 
@@ -350,16 +343,16 @@ Specifies the type of resource that the configuration routes traffic to. To refe
 
   | 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 Kubenretes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String (in code, should be int based on desc.)   | None     |
+  | `groupVersion` | Specifies a groupVersion for the resource type within the Kubenretes 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, 100% of traffic is forwarded. 
+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, it assumes the default value `1`.
+When this parameter is not specified, Consul defaults to `1`.
 
 #### Values
 
@@ -388,8 +381,7 @@ spec:
           groupVersion: v2beta1
           kind: Service
         name: api
-      # Note that right now, we must target the workload port,
-      # not the service port. 
+      # The configuration targets the workload port, not the service port.
       port: "api-workload"
   rules:
     - backendRefs:
@@ -400,8 +392,7 @@ spec:
               groupVersion: v2beta1
               kind: Service
             name: api
-          # Note that right now, we must target the workload port,
-          # not the service port. 
+          # The configuration targets the workload port, not the service port.
           port: "api-workload"
         weight: 50
       - backendRef:
@@ -411,8 +402,7 @@ spec:
               groupVersion: v2beta1
               kind: Service
             name: api
-          # Note that right now, we must target the workload port,
-          # not the service port. 
+          # The configuration targets the workload port, not the service port.
           port: "admin-workload"
         weight: 50
 ```
\ No newline at end of file
diff --git a/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx b/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
index e2a088a4ba57..ce2a46c3db1e 100644
--- a/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
+++ b/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
@@ -8,7 +8,7 @@ description: The TrafficPermissions CRD defines rules for allowing and denying t
 
 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/catalog/v2#changes-to-consul-s-existing-architecture) for more information.
 
-This custom resource definition (CRD) describes a GAMMA resource that requires the [v2 catalog API](/consul/docs/architecture/catalog/v2). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog/v1). For more information about GAMMA resources, refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/gamma/).
+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/catalog/v2). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog/v1). For more information about GAMMA resources, refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/gamma/).
 
 ## Configuration model
 
@@ -41,6 +41,7 @@ The following list outlines field hierarchy, language-specific data types, and r
         - [`peer`](#spec-permissions-sources-exclude): string
         - [`samenessGroup`](#spec-permissions-sources-exclude): string
     - [`destinationRules`](#spec-permissions-destinationrules):
+
       - [`portNames`](#spec-permissions-destinationrules-portNames): array of strings
+
 
 
 
 
 ## Complete configuration
 
-
 When every field is defined, a `TrafficPermissions` CRD has the following form:
 
-
-
-
-
 ```yaml
 apiVersion: auth.consul.hashicorp.com/v2beta1    # required
 kind: TrafficPermissions                         # required
@@ -93,48 +92,22 @@ spec:
   action: allow
   permissions:
     - sources:
-      identityName:  
-      namespace: 
-      partition:
-      peer:
-      samenessGroup:
+      identityName:  
+      namespace: 
+      partition: 
+      peer: 
+      samenessGroup: 
       exclude:
-        identityName:
-        namespace:
-        partition:
-        peer:
-        samenessGroup:
+        identityName: 
+        namespace: 
+        partition: 
+        peer: 
+        samenessGroup: 
     destinationRules:
-      - header:
-        exact:
-        invert:
-        name:
-        prefix:
-        present:
-        regex:
-        suffix:
-      methods: ["GET", "POST"]
-      pathExact: 
-      pathReges:
-      portNames: [""]
-      exclude:
-        - header:
-          exact:
-          invert:
-          name:
-          prefix:
-          present:
-          regex:
-          suffix:
-        methods:
-        pathExact:
-        pathPrefix:
-        pathRegex:
+      portNames: 
+        - 
 ```
 
-
-
-
 ## Specification
 
 This section provides details about the fields you can configure in the `TrafficPermissions` custom resource definition (CRD).
@@ -219,9 +192,10 @@ Specifies the Workload identity for a service. The permissions you configure in
 
 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).
 
-By default, Consul allows traffic between all services.
-
+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
 
@@ -230,7 +204,9 @@ The `ACTION_UNKNOWN` value is a reserved value that enables compatibility with f
 
   - `ACTION_ALLOW`
   - `ACTION_DENY`
+
 
 ### `spec.permissions`
 
@@ -318,7 +294,7 @@ When [`spec.action`](#spec-action) _denies traffic_, Consul denies authorization
 
 - Default: None
 - Data type: Map
-
+
 
 ### `spec.permissions.destinationRules.portNames`
 
@@ -396,7 +373,7 @@ Specifies a port name that the Kubernetes Service exposes at the destination.
 
 - Default: None
 - Data type: String
-
+
 
 ## Examples
 
-The following examples demonstrate common TrafficPermissions CRD configuration patterns for specific use cases.
+The following examples demonstrate common `TrafficPermissions`` CRD configuration patterns for specific use cases.
 
 ### Deny traffic between services
 

From 364b49cd1df08d17f65775259c89f17755bf2ef2 Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Tue, 31 Oct 2023 16:18:08 -0700
Subject: [PATCH 35/57] More code review suggestions

---
 .../reference/proxyconfiguration.mdx          | 66 +++++++++----------
 .../reference/trafficpermissions.mdx          | 12 ++--
 2 files changed, 36 insertions(+), 42 deletions(-)

diff --git a/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx b/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx
index 6ca2493c18c7..636c6528d46a 100644
--- a/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx
+++ b/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx
@@ -8,7 +8,7 @@ description: The ProxyConfiguration resource CRD configures sidecar proxy behavi
 
 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 GAMMA resource that requires the [v2 catalog API](/consul/docs/architecture/catalog/v2). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog/v1). For more information about GAMMA resources, refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/gamma/).
+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/catalog/v2). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog/v1). For more information about GAMMA resources, refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/gamma/).
 
 ## Configuration model
 
@@ -88,50 +88,46 @@ spec:
     names: ["api", "admin"]
     prefixes: ["
", ""]
   bootstrapConfig: 
-    dogstatsdUrl: 
-    overrideJsonTpl: 
-    prometheusBindAddr:
-    readyBindAddr: 
-    staticClustersJson:
-    staticListenersJson:
-    statsBindAddr:
-    statsConfigJson:
-    statsFlushInterval:
-    statsSinkJson:
+    dogstatsdUrl: 
+    overrideJsonTpl: 
+    prometheusBindAddr: <0.0.0.0>
+    readyBindAddr: 
+    staticClustersJson: 
+    staticListenersJson: 
+    statsBindAddr: <0.0.0.0>
+    statsConfigJson: 
+    statsFlushInterval: 5000ms
+    statsSinkJson: 
     statsTags:
-      - string
-    statsdUrl:
-    telemetryCollectorBindSocketDir:
-    tracingConfigJson:
+      - 
+    statsdUrl: 
+    telemetryCollectorBindSocketDir: 
+    tracingConfigJson: 
   dynamicConfig:
     accessLogs:
       enabled: false
       disableListenerLogs: false
-      jsonFormat: 
-      path: 
-      textFormat: 
-      type: 
+      jsonFormat: 
+      path: 
+      textFormat: 
+      type: 
     exposeConfig:
       exposePaths:
-        listenerPort: <42>
-        localPathPort: <4242>
+        listenerPort: 42
+        localPathPort: 4242
         path: 
         protocol: 
       inboundConnections:
-        balanceInboundConnections:
-        maxInboundConnections:
-    listenerTracingJson:
-    localClusterJson:
+        balanceInboundConnections: 
+        maxInboundConnections: 1024
+    listenerTracingJson: 
+    localClusterJson: 
     localConnection:
-      connectTimeout:
-        nanos: 
-        seconds: 
-      requestTimeout:
-        nanos:
-        seconds:
-    meshGatewayMode:
-    mode:
-    publicListenerJson:
+      connectTimeout: <1s>
+      requestTimeout: <1s>
+    meshGatewayMode: 
+    mode: 
+    publicListenerJson: 
     transparentProxy:
       dialedDirectly: false
       outboundListenerPort: 15001
@@ -139,7 +135,7 @@ spec:
 
 ## Specification
 
-This section provides details about the fields you can configure in the ProxyConfiguration custom resource definition (CRD).
+This section provides details about the fields you can configure in the `ProxyConfiguration` custom resource definition (CRD).
 
 ### `apiVersion`
 
diff --git a/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx b/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
index ce2a46c3db1e..e728cbacb9b8 100644
--- a/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
+++ b/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
@@ -6,13 +6,13 @@ description: The TrafficPermissions CRD defines rules for allowing and denying t
 
 # 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/catalog/v2#changes-to-consul-s-existing-architecture) for more information.
+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/catalog/v2#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/catalog/v2). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog/v1). 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 TrafficPermissions CRD. Click on a property name to view additional details, including default values.
+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.
 
 
 
@@ -41,6 +41,7 @@ The following list outlines field hierarchy, language-specific data types, and r
         - [`peer`](#spec-permissions-sources-exclude): string
         - [`samenessGroup`](#spec-permissions-sources-exclude): string
     - [`destinationRules`](#spec-permissions-destinationrules):
+      - [`portNames`](#spec-permissions-destinationrules-portNames): array of strings
 
-      - [`portNames`](#spec-permissions-destinationrules-portNames): array of strings
-
-
-
-
+{:/comment}
 
 ## Complete configuration
 
@@ -191,9 +184,9 @@ Specifies the Workload identity for a service. The permissions you configure in
 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).
 
 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.
-
+{:/comment}
 
 #### Values
 
@@ -202,9 +195,9 @@ The `ACTION_UNKNOWN` value is a reserved value that enables compatibility with f
 
   - `ACTION_ALLOW`
   - `ACTION_DENY`
-
+{:/comment}
 
 ### `spec.permissions`
 
@@ -292,7 +285,7 @@ When [`spec.action`](#spec-action) _denies traffic_, Consul denies authorization
 
 - Default: None
 - Data type: Map
-
+{:/comment}
 
 ### `spec.permissions.destinationRules.portNames`
 
@@ -371,7 +364,7 @@ Specifies a port name that the Kubernetes Service exposes at the destination.
 
 - Default: None
 - Data type: String
-
+{:/comment}
 
 ## Examples
 

From 28e487bcc1457fdc20d1351a1cdd169c46794ca2 Mon Sep 17 00:00:00 2001
From: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
Date: Wed, 1 Nov 2023 08:53:05 -0700
Subject: [PATCH 37/57] Apply suggestions from code review

---
 website/content/docs/architecture/catalog/v1.mdx | 2 +-
 website/content/docs/architecture/catalog/v2.mdx | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/website/content/docs/architecture/catalog/v1.mdx b/website/content/docs/architecture/catalog/v1.mdx
index d55ea1fcd840..f461ee119f58 100644
--- a/website/content/docs/architecture/catalog/v1.mdx
+++ b/website/content/docs/architecture/catalog/v1.mdx
@@ -25,7 +25,7 @@ When Consul registers a service instance using the v1 catalog API, it records th
 | ID | A unique identifier for a service instance. | Defined by user in [service definition](/consul/docs/services/configuration/services-configuration-reference#id). |
 | Node | The connection point where the service is available.  | On VMs, defined by user. 

 On Kubernetes, computed by Consul according to [Kubernetes Nodes](https://kubernetes.io/docs/concepts/architecture/nodes/). |
 | Address  | The registered address of the service instance. | Defined by user in [service definition](/consul/docs/services/configuration/services-configuration-reference#address). |
-| Tagged Addresses | User-defined labels for addresses. | Defined by user in [service definition](/consul/docs/services/configuration/services-configuration-reference#tags). |
+| Tagged Addresses | User-defined labels for addresses. | Defined by user in [service definition](/consul/docs/services/configuration/services-configuration-reference#tagged_addresses). |
 | NodeMeta | User-defined metadata about the node. | Defined by user |
 | Datacenter | The name of the datacenter the service is registered in. | Defined by user |
 | Service | The name of the service Consul registers the service instance under. | Defined by user |
diff --git a/website/content/docs/architecture/catalog/v2.mdx b/website/content/docs/architecture/catalog/v2.mdx
index c467c7b15990..3fa7b86dbf47 100644
--- a/website/content/docs/architecture/catalog/v2.mdx
+++ b/website/content/docs/architecture/catalog/v2.mdx
@@ -26,7 +26,7 @@ This information enables Consul to associate service names with the individual i
 
 The [Consul v1 catalog API](/consul/docs/architecture/catalog/v1) was designed prior to the introduction of Consul’s service mesh features. 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 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/), enabling functionality such as associating Kubernetes Pods with multiple Kubernetes Services and allowing Services and Pods registered with Consul to have multiple ports. For more information about how the differences between the catalog API impacts Consul operations, refer to [changes to Consul's existing architecture](#changes-to-consuls-existing-architecture).
+The v2 catalog API aligns more closely with the [Kubernetes Gateway API's GAMMA initiative](https://gateway-api.sigs.k8s.io/concepts/gamma/), enabling functionality such as associating Kubernetes Pods with multiple Kubernetes Services and allowing Services and Pods registered with Consul to have multiple ports. For more information about how the differences between the catalog API impacts 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.
 

From 376eeb052e6e2938e4e777e9a83b0f00022107ca Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Wed, 1 Nov 2023 11:16:14 -0700
Subject: [PATCH 38/57] Index + usage updates

---
 .../content/docs/k8s/multiport/configure.mdx  | 100 +++++++-----------
 website/content/docs/k8s/multiport/index.mdx  |  26 +++--
 .../k8s/multiport/reference/httproute.mdx     |  70 +++++++++++-
 .../multiport/reference/resource-command.mdx  |  15 ++-
 .../docs/k8s/multiport/traffic-split.mdx      |  92 ++++++++++++++++
 website/data/docs-nav-data.json               |   4 +
 6 files changed, 230 insertions(+), 77 deletions(-)
 create mode 100644 website/content/docs/k8s/multiport/traffic-split.mdx

diff --git a/website/content/docs/k8s/multiport/configure.mdx b/website/content/docs/k8s/multiport/configure.mdx
index 8beaf8339d1c..81d87b738a10 100644
--- a/website/content/docs/k8s/multiport/configure.mdx
+++ b/website/content/docs/k8s/multiport/configure.mdx
@@ -18,7 +18,7 @@ This page describes the process for integrating a service that uses multiple por
 
 Registering multi-port services with Consul requires Kubernetes. Multi-port services are not supported on VM deployments.
 
-The following software versions are required:
+The following minimum versions are required:
 
 - Consul v1.17.0
 - `consul-k8s` CLI v1.3.0+ or `hashicorp/consul` Helm chart release v1.3.0+
@@ -29,7 +29,7 @@ There are additional requirements for service mesh proxies in transparent proxy
 
 ## 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 minimal required configurations for the Consul installation:
+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:
 
 
 
@@ -37,10 +37,12 @@ To enable the v2 catalog and its support for multi-port services, set `global.ex
 global:
   enabled: true
   name: consul
-  image: hashicorp/consul:1.17.0-rc1
+  image: hashicorp/consul:1.17.0
   datacenter: dc1
   tls:
     enabled: true
+  acls:
+    manageSystemACLs: true
   experiments: ["resource-apis"]
 server:
   enabled: true
@@ -59,22 +61,28 @@ Then install Consul to your Kubernetes cluster using either the `consul-k8s` CLI
 
 
 
-For platforms other than Mac OSX amd64, refer to [Install a previous version](/consul/docs/k8s/installation/install-cli#install-a-previous-version) for instructions on how to install a specific version of the `consul-k8s` CLI prior to running `consul-k8s install`. 
+```shell-session
+$ consul-k8s install -config-file=values.yaml
+```
+
+To download a compatible version of `consul-k8s` and add it to your `PATH`, run the following commands instead:
 
 ```shell-session
-$ export VERSION=1.3.0-rc1 && \
+$ export VERSION=1.3.0 && \
     curl --location "https://releases.hashicorp.com/consul-k8s/${VERSION}/consul-k8s_${VERSION}_darwin_amd64.zip" --output consul-k8s-cli.zip
 $ unzip -o consul-k8s-cli.zip -d ~/consul-k8s
 $ export PATH=$PATH:$HOME/consul-k8s
 $ consul-k8s install -config-file=values.yaml
 ```
 
+For platforms other than Mac OSX amd64, refer to [Install a previous version](/consul/docs/k8s/installation/install-cli#install-a-previous-version). This page contains instructions on how to install a specific version of the `consul-k8s` CLI on Linux prior to running `consul-k8s install`.
+
 
 
 
 
 ```shell-session
-$ helm install consul hashicorp/consul --create-namespace --namespace consul --version 1.3.0-rc1 --values values.yaml
+$ helm install consul hashicorp/consul --create-namespace --namespace consul --version 1.3.0 --values values.yaml
 ```
 
 
@@ -289,23 +297,23 @@ $ kubectl apply -f api.yaml -f web.yaml
 
 ## Configure traffic permissions
 
-Consul uses traffic permissions to validate communication between services based on L4 identity. In the beta release of the v2 catalog API, traffic permissions allow all services by default. In order to verify that services function correctly on each port, create CRDs that deny traffic to each port.
+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.
 
-
+
 
-
+
 
 ```yaml
 apiVersion: auth.consul.hashicorp.com/v2beta1
 kind: TrafficPermissions
 metadata:
-  name: web-to-api-port-deny
+  name: web-to-api
 spec:
   destination:
     identityName: api
-  action: deny
+  action: allow
   permissions:
     - sources:
         - identityName: web
@@ -315,17 +323,17 @@ spec:
 
 
 
-
+
 
 ```yaml
 apiVersion: auth.consul.hashicorp.com/v2beta1
 kind: TrafficPermissions
 metadata:
-  name: web-to-admin-port-deny
+  name: web-to-admin
 spec:
   destination:
     identityName: api
-  action: deny
+  action: allow
   permissions:
     - sources:
         - identityName: web
@@ -353,9 +361,9 @@ Set environment variables to remember the pod name for the web workload for use
 $ export WEB_POD=web-6dcbd684bc-gk8n5
 ```
 
-### Validate both ports
+### Apply traffic permissions
 
-Use the `web` Pod's name to open a shell session and test the `api` service on port 80.
+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.
 
 
 
@@ -363,14 +371,12 @@ Use the `web` Pod's name to open a shell session and test the `api` service on p
 
 ```shell-session
 $ kubectl exec -it ${WEB_POD} -c web -- curl api:80
-hello world
 ```
 
 Then test the `api` service on port 90.
 
 ```shell-session
 $ kubectl exec -it ${WEB_POD} -c web -- curl api:90
-hello world from 9090 admin
 ```
 
 
@@ -379,25 +385,21 @@ hello world from 9090 admin
 
 ```shell-session
 $ kubectl exec -it ${WEB_POD} -c web -- curl api:80
-hello world
 ```
 
 Then test the `api-admin` service on port 90.
 
 ```shell-session
-$ kubectl exec -it ${WEB_POD} -c web --namespace consul -- curl api-admin:90
-hello world from 9090 admin
+$ kubectl exec -it ${WEB_POD} -c web -- curl api-admin:90
 ```
 
 
 
 
-### Validate port 80
-
-Apply the CRD to allow traffic to port 80 only:
+Apply the CRD to allow traffic to port 80:
 
 ```shell-session
-$ kubectl apply -f deny-90.yaml 
+$ kubectl apply -f allow-80.yaml 
 ```
 
 
@@ -410,13 +412,6 @@ Then, open a shell session in the `web` container and test the `api` service on
 $ kubectl exec -it ${WEB_POD} -c web -- curl api:80
 hello world
 ```
-
-Test the `api` service on port 90. This command should fail, indicating that the traffic permission is in effect.
-
-```shell-session
-$ kubectl exec -it ${WEB_POD} -c web -- curl api:90
-```
-
 
 
 
@@ -428,27 +423,13 @@ $ kubectl exec -it ${WEB_POD} -c web -- curl api:80
 hello world
 ```
 
-Test the `admin` service on port 90. This command should fail, indicating that the traffic permission is in effect.
-
-```shell-session
-$ kubectl exec -it ${WEB_POD} -c web -- curl api-admin:90
-```
-
 
 
 
-Before testing the other port, remove the `TrafficPermissions` CRD.
-
-```shell-session
-$ kubectl delete -f deny-90.yaml 
-```
-
-### Validate port 90
-
-Apply the CRD to allow traffic to port 90 only:
+Apply the CRD to allow traffic to port 90:
 
 ```shell-session
-$ kubectl apply -f deny-80.yaml 
+$ kubectl apply -f allow-90.yaml 
 ```
 
 
@@ -462,12 +443,6 @@ $ kubectl exec -it ${WEB_POD} -c web -- curl api:90
 hello world from 9090 admin
 ```
 
-Test the `api` service on port 80. This command should fail, indicating that the traffic permission is in effect.
-
-```shell-session
-$ kubectl exec -it ${WEB_POD} -c web -- curl api:80
-```
-
 
 
 
@@ -479,11 +454,16 @@ $ kubectl exec -it ${WEB_POD} -c web -- curl api-admin:90
 hello world from 9090 admin
 ```
 
-Test the `api` service on port 80. This command should fail, indicating that the traffic permission is in effect.
-
-```shell-session
-$ kubectl exec -it ${WEB_POD} -c web  -- curl api:80
-```
-
 
 
+
+## 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 match HTTP traffic with ports using query parameters.
+
+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)
\ No newline at end of file
diff --git a/website/content/docs/k8s/multiport/index.mdx b/website/content/docs/k8s/multiport/index.mdx
index 2524e7f8cd5c..ec8dd6354e7b 100644
--- a/website/content/docs/k8s/multiport/index.mdx
+++ b/website/content/docs/k8s/multiport/index.mdx
@@ -18,14 +18,21 @@ This topic describes the process to register a service with multiple ports on Ku
 
 To use a multi-port service in Consul on Kubernetes deployments, complete the following steps:
 
-1. Enable the v2 catalog. Add `global.experiments: ["resource-apis"]` and `ui.enabled: false` to a cluster's Helm chart before deploying Consul.
+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"` annotation so that Consul registers the service automatically when Kubernetes deploys containers.
-1. Configure traffic permissions. In the beta release, services registered to the v2 catalog allow all traffic by default. You can use the `TrafficPermissions` CRD to deny traffic to individual services for testing purposes.
-1. Validate multi-port functionality. Send test traffic to each port to confirm that traffic is authorized and routed correctly.
+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).
 
-[Link to/describe advanced routing configurations re: examples on configuration pages]
+### 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.
+1. Output the resource path with the `consul resource read` command.
+
+For an example configuration and instructions for each of the steps in this workflow, refer to [split service traffic between ports](/consul/docs/k8s/multiport/traffic-split).
 
 ## Constraints and limitations
 
@@ -48,12 +55,13 @@ The following resources are available to help you use multi-port services:
 ### Usage documentation
 
 - [Configure multi-port services](/consul/docs/k8s/multiport/configure)
+- [Split traffic between multi-port services](/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)
+- [`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)
diff --git a/website/content/docs/k8s/multiport/reference/httproute.mdx b/website/content/docs/k8s/multiport/reference/httproute.mdx
index b7bfc8f0f48c..31f722e32878 100644
--- a/website/content/docs/k8s/multiport/reference/httproute.mdx
+++ b/website/content/docs/k8s/multiport/reference/httproute.mdx
@@ -866,10 +866,10 @@ spec:
 
 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 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.
+- 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 includes how to include filters that modify request or response headers.
+This example also configures Consul to modify request and response headers when routing traffic.
 
 ```yaml
 apiVersion: mesh.consul.hashicorp.com/v2beta1
@@ -936,4 +936,68 @@ spec:
             name: api-admin
           # The configuration targets the workload port, not the service port.
           port: "admin-workload"
+```
+
+### 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 configuration targets the workload port, not the service port.
+      port: "api-workload"
+  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 configuration targets the workload port, not the service port.
+          port: "api-workload"
+    - 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 configuration targets the workload port, not the service port.
+          port: "admin-workload"
 ```
\ No newline at end of file
diff --git a/website/content/docs/k8s/multiport/reference/resource-command.mdx b/website/content/docs/k8s/multiport/reference/resource-command.mdx
index 593a6ceba725..6f7470b16c86 100644
--- a/website/content/docs/k8s/multiport/reference/resource-command.mdx
+++ b/website/content/docs/k8s/multiport/reference/resource-command.mdx
@@ -35,7 +35,12 @@ 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. 
-You must present a token with `operator:write` [ACL permissions](/consul/api-docs/api-structure#authentication) to use the `apply` command. 
+
+The following table shows the required [ACLs permissions](/consul/api-docs/api-structure#authentication) to run the `apply` command:
+
+| ACL Required |
+| ------------ |
+| `operator:write`  |
 
 #### Command Options
 
@@ -53,7 +58,7 @@ $ consul resource apply -f=trafficpermissions.yaml
 
 `consul resource delete`removes a Consul resource at a given file path.
 
-The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication).
+The following table shows the required [ACLs permissions](/consul/api-docs/api-structure#authentication) to run the `delete` command:
 
 | ACL Required |
 | ------------ |
@@ -77,7 +82,7 @@ $ consul resource delete -f=trafficpermissions.yaml
 
 This command must be issued with a resource type. All resource definitions include a `type` configuration block that contains a `group`, `groupVersion`, and `kind`. By formatting the `type` on the command line as `group.groupVersion.kind`, you can return all resources with a matching `type` in the configuration.
 
-The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication).
+The following table shows the required [ACLs permissions](/consul/api-docs/api-structure#authentication) to run the `list` command:
 
 | ACL Required |
 | ------------ |
@@ -101,9 +106,9 @@ $ consul resource list catalog.v2beta1.Service card-processor -partition=billing
 
 ### `read`
 
-`consul resource list` outputs names of resources according to the type of resource or where the resource is applied.
+`consul resource read` outputs names of resources according to the type of resource or where the resource is applied.
 
-The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication).
+The following table shows the required [ACLs permissions](/consul/api-docs/api-structure#authentication) to run the `read` command:
 
 | ACL Required |
 | ------------ |
diff --git a/website/content/docs/k8s/multiport/traffic-split.mdx b/website/content/docs/k8s/multiport/traffic-split.mdx
new file mode 100644
index 000000000000..03a72834d585
--- /dev/null
+++ b/website/content/docs/k8s/multiport/traffic-split.mdx
@@ -0,0 +1,92 @@
+---
+layout: docs
+page_title: Split traffic between multi-port services 
+description: Learn how to 
+---
+
+# Split traffic between multi-port services
+
+
+
+Multi-port services are part of a beta release. This documentation supports testing and development scenarios. Do not use multi-port services or the v2 catalog API in secure production environments.
+
+
+
+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/catalog/v2). For guidance on enabling the v2 catalog, deploying multi-port services, and applying traffic permissions to them, refer to [configure multi-port services](/consul/docs/k8s/multiport/configure).
+
+## Split traffic using route resources
+
+You can split traffic according to the application traffic's network protocol using the following CRDs:
+
+- [`TCPRoute` resource](/consul/docs/k8s/multiport/reference/tcproute)
+- [`HTTPRoute` resource](/consul/docs/k8s/multiport/reference/httproute)
+- [`GRPCRoute` resource](/consul/docs/k8s/multiport/reference/tcproute)
+
+The process for implementing these resources in your Consul on Kubernetes deployment is the same:
+
+1. Define the resource's behavior in a custom resource definition (CRD).
+1. Apply the resource to your cluster.
+1. Output the resource path with the `consul resource read` command.
+
+Configurable fields between each resource vary. The usage instructions on this page configure a TCP route resource to use with the [end-to-end multi-port deployment example](/consul/docs/k8s/multiport/configure).
+
+## 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.
+
+
+
+```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
+      port: "api-workload"
+  rules:
+    - backendRefs:
+      - backendRef:
+          ref: 
+            type:
+              group: catalog
+              groupVersion: v2beta1
+              kind: Service
+            name: api
+          port: "api-workload"
+        weight: 50
+      - backendRef:
+          ref: 
+            type:
+              group: catalog
+              groupVersion: v2beta1
+              kind: Service
+            name: api
+          port: "admin-workload"
+        weight: 50
+```
+
+
+
+## Apply the resource
+
+Use the `kubectl` command to apply the resource to your Consul cluster.
+
+```shell-session
+$ kubectl apply -f api-split.yaml
+```
+
+## Read the resource path
+
+[Final TODO]
\ No newline at end of file
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
index e2d6255f4a24..0b15632842ac 100644
--- a/website/data/docs-nav-data.json
+++ b/website/data/docs-nav-data.json
@@ -1538,6 +1538,10 @@
             "title": "Configure multi-port services",
             "path": "k8s/multiport/configure"
           },
+          {
+            "title": "Split traffic between multi-port services",
+            "path": "k8s/multiport/traffic-split"
+          },
           {
             "title": "Reference",
             "routes": [

From 1b8c67549961a0b6f86c013bf957009f0b3bdcb4 Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Wed, 1 Nov 2023 11:19:27 -0700
Subject: [PATCH 39/57] TCP clarification

---
 website/content/docs/k8s/multiport/traffic-split.mdx | 4 ++--
 website/data/docs-nav-data.json                      | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/website/content/docs/k8s/multiport/traffic-split.mdx b/website/content/docs/k8s/multiport/traffic-split.mdx
index 03a72834d585..8ab7215eacd0 100644
--- a/website/content/docs/k8s/multiport/traffic-split.mdx
+++ b/website/content/docs/k8s/multiport/traffic-split.mdx
@@ -1,10 +1,10 @@
 ---
 layout: docs
 page_title: Split traffic between multi-port services 
-description: Learn how to 
+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 traffic between multi-port services
+# Split TCP traffic between multi-port services
 
 
 
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
index 0b15632842ac..217da04b5094 100644
--- a/website/data/docs-nav-data.json
+++ b/website/data/docs-nav-data.json
@@ -1539,7 +1539,7 @@
             "path": "k8s/multiport/configure"
           },
           {
-            "title": "Split traffic between multi-port services",
+            "title": "Split TCP traffic between multi-port services",
             "path": "k8s/multiport/traffic-split"
           },
           {

From af1746b3af8250ce1f984298c2f220a3987a882f Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Wed, 1 Nov 2023 11:32:14 -0700
Subject: [PATCH 40/57] Minor fixes

---
 website/content/docs/k8s/multiport/configure.mdx     |  2 +-
 website/content/docs/k8s/multiport/index.mdx         |  4 ++--
 website/content/docs/k8s/multiport/traffic-split.mdx | 12 ++----------
 3 files changed, 5 insertions(+), 13 deletions(-)

diff --git a/website/content/docs/k8s/multiport/configure.mdx b/website/content/docs/k8s/multiport/configure.mdx
index 81d87b738a10..6d43064b204e 100644
--- a/website/content/docs/k8s/multiport/configure.mdx
+++ b/website/content/docs/k8s/multiport/configure.mdx
@@ -459,7 +459,7 @@ hello world from 9090 admin
 
 ## 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 match HTTP traffic with ports using query parameters.
+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:
 
diff --git a/website/content/docs/k8s/multiport/index.mdx b/website/content/docs/k8s/multiport/index.mdx
index ec8dd6354e7b..19cbfac03355 100644
--- a/website/content/docs/k8s/multiport/index.mdx
+++ b/website/content/docs/k8s/multiport/index.mdx
@@ -32,7 +32,7 @@ You can also configure Envoy proxies and sidecar behavior with the proxy configu
 1. Apply the resource to your cluster.
 1. Output the resource path with the `consul resource read` command.
 
-For an example configuration and instructions for each of the steps in this workflow, refer to [split service traffic between ports](/consul/docs/k8s/multiport/traffic-split).
+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
 
@@ -55,7 +55,7 @@ The following resources are available to help you use multi-port services:
 ### Usage documentation
 
 - [Configure multi-port services](/consul/docs/k8s/multiport/configure)
-- [Split traffic between multi-port services](/consul/docs/k8s/multiport/traffic-split)
+- [Split TCP traffic between multi-port services](/consul/docs/k8s/multiport/traffic-split)
 
 ### Reference documentation
 
diff --git a/website/content/docs/k8s/multiport/traffic-split.mdx b/website/content/docs/k8s/multiport/traffic-split.mdx
index 8ab7215eacd0..1a3077f2aa08 100644
--- a/website/content/docs/k8s/multiport/traffic-split.mdx
+++ b/website/content/docs/k8s/multiport/traffic-split.mdx
@@ -18,22 +18,14 @@ This page describes the process for splitting TCP, HTTP, and gRPC traffic betwee
 
 Splitting traffic between two ports of a multi-port service requires the [v2 catalog API](/consul/docs/architecture/catalog/v2). For guidance on enabling the v2 catalog, deploying multi-port services, and applying traffic permissions to them, refer to [configure multi-port services](/consul/docs/k8s/multiport/configure).
 
-## Split traffic using route resources
+## Overview
 
-You can split traffic according to the application traffic's network protocol using the following CRDs:
-
-- [`TCPRoute` resource](/consul/docs/k8s/multiport/reference/tcproute)
-- [`HTTPRoute` resource](/consul/docs/k8s/multiport/reference/httproute)
-- [`GRPCRoute` resource](/consul/docs/k8s/multiport/reference/tcproute)
-
-The process for implementing these resources in your Consul on Kubernetes deployment is the same:
+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.
 1. Output the resource path with the `consul resource read` command.
 
-Configurable fields between each resource vary. The usage instructions on this page configure a TCP route resource to use with the [end-to-end multi-port deployment example](/consul/docs/k8s/multiport/configure).
-
 ## 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.

From e3ea5f2fa4b7e548a963d410c9cdbb2977b50260 Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Wed, 1 Nov 2023 12:39:07 -0700
Subject: [PATCH 41/57] remove references to unsupported features

---
 .../content/docs/architecture/catalog/v2.mdx  |  2 +-
 .../k8s/multiport/reference/grpcroute.mdx     | 24 ++++---------------
 .../k8s/multiport/reference/httproute.mdx     | 24 ++++---------------
 .../docs/k8s/multiport/reference/tcproute.mdx | 24 ++++---------------
 .../reference/trafficpermissions.mdx          | 22 ++---------------
 5 files changed, 15 insertions(+), 81 deletions(-)

diff --git a/website/content/docs/architecture/catalog/v2.mdx b/website/content/docs/architecture/catalog/v2.mdx
index 3fa7b86dbf47..837c6ca59f56 100644
--- a/website/content/docs/architecture/catalog/v2.mdx
+++ b/website/content/docs/architecture/catalog/v2.mdx
@@ -45,7 +45,7 @@ The following table describes resources in the v2 catalog and compares them to t
 | Service endpoints | 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 | A resource for reporting the health status of a workload. | Service instance health status | None | Computed by Consul |
 | Health check | 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) | Defined by user in Kubernetes |
-| Proxy configuration | Represents a configuration for a sidecar or gateway proxy. | `Proxy` field in service definition | None | Defined by user in Consul |
+| Proxy configuration | Represents a configuration for a sidecar or gateway proxy. | `Proxy` field in service definition | None | Defined by user in Kubernetes or Consul |
 | Destinations | Represents explicit service upstreams. | [Proxy Configuration](/consul/docs/connect/proxies/envoy#envoy-proxy-configuration-for-service-mesh) | [Upstream Service annotation](/consul/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams)  | Defined by user in Kubernetes |
 | Traffic permissions | Enables L4 traffic authorization according to workload identity instead of service identity. | [Service intentions](/consul/docs/connect/intentions) | None | Defined by user in Consul |
 
diff --git a/website/content/docs/k8s/multiport/reference/grpcroute.mdx b/website/content/docs/k8s/multiport/reference/grpcroute.mdx
index 752c2878d9d3..49af02dde2a7 100644
--- a/website/content/docs/k8s/multiport/reference/grpcroute.mdx
+++ b/website/content/docs/k8s/multiport/reference/grpcroute.mdx
@@ -24,11 +24,6 @@ The following list outlines field hierarchy, language-specific data types, and r
     - [`port`](#spec-parentrefs-port): string
     - [`ref`](#spec-parentrefs-ref):  string | required
       - [`name`](#spec-parentrefs-ref-name): string
-      - [`section`](#spec-parentrefs-ref-section): string
-      - [`tenancy`](#spec-parentrefs-ref-tenancy): string
-        - [`namespace`](#spec-parentrefs-ref-tenancy): string 
-        - [`partition`](#spec-parentrefs-ref-tenancy): string 
-        - [`peerName`](#spec-parentrefs-ref-tenancy): string
       - [`type`](#spec-parentrefs-ref-type): map
          - [`group`](#spec-parentrefs-ref-type): string
          - [`groupVersion`](#spec-parentrefs-ref-type): string
@@ -40,11 +35,6 @@ The following list outlines field hierarchy, language-specific data types, and r
         - [`port`](#spec-rules-backendrefs-backendref-port): string
         - [`ref`](#spec-rules-backendrefs-backendref-ref): map
           - [`name`](#spec-rules-backendrefs-backendref-ref-name): string
-          - [`section`](#spec-rules-backendrefs-backendref-ref-section): string
-          - [`tenancy`](#spec-rules-backendrefs-backendref-ref-tenancy): map
-            - [`namespace`](#spec-rules-backendrefs-backendref-ref-tenancy): string
-            - [`partition`](#spec-rules-backendrefs-backendref-ref-tenancy): string
-            - [`peerName`](#spec-rules-backendrefs-backendref-ref-tenancy): 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
@@ -110,11 +100,6 @@ spec:
     port: 
     - ref:
       name: 
-      section: 
-      tenancy:
-        namespace: 
-        partition: 
-        peerName: 
       type: 
         group: 
         groupVersion: 
@@ -126,11 +111,6 @@ spec:
         port: ""
         ref:
           name: 
-          section: 
-          tenancy:
-            namespace: 
-            partition: 
-            peerName: 
           type:
             group: 
             groupVersion: 
@@ -283,6 +263,7 @@ Specifies the user-defined name of the resource that the configuration applies t
 - Default: None
 - Data type: String
 
+{::comment}
 ### `spec.parentRefs.ref.section`
 
 Specifies the section of the resource that the configuration applies to.
@@ -306,6 +287,7 @@ Specifies the user-defined namespace, partition, or cluster peer of the resource
   | `namespace`   | Identifies the namespace of the resource the configuration applies to.                 | String    | None     |
   | `partition`   | Identifies the admin partition of the resource the configuration applies to.           | String    | None     |
   | `peerName`    | Identifies the name of a cluster peer the resource is imported from that the configuration applies to. | String    | None     |
+{:/comment}
 
 ### `spec.parentRefs.ref.type`
 
@@ -389,6 +371,7 @@ Specifies the user-defined name of the resource that the configuration routes tr
 - Default: None
 - Data type: String
 
+{::comment}
 ### `spec.rules.backendRefs.backendRef.ref.section`
 
 Specifies the section the resource that the configuration routes traffic to.
@@ -412,6 +395,7 @@ Specifies the user-defined namespace, partition, or cluster peer of the resource
   | `namespace`   | Identifies the namespace of the resource the configuration routes traffic to.                 | String    | None     |
   | `partition`   | Identifies the admin partition of the resource the configuration routes traffic to.         | String    | None     |
   | `peerName`    | Identifies the name of a cluster peer the resource is imported from that the configuration routes traffic to. | String    | None     |
+{:/comment}
 
 ### `spec.rules.backendRefs.backendRef.ref.type`
 
diff --git a/website/content/docs/k8s/multiport/reference/httproute.mdx b/website/content/docs/k8s/multiport/reference/httproute.mdx
index 31f722e32878..6a32636aad05 100644
--- a/website/content/docs/k8s/multiport/reference/httproute.mdx
+++ b/website/content/docs/k8s/multiport/reference/httproute.mdx
@@ -24,11 +24,6 @@ The following list outlines field hierarchy, language-specific data types, and r
     - [`port`](#spec-parentrefs-port): string
     - [`ref`](#spec-parentrefs-ref):  string | required
       - [`name`](#spec-parentrefs-ref-name): string
-      - [`section`](#spec-parentrefs-ref-section): string
-      - [`tenancy`](#spec-parentrefs-ref-tenancy): string
-        - [`namespace`](#spec-parentrefs-ref-tenancy): string 
-        - [`partition`](#spec-parentrefs-ref-tenancy): string 
-        - [`peerName`](#spec-parentrefs-ref-tenancy): string
       - [`type`](#spec-parentrefs-ref-type): map
          - [`group`](#spec-parentrefs-ref-type): string
          - [`groupVersion`](#spec-parentrefs-ref-type): string
@@ -40,11 +35,6 @@ The following list outlines field hierarchy, language-specific data types, and r
         - [`port`](#spec-rules-backendrefs-backendref-port): string
         - [`ref`](#spec-rules-backendrefs-backendref-ref): map
           - [`name`](#spec-rules-backendrefs-backendref-ref-name): string
-          - [`section`](#spec-rules-backendrefs-backendref-ref-section): string
-          - [`tenancy`](#spec-rules-backendrefs-backendref-ref-tenancy): map
-            - [`namespace`](#spec-rules-backendrefs-backendref-ref-tenancy): string
-            - [`partition`](#spec-rules-backendrefs-backendref-ref-tenancy): string
-            - [`peerName`](#spec-rules-backendrefs-backendref-ref-tenancy): 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
@@ -114,11 +104,6 @@ spec:
     port: 
     - ref:
       name: 
-      section: 
-      tenancy:
-        namespace: 
-        partition: 
-        peerName: 
       type: 
         group: 
         groupVersion: 
@@ -130,11 +115,6 @@ spec:
         port: 
         ref:
           name: 
-          section: 
-          tenancy:
-            namespace: 
-            partition: 
-            peerName: 
           type:
             group: 
             groupVersion: 
@@ -291,6 +271,7 @@ Specifies the user-defined name of the resource that the configuration applies t
 - Default: None
 - Data type: String
 
+{::comment}
 ### `spec.parentRefs.ref.section`
 
 Specifies the section of the resource that the configuration applies to.
@@ -314,6 +295,7 @@ Specifies the user-defined namespace, partition, or cluster peer of the resource
   | `namespace`   | Identifies the namespace of the resource the configuration applies to.                 | String    | None     |
   | `partition`   | Identifies the admin partition of the resource the configuration applies to.           | String    | None     |
   | `peerName`    | Identifies the name of a cluster peer the resource is imported from that the configuration applies to. | String    | None     |
+{:/comment}
 
 ### `spec.parentRefs.ref.type`
 
@@ -397,6 +379,7 @@ Specifies the user-defined name of the resource that the configuration routes tr
 - Default: None
 - Data type: String
 
+{::comment}
 ### `spec.rules.backendRefs.backendRef.ref.section`
 
 Specifies the section the resource that the configuration routes traffic to.
@@ -420,6 +403,7 @@ Specifies the user-defined namespace, partition, or cluster peer of the resource
   | `namespace`   | Identifies the namespace of the resource the configuration routes traffic to.                 | String    | None     |
   | `partition`   | Identifies the admin partition of the resource the configuration routes traffic to.         | String    | None     |
   | `peerName`    | Identifies the name of a cluster peer the resource is imported from that the configuration routes traffic to. | String    | None     |
+{:/comment}
 
 ### `spec.rules.backendRefs.backendRef.ref.type`
 
diff --git a/website/content/docs/k8s/multiport/reference/tcproute.mdx b/website/content/docs/k8s/multiport/reference/tcproute.mdx
index 6af82963a713..d7cd91f3d5b3 100644
--- a/website/content/docs/k8s/multiport/reference/tcproute.mdx
+++ b/website/content/docs/k8s/multiport/reference/tcproute.mdx
@@ -28,11 +28,6 @@ The following list outlines field hierarchy, language-specific data types, and r
     - [`port`](#spec-parentrefs-port): string
     - [`ref`](#spec-parentrefs-ref):  string | required
       - [`name`](#spec-parentrefs-ref-name): string
-      - [`section`](#spec-parentrefs-ref-section): string
-      - [`tenancy`](#spec-parentrefs-ref-tenancy): string
-        - [`namespace`](#spec-parentrefs-ref-tenancy): string 
-        - [`partition`](#spec-parentrefs-ref-tenancy): string 
-        - [`peerName`](#spec-parentrefs-ref-tenancy): string
       - [`type`](#spec-parentrefs-ref-type): map
          - [`group`](#spec-parentrefs-ref-type): string
          - [`groupVersion`](#spec-parentrefs-ref-type): string
@@ -44,11 +39,6 @@ The following list outlines field hierarchy, language-specific data types, and r
         - [`port`](#spec-rules-backendrefs-backendref-port): string
         - [`ref`](#spec-rules-backendrefs-backendref-ref): map
           - [`name`](#spec-rules-backendrefs-backendref-ref-name): string
-          - [`section`](#spec-rules-backendrefs-backendref-ref-section): string
-          - [`tenancy`](#spec-rules-backendrefs-backendref-ref-tenancy): map
-            - [`namespace`](#spec-rules-backendrefs-backendref-ref-tenancy): string
-            - [`partition`](#spec-rules-backendrefs-backendref-ref-tenancy): string
-            - [`peerName`](#spec-rules-backendrefs-backendref-ref-tenancy): 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
@@ -73,11 +63,6 @@ spec:
     port: 
     - ref:
       name: 
-      section: 
-      tenancy:
-        namespace: 
-        partition: 
-        peerName: 
       type: 
         group: 
         groupVersion: 
@@ -89,11 +74,6 @@ spec:
         port: 
         ref:
           name: 
-          section: 
-          tenancy:
-            namespace: 
-            partition: 
-            peerName: 
           type:
             group: 
             groupVersion: 
@@ -202,6 +182,7 @@ Specifies the user-defined name of the resource that the configuration applies t
 - Default: None
 - Data type: String
 
+{::comment}
 ### `spec.parentRefs.ref.section`
 
 Specifies the section of the resource that the configuration applies to.
@@ -225,6 +206,7 @@ Specifies the user-defined namespace, partition, or cluster peer of the resource
   | `namespace`   | Identifies the namespace of the resource the configuration applies to.                 | String    | None     |
   | `partition`   | Identifies the admin partition of the resource the configuration applies to.           | String    | None     |
   | `peerName`    | Identifies the name of a cluster peer the resource is imported from that the configuration applies to. | String    | None     |
+{:/comment}
 
 ### `spec.parentRefs.ref.type`
 
@@ -308,6 +290,7 @@ Specifies the user-defined name of the resource that the configuration routes tr
 - Default: None
 - Data type: String
 
+{::comment}
 ### `spec.rules.backendRefs.backendRef.ref.section`
 
 Specifies the section the resource that the configuration routes traffic to.
@@ -331,6 +314,7 @@ Specifies the user-defined namespace, partition, or cluster peer of the resource
   | `namespace`   | Identifies the namespace of the resource the configuration routes traffic to.                 | String    | None     |
   | `partition`   | Identifies the admin partition of the resource the configuration routes traffic to.         | String    | None     |
   | `peerName`    | Identifies the name of a cluster peer the resource is imported from that the configuration routes traffic to. | String    | None     |
+{:/comment}
 
 ### `spec.rules.backendRefs.backendRef.ref.type`
 
diff --git a/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx b/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
index 860fa49a7eff..4dbfd27ed168 100644
--- a/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
+++ b/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
@@ -26,16 +26,6 @@ The following list outlines field hierarchy, language-specific data types, and r
   - [`permissions`](#spec-permissions): list of maps
     - [`sources`](#spec-permissions-sources): map
       - [`identityName`](#spec-permissions-sources-identityname): string
-      - [`namespace`](#spec-permissions-sources-namespace): string
-      - [`partition`](#spec-permissions-sources-partition): string
-      - [`peer`](#spec-permissions-sources-peer): string
-      - [`samenessGroup`](#spec-permissions-sources-samenessgroup): string
-      - [`exclude`](#spec-permissions-sources-exclude): map
-        - [`identityName`](#spec-permissions-sources-exclude): string
-        - [`namespace`](#spec-permissions-sources-exclude): string
-        - [`partition`](#spec-permissions-sources-exclude): string
-        - [`peer`](#spec-permissions-sources-exclude): string
-        - [`samenessGroup`](#spec-permissions-sources-exclude): string
     - [`destinationRules`](#spec-permissions-destinationrules):
       - [`portNames`](#spec-permissions-destinationrules-portNames): array of strings
 {::comment}
@@ -84,16 +74,6 @@ spec:
   permissions:
     - sources:
       identityName:  
-      namespace: 
-      partition: 
-      peer: 
-      samenessGroup: 
-      exclude:
-        identityName: 
-        namespace: 
-        partition: 
-        peer: 
-        samenessGroup: 
     destinationRules:
       portNames: 
         - 
@@ -228,6 +208,7 @@ Specifies the Workload identity for the service that originates the request.
 - Default: None
 - Data type: Map
 
+{::comment}
 ### `spec.permissions.sources.namespace`
 
 Specifies the Consul namespace for the service that originates the request.
@@ -272,6 +253,7 @@ Specifies sources to exclude from the defined source.
 
 - Default: None
 - Data type: Array of maps
+{:/comment}
 
 ### `spec.permissions.destinationRules`
 

From 4c464e2fc85ef20245e90ef4f5cb35fb9b663e94 Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Wed, 1 Nov 2023 14:29:54 -0700
Subject: [PATCH 42/57] comment fix

---
 .../k8s/multiport/reference/grpcroute.mdx     |  52 ----
 .../k8s/multiport/reference/httproute.mdx     |  52 ----
 .../docs/k8s/multiport/reference/tcproute.mdx |  52 ----
 .../reference/trafficpermissions.mdx          | 247 ------------------
 4 files changed, 403 deletions(-)

diff --git a/website/content/docs/k8s/multiport/reference/grpcroute.mdx b/website/content/docs/k8s/multiport/reference/grpcroute.mdx
index 49af02dde2a7..e2376490731e 100644
--- a/website/content/docs/k8s/multiport/reference/grpcroute.mdx
+++ b/website/content/docs/k8s/multiport/reference/grpcroute.mdx
@@ -263,32 +263,6 @@ Specifies the user-defined name of the resource that the configuration applies t
 - Default: None
 - Data type: String
 
-{::comment}
-### `spec.parentRefs.ref.section`
-
-Specifies the section of the resource that the configuration applies to.
-
-#### Values
-
-- Default: None
-- Data type: String
-
-### `spec.parentRefs.ref.tenancy`
-
-Specifies the user-defined namespace, partition, or cluster peer of the resource that the configuration applies to.
-
-#### Values
-
-- Default: None
-- Data type: Map containing the following parameters:
-
-  | Parameter     | Description                                                          | Data type | Default  |
-  | :------------ | :------------------------------------------------------------------- | :-------- | :------- |
-  | `namespace`   | Identifies the namespace of the resource the configuration applies to.                 | String    | None     |
-  | `partition`   | Identifies the admin partition of the resource the configuration applies to.           | String    | None     |
-  | `peerName`    | Identifies the name of a cluster peer the resource is imported from that the configuration applies to. | String    | None     |
-{:/comment}
-
 ### `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`.
@@ -371,32 +345,6 @@ Specifies the user-defined name of the resource that the configuration routes tr
 - Default: None
 - Data type: String
 
-{::comment}
-### `spec.rules.backendRefs.backendRef.ref.section`
-
-Specifies the section the resource that the configuration routes traffic to.
-
-#### Values
-
-- Default: None
-- Data type: String
-
-### `spec.rules.backendRefs.backendRef.ref.tenancy`
-
-Specifies the user-defined namespace, partition, or cluster peer of the resource that the configuration routes to.
-
-#### Values
-
-- Default: None
-- Data type: Map containing the following parameters:
-
-  | Parameter     | Description                                                          | Data type | Default  |
-  | :------------ | :------------------------------------------------------------------- | :-------- | :------- |
-  | `namespace`   | Identifies the namespace of the resource the configuration routes traffic to.                 | String    | None     |
-  | `partition`   | Identifies the admin partition of the resource the configuration routes traffic to.         | String    | None     |
-  | `peerName`    | Identifies the name of a cluster peer the resource is imported from that the configuration routes traffic to. | String    | None     |
-{:/comment}
-
 ### `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`.
diff --git a/website/content/docs/k8s/multiport/reference/httproute.mdx b/website/content/docs/k8s/multiport/reference/httproute.mdx
index 6a32636aad05..e06a1ed34d65 100644
--- a/website/content/docs/k8s/multiport/reference/httproute.mdx
+++ b/website/content/docs/k8s/multiport/reference/httproute.mdx
@@ -271,32 +271,6 @@ Specifies the user-defined name of the resource that the configuration applies t
 - Default: None
 - Data type: String
 
-{::comment}
-### `spec.parentRefs.ref.section`
-
-Specifies the section of the resource that the configuration applies to.
-
-#### Values
-
-- Default: None
-- Data type: String
-
-### `spec.parentRefs.ref.tenancy`
-
-Specifies the user-defined namespace, partition, or cluster peer of the resource that the configuration applies to.
-
-#### Values
-
-- Default: None
-- Data type: Map containing the following parameters:
-
-  | Parameter     | Description                                                          | Data type | Default  |
-  | :------------ | :------------------------------------------------------------------- | :-------- | :------- |
-  | `namespace`   | Identifies the namespace of the resource the configuration applies to.                 | String    | None     |
-  | `partition`   | Identifies the admin partition of the resource the configuration applies to.           | String    | None     |
-  | `peerName`    | Identifies the name of a cluster peer the resource is imported from that the configuration applies to. | String    | None     |
-{:/comment}
-
 ### `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`.
@@ -379,32 +353,6 @@ Specifies the user-defined name of the resource that the configuration routes tr
 - Default: None
 - Data type: String
 
-{::comment}
-### `spec.rules.backendRefs.backendRef.ref.section`
-
-Specifies the section the resource that the configuration routes traffic to.
-
-#### Values
-
-- Default: None
-- Data type: String
-
-### `spec.rules.backendRefs.backendRef.ref.tenancy`
-
-Specifies the user-defined namespace, partition, or cluster peer of the resource that the configuration routes to.
-
-#### Values
-
-- Default: None
-- Data type: Map containing the following parameters:
-
-  | Parameter     | Description                                                          | Data type | Default  |
-  | :------------ | :------------------------------------------------------------------- | :-------- | :------- |
-  | `namespace`   | Identifies the namespace of the resource the configuration routes traffic to.                 | String    | None     |
-  | `partition`   | Identifies the admin partition of the resource the configuration routes traffic to.         | String    | None     |
-  | `peerName`    | Identifies the name of a cluster peer the resource is imported from that the configuration routes traffic to. | String    | None     |
-{:/comment}
-
 ### `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`.
diff --git a/website/content/docs/k8s/multiport/reference/tcproute.mdx b/website/content/docs/k8s/multiport/reference/tcproute.mdx
index d7cd91f3d5b3..f2666f28e500 100644
--- a/website/content/docs/k8s/multiport/reference/tcproute.mdx
+++ b/website/content/docs/k8s/multiport/reference/tcproute.mdx
@@ -182,32 +182,6 @@ Specifies the user-defined name of the resource that the configuration applies t
 - Default: None
 - Data type: String
 
-{::comment}
-### `spec.parentRefs.ref.section`
-
-Specifies the section of the resource that the configuration applies to.
-
-#### Values
-
-- Default: None
-- Data type: String
-
-### `spec.parentRefs.ref.tenancy`
-
-Specifies the user-defined namespace, partition, or cluster peer of the resource that the configuration applies to.
-
-#### Values
-
-- Default: None
-- Data type: Map containing the following parameters:
-
-  | Parameter     | Description                                                          | Data type | Default  |
-  | :------------ | :------------------------------------------------------------------- | :-------- | :------- |
-  | `namespace`   | Identifies the namespace of the resource the configuration applies to.                 | String    | None     |
-  | `partition`   | Identifies the admin partition of the resource the configuration applies to.           | String    | None     |
-  | `peerName`    | Identifies the name of a cluster peer the resource is imported from that the configuration applies to. | String    | None     |
-{:/comment}
-
 ### `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`.
@@ -290,32 +264,6 @@ Specifies the user-defined name of the resource that the configuration routes tr
 - Default: None
 - Data type: String
 
-{::comment}
-### `spec.rules.backendRefs.backendRef.ref.section`
-
-Specifies the section the resource that the configuration routes traffic to.
-
-#### Values
-
-- Default: None
-- Data type: String
-
-### `spec.rules.backendRefs.backendRef.ref.tenancy`
-
-Specifies the user-defined namespace, partition, or cluster peer of the resource that the configuration routes to.
-
-#### Values
-
-- Default: None
-- Data type: Map containing the following parameters:
-
-  | Parameter     | Description                                                          | Data type | Default  |
-  | :------------ | :------------------------------------------------------------------- | :-------- | :------- |
-  | `namespace`   | Identifies the namespace of the resource the configuration routes traffic to.                 | String    | None     |
-  | `partition`   | Identifies the admin partition of the resource the configuration routes traffic to.         | String    | None     |
-  | `peerName`    | Identifies the name of a cluster peer the resource is imported from that the configuration routes traffic to. | String    | None     |
-{:/comment}
-
 ### `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`.
diff --git a/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx b/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
index 4dbfd27ed168..5d2f61c36cac 100644
--- a/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
+++ b/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
@@ -28,34 +28,6 @@ The following list outlines field hierarchy, language-specific data types, and r
       - [`identityName`](#spec-permissions-sources-identityname): string
     - [`destinationRules`](#spec-permissions-destinationrules):
       - [`portNames`](#spec-permissions-destinationrules-portNames): array of strings
-{::comment}
-      - [`header`](#spec-permissions-destinationrules-header): map
-        - [`name`](#spec-permissions-destinationrules-header): string
-        - [`present`](#spec-permissions-destinationrules-header): boolean | `false`
-        - [`exact`](#spec-permissions-destinationrules-header): string
-        - [`prefix`](#spec-permissions-destinationrules-header): string
-        - [`suffix`](#spec-permissions-destinationrules-header): string
-        - [`regex`](#spec-permissions-destinationrules-header): string
-        - [`invert`](#spec-permissions-destinationrules-header): boolean | `false`
-      - [`methods`](#spec-permissions-destinationrules-methods): array of strings
-      - [`pathExact`](#spec-permissions-destinationrules-pathexact): string
-      - [`pathPrefix`](#spec-permissions-destinationrules-pathprefix): string
-      - [`pathRegex`](#spec-permissions-destinationrules-pathregex): string
-      - [`exclude`](#spec-permissions-destinationrules-exclude): map
-        - [`header`](#spec-permissions-destinationrules-exclude-header): map
-          - [`exact`](#spec-permissions-destinationrules-exclude-header): string
-          - [`invert`](#spec-permissions-destinationrules-exclude-header): boolean | `false`
-          - [`name`](#spec-permissions-destinationrules-exclude-header): string
-          - [`prefix`](#spec-permissions-destinationrules-exclude-header): string
-          - [`present`](#spec-permissions-destinationrules-exclude-header): boolean | `false`
-          - [`regex`](#spec-permissions-destinationrules-exclude-header): string
-          - [`suffix`](#spec-permissions-destinationrules-exclude-header): string
-        - [`methods`](#spec-permissions-destinationrules-exclude-methods): array of strings
-        - [`pathExact`](#spec-permissions-destinationrules-exclude-pathexact): string
-        - [`pathPrefix`](#spec-permissions-destinationrules-exclude-pathprefix): string
-        - [`pathRegex`](#spec-permissions-destinationrules-exclude-pathregex): string
-        - [`portNames`](#spec-permissions-destinationrules-exclude-portNames): array of strings
-{:/comment}
 
 ## Complete configuration
 
@@ -164,9 +136,6 @@ Specifies the Workload identity for a service. The permissions you configure in
 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).
 
 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.
-{::comment}
-The `ACTION_UNKNOWN` value is a reserved value that enables compatibility with future configurations. Do not specify this value in the current release.
-{:/comment}
 
 #### Values
 
@@ -175,9 +144,6 @@ The `ACTION_UNKNOWN` value is a reserved value that enables compatibility with f
 
   - `ACTION_ALLOW`
   - `ACTION_DENY`
-{::comment}
-  - `ACTION_UNKNOWN`
-{:/comment}
 
 ### `spec.permissions`
 
@@ -208,53 +174,6 @@ Specifies the Workload identity for the service that originates the request.
 - Default: None
 - Data type: Map
 
-{::comment}
-### `spec.permissions.sources.namespace`
-
-Specifies the Consul namespace for the service that originates the request.
-
-#### Values
-
-- Default: None
-- Data type: Map
-
-### `spec.permissions.sources.partition`
-
-Specifies the Consul admin partition for the service that originates the request.
-
-#### Values
-
-- Default: None
-- Data type: Map
-
-### `spec.permissions.sources.peer`
-
-Specifies the Consul cluster peer where the service that originates the request is scheduled.
-
-#### Values
-
-- Default: None
-- Data type: Map
-
-### `spec.permissions.sources.samenessGroup`
-
-Specifies the sameness group that includes the service that originates the request.
-
-#### Values
-
-- Default: None
-- Data type: Map
-
-### `spec.permissions.sources.exclude`
-
-Specifies sources to exclude from the defined source.
-
-#### Values
-
-- Default: None
-- Data type: Array of maps
-{:/comment}
-
 ### `spec.permissions.destinationRules`
 
 Specifies L7 properties to match against when Consul enforces traffic permissions.
@@ -267,76 +186,6 @@ When [`spec.action`](#spec-action) _denies traffic_, Consul denies authorization
 
 - Default: None
 - Data type: Map
-{::comment}
-### `spec.permissions.destinationRules.header`
-
-Specifies a set of criteria for matching HTTP request headers. The request header must match all specified criteria for the permission to apply.
-
-#### Values
-
-- Default: None
-- Data type: List of maps
-
-Each member of the header list is a map that contains a name field and at least one match criterion. The following table describes the parameters that each member of the header list may contain:
-
-| Parameter | Description | Data type | Required |
-| --- | --- | --- | --- |
-| `name` | Specifies the name of the header to match. | string | required |
-| `present` | Enables a match if the header configured in the `name` field appears in the request. Consul matches on any value as long as the header key appears in the request. Do not specify `present` if `exact`, `prefix`, `suffix`, or `regex` are configured in the same `header` configuration. | boolean | optional |
-| `exact` | Specifies a value for the header key set in the `name` field. If the request header value matches the `exact` value, Consul applies the permission.  Do not specify `exact` if `present`, `prefix`, `suffix`, or `regex` are configured in the same `header` configuration. | string | optional |
-| `prefix` | Specifies a prefix value for the header key set in the `name` field. If the request header value starts with the `prefix` value, Consul applies the permission.  Do not specify `prefix` if `present`, `exact`, `suffix`, or `regex` are configured in the same `header` configuration. | string | optional |
-| `suffix` | Specifies a suffix value for the header key set in the `name` field. If the request header value ends with the `suffix` value, Consul applies the permission.  Do not specify `suffix` if `present`, `exact`, `prefix`, or `regex` are configured in the same `header` configuration. | string | optional |
-| `regex` | Specifies a regular expression pattern as the value for the header key set in the `name` field. If the request header value matches the regex, Consul applies the permission. Do not specify `regex` if `present`, `exact`, `prefix`, or `suffix` are configured in the same `header` configuration. The regex syntax is proxy-specific. If using Envoy, refer to the [re2 documentation](https://github.com/google/re2/wiki/Syntax) for details. | string | optional |
-| `invert` | Inverts the matching logic configured in the `header`. Default is `false`. | boolean | optional |
-
-### `spec.permissions.destinationRules.methods`
-
-Specifies a list of HTTP methods. Consul applies the permission if the source sent the request using one of the specified methods. Refer to the [Mozilla documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) for details on supported request methods.
-
-#### Values
-
-- Default: None
-- Data type: List of strings with one or more of the following values:
-
-  - `GET`
-  - `HEAD`
-  - `POST`
-  - `PUT`
-  - `DELETE`
-  - `CONNECT`
-  - `OPTIONS`
-  - `TRACE`
-  - `PATCH`
-
-Refer to the [Mozilla documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) for more information about each method.
-
-### `spec.permissions.destinationRules.pathExact`
-
-Specifies an exact path to match on the request path. Do not specify `pathExact` if `pathPrefix` or `pathRegex` are configured in the same destination rule.
-
-#### Values
-
-- Default: None
-- Data type: String
-
-### `spec.permissions.destinationRules.pathPrefix`
-
-Specifies a path prefix to match on the request path. Do not specify `pathPrefix` if `pathExact` or `pathRegex` are configured in the same destination rule.
-
-#### Values
-
-- Default: None
-- Data type: String
-
-### `spec.permissions.destinationRules.pathRegex`
-
-Defines a regular expression to match on the request path. Do not specify `pathRegex` if `pathExact` or `pathPrefix` are configured in the same destination rule. The regex syntax is proxy-specific. If using Envoy, refer to the [re2 documentation](https://github.com/google/re2/wiki/Syntax) for details.
-
-#### Values
-
-- Default: None
-- Data type: String
-{:/comment}
 
 ### `spec.permissions.destinationRules.portNames`
 
@@ -346,102 +195,6 @@ Specifies a port name that the Kubernetes Service exposes at the destination.
 
 - Default: None
 - Data type: String
-{::comment}
-### `spec.permissions.destinationRules.exclude`
-
-Specifies a list of destination rules to exclude when evaluating an incoming connection.
-
-#### Values
-
-- Default: None
-- Data type: List of maps
-
-### `spec.permissions.destinationRules.exclude.header`
-
-Specifies a set of header information that qualify for an exclusion to the destination rules. When an incoming request contains matching header information, the request will not produce a match when evaluating the destination rule that is otherwise defined.
-
-When [`spec.action`](#spec-action) _allows traffic_, Consul denies permission to the exclusion.
-
-When [`spec.action`](#spec-action) _denies traffic_, Consul allows permission to the exclusion.
-
-The request header must match all specified criteria to be considered an exclusion.
-
-#### Values
-
-- Default: None
-- Data type: List of maps
-
-Each member of the header list is a map that contains a name field and at least one match criterion. The following table describes the parameters that each member of the header list may contain:
-
-| Parameter | Description | Data type | Required |
-| --- | --- | --- | --- |
-| `name` | Specifies the name of the header to match. | string | required |
-| `present` | Enables a match if the header configured in the `name` field appears in the request. Consul matches on any value as long as the header key appears in the request. Do not specify `present` if `exact`, `prefix`, `suffix`, or `regex` are configured in the same `exclude.header` configuration. | boolean | optional |
-| `exact` | Specifies a value for the header key set in the `name` field. If the request header value matches the `exact` value, Consul applies the permission.  Do not specify `exact` if `present`, `prefix`, `suffix`, or `regex` are configured in the same `exclude.header` configuration. | string | optional |
-| `prefix` | Specifies a prefix value for the header key set in the `name` field. If the request header value starts with the `prefix` value, Consul applies the permission.  Do not specify `prefix` if `present`, `exact`, `suffix`, or `regex` are configured in the same `exclude.header` configuration. | string | optional |
-| `suffix` | Specifies a suffix value for the header key set in the `name` field. If the request header value ends with the `suffix` value, Consul applies the permission.  Do not specify `suffix` if `present`, `exact`, `prefix`, or `regex` are configured in the same `exclude.header` configuration. | string | optional |
-| `regex` | Specifies a regular expression pattern as the value for the header key set in the `name` field. If the request header value matches the regex, Consul applies the permission. Do not specify `regex` if `present`, `exact`, `prefix`, or `suffix` are configured in the same `exclude.header` configuration. The regex syntax is proxy-specific. If using Envoy, refer to the [re2 documentation](https://github.com/google/re2/wiki/Syntax) for details. | string | optional |
-| `invert` | Inverts the matching logic configured in the `exclude.header`. Default is `false`. | boolean | optional |
-
-### `spec.permissions.destinationRules.exclude.methods`
-
-Specifies a set of HTTP methods that qualify a request for an exclusion to the destination rules. When an incoming request uses one of the specified methods, the request will not produce a match when evaluating the destination rule that is otherwise defined.
-
-Refer to the [Mozilla documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) for details on supported request methods.
-
-#### Values
-
-- Default: None
-- Data type: List of strings with one or more of the following values:
-
-  - `GET`
-  - `HEAD`
-  - `POST`
-  - `PUT`
-  - `DELETE`
-  - `CONNECT`
-  - `OPTIONS`
-  - `TRACE`
-  - `PATCH`
-
-Refer to the [Mozilla documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) for more information about each method.
-
-### `spec.permissions.destinationRules.exclude.pathExact`
-
-Specifies an exact path that causes a request to be considered an exclusion to the destination rules.
-
-#### Values
-
-- Default: None
-- Data type: String
-
-### `spec.permissions.destinationRules.exclude.pathPrefix`
-
-Specifies a path prefix that causes a request to be considered an exclusion to the destination rules.
-
-#### Values
-
-- Default: None
-- Data type: String
-
-### `spec.permissions.destinationRules.exclude.pathRegex`
-
-Defines a regular expression that causes a request to be considered an exclusion to the destination rules when it matches a request path. The regex syntax is proxy-specific. If using Envoy, refer to the [re2 documentation](https://github.com/google/re2/wiki/Syntax) for details.
-
-#### Values
-
-- Default: None
-- Data type: String
-
-### `spec.permissions.destinationRules.exclude.portNames`
-
-Specifies a port name that exposes a Kubernetes Service. An incoming requests addressed to the port is considered an exclusion to the destination rules.
-
-#### Values
-
-- Default: None
-- Data type: List of strings
-{:/comment}
 
 ## Examples
 

From da48d80add325da8a710e2af8b42b0d8dc1e5966 Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Wed, 1 Nov 2023 16:31:52 -0700
Subject: [PATCH 43/57] Resource command section removed

---
 website/content/docs/k8s/multiport/configure.mdx     | 8 ++++----
 website/content/docs/k8s/multiport/index.mdx         | 1 -
 website/content/docs/k8s/multiport/traffic-split.mdx | 6 +-----
 3 files changed, 5 insertions(+), 10 deletions(-)

diff --git a/website/content/docs/k8s/multiport/configure.mdx b/website/content/docs/k8s/multiport/configure.mdx
index 6d43064b204e..45334dd89d7f 100644
--- a/website/content/docs/k8s/multiport/configure.mdx
+++ b/website/content/docs/k8s/multiport/configure.mdx
@@ -69,10 +69,10 @@ To download a compatible version of `consul-k8s` and add it to your `PATH`, run
 
 ```shell-session
 $ export VERSION=1.3.0 && \
-    curl --location "https://releases.hashicorp.com/consul-k8s/${VERSION}/consul-k8s_${VERSION}_darwin_amd64.zip" --output consul-k8s-cli.zip
-$ unzip -o consul-k8s-cli.zip -d ~/consul-k8s
-$ export PATH=$PATH:$HOME/consul-k8s
-$ consul-k8s install -config-file=values.yaml
+    curl --location "https://releases.hashicorp.com/consul-k8s/${VERSION}/consul-k8s_${VERSION}_darwin_amd64.zip" --output consul-k8s-cli.zip \
+    unzip -o consul-k8s-cli.zip -d ~/consul-k8s \
+    export PATH=$PATH:$HOME/consul-k8s \
+    consul-k8s install -config-file=values.yaml
 ```
 
 For platforms other than Mac OSX amd64, refer to [Install a previous version](/consul/docs/k8s/installation/install-cli#install-a-previous-version). This page contains instructions on how to install a specific version of the `consul-k8s` CLI on Linux prior to running `consul-k8s install`.
diff --git a/website/content/docs/k8s/multiport/index.mdx b/website/content/docs/k8s/multiport/index.mdx
index 19cbfac03355..bd474ffec120 100644
--- a/website/content/docs/k8s/multiport/index.mdx
+++ b/website/content/docs/k8s/multiport/index.mdx
@@ -30,7 +30,6 @@ You can also configure Envoy proxies and sidecar behavior with the proxy configu
 
 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.
-1. Output the resource path with the `consul resource read` command.
 
 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).
 
diff --git a/website/content/docs/k8s/multiport/traffic-split.mdx b/website/content/docs/k8s/multiport/traffic-split.mdx
index 1a3077f2aa08..db8ec0fa29e4 100644
--- a/website/content/docs/k8s/multiport/traffic-split.mdx
+++ b/website/content/docs/k8s/multiport/traffic-split.mdx
@@ -77,8 +77,4 @@ Use the `kubectl` command to apply the resource to your Consul cluster.
 
 ```shell-session
 $ kubectl apply -f api-split.yaml
-```
-
-## Read the resource path
-
-[Final TODO]
\ No newline at end of file
+```
\ No newline at end of file

From 42a6ef005be016a7cd5e3218aba15449e7a19edd Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Wed, 1 Nov 2023 17:04:14 -0700
Subject: [PATCH 44/57] Tested instructions

---
 .../content/docs/k8s/multiport/configure.mdx  | 14 +++++++++++---
 .../docs/k8s/multiport/traffic-split.mdx      | 19 +++++++++++++------
 2 files changed, 24 insertions(+), 9 deletions(-)

diff --git a/website/content/docs/k8s/multiport/configure.mdx b/website/content/docs/k8s/multiport/configure.mdx
index 45334dd89d7f..5ce70700b8fc 100644
--- a/website/content/docs/k8s/multiport/configure.mdx
+++ b/website/content/docs/k8s/multiport/configure.mdx
@@ -313,7 +313,7 @@ metadata:
 spec:
   destination:
     identityName: api
-  action: allow
+  action: ACTION_ALLOW
   permissions:
     - sources:
         - identityName: web
@@ -333,7 +333,7 @@ metadata:
 spec:
   destination:
     identityName: api
-  action: allow
+  action: ACTION_ALLOW
   permissions:
     - sources:
         - identityName: web
@@ -355,12 +355,16 @@ api-5784b54bcc-tp98l                           3/3     Running   0          6m55
 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. 
+Set environment variables to remember the pod name for the web workload for use in future commands.
+
+
 
 ```shell-session
 $ export WEB_POD=web-6dcbd684bc-gk8n5
 ```
 
+
+
 ### 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.
@@ -369,6 +373,8 @@ Use the `web` Pod's name to open a shell session and test the `api` service on b
 
 
 
+Test the `api` service on port 80.
+
 ```shell-session
 $ kubectl exec -it ${WEB_POD} -c web -- curl api:80
 ```
@@ -383,6 +389,8 @@ $ kubectl exec -it ${WEB_POD} -c web -- curl api:90
 
 
 
+Test the `api` service on port 80.
+
 ```shell-session
 $ kubectl exec -it ${WEB_POD} -c web -- curl api:80
 ```
diff --git a/website/content/docs/k8s/multiport/traffic-split.mdx b/website/content/docs/k8s/multiport/traffic-split.mdx
index db8ec0fa29e4..5ac37842dff7 100644
--- a/website/content/docs/k8s/multiport/traffic-split.mdx
+++ b/website/content/docs/k8s/multiport/traffic-split.mdx
@@ -36,8 +36,7 @@ The following example splits traffic for the `api` service. TCP traffic for serv
 apiVersion: mesh.consul.hashicorp.com/v2beta1
 kind: TCPRoute
 metadata:
-  name: api-split
-  namespace: default
+  name: api
 spec:
   parentRefs:
     - ref:
@@ -46,7 +45,7 @@ spec:
           groupVersion: v2beta1
           kind: Service
         name: api
-      port: "api-workload"
+      port: "admin"
   rules:
     - backendRefs:
       - backendRef:
@@ -56,7 +55,7 @@ spec:
               groupVersion: v2beta1
               kind: Service
             name: api
-          port: "api-workload"
+          port: "api"
         weight: 50
       - backendRef:
           ref: 
@@ -65,7 +64,7 @@ spec:
               groupVersion: v2beta1
               kind: Service
             name: api
-          port: "admin-workload"
+          port: "admin"
         weight: 50
 ```
 
@@ -77,4 +76,12 @@ Use the `kubectl` command to apply the resource to your Consul cluster.
 
 ```shell-session
 $ kubectl apply -f api-split.yaml
-```
\ No newline at end of file
+```
+
+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
+```
+
+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.
\ No newline at end of file

From f7fad9bfb5df23fb0d44cb874305a98eef2e1dad Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Wed, 1 Nov 2023 17:22:59 -0700
Subject: [PATCH 45/57] More updates based on testing

---
 .../k8s/multiport/reference/httproute.mdx     |  8 +-
 .../multiport/reference/resource-command.mdx  | 82 +++++++++++++++++--
 .../docs/k8s/multiport/reference/tcproute.mdx |  8 +-
 .../reference/trafficpermissions.mdx          |  2 +-
 4 files changed, 82 insertions(+), 18 deletions(-)

diff --git a/website/content/docs/k8s/multiport/reference/httproute.mdx b/website/content/docs/k8s/multiport/reference/httproute.mdx
index e06a1ed34d65..dcb4ab464371 100644
--- a/website/content/docs/k8s/multiport/reference/httproute.mdx
+++ b/website/content/docs/k8s/multiport/reference/httproute.mdx
@@ -752,7 +752,7 @@ The following examples demonstrate common HTTP route CRD configuration patterns
 
 ### 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-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.
+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
@@ -769,7 +769,7 @@ spec:
           kind: Service
         name: api
       # The configuration targets the workload port, not the service port.
-      port: "api-workload"
+      port: "api"
   rules:
     - backendRefs:
       - backendRef:
@@ -780,7 +780,7 @@ spec:
               kind: Service
             name: api
           # The configuration targets the workload port, not the service port.
-          port: "api-workload"
+          port: "api"
         weight: 50
       - backendRef:
           ref: 
@@ -790,7 +790,7 @@ spec:
               kind: Service
             name: api
           # The configuration targets the workload port, not the service port.
-          port: "admin-workload"
+          port: "admin"
         weight: 50
 ```
 
diff --git a/website/content/docs/k8s/multiport/reference/resource-command.mdx b/website/content/docs/k8s/multiport/reference/resource-command.mdx
index 6f7470b16c86..0b8af4752880 100644
--- a/website/content/docs/k8s/multiport/reference/resource-command.mdx
+++ b/website/content/docs/k8s/multiport/reference/resource-command.mdx
@@ -36,7 +36,7 @@ You can issue the following subcommands with the `consul resource` command.
 
 `consul resource apply` writes or updates a resource at a given file path. 
 
-The following table shows the required [ACLs permissions](/consul/api-docs/api-structure#authentication) to run the `apply` command:
+The following table shows the required [ACLs permission](/consul/api-docs/api-structure#authentication) to run the `apply` command:
 
 | ACL Required |
 | ------------ |
@@ -51,14 +51,14 @@ The following table shows the required [ACLs permissions](/consul/api-docs/api-s
 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.yaml
+$ 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 [ACLs permissions](/consul/api-docs/api-structure#authentication) to run the `delete` command:
+The following table shows the required [ACL permissions](/consul/api-docs/api-structure#authentication) to run the `delete` command:
 
 | ACL Required |
 | ------------ |
@@ -73,7 +73,7 @@ The following table shows the required [ACLs permissions](/consul/api-docs/api-s
 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.yaml
+$ consul resource delete -f=trafficpermissions.hcl
 ```
 
 ### `list`
@@ -82,7 +82,7 @@ $ consul resource delete -f=trafficpermissions.yaml
 
 This command must be issued with a resource type. All resource definitions include a `type` configuration block that contains a `group`, `groupVersion`, and `kind`. By formatting the `type` on the command line as `group.groupVersion.kind`, you can return all resources with a matching `type` in the configuration.
 
-The following table shows the required [ACLs permissions](/consul/api-docs/api-structure#authentication) to run the `list` command:
+The following table shows the required [ACL permissions](/consul/api-docs/api-structure#authentication) to run the `list` command:
 
 | ACL Required |
 | ------------ |
@@ -106,9 +106,9 @@ $ consul resource list catalog.v2beta1.Service card-processor -partition=billing
 
 ### `read`
 
-`consul resource read` outputs names of resources according to the type of resource or where the resource is applied.
+`consul resource read` outputs information about resources according to the type of resource or where the resource is applied.
 
-The following table shows the required [ACLs permissions](/consul/api-docs/api-structure#authentication) to run the `read` command:
+The following table shows the required [ACL permissions](/consul/api-docs/api-structure#authentication) to run the `read` command:
 
 | ACL Required |
 | ------------ |
@@ -124,8 +124,72 @@ The following table shows the required [ACLs permissions](/consul/api-docs/api-s
 
 #### Example usage
 
-The following command outputs the resource that applies to a specific `card-processor` service when the service runs on the `billing partition` in the `payments` namespace on peer cluster `dc2-store`.
+In the following example, the output for reading the resource for the `web` service includes information such as ports, virtual IPs, and workload identity.
 
 ```shell-session hideClipboard
-$ consul resource read catalog.v2beta1.Service card-processor -partition=billing -namespace=payments -peer=dc2-store
+$ 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",
+            "peerName": "local"
+        },
+        "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"
+}
 ```
diff --git a/website/content/docs/k8s/multiport/reference/tcproute.mdx b/website/content/docs/k8s/multiport/reference/tcproute.mdx
index f2666f28e500..b914c9a8f726 100644
--- a/website/content/docs/k8s/multiport/reference/tcproute.mdx
+++ b/website/content/docs/k8s/multiport/reference/tcproute.mdx
@@ -297,7 +297,7 @@ The following examples demonstrate common TCPRoute CRD configuration patterns fo
 
 ### 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.
+The following example splits traffic for the `api` service. TCP 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
@@ -314,7 +314,7 @@ spec:
           kind: Service
         name: api
       # The configuration targets the workload port, not the service port.
-      port: "api-workload"
+      port: "api"
   rules:
     - backendRefs:
       - backendRef:
@@ -325,7 +325,7 @@ spec:
               kind: Service
             name: api
           # The configuration targets the workload port, not the service port.
-          port: "api-workload"
+          port: "api"
         weight: 50
       - backendRef:
           ref: 
@@ -335,6 +335,6 @@ spec:
               kind: Service
             name: api
           # The configuration targets the workload port, not the service port.
-          port: "admin-workload"
+          port: "admin"
         weight: 50
 ```
\ No newline at end of file
diff --git a/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx b/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
index 5d2f61c36cac..457903743504 100644
--- a/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
+++ b/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
@@ -212,7 +212,7 @@ metadata:
 spec:
   destination:
     identityName: api
-  action: deny
+  action: ACTION_DENY
   permissions:
     - sources:
         - identityName: web

From ea54ebb80da712734565897d1d0eaf9b8bd577e8 Mon Sep 17 00:00:00 2001
From: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
Date: Thu, 2 Nov 2023 08:14:19 -0700
Subject: [PATCH 46/57] Apply suggestions from code review

Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
---
 .../content/docs/architecture/catalog/v2.mdx  |  2 +-
 .../k8s/multiport/reference/grpcroute.mdx     | 25 ++++++++++---------
 .../reference/proxyconfiguration.mdx          | 13 +++-------
 3 files changed, 18 insertions(+), 22 deletions(-)

diff --git a/website/content/docs/architecture/catalog/v2.mdx b/website/content/docs/architecture/catalog/v2.mdx
index 837c6ca59f56..2b45df3dd0c3 100644
--- a/website/content/docs/architecture/catalog/v2.mdx
+++ b/website/content/docs/architecture/catalog/v2.mdx
@@ -89,7 +89,7 @@ The following resources are available to help you use the v2 catalog API:
 
 ### Usage documentation
 
-- [Multi-port services overview](/consul/docs/k8s/multiport/configure)
+- [Multi-port services overview](/consul/docs/k8s/multiport)
 - [Configure multi-port services](/consul/docs/k8s/multiport/configure)
 
 ### Reference documentation
diff --git a/website/content/docs/k8s/multiport/reference/grpcroute.mdx b/website/content/docs/k8s/multiport/reference/grpcroute.mdx
index e2376490731e..cab90fd9d545 100644
--- a/website/content/docs/k8s/multiport/reference/grpcroute.mdx
+++ b/website/content/docs/k8s/multiport/reference/grpcroute.mdx
@@ -355,6 +355,7 @@ Specifies the type of resource that the configuration routes traffic to. To refe
 - 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 Kubenretes 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     |
@@ -384,9 +385,9 @@ 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 |
+| `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
 
@@ -408,9 +409,9 @@ 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 |
+| `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
 
@@ -467,9 +468,9 @@ 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 |
+| `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
 
@@ -491,9 +492,9 @@ 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 |
+| `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
 
diff --git a/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx b/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx
index 636c6528d46a..36986be6d759 100644
--- a/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx
+++ b/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx
@@ -252,7 +252,7 @@ Refer to [Envoy proxy escape-hatch overrides](/consul/docs/connect/proxies/envoy
 
 ### `spec.bootstrapConfig.prometheusBindAddr`
 
-Specifies that the proxy should expose a Prometheus metrics endpoint to the _public_ network. It must be supplied in the form `ip:port` and port and 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.
+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
 
@@ -309,7 +309,7 @@ Specifies that the proxy should expose the `/stats` prefix to the _public_ netwo
 
 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-boostrapconfig-statstags) and enables full control over dynamic tag replacements.
+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.
 
@@ -329,7 +329,7 @@ Refer to [Envoy proxy advanced bootstrap options](/consul/docs/connect/proxies/e
 
 ### `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-boostrapconfig-dogstatsdurl).
+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.
 
@@ -458,14 +458,9 @@ Specifies the output type for the access logs.
   - `LOG_SINK_TYPE_STDERR`
   - `LOG_SINK_TYPE_STDOUT`
 
-#### Values
-
-- Default: None
-- Data type: String
-
 ### `spec.dynamicConfig.exposeConfig`
 
-Specifies configurations to expose the proxy.
+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.
 

From 8d3e88e9b52bdbceac4eac6e55efaf5ff55ffab7 Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Thu, 2 Nov 2023 09:05:57 -0700
Subject: [PATCH 47/57] Multi-port traffic permissions example

---
 .../reference/trafficpermissions.mdx          | 21 +++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx b/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
index 457903743504..2813fbb48424 100644
--- a/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
+++ b/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
@@ -200,6 +200,27 @@ Specifies a port name that the Kubernetes Service exposes at the destination.
 
 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 services
 
 The following example configures traffic permissions to deny traffic when the `web` service makes a request to the `api` service on the `admin` port.

From 0b0b4c9f036d37fac48657a59a2a62655c3d017b Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Thu, 2 Nov 2023 10:10:32 -0700
Subject: [PATCH 48/57] parent/child alignment

---
 .../docs/k8s/multiport/reference/proxyconfiguration.mdx   | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx b/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx
index 36986be6d759..0941700c7d41 100644
--- a/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx
+++ b/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx
@@ -60,11 +60,11 @@ The following list outlines field hierarchy, language-specific data types, and r
     - [`localClusterJson`](#spec-dynamicconfig-localclusterjson): string
     - [`localConnection`](#spec-dynamicconfig-localconnection): map
       - [`connectTimeout`](#spec-dynamicconfig-localconnection-connecttimeout): map
-       - [`nanos`](#spec-dynamicconfig-localconnection-connecttimeout): integer
-       - [`seconds`](#spec-dynamicconfig-localconnection-connecttimeout): integer
+        - [`nanos`](#spec-dynamicconfig-localconnection-connecttimeout): integer
+        - [`seconds`](#spec-dynamicconfig-localconnection-connecttimeout): integer
       - [`requestTimeout`](#spec-dynamicconfig-localconnection-requesttimeout): map
-       - [`nanos`](#spec-dynamicconfig-localconnection-requesttimeout): integer
-       - [`seconds`](#spec-dynamicconfig-localconnection-requesttimeout): integer
+        - [`nanos`](#spec-dynamicconfig-localconnection-requesttimeout): integer
+        - [`seconds`](#spec-dynamicconfig-localconnection-requesttimeout): integer
     - [`meshGatewayMode`](#spec-dynamicconfig-meshgatewaymode): string
     - [`mode`](#spec-dynamicconfig-mode): string
     - [`publicListenerJson`](#spec-dynamicconfig-publiclistenerjson): string

From 464e4fc520381f991a70fc5b4c2fcc0a8a49779b Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Thu, 2 Nov 2023 10:17:00 -0700
Subject: [PATCH 49/57] Dataplanes requirement

---
 website/content/docs/k8s/multiport/configure.mdx | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/website/content/docs/k8s/multiport/configure.mdx b/website/content/docs/k8s/multiport/configure.mdx
index 5ce70700b8fc..6bec2ea06d1e 100644
--- a/website/content/docs/k8s/multiport/configure.mdx
+++ b/website/content/docs/k8s/multiport/configure.mdx
@@ -21,7 +21,10 @@ Registering multi-port services with Consul requires Kubernetes. Multi-port serv
 The following minimum versions are required:
 
 - Consul v1.17.0
-- `consul-k8s` CLI v1.3.0+ or `hashicorp/consul` Helm chart release v1.3.0+
+- `consul-k8s` CLI v1.3.0 or `hashicorp/consul` Helm chart release v1.3.0
+- `consul-dataplanes` v1.3.0
+
+The required version of Consul dataplanes deploy automatically when using the required `consul-k8s` version. To change the dataplane version, [modify `imageConsulDataplane`](/consul/docs/k8s/helm#v-global-imageconsuldataplane).
 
 For more information about upgrading versions for `consul-k8s` and Helm charts, refer to [Update the Consul K8s CLI](/consul/docs/k8s/upgrade/upgrade-cli) and [Upgrade Helm chart version](/consul/docs/k8s/upgrade#upgrade-helm-chart-version).
 

From 7d679fd5d3c717ce25abd272428e11f452ae536a Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Thu, 2 Nov 2023 11:38:52 -0700
Subject: [PATCH 50/57] Update version-specific CLI install

---
 .../content/docs/k8s/multiport/configure.mdx   | 18 ++++--------------
 1 file changed, 4 insertions(+), 14 deletions(-)

diff --git a/website/content/docs/k8s/multiport/configure.mdx b/website/content/docs/k8s/multiport/configure.mdx
index 6bec2ea06d1e..cbd781ad2dc0 100644
--- a/website/content/docs/k8s/multiport/configure.mdx
+++ b/website/content/docs/k8s/multiport/configure.mdx
@@ -24,9 +24,11 @@ The following minimum versions are required:
 - `consul-k8s` CLI v1.3.0 or `hashicorp/consul` Helm chart release v1.3.0
 - `consul-dataplanes` v1.3.0
 
-The required version of Consul dataplanes deploy automatically when using the required `consul-k8s` version. To change the dataplane version, [modify `imageConsulDataplane`](/consul/docs/k8s/helm#v-global-imageconsuldataplane).
+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). 
 
-For more information about upgrading versions for `consul-k8s` and Helm charts, refer to [Update the Consul K8s CLI](/consul/docs/k8s/upgrade/upgrade-cli) and [Upgrade Helm chart version](/consul/docs/k8s/upgrade#upgrade-helm-chart-version).
+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).
 
 There are additional requirements for service mesh proxies in transparent proxy mode. This mode enables queries through Kube DNS instead of Consul DNS over permissive mTLS settings. For more information about the steps to configure global settings and enable permissive mTLS mode before registering a service, refer to the [onboard services in transparent mode workflow](/consul/docs/k8s/connect/onboarding-tproxy-mode#workflow).
 
@@ -68,18 +70,6 @@ Then install Consul to your Kubernetes cluster using either the `consul-k8s` CLI
 $ consul-k8s install -config-file=values.yaml
 ```
 
-To download a compatible version of `consul-k8s` and add it to your `PATH`, run the following commands instead:
-
-```shell-session
-$ export VERSION=1.3.0 && \
-    curl --location "https://releases.hashicorp.com/consul-k8s/${VERSION}/consul-k8s_${VERSION}_darwin_amd64.zip" --output consul-k8s-cli.zip \
-    unzip -o consul-k8s-cli.zip -d ~/consul-k8s \
-    export PATH=$PATH:$HOME/consul-k8s \
-    consul-k8s install -config-file=values.yaml
-```
-
-For platforms other than Mac OSX amd64, refer to [Install a previous version](/consul/docs/k8s/installation/install-cli#install-a-previous-version). This page contains instructions on how to install a specific version of the `consul-k8s` CLI on Linux prior to running `consul-k8s install`.
-
 
 
 

From 3255c983b4a3fd86272a98bc6379c7299753b0c1 Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Thu, 2 Nov 2023 12:45:21 -0700
Subject: [PATCH 51/57] Method 2

---
 .../docs/k8s/multiport/traffic-split.mdx      | 84 +++++++++++++++++--
 1 file changed, 79 insertions(+), 5 deletions(-)

diff --git a/website/content/docs/k8s/multiport/traffic-split.mdx b/website/content/docs/k8s/multiport/traffic-split.mdx
index 5ac37842dff7..2f7276b39b45 100644
--- a/website/content/docs/k8s/multiport/traffic-split.mdx
+++ b/website/content/docs/k8s/multiport/traffic-split.mdx
@@ -16,7 +16,14 @@ This page describes the process for splitting TCP, HTTP, and gRPC traffic betwee
 
 ## Prerequisites
 
-Splitting traffic between two ports of a multi-port service requires the [v2 catalog API](/consul/docs/architecture/catalog/v2). For guidance on enabling the v2 catalog, deploying multi-port services, and applying traffic permissions to them, refer to [configure multi-port services](/consul/docs/k8s/multiport/configure).
+Splitting traffic between two ports of a multi-port service requires the [v2 catalog API](/consul/docs/architecture/catalog/v2).
+
+In addition, how you define a multi-port service affects how Services are addressed in Kubernetes. The instructions on this page offer examples for two configuration methods:
+
+- **Method 1**: Define a single Kubernetes Service that exposes multiple ports
+- **Method 2**: Define multiple Kubernetes Services that expose individual ports
+
+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
 
@@ -24,11 +31,16 @@ Complete the following steps to implement a split in TCP traffic between two ser
 
 1. Define the resource's behavior in a custom resource definition (CRD).
 1. Apply the resource to your cluster.
-1. Output the resource path with the `consul resource read` command.
 
 ## 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.
+The following example splits traffic for the services in the `api` Pod.
+
+
+
+
+
+TCP traffic for services registered to the Consul catalog that are available at the `admin` 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.
 
 
 
@@ -36,7 +48,7 @@ The following example splits traffic for the `api` service. TCP traffic for serv
 apiVersion: mesh.consul.hashicorp.com/v2beta1
 kind: TCPRoute
 metadata:
-  name: api
+  name: api-split
 spec:
   parentRefs:
     - ref:
@@ -68,6 +80,51 @@ spec:
         weight: 50
 ```
 
+
+
+
+
+
+TCP traffic for services registered to the Consul catalog that are available at the `api-admin` 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 `api-admin` port.
+
+
+
+```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-admin
+      port: "admin"
+  rules:
+    - backendRefs:
+      - backendRef:
+          ref: 
+            type:
+              group: catalog
+              groupVersion: v2beta1
+              kind: Service
+            name: api
+          port: "api"
+        weight: 50
+      - backendRef:
+          ref: 
+            type:
+              group: catalog
+              groupVersion: v2beta1
+              kind: Service
+            name: api-admin
+          port: "admin"
+        weight: 50
+```
+
 
 
 ## Apply the resource
@@ -78,10 +135,27 @@ Use the `kubectl` command to apply the resource to your Consul cluster.
 $ kubectl apply -f api-split.yaml
 ```
 
-Then, open a shell session in the `web` container and test the `api` service on port 90. 
+
+
+
+
+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
 ```
 
+
+
+
+
+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
+```
+
+
+
+
 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.
\ No newline at end of file

From 48bc056e17e9bb7b95a43cdc7b1ddc96237f7229 Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Thu, 2 Nov 2023 12:56:21 -0700
Subject: [PATCH 52/57] Tab fix

---
 website/content/docs/k8s/multiport/traffic-split.mdx | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/website/content/docs/k8s/multiport/traffic-split.mdx b/website/content/docs/k8s/multiport/traffic-split.mdx
index 2f7276b39b45..23a714f12466 100644
--- a/website/content/docs/k8s/multiport/traffic-split.mdx
+++ b/website/content/docs/k8s/multiport/traffic-split.mdx
@@ -127,6 +127,9 @@ spec:
 
 
 
+
+
+
 ## Apply the resource
 
 Use the `kubectl` command to apply the resource to your Consul cluster.

From ac82bda1c278d4cb68ad12cf0743dbf2529442d7 Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Fri, 3 Nov 2023 09:15:58 -0700
Subject: [PATCH 53/57] Consul resource updates

---
 .../multiport/reference/resource-command.mdx  | 211 +++++++++++++++++-
 website/content/docs/service-discovery.mdx    |   0
 website/content/docs/service-mesh.mdx         |   0
 3 files changed, 203 insertions(+), 8 deletions(-)
 create mode 100644 website/content/docs/service-discovery.mdx
 create mode 100644 website/content/docs/service-mesh.mdx

diff --git a/website/content/docs/k8s/multiport/reference/resource-command.mdx b/website/content/docs/k8s/multiport/reference/resource-command.mdx
index 0b8af4752880..9673b5e26938 100644
--- a/website/content/docs/k8s/multiport/reference/resource-command.mdx
+++ b/website/content/docs/k8s/multiport/reference/resource-command.mdx
@@ -11,6 +11,8 @@ Command: `consul resource`
 
 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).
 
+The `consul resource` command has usage limitations in Consul v1.17.0. The CLI does not accept partition, namespace, and peer arguments, but the v2 catalog outputs this information when you add the `read` or `list` subcommand. In addition, do not use the `apply` and `delete` commands with Consul on Kubernetes in this release. Use the `kubectl` command to apply or delete resources instead. Refer to [configure multi-port services](/consul/docs/k8s/multiport/configure) for an example of the workflow to apply resources.
+
 ## Usage
 
 ```text
@@ -34,7 +36,7 @@ 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. 
+`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:
 
@@ -56,7 +58,7 @@ $ consul resource apply -f=trafficpermissions.hcl
 
 ### `delete`
 
-`consul resource delete`removes a Consul resource at a given file path.
+`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:
 
@@ -78,7 +80,7 @@ $ consul resource delete -f=trafficpermissions.hcl
 
 ### `list`
 
-`consul resource list` outputs names of resources according to the type of resource and the location where the resource is applied. 
+`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. All resource definitions include a `type` configuration block that contains a `group`, `groupVersion`, and `kind`. By formatting the `type` on the command line as `group.groupVersion.kind`, you can return all resources with a matching `type` in the configuration.
 
@@ -98,15 +100,209 @@ The following flags enable you to filter results.
 
 #### Example usage
 
-The following command lists resources that apply to the `card-processor` service when the service runs on the `billing partition` in the `payments` namespace on peer cluster `dc2-store`.
+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 card-processor -partition=billing -namespace=payments -peer=dc2-store
+$ 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",
+                    "peerName": "local"
+                },
+                "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",
+                    "peerName": "local"
+                },
+                "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",
+                    "peerName": "local"
+                },
+                "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 of resource or where the resource is applied.
+`consul resource read` outputs information about resources according to the type and name of the resource.
 
 The following table shows the required [ACL permissions](/consul/api-docs/api-structure#authentication) to run the `read` command:
 
@@ -119,8 +315,7 @@ The following table shows the required [ACL permissions](/consul/api-docs/api-st
 - `-partition=` - The partition where the resource applies.
 - `-namespace=` - The namespace where the resource applies.
 - `-peer=` - The clusters with established cluster peering connections where the resource applies.
-- `-consistent=` - Determines whether Consul returns stale resource information. Set this flag to `true` to prevent Consul from returning stale information.
-- `-json` - Include this flag to output the response in JSON format.
+- `-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.
 
 #### Example usage
 
diff --git a/website/content/docs/service-discovery.mdx b/website/content/docs/service-discovery.mdx
new file mode 100644
index 000000000000..e69de29bb2d1
diff --git a/website/content/docs/service-mesh.mdx b/website/content/docs/service-mesh.mdx
new file mode 100644
index 000000000000..e69de29bb2d1

From 8ba577bd04f67c7563a253b9c2923177f04dcef6 Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Fri, 3 Nov 2023 09:20:52 -0700
Subject: [PATCH 54/57] nav fix

---
 website/content/docs/service-discovery.mdx | 0
 website/content/docs/service-mesh.mdx      | 0
 2 files changed, 0 insertions(+), 0 deletions(-)
 delete mode 100644 website/content/docs/service-discovery.mdx
 delete mode 100644 website/content/docs/service-mesh.mdx

diff --git a/website/content/docs/service-discovery.mdx b/website/content/docs/service-discovery.mdx
deleted file mode 100644
index e69de29bb2d1..000000000000
diff --git a/website/content/docs/service-mesh.mdx b/website/content/docs/service-mesh.mdx
deleted file mode 100644
index e69de29bb2d1..000000000000

From 4ee651e2f211103361af8ffd84546c1eafbd635a Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Fri, 3 Nov 2023 15:20:52 -0700
Subject: [PATCH 55/57] Catalog groups

---
 .../content/docs/architecture/catalog/v2.mdx  | 36 ++++++++++---------
 .../docs/k8s/multiport/reference/tcproute.mdx |  1 +
 2 files changed, 21 insertions(+), 16 deletions(-)

diff --git a/website/content/docs/architecture/catalog/v2.mdx b/website/content/docs/architecture/catalog/v2.mdx
index 2b45df3dd0c3..eaa49874a110 100644
--- a/website/content/docs/architecture/catalog/v2.mdx
+++ b/website/content/docs/architecture/catalog/v2.mdx
@@ -1,7 +1,7 @@
 ---
 layout: docs
 page_title: v2 Catalog API
-description: Learn about version 2 of the Consul catalog, which uses GAMMA specified resources. Learn how the v2 catalog corresponds to the v1 catalog and Kubernetes resources..
+description: Learn about version 2 of the Consul catalog, which uses GAMMA specified resources. Learn how the v2 catalog corresponds to the v1 catalog and Kubernetes resources.
 ---
 
 # v2 Catalog API
@@ -32,24 +32,28 @@ The v2 catalog API is available alongside the existing v1 catalog API, but the c
 
 ## 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 still tracks services and nodes for Consul, but replaces service instances with _workloads_ and _workload identites_.
+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 still tracks services and nodes for Consul, but replaces service instances with _workloads_ and _workload identites_, which belong to different catalog groups.
 
-The following table describes resources in the v2 catalog and compares them to the v1 catalog and Kubernetes resources. It also states whether these resources are defined by the user or computed by Consul when it registers a service.
+Traffic permissions are part of the `auth` group, and the [`TrafficPermissions` CRD](/consul/docs/k8s/multiport/reference/trafficpermissions) configures permissions according to an `identityName` that corresponds to the other resource in the `auth` group, workload identity.
 
-| Catalog v2 resource | Description | Catalog v1 resource analogue | Kubernetes resource analogue | Source |
-| :------------------ | :---------- | :--------------------------- | :--------------------------- | :----- |
-| Service | The name of the service Consul registers a workload under. | Service | None  | Defined by user in Kubernetes |
-| Node | The address of the node where the workload runs. | Node | [Kubernetes Node](https://kubernetes.io/docs/concepts/architecture/nodes/) | Computed by Consul |
-| Workload | 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/) | Defined by user in Kubernetes |
-| Workload identities | Provides a distinct identity for a workload to assume and is used for Traffic Permissions. | Service instance | [Kubernetes Service Accounts](https://kubernetes.io/docs/concepts/security/service-accounts/) | Defined by user in Kubernetes |
-| Service endpoints | 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 | A resource for reporting the health status of a workload. | Service instance health status | None | Computed by Consul |
-| Health check | 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) | Defined by user in Kubernetes |
-| Proxy configuration | Represents a configuration for a sidecar or gateway proxy. | `Proxy` field in service definition | None | Defined by user in Kubernetes or Consul |
-| Destinations | Represents explicit service upstreams. | [Proxy Configuration](/consul/docs/connect/proxies/envoy#envoy-proxy-configuration-for-service-mesh) | [Upstream Service annotation](/consul/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams)  | Defined by user in Kubernetes |
-| Traffic permissions | Enables L4 traffic authorization according to workload identity instead of service identity. | [Service intentions](/consul/docs/connect/intentions) | None | Defined by user in Consul |
+The [`HTTPRoute`](/consul/docs/k8s/multiport/reference/httproute), [`GRPCRoute`](/consul/docs/k8s/multiport/reference/grpcroute), and [`TCPRoute`](/consul/docs/k8s/multiport/reference/tcproute) CRDS include `type` blocks that use a `group.groupVersion.kind` syntax to reference Consul services. Because a service is part of the `catalog` group, their reference types are formatted as `catalog.v2beta1.Service`.
 
-Refer to [`consul resource`](/consul/docs/k8s/multiport/reference/resource-command) for more information about using the Consul CLI to interact with the v2 catalog.
+The following table describes resources in the v2 catalog, including their `group`, how they 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 | Catalog v2 `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 |
+
+You can also use the `consul resource` command to return information about resources using the `group.groupVersion.kind` syntax. Refer to [`consul resource`](/consul/docs/k8s/multiport/reference/resource-command) for more information.
 
 ## Changes to Consul’s existing architecture
 
diff --git a/website/content/docs/k8s/multiport/reference/tcproute.mdx b/website/content/docs/k8s/multiport/reference/tcproute.mdx
index b914c9a8f726..9dd8a4ca1bed 100644
--- a/website/content/docs/k8s/multiport/reference/tcproute.mdx
+++ b/website/content/docs/k8s/multiport/reference/tcproute.mdx
@@ -274,6 +274,7 @@ Specifies the type of resource that the configuration routes traffic to. To refe
 - 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 Kubenretes 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     |

From b70c39f775d471984825f4bbb7eb0e876d04eea7 Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Fri, 3 Nov 2023 15:45:01 -0700
Subject: [PATCH 56/57] Catalog `group` info

---
 website/content/docs/architecture/catalog/v2.mdx         | 2 +-
 .../docs/k8s/multiport/reference/resource-command.mdx    | 9 +++++++--
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/website/content/docs/architecture/catalog/v2.mdx b/website/content/docs/architecture/catalog/v2.mdx
index eaa49874a110..c18255fa9ee3 100644
--- a/website/content/docs/architecture/catalog/v2.mdx
+++ b/website/content/docs/architecture/catalog/v2.mdx
@@ -36,7 +36,7 @@ Consul v1.17 introduces a new version of the catalog API designed to bridge diff
 
 Traffic permissions are part of the `auth` group, and the [`TrafficPermissions` CRD](/consul/docs/k8s/multiport/reference/trafficpermissions) configures permissions according to an `identityName` that corresponds to the other resource in the `auth` group, workload identity.
 
-The [`HTTPRoute`](/consul/docs/k8s/multiport/reference/httproute), [`GRPCRoute`](/consul/docs/k8s/multiport/reference/grpcroute), and [`TCPRoute`](/consul/docs/k8s/multiport/reference/tcproute) CRDS include `type` blocks that use a `group.groupVersion.kind` syntax to reference Consul services. Because a service is part of the `catalog` group, their reference types are formatted as `catalog.v2beta1.Service`.
+The [`HTTPRoute`](/consul/docs/k8s/multiport/reference/httproute), [`GRPCRoute`](/consul/docs/k8s/multiport/reference/grpcroute), and [`TCPRoute`](/consul/docs/k8s/multiport/reference/tcproute) CRDS are part of the `mesh` group, but they include `type` blocks that use a `group.groupVersion.kind` syntax to reference Consul services. Because a service is part of the `catalog` group, these CRDs refer to services using `catalog.v2beta1.Service`.
 
 The following table describes resources in the v2 catalog, including their `group`, how they compare to the v1 catalog and Kubernetes resources, and whether they are created by Kubernetes or computed by Consul when it registers a service.
 
diff --git a/website/content/docs/k8s/multiport/reference/resource-command.mdx b/website/content/docs/k8s/multiport/reference/resource-command.mdx
index 9673b5e26938..b7845787e3ab 100644
--- a/website/content/docs/k8s/multiport/reference/resource-command.mdx
+++ b/website/content/docs/k8s/multiport/reference/resource-command.mdx
@@ -82,7 +82,9 @@ $ consul resource delete -f=trafficpermissions.hcl
 
 `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. All resource definitions include a `type` configuration block that contains a `group`, `groupVersion`, and `kind`. By formatting the `type` on the command line as `group.groupVersion.kind`, you can return all resources with a matching `type` in the configuration.
+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/catalog/v2#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:
 
@@ -304,6 +306,8 @@ $ consul resource list catalog.v2beta1.Service
 
 `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/catalog/v2#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 |
@@ -316,10 +320,11 @@ The following table shows the required [ACL permissions](/consul/api-docs/api-st
 - `-namespace=` - The namespace where the resource applies.
 - `-peer=` - The clusters with established cluster peering connections 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
 
-In the following example, the output for reading the resource for the `web` service includes information such as ports, virtual IPs, and workload identity.
+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

From 64b2bb2f918d83bb1fc56dfa56be18bd6a0d77f9 Mon Sep 17 00:00:00 2001
From: boruszak 
Date: Mon, 6 Nov 2023 11:40:52 -0800
Subject: [PATCH 57/57] time formatting

---
 .../k8s/multiport/reference/grpcroute.mdx     | 34 ++++++-------------
 .../k8s/multiport/reference/httproute.mdx     | 34 ++++++-------------
 .../reference/proxyconfiguration.mdx          | 26 +++++---------
 .../reference/trafficpermissions.mdx          |  4 +--
 4 files changed, 30 insertions(+), 68 deletions(-)

diff --git a/website/content/docs/k8s/multiport/reference/grpcroute.mdx b/website/content/docs/k8s/multiport/reference/grpcroute.mdx
index cab90fd9d545..2373ff96a67d 100644
--- a/website/content/docs/k8s/multiport/reference/grpcroute.mdx
+++ b/website/content/docs/k8s/multiport/reference/grpcroute.mdx
@@ -78,12 +78,8 @@ The following list outlines field hierarchy, language-specific data types, and r
       - [`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): map
-        - [`nanos`](#spec-rules-timeouts-idle): number
-        - [`seconds`](#spec-rules-timeouts-idle): number
-      - [`request`](#spec-rules-timeouts-request): map
-        - [`nanos`](#spec-rules-timeouts-request): numberer
-        - [`seconds`](#spec-rules-timeouts-request): number
+      - [`idle`](#spec-rules-timeouts-idle): string
+      - [`request`](#spec-rules-timeouts-request): string
 
 ## Complete configuration
 
@@ -154,12 +150,8 @@ spec:
       onConnectFailure: false
       onStatusCodes: [400, 404]
     timeouts:
-      idle:
-        nanos: 15
-        seconds: 1
-      request:
-        nanos: 10
-        seconds: 1
+      idle: <1s>
+      request: <1s>
 ```
 
 ## Specification
@@ -669,29 +661,23 @@ Specifies timeout logic when routing gRPC traffic
 
 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: Map that can contain the following parameters:
-
-  | Parameter | Description                                                      | Data type | Default |
-  | :-------- | :--------------------------------------------------------------- | --------- | ------- |
-  | `nanos`   | Specifies the number of nanoseconds before triggering a timeout. | Integer   | None    |
-  | `seconds` | Specifies the number of seconds before triggering a timeout.     | Integer   | 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: Map that can contain the following parameters:
-
-  | Parameter | Description                                                      | Data type | Default |
-  | :-------- | :--------------------------------------------------------------- | --------- | ------- |
-  | `nanos`   | Specifies the number of nanoseconds before triggering a timeout. | Integer   | None    |
-  | `seconds` | Specifies the number of seconds before triggering a timeout.     | Integer   | None    |
+- Data type: String
 
 ## Examples
 
diff --git a/website/content/docs/k8s/multiport/reference/httproute.mdx b/website/content/docs/k8s/multiport/reference/httproute.mdx
index dcb4ab464371..377e5f3a7235 100644
--- a/website/content/docs/k8s/multiport/reference/httproute.mdx
+++ b/website/content/docs/k8s/multiport/reference/httproute.mdx
@@ -82,12 +82,8 @@ The following list outlines field hierarchy, language-specific data types, and r
       - [`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): map
-        - [`nanos`](#spec-rules-timeouts-idle): number
-        - [`seconds`](#spec-rules-timeouts-idle): number
-      - [`request`](#spec-rules-timeouts-request): map
-        - [`nanos`](#spec-rules-timeouts-request): number
-        - [`seconds`](#spec-rules-timeouts-request): number
+      - [`idle`](#spec-rules-timeouts-idle): string
+      - [`request`](#spec-rules-timeouts-request): string
 
 ## Complete configuration
 
@@ -162,12 +158,8 @@ spec:
       onConnectFailure: false
       onStatusCodes: [400, 404]
     timeouts:
-      idle:
-        nanos: 15
-        seconds: 1
-      request:
-        nanos: 10
-        seconds: 1
+      idle: <1s>
+      request: <1s>
 ```
 
 ## Specification
@@ -722,29 +714,23 @@ Specifies timeout logic when routing HTTP traffic
 
 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: Map that can contain the following parameters:
-
-  | Parameter | Description                                                      | Data type | Default |
-  | :-------- | :--------------------------------------------------------------- | --------- | ------- |
-  | `nanos`   | Specifies the number of nanoseconds before triggering a timeout. | Integer   | None    |
-  | `seconds` | Specifies the number of seconds before triggering a timeout.     | Integer   | 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: Map that can contain the following parameters:
-
-  | Parameter | Description                                                      | Data type | Default |
-  | :-------- | :--------------------------------------------------------------- | --------- | ------- |
-  | `nanos`   | Specifies the number of nanoseconds before triggering a timeout. | Integer   | None    |
-  | `seconds` | Specifies the number of seconds before triggering a timeout.     | Integer   | None    |
+- Data type: String
 
 ## Examples
 
diff --git a/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx b/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx
index 0941700c7d41..735a1f905b8a 100644
--- a/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx
+++ b/website/content/docs/k8s/multiport/reference/proxyconfiguration.mdx
@@ -59,12 +59,8 @@ The following list outlines field hierarchy, language-specific data types, and r
     - [`listenerTracingJson`](#spec-dynamicconfig-listenertracingjson): string
     - [`localClusterJson`](#spec-dynamicconfig-localclusterjson): string
     - [`localConnection`](#spec-dynamicconfig-localconnection): map
-      - [`connectTimeout`](#spec-dynamicconfig-localconnection-connecttimeout): map
-        - [`nanos`](#spec-dynamicconfig-localconnection-connecttimeout): integer
-        - [`seconds`](#spec-dynamicconfig-localconnection-connecttimeout): integer
-      - [`requestTimeout`](#spec-dynamicconfig-localconnection-requesttimeout): map
-        - [`nanos`](#spec-dynamicconfig-localconnection-requesttimeout): integer
-        - [`seconds`](#spec-dynamicconfig-localconnection-requesttimeout): integer
+      - [`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
@@ -586,29 +582,23 @@ Specify this field as a map containing a key/value. The map keys correspond to p
 
 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: Map that can contain the following parameters:
-
-  | Parameter | Description                                                      | Data type | Default |
-  | :-------- | :--------------------------------------------------------------- | --------- | ------- |
-  | `nanos`   | Specifies the number of nanoseconds before triggering a timeout. | Integer   | None    |
-  | `seconds` | Specifies the number of seconds before triggering a timeout.     | Integer   | 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: Map that can contain the following parameters:
-
-  | Parameter | Description                                                      | Data type | Default |
-  | :-------- | :--------------------------------------------------------------- | --------- | ------- |
-  | `nanos`   | Specifies the number of nanoseconds before triggering a timeout. | Integer   | None    |
-  | `seconds` | Specifies the number of seconds before triggering a timeout.     | Integer   | None    |
+- Data type: String
 
 ### `spec.dynamicConfig.meshGatewayMode`
 
diff --git a/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx b/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
index 2813fbb48424..0eae49e88b47 100644
--- a/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
+++ b/website/content/docs/k8s/multiport/reference/trafficpermissions.mdx
@@ -221,7 +221,7 @@ spec:
 
 ```
 
-### Deny traffic between services
+### Deny traffic between a service and a specific port
 
 The following example configures traffic permissions to deny traffic when the `web` service makes a request to the `api` service on the `admin` port.
 
@@ -229,7 +229,7 @@ The following example configures traffic permissions to deny traffic when the `w
 apiVersion: auth.consul.hashicorp.com/v2beta1
 kind: TrafficPermissions
 metadata:
-  name: web-to-api-port-deny
+  name: web-to-admin-port-deny
 spec:
   destination:
     identityName: api