v2 Catalog API

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 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.

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, GRPCRoute, and 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 for more information.

The following table describes the Consul resources that belong to each resource group and the resource's group.groupVersion.kind syntax.

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.

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.

For more information about these resource, including specifications and example configurations, refer to HTTPRoute resource configuration reference, GRPCRoute resource configuration reference, and TCPRoute resource configuration reference.

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. You can also separately define a service mesh proxy and configure 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 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 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 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.

Guidance

The following resources are available to help you use the v2 catalog API:

Usage documentation

• Multi-port services overview
• Configure multi-port services

Reference documentation

• consul resource CLI command
• GRPCRoute configuration reference
• HTTPRoute configuration reference
• ProxyConfiguration configuration reference
• TCPRoute configuration reference
• TrafficPermissions configuration reference