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

docs: v2 and multiport updates for v1.18 (#20705) 

* Move consul resource page + redirect

* Updates for v1.18

* Remove beta warning

* Secondary datacenter constraint

* Clarify transparent proxy in prereqs

* Config entry mention

* requested improvements

* suggestions from review

* additional suggestion
This commit is contained in:
Jeff Boruszak 2024-02-27 17:14:25 -08:00 committed by GitHub
parent 930a20b523
commit 90d3a7c16d
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
19 changed files with 290 additions and 202 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
website/content/docs/k8s/multiport/reference/resource-command.mdx → website/content/commands/resource.mdx
View File

@ -9,9 +9,13 @@ description: >-
Command: `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). <Note>
The `consul resource` command has usage limitations in Consul v1.17.0. The CLI does not accept the partition and namespace 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. You must enable the [v2 catalog API](/consul/docs/concept/catalog/v2) to use this command.
</Note>
Use the `resource` command to apply, list, read, and delete resources when interacting with Consul's v2 catalog through the command line. For more information, refer to [v2 catalog API](/consul/docs/concept/catalog/v2).
## Usage ## Usage
@ -28,8 +32,6 @@ Subcommands:
read Read resource information 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 ## Subcommands
You can issue the following subcommands with the `consul resource` command. You can issue the following subcommands with the `consul resource` command.
@ -82,7 +84,7 @@ $ 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. `consul resource list` outputs information about resources according to the type of resource and the location where the resource is applied.
This command must be issued with a resource type. By formatting the type on the command line as `group.groupVersion.kind`, you can return all matching resources. For example, you can list information about services with `catalog.v2beta1.Service` and TCP routes with `mesh.v2beta1.TCPRoute`. Refer to [v2 catalog](/consul/docs/architecture/catalog/v2#catalog-structure) for more information. This command must be issued with a resource type. By formatting the type on the command line as `group.groupVersion.kind`, you can return all matching resources. For example, you can list information about services with `catalog.v2beta1.Service` and TCP routes with `mesh.v2beta1.TCPRoute`. Refer to [v2 catalog](/consul/docs/architecture/v2/catalog#catalog-structure) for more information.
Do not include a resource name when listing resources. Do not include a resource name when listing resources.
@ -302,7 +304,7 @@ $ consul resource list catalog.v2beta1.Service
`consul resource read` outputs information about resources according to the type and name of the resource. `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. This command must be issued with a resource type and a resource name. By formatting the type on the command line as `group.groupVersion.kind`, you can return all matching resources. For example, you can read information about services with `catalog.v2beta1.Service`, TCP routes with `mesh.v2beta1.TCPRoute`, and traffic permissions with `auth.v2beta1.TrafficPermissions`. Refer to [v2 catalog](/consul/docs/architecture/v2/catalog#catalog-structure) for more information.
The following table shows the required [ACL permissions](/consul/api-docs/api-structure#authentication) to run the `read` command: The following table shows the required [ACL permissions](/consul/api-docs/api-structure#authentication) to run the `read` command:

2
website/content/docs/architecture/catalog/v1.mdx → website/content/docs/architecture/catalog.mdx
View File

@ -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 tracks information about registered services through its catalog API. This API records user-defined information about the external services, such as their partitions and required health checks. It also records information that Consul assigns for its own operations, such as an ID for each service instance and the [Raft indices](/consul/docs/architecture/consensus) when the instance is registered and modified.
Consul uses v1 of the catalog API by default. Consul v1.17.0 and later ships with version 2 (v2) of the catalog API. V2 is intended for testing and development purposes. V1 and V2 of the catalog APIs cannot run concurrently in a Consul deployment. There is no migration path between catalog versions. For more information, refer to [Consul v2 Catalog API](/consul/docs/architecture/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/v2/catalog).
## Catalog structure ## Catalog structure

139
website/content/docs/architecture/catalog/v2.mdx
View File

@ -1,139 +0,0 @@
---
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.
---
# v2 Catalog API
<Warning>
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.
</Warning>
This topic provides information about version 2 (v2) of the Consul catalog API. The catalog tracks registered services and their locations for both service discovery and service mesh use cases.
Consul supports the v2 catalog for service mesh use cases on Kubernetes deployments only. For more information about Consul’s default catalog, refer to [v1 Catalog API](/consul/docs/architecture/catalog/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, which makes it 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. One major implication of this design is that communication in Consul’s service mesh is secured through Consul's ACL system, which requires that a Kubernetes ServiceAccount resource match the Service name. As a result, only one Kubernetes Service can represent a service instance in the v1 catalog.
The v2 catalog API aligns more closely with the [Kubernetes Gateway API's GAMMA initiative](https://gateway-api.sigs.k8s.io/concepts/gamma/), which conceptualizes a Kubernetes Service as having two facets:
- The Service _front end_ is a combination of cluster IP and DNS name
- The Service _back end_ is a collection of endpoint IPs
For more information about the differences between the two facets and their impact on how Kubernetes directs requests, refer to [The Different Facets of a Service](https://gateway-api.sigs.k8s.io/concepts/service-facets/) in the Kubernetes documentation.
Consul's v2 catalog API makes a similar distinction, enabling it associate Kubernetes Pods with multiple Kubernetes Services. As a direct result of this change in catalog structure, Consul can register Services and Pods with multiple ports. For more information about how the differences between the catalog API impacts other Consul operations, refer to [changes to Consul's existing architecture](#changes-to-consul-s-existing-architecture).
The v2 catalog API is available alongside the existing v1 catalog API, but the catalogs cannot be used simultaneously. The v2 catalog is disabled by default. This beta release is for testing and development purposes only. We do not recommend implementing v2 in production environments or migrating to v2 until the API is generally available.
## Catalog structure
Consul v1.17 introduces a new version of the catalog API designed to bridge differences between the Consul and Kubernetes data models. The v2 catalog API continues to track services and nodes for Consul, but it replaces service instances with _workloads_ and _workload identites_.
### Catalog resources
The following table describes resources in the v2 catalog, how they generally compare to the v1 catalog and Kubernetes resources, and whether they are created by Kubernetes or computed by Consul when it registers a service.
| Catalog v2 resource | Description | Catalog v1 analogue | Kubernetes analogue | Source |
| :------------------ | :---------- | :--------------------------- | :--------------------------- | :----- |
| Service | 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 | The address of the Consul 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/) | Created by Kubernetes |
| Workload identity | 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 | 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 | 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 | Represents a configuration for a sidecar or gateway proxy. | `Proxy` field in service definition | None | Created by Kubernetes or user CRD |
| Destinations | 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| Enables L4 traffic authorization according to workload identity instead of service identity. | [Service intentions](/consul/docs/connect/intentions) | None | Created by user CRD |
## Resource groups
Each resource is part of a _resource group_. These resource groups structure Consul's ability to target either an _individual workload identity_ or an _entire collection of workload endpoints_ when managing service mesh traffic. There are three resource groups in the v2 API:
- `auth` group: Resources apply to workload identity
- `catalog` group: Resources apply to all workloads associated with a service
- `mesh` group: Resources apply to either workload identities or all workloads
For example, traffic permissions are part of the `auth` group. Permissions allow or deny traffic according to the other v2 catalog resource in the `auth` group, the workload identity. Meanwhile, when Consul routes service mesh traffic it applies rules to workloads based on the Service, which is a resource in the `catalog` group.
One practical impact of resource groups is that the [HTTPRoute](/consul/docs/k8s/multiport/reference/httproute), [GRPCRoute](/consul/docs/k8s/multiport/reference/grpcroute), and [TCPRoute](/consul/docs/k8s/multiport/reference/tcproute) CRDs require you to specify a `name` and `type` in configuration blocks. The `catalog.v2beta1.Service` type indicates that the rules defined in these CRDs apply to all workloads registered in the Consul catalog under the given name.
You can also use the `consul resource` command to return information about Consul resources in each group using a `group.groupVersion.kind` syntax. Refer to [`consul resource`](/consul/docs/k8s/multiport/reference/resource-command) for more information.
The following table describes the Consul resources that belong to each resource group and the resource's `group.groupVersion.kind` syntax.
| Resource `group` | v2 resource | Consul resource syntax |
| :------------------ | :-------- | :---- |
| `auth` | Traffic permissions | `auth.v2beta1.TrafficPermissions` |
| `auth` | Workload identity | `auth.v2beta1.WorkloadIdentity` |
| `catalog` | Service | `catalog.v2beta1.Service` |
| `catalog` | Node | `catalog.v2beta1.Node` |
| `catalog` | Workload | `catalog.v2beta1.Workload` |
| `catalog` | Health status | `catalog.v2beta1.HealthStatus` |
| `catalog` | Destinations | `catalog.v2beta1.Destination` |
| `mesh` | GRPCRoute | `mesh.v2beta1.GRPCRoute` |
| `mesh` | HTTPRoute | `mesh.v2beta1.HTTPRoute` |
| `mesh` | Proxy configuration | `mesh.v2beta1.ProxyConfiguration` |
| `mesh` | TCPRoute | `mesh.v2beta1.TCPRoute` |
## 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 traffic permissions resource. This resource replaces the service intentions configuration entry, and enables authorized service-to-service communication for both L4 and L7 applications.
For more information about this resource, including example configurations, refer to [Traffic permissions configuration reference](/consul/docs/k8s/multiport/reference/trafficpermissions).
### HTTPRoute, GRPCRoute, and TCPRoute resources for traffic management
You can configure traffic management behavior such as service splitting in an `HTTPRoute`, `GRPCRoute`, or `TCPRoute` resource. In the v1 catalog, this behavior is defined in dedicated configuration entries. For examples, refer to [service splitter configuration entry reference](/consul/docs/connect/config-entries/service-splitter#examples).
For more information about these resource, including specifications and example configurations, refer to [HTTPRoute resource configuration reference](/consul/docs/k8s/multiport/reference/httproute), [GRPCRoute resource configuration reference](/consul/docs/k8s/multiport/reference/grpcroute), and [TCPRoute resource configuration reference](/consul/docs/k8s/multiport/reference/tcproute).
### New proxy configuration resource
In the v1 catalog, a service’s sidecar proxy and its behavior is [defined in the `Proxy` field of the service definition](/consul/docs/services/usage/define-services). You can also separately [define a service mesh proxy](/consul/docs/connect/proxies/deploy-service-mesh-proxies) and [configure proxy defaults](/consul/docs/connect/config-entries/proxy-defaults).
In the v2 catalog, the `ProxyConfiguration` resource configures a workload's sidecar proxy behavior according to Consul workload identity. Refer to [ProxyConfiguration resource configuration reference](/consul/docs/k8s/multiport/reference/proxyconfiguration) for more information.
## Constraints and limitations
Be aware of the following constraints and technical limitations on the v2 catalog API:
- The v2 catalog API only supports deployments using [Consul dataplanes](/consul/docs/connect/dataplane) instead of client agents. Consul on Kubernetes uses dataplanes by default.
- The v1 and v2 catalog APIs cannot run concurrently.
- 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 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)

55
website/content/docs/architecture/v2/catalog.mdx Normal file
View File

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

45
website/content/docs/architecture/v2/groups.mdx Normal file
View File

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

70
website/content/docs/architecture/v2/index.mdx Normal file
View File

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

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

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

49
website/content/docs/k8s/multiport/configure.mdx
View File

@ -6,22 +6,24 @@ description: Learn how to enable the v2 catalog and configure services to suppor
# Configure multi-port services # Configure multi-port services
<Warning> <Note>
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. Multi-port services and selecting workloads using multiple services require enabling [Consul's v2 architecture](/consul/docs/architecture/v2).
</Warning> </Note>
This page describes the process for integrating a service that uses multiple ports in a single container when running Consul on Kubernetes deployments. It includes example configurations to demonstrate an end-to-end deployment test of Consul's multi-port features. This page describes the process for integrating a service that uses multiple ports in a single container when running Consul on Kubernetes deployments. It includes example configurations to demonstrate an end-to-end deployment test of Consul's multi-port features.
## Prerequisites ## Requirements
Registering multi-port services with Consul requires Kubernetes. Multi-port services are not supported on VM deployments. Registering multi-port services with Consul requires Kubernetes. Multi-port services are not supported on VM deployments.
The following minimum versions are required: ### Version requirements
- Consul v1.17.0 Consul deployments that use the v2 catalog enabled must meet the following minimum version requirements:
- `consul-k8s` CLI v1.3.0 or `hashicorp/consul` Helm chart release v1.3.0
- Consul v1.18.0
- `consul-k8s` CLI v1.4.0 or `hashicorp/consul` Helm chart release v1.4.0
- `consul-dataplanes` v1.3.0 - `consul-dataplanes` v1.3.0
To install or update the `consul-k8s CLI`, refer to [install the latest version](/consul/docs/k8s/installation/install-cli#install-the-latest-version) or [upgrade the CLI](/consul/docs/k8s/upgrade/upgrade-cli#upgrade-the-cli). 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).
@ -30,7 +32,20 @@ The required version of Consul dataplanes deploy automatically when using the la
For more information about upgrading Helm charts, refer to [Upgrade Helm chart version](/consul/docs/k8s/upgrade#upgrade-helm-chart-version). 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). ### Annotation requirements
The examples on this page include the following required annotations in Kubernetes Deployment resources:
```yaml
spec:
template:
metadata:
annotations:
"consul.hashicorp.com/mesh-inject": "true"
"consul.hashicorp.com/transparent-proxy": "true"
```
These annotations inject Consul dataplanes and enable transparent proxy mode so that the services can curl each other on ports configured in the Kubernetes Service resource. Refer to [annotations and labels](/consul/docs/k8s/annotations-and-labels) for more information.
## Enable the v2 catalog ## Enable the v2 catalog
@ -42,7 +57,7 @@ To enable the v2 catalog and its support for multi-port services, set `global.ex
global: global:
enabled: true enabled: true
name: consul name: consul
image: hashicorp/consul:1.17.0 image: hashicorp/consul:1.18.0
datacenter: dc1 datacenter: dc1
tls: tls:
enabled: true enabled: true
@ -75,7 +90,7 @@ $ consul-k8s install -config-file=values.yaml
<Tab heading="Helm" group="helm"> <Tab heading="Helm" group="helm">
```shell-session ```shell-session
$ helm install consul hashicorp/consul --create-namespace --namespace consul --version 1.3.0 --values values.yaml $ helm install consul hashicorp/consul --create-namespace --namespace consul --version 1.4.0 --values values.yaml
``` ```
</Tab> </Tab>
@ -83,10 +98,10 @@ $ helm install consul hashicorp/consul --create-namespace --namespace consul --v
## Define the multi-port service ## Define the multi-port service
Consul's v2 catalog supports two methods for defining multi-port services in Kubernetes: Consul's v2 catalog supports two new methods for registering services on the mesh in Kubernetes:
- **Method 1**: Define a single Kubernetes Service that exposes multiple ports - **Method 1**: Register a Kubernetes service that select workloads which expose multiple ports
- **Method 2**: Define multiple Kubernetes Services that expose individual ports - **Method 2**: Register multiple Kubernetes Services that direct traffic to an explicit port on the same workload
These methods affect how the Services are addressed in Kubernetes. These methods affect how the Services are addressed in Kubernetes.
@ -138,7 +153,7 @@ spec:
spec: spec:
containers: containers:
- name: api - name: api
image: docker.mirror.hashicorp.services/hashicorp/http-echo:latest image: hashicorp/http-echo:latest
args: args:
- -text="hello world" - -text="hello world"
- -listen=:8080 - -listen=:8080
@ -146,7 +161,7 @@ spec:
- containerPort: 8080 - containerPort: 8080
name: api name: api
- name: api-admin - name: api-admin
image: docker.mirror.hashicorp.services/hashicorp/http-echo:latest image: hashicorp/http-echo:latest
args: args:
- -text="hello world from 9090 admin" - -text="hello world from 9090 admin"
- -listen=:9090 - -listen=:9090
@ -212,7 +227,7 @@ spec:
spec: spec:
containers: containers:
- name: api - name: api
image: docker.mirror.hashicorp.services/hashicorp/http-echo:latest image: hashicorp/http-echo:latest
args: args:
- -text="hello world" - -text="hello world"
- -listen=:8080 - -listen=:8080
@ -220,7 +235,7 @@ spec:
- containerPort: 8080 - containerPort: 8080
name: api name: api
- name: api-admin - name: api-admin
image: docker.mirror.hashicorp.services/hashicorp/http-echo:latest image: hashicorp/http-echo:latest
args: args:
- -text="hello world from 9090 admin" - -text="hello world from 9090 admin"
- -listen=:9090 - -listen=:9090

31
website/content/docs/k8s/multiport/index.mdx
View File

@ -1,25 +1,19 @@
--- ---
layout: docs layout: docs
page_title: Multi-port services overview page_title: Use the v2 Catalog API
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. description: Consul on Kubernetes supports the Catalog V2 API, which unlocks new service discovery and service mesh workflows. Learn how Consul’s Catalog V2 API supports workloads with multiple ports and selecting a workload using multiple services.
--- ---
# Multi-port services overview # Use the v2 Catalog API
<Warning> This topic describes the process to use the v2 catalog API to register a service with multiple ports or select a workload using multiple services on Kubernetes deployments. For information about the v2 catalog’s contents and structure, refer to [v2 catalog architecture](/consul/docs/architecture/v2/catalog).
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.
</Warning>
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 ## Workflow
To use a multi-port service in Consul on Kubernetes deployments, complete the following steps: To use a multi-port service in Consul on Kubernetes deployments, complete the following steps:
1. Enable the v2 catalog with ACLs enabled. Add `global.experiments: ["resource-apis"]`, `ui.enabled: false`, and `manageSystemACLs: true` to a cluster's Helm chart before deploying Consul. 1. 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. Use the `"consul.hashicorp.com/mesh-inject": "true"` and `"consul.hashicorp.com/transparent-proxy": "true"` annotations so that Consul automatically registers the service with transparent proxy mode enabled when Kubernetes deploys containers.
1. Configure traffic permissions. When ACLs are enabled, Consul denies all traffic by default. You can use the `TrafficPermissions` CRD to allow traffic to services. 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). 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).
@ -39,26 +33,29 @@ Be aware of the following constraints and technical limitations on using multi-p
- 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. - 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. - When running the v2 catalog for multi-port services, you cannot run the v1 catalog API at the same time.
- Because configuration entries are part of the v1 catalog, you cannot use them when the v2 catalog is enabled. Use v2 resources instead to configure multi-port service behavior in the service mesh.
- The Consul UI does not support multi-port services in this release. You must disable the UI in the Helm chart in order to use multi-port services. - 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. - 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. - 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 ## Guidance
The following resources are available to help you use multi-port services: The following resources are available to help you use the v2 Catalog API:
### Concepts ### Architecture
- [v2 catalog API](/consul/docs/architecture/catalog/v2) - [v2 architecture overview](/consul/docs/architecture/v2/catalog)
- [v2 Consul catalog](/consul/docs/architecture/v2/catalog)
- [v2 resource groups](/consul/docs/architecture/v2/catalog)
### Usage documentation ### Usage documentation
- [Configure multi-port services](/consul/docs/k8s/multiport/configure) - [Configure v2 services with multiple ports](/consul/docs/k8s/multiport/configure)
- [Split TCP traffic between multi-port services](/consul/docs/k8s/multiport/traffic-split) - [Split TCP traffic between v2 services with multiple ports](/consul/docs/k8s/multiport/traffic-split)
### Reference documentation ### Reference documentation
- [`consul resource` CLI command](/consul/docs/k8s/multiport/reference/resource-command) - [`consul resource` CLI command](/consul/commands/resource)
- [`GRPCRoute` resource configuration reference](/consul/docs/k8s/multiport/reference/grpcroute) - [`GRPCRoute` resource configuration reference](/consul/docs/k8s/multiport/reference/grpcroute)
- [`HTTPRoute` resource configuration reference](/consul/docs/k8s/multiport/reference/httproute) - [`HTTPRoute` resource configuration reference](/consul/docs/k8s/multiport/reference/httproute)
- [`ProxyConfiguration` resource configuration reference](/consul/docs/k8s/multiport/reference/proxyconfiguration) - [`ProxyConfiguration` resource configuration reference](/consul/docs/k8s/multiport/reference/proxyconfiguration)

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

@ -8,7 +8,7 @@ description: The GRPCRoute resource CRD configures L7 gRPC traffic behavior with
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 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/). This custom resource definition (CRD) describes a resource related to the [Kubernetes GAMMA initiative](https://gateway-api.sigs.k8s.io/concepts/gamma/) that requires the [v2 catalog API](/consul/docs/architecture/v2/catalog). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog). For more information about GAMMA resources, refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/gamma/).
## Configuration model ## Configuration model

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

@ -8,7 +8,7 @@ description: The HTTPRoute resource CRD configures L7 HTTP traffic behavior with
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 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/). This custom resource definition (CRD) describes a resource related to the [Kubernetes GAMMA initiative](https://gateway-api.sigs.k8s.io/concepts/gamma/) that requires the [v2 catalog API](/consul/docs/architecture/v2/catalog). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog). For more information about GAMMA resources, refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/gamma/).
## Configuration model ## Configuration model

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

@ -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 page provides reference information for the `ProxyConfigurations` resource, which defines proxy behavior for traffic within the service mesh. The resource specifies both bootstrap and dynamic configurations for proxies.
This custom resource definition (CRD) describes a resource related to the [Kubernetes GAMMA initiative](https://gateway-api.sigs.k8s.io/concepts/gamma/) that requires the [v2 catalog API](/consul/docs/architecture/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/v2/catalog). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog). For more information about GAMMA resources, refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/gamma/).
## Configuration model ## Configuration model

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

@ -8,7 +8,7 @@ description: The TCPRoute resource CRD configures L4 TCP behavior within the ser
This page provides reference information for the `TCPRoute` resource, which defines Transport Layer (L4) 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 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/). This custom resource definition (CRD) describes a resource related to the [Kubernetes GAMMA initiative](https://gateway-api.sigs.k8s.io/concepts/gamma/) that requires the [v2 catalog API](/consul/docs/architecture/v2/catalog). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog). For more information about GAMMA resources, refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/gamma/).
## Configuration model ## Configuration model

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

@ -6,9 +6,9 @@ description: The TrafficPermissions CRD defines rules for allowing and denying t
# TrafficPermissions configuration reference # 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/v2/catalog#changes-to-consul-s-existing-architecture) for more information.
This custom resource definition (CRD) describes a resource related to the [Kubernetes GAMMA initiative](https://gateway-api.sigs.k8s.io/concepts/gamma/) that requires the [v2 catalog API](/consul/docs/architecture/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/v2/catalog). It is not compatible with the [v1 catalog API](/consul/docs/architecture/catalog). For more information about GAMMA resources, refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/concepts/gamma/).
## Configuration model ## Configuration model

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

@ -16,7 +16,7 @@ This page describes the process for splitting TCP, HTTP, and gRPC traffic betwee
## Prerequisites ## Prerequisites
Splitting traffic between two ports of a multi-port service requires the [v2 catalog API](/consul/docs/architecture/catalog/v2). Splitting traffic between two ports of a multi-port service requires the [v2 catalog API](/consul/docs/architecture/v2/catalog).
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: 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:

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

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

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

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

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

@ -103,15 +103,23 @@
"path": "architecture" "path": "architecture"
}, },
{ {
"title": "Catalog", "title": "v1 Catalog",
"routes": [ "path": "architecture/catalog"
{
"title": "v1 API",
"path": "architecture/catalog/v1"
}, },
{ {
"title": "v2 API", "title": "v2 architecture",
"path": "architecture/catalog/v2" "routes": [
{
"title": "Overview",
"path": "architecture/v2"
},
{
"title": "Catalog",
"path": "architecture/v2/catalog"
},
{
"title": "Resource groups",
"path": "architecture/v2/groups"
} }
] ]
}, },
@ -1540,7 +1548,7 @@
] ]
}, },
{ {
"title": "Multi-port services", "title": "V2 Catalog API",
"routes": [ "routes": [
{ {
"title": "Overview", "title": "Overview",
@ -1551,16 +1559,12 @@
"path": "k8s/multiport/configure" "path": "k8s/multiport/configure"
}, },
{ {
"title": "Split TCP traffic between multi-port services", "title": "Split TCP traffic between multiple ports",
"path": "k8s/multiport/traffic-split" "path": "k8s/multiport/traffic-split"
}, },
{ {
"title": "Reference", "title": "Reference",
"routes": [ "routes": [
{
"title": "Consul resource command",
"path": "k8s/multiport/reference/resource-command"
},
{ {
"title": "GRPCRoute resource", "title": "GRPCRoute resource",
"path": "k8s/multiport/reference/grpcroute" "path": "k8s/multiport/reference/grpcroute"

30
website/redirects.js
View File

@ -212,4 +212,34 @@ module.exports = [
destination: '/consul/docs/v1.8.x/agent/config-entries/:slug', destination: '/consul/docs/v1.8.x/agent/config-entries/:slug',
permanent: true, permanent: true,
}, },
{
source: '/consul/docs/k8s/multiport/reference/resource-command/:slug',
destination: '/consul/commands/resource/:slug',
permanent: true,
},
{
source: '/consul/commands/:version(v1\.(?:8|9|10|11|12|13|14|15|16|17)\.x)/resource/:slug*',
destination: '/consul/docs/:version/k8s/multiport/reference/resource-command/:slug',
permanent: true
},
{
source: '/consul/docs/architecture/catalog/v1/:slug',
destination: '/consul/docs/architecture/catalog/:slug',
permanent: true,
},
{
source: '/consul/docs/:version(v1\.(?:8|9|10|11|12|13|14|15|16|17)\.x)/architecture/catalog/:slug*',
destination: '/consul/docs/:version/architecture/catalog/v1/:slug',
permanent: true
},
{
source: '/consul/docs/architecture/catalog/v2/:slug',
destination: '/consul/docs/architecture/v2/catalog/:slug',
permanent: true,
},
{
source: '/consul/docs/:version(v1\.(?:8|9|10|11|12|13|14|15|16|17)\.x)/architecture/v2/catalog/:slug*',
destination: '/consul/docs/:version/architecture/catalog/v2/:slug',
permanent: true
},
] ]