Multi-port services overview
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 the process to register a service with multiple ports on Kubernetes deployments using the v2 catalog API. For information about the v2 catalog’s contents and structure, refer to v2 catalog API.
To use a multi-port service in Consul on Kubernetes deployments, complete the following steps:
- Enable the v2 catalog with ACLs enabled. Add
ui.enabled: false, and
manageSystemACLs: trueto 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. When ACLs are enabled, Consul denies all traffic by default. You can use the
TrafficPermissionsCRD 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.
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:
- Define the resource's behavior in a custom resource definition (CRD). For specifications and example configurations, refer to the configuration reference for each resource.
- 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.
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.
- 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 does not support multi-port services 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. To register multi-port services, deploy a new Consul cluster that enables the v2 catalog.
The following resources are available to help you use multi-port services: