Configure multi-port services
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 page describes the process for integrating a service that uses multiple ports in a single container when running Consul on Kubernetes deployments. It includes example configurations to demonstrate an end-to-end deployment test of Consul's multi-port features.
Prerequisites
Registering multi-port services with Consul requires Kubernetes. Multi-port services are not supported on VM deployments.
The following software versions are required:
- Consul v1.17.0
consul-k8s
CLI v1.3.0+ orhashicorp/consul
Helm chart release v1.3.0+
For more information about upgrading versions for consul-k8s
and Helm charts, refer to Update the Consul K8s CLI and Upgrade Helm chart version.
There are additional requirements for service mesh proxies in transparent proxy mode. This mode enables queries through Kube DNS instead of Consul DNS over permissive mTLS settings. For more information about the steps to configure global settings and enable permissive mTLS mode before registering a service, refer to the onboard services in transparent mode workflow.
Enable the v2 catalog
To enable the v2 catalog and its support for multi-port services, set global.experiments: ["resource-apis"]
and ui.enabled: false
. The following example includes these parameters in a Helm chart with minimal required configurations for the Consul installation:
Then install Consul to your Kubernetes cluster using either the consul-k8s
CLI or Helm.
Define the multi-port service
Consul's v2 catalog supports two methods for defining multi-port services in Kubernetes:
- Method 1: Define a single Kubernetes Service that exposes multiple ports
- Method 2: Define multiple Kubernetes Services that expose individual ports
These methods affect how the Services are addressed in Kubernetes.
Each tab in the following example contains a configuration that defines an api
service using one of these methods. Both definitions schedule a Pod running two containers that each support traffic to one of the ports exposed by the Service. In Method 1
, both services are addressed using api
because both services are exposed by a single service. In Method 2
, api
and api-admin
are defined as separate services and can be addressed using distinct names.
For testing purposes, the following example defines a Service to function as a static client that you can use to verify that the multi-port services function correctly.
To apply these services to your Kubernetes deployment and register them with Consul, run the following command:
Configure traffic permissions
Consul uses traffic permissions to validate communication between services based on L4 identity. In the beta release of the v2 catalog API, traffic permissions allow all services by default. In order to verify that services function correctly on each port, create CRDs that deny traffic to each port.
The following examples create Consul CRDs that allow traffic to only one port of the multi-port service. Each resource separately denies web
permission when it is a source of traffic to one of the services. These traffic permissions work with either method for defining a multi-port service.
Validate multi-port connection
To open a shell to the web
container, you need the name of the Pod it currently runs on. Run the following command to return a list of Pods:
Validate both ports
Use the web
Pod's name to open a shell session and test the api
service on port 80.
Then test the api
service on port 90.
Validate port 80
Apply the CRD to allow traffic to port 80 only:
Then, open a shell session in the web
container and test the api
service on port 80.
Test the api
service on port 90. This command should fail, indicating that the traffic permission is in effect.
Before testing the other port, remove the TrafficPermissions
CRD.
Validate port 90
Apply the CRD to allow traffic to port 90 only:
Then, open a shell session in the web
container and test the api
service on port 90.
Test the api
service on port 80. This command should fail, indicating that the traffic permission is in effect.