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

Addresses comments from review

pull/19678/head
boruszak 2023-11-27 15:41:42 -08:00
parent 425888af34
commit 93f981e702
1 changed files with 9 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -24,7 +24,7 @@ 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, 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 service can represent a service instance 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. 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:
@ -39,7 +39,7 @@ 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 continues to track services and nodes for Consul, but it replaces service instances with _workloads_ and _workload identites_. Resources belong to separate _resource groups_ that determine whether they affect all workloads associated with a service or specific workload identities.
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
@ -54,19 +54,19 @@ The following table describes resources in the v2 catalog, how they generally co
| 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 | `mesh` | Represents a configuration for a sidecar or gateway proxy. | `Proxy` field in service definition | None | Created by Kubernetes or user CRD |
| 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
## Resource groups
Each catalog resource is part of a _resource group_. These resource groups structure Consul's ability to target an individual workload identity or an entire collection of workload endpoints registered to a service when managing service mesh traffic. There are three resource groups in the v2 catalog:
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. But when Consul routes service mesh traffic, it applies rules to workloads based on the Service, which is a resource in the `catalog` group.
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.
@ -83,7 +83,10 @@ The following table describes the Consul resources that belong to each resource
| `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