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.

Introduction

When Consul registers services, it records user-defined and Consul-assigned information. 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 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, 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 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.

The v2 catalog API is available alongside the existing v1 catalog API, but the catalogs cannot be used simultaneously. The v2 catalog is disabled by default. This beta release is for testing and development purposes only. We do not recommend implementing v2 in production environments or migrating to v2 until the API is generally available.

Catalog structure

Consul v1.17 introduces a new version of the catalog API designed to bridge differences between the Consul and Kubernetes data models. The v2 catalog API continues to track services and nodes for Consul, but it replaces service instances with workloads and workload identities.

Catalog resources

The following table describes resources in the v2 catalog, how they generally compare to the v1 catalog and Kubernetes resources, and whether they are created by Kubernetes or computed by Consul when it registers a service.