Multi-port services for service mesh
Warning
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.
This topic describes changes to Consul's catalog that allow you to register a service with multiple ports on Kubernetes deployments.
Introduction
When Consul registers services, v1 of its catalog API tracks 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 catalog API was designed prior to the introduction of Consul’s service mesh features. The service mesh uses Consul's ACL system, which requires a Kubernetes ServiceAccount resource to match the Service name. As a result, only one service can represent a Kubernetes Workload in the Consul catalog.
Since then, the cloud networking needs for applications have evolved and the Consul catalog adapted to support workarounds for these needs. For example, Kubernetes Pods with multiple ports demonstrates how you can schedule a service with multiple ports so that Consul registers it in the catalog as distinct services with their own service instances. However, this workaround results in additional resource consumption because Consul requires that each service and port use their own proxy and Consul dataplane so that it can recognize them as distinct services.
Catalog API v2 beta
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 still tracks services and nodes for Consul, but replaces service instances with workloads and workload identites.
Workload
is 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. It is similar to Kubernetes Workloads.WorkloadIdentities
provide a distinct identity for a Workload to assume in a Kubernetes cluster. They are similar to Kubernetes Service Accounts.
This catalog structure enables Consul to associate a single Kubernetes Workload with multiple services in its catalog.
The v2 catalog API also tracks the following information about services when they are registered with Consul:
ServiceEndpoints
maps services to workload addresses and endpoints. This resource is computed by Consul.HealthStatus
is a resource for reporting the health status of a workload.HealthCheck
is a resource for defining the health checks for a workload.ProxyConfiguration
represents a configuration for a sidecar or gateway proxy, similar to theProxy
field in the current service definition.Destinations
represents explicit service upstreams.TrafficPermissions
is a replacement for theServiceIntentions
custom resource definition (CRD). Traffic permissions replace service intentions for all services in the v2 catalog, which enables L4 traffic authorization according to workload identity instead of service identity.
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.
Workflow
To use a multi-port service in Consul on Kubernetes deployments, complete the following steps:
- Enable the v2 catalog. Add
global.experiments: ["resource-apis"]
andui.enabled: false
to a cluster's Helm chart before deploying Consul. - Use the
"consul.hashicorp.com/mesh-inject": "true"
annotation so that Consul registers the service automatically when Kubernetes deploys containers. - Configure traffic permissions. In the beta release, services registered to the v2 catalog allow all traffic by default. You can use the
TrafficPermissions
CRD to deny traffic to individual services for testing purposes. - Validate multi-port functionality. Send test traffic to each port to confirm that traffic is authorized and routed correctly.
For an example configuration and instructions for each of the steps in this workflow, refer to configure multi-port services.
Constraints and limitations
Be aware of the following constraints and technical limitations on using multi-port services and the v2 catalog API:
- The v2 catalog API beta does not support connections with client agents. It is only available for Kubernetes deployments, which use Consul dataplanes instead of client agents.
- The v1 and v2 catalog APIs cannot run concurrently.
- The Consul UI does not support multi-port services or 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 multi-port services or 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.
- The v2 catalog API does not support ACLs in the beta release.
- We do not recommend updating existing clusters to enable the v2 catalog in this release. To use the v2 catalog, deploy a new Consul cluster.