Use the v2 Catalog API

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.

Workflow

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

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, 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 for each resource.
2. Apply the resource to your cluster.

For an example configuration and instructions for each of the steps in this workflow, refer to split TCP service traffic between ports.

Constraints and limitations

Be aware of the following constraints and technical limitations on using multi-port services and the v2 catalog API:

• Multi-port services are available for deployments using Consul dataplanes 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.
• 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.
• HCP Consul Dedicated does not support multi-port services in this release.
• You cannot link a self-managed Enterprise cluster to HCP Consul Central 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

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

Architecture

• v2 architecture overview
• v2 Consul catalog
• v2 resource groups

Usage documentation

• Configure v2 services with multiple ports
• Split TCP traffic between v2 services with multiple ports

Reference documentation

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