Multiport services

This page describes how to configure and deploy services that utilize multiple ports in a Consul service mesh.

In a Consul service mesh, you may configure services to use multiple ports. This configuration lets you run different types of traffic through the same service while still benefiting from Consul's service discovery and traffic management features. For example, a web application might have one port for HTTP traffic and another for gRPC traffic. With Consul service mesh, you may configure your services to use multiple ports while still leveraging the benefits of service mesh features such as secure communication, traffic routing, and observability.

Configuring multiport services

Configure a multiport service in Consul service mesh by specifying the ports in the service registration. Each port should have a unique name, port number, and whether it is the default port.

This example demonstrates a web application with both HTTP and gRPC ports defined in HCL and JSON formats.

multiport-service.hcl

service {
  name = "api"
  id   = "api-1"
  ports = [
    {
      name = "http"
      port = 8080
      default = true
    },
    {
      name = "grpc"
      port = 9090
    }
  ]
}

multiport-service.json

{
  "name": "api",
  "id": "api-1",
  "ports": [
    {
      "name": "http",
      "port": 8080,
      "default": true
    },
    {
      "name": "grpc",
      "port": 9090
    }
  ]
}

Addressing multiport services

Non-transparent proxy

In non-transparent proxy mode, downstream services explicitly configure upstreams by defining these parameters:

A service destination_name
The local_bind_port
The destination_port, which is specific to the multiport use case

This configuration lets the downstream service specify which port on the upstream service it wants to connect to. The proxy handles routing the traffic accordingly. Refer to the upstream configuration reference for details.

This example configuration is for a non-transparent proxy service with multiport upstream services and illustrates the following:

The web service connecting to localhost:9191 is rerouted to the single port db:9191 service.
The web service connecting to localhost:9192 is rerouted to the multiport destination of api:8080.
The web service connecting to localhost:9193 is rerouted to the multiport destination of api:9090.

service {
  name = "web"
  port = 8080
  connect {
    sidecar_service {
      proxy {
        upstreams = [
          {
            destination_name = "db"
            local_bind_port = 9191
          },
          {
            destination_name = "api"
            destination_port = "http"
            local_bind_port = 9192
          },
          {
            destination_name = "api"
            destination_port = "grpc"
            local_bind_port = 9193
          }
        ]
        config {
          handshake_timeout_ms = 1000
        }
      }
    }
  }
}

{
  "name": "web",
  "port": 8080,
  "connect": {
    "sidecar_service": {
      "proxy": {
        "upstreams": [
          {
            "destination_name": "db",
            "local_bind_port": 9191
          },
          {
            "destination_name": "api",
            "destination_port": "http",
            "local_bind_port": 9192
          },
          {
            "destination_name": "api",
            "destination_port": "grpc",
            "local_bind_port": 9193
          }
        ],
        "config": {
          "handshake_timeout_ms": 1000
        }
      }
    }
  }
}

Transparent proxy

In transparent proxy mode, Consul uses virtual DNS to resolve the correct port for an upstream service without needing to specify the port in the configuration.

Consul generates the virtual DNS entries based on the service name and port name, following the naming convention <port-name>.<service-name>.virtual.consul.

Consul's internal DNS returns a Virtual IP (VIP) unique to that specific service-port combination. For example, if you have a service named api with two ports named http and grpc, the virtual DNS entries would be http.api.virtual.consul and grpc.api.virtual.consul.

Multiport functionality in Consul services

The following functionality has partial support for Consul Multiport:

Mesh gateways
Proxy and Service defaults
Consul DNS

Note that multiport in WAN Federation is not supported.

Next steps

Multiport services in Consul service mesh let you run different types of traffic through the same service while still benefiting from Consul's service discovery and traffic management features. By configuring your services to use multiple ports, you can ensure that your applications can communicate effectively while still leveraging the benefits of a service mesh.

For more information about the topics covered in this guide, refer to the following resources: