Deploy API gateway listeners to virtual machines

This topic describes how to deploy Consul API gateway listeners to networks that operate in virtual machine (VM) environments. If you want to implement API gateway listeners in a Kubernetes environment, refer to Deploy API gateway listeners to Kubernetes.

Overview

API gateways have one or more listeners that serve as ingress points for requests to services in a Consul service mesh. Create an API gateway configuration entry and define listeners that expose ports on the endpoint for ingress.

The following steps describe the general workflow for deploying a Consul API gateway to a VM environment:

Create an API gateway configuration entry. The configuration entry includes listener configurations and references to TLS certificates.
Deploy the API gateway configuration entry to create the listeners.

Encryption

To encrypt traffic between the external client and the service that the API gateway routes traffic to, configure listener TLS.

You can configure listener TLS in two primary ways:

Reference certificate entries with Listeners[].TLS.Certificates (for example, inline-certificate)
Configure SDS for dynamic certificate delivery with:
- gateway-level default: api-gateway.TLS.SDS
- listener-level override/default: api-gateway.Listeners[].TLS.SDS

When route service overrides are configured (http-route or tcp-route service TLS.SDS), certificate selection precedence is:

Route service TLS.SDS
Listener TLS.SDS
Gateway-level TLS.SDS

Refer to Encrypt API gateway traffic on virtual machines for additional information.

To terminate TLS without providing a certificate, set api-gateway.TLS.Enabled to true and do not reference a certificate on the listener. The gateway uses its Consul service mesh leaf certificate, which Consul issues and rotates automatically. Refer to Terminate TLS with Consul-managed certificates for additional information.

Routes

After deploying the gateway, attach HTTP routes and TCP routes to listeners defined in the gateway to control how requests route to services in the network. Refer to Define API gateway routes on VMs for additional information.

DNS

When a route binds to a gateway listener, Consul automatically registers each service that the route targets in Consul DNS at <service>.api-gateway.<domain>. Clients can use this name to reach the service through the gateway. Refer to API gateway service lookups for additional information.

Consul resolves these names from the gateway-services catalog mapping, which is the same mapping that ingress gateways use. Refer to API gateway service mapping for details about how Consul builds the mapping, and to Verify API gateway DNS resolution for verification steps.

Requirements

The following requirements must be satisfied to use API gateways on VMs:

Consul 1.15 or later
A Consul cluster with service mesh enabled. Refer to connect
Network connectivity between the machine deploying the API Gateway and a Consul cluster agent or server

ACL requirements

If ACLs are enabled, you must present a token with the following permissions to configure Consul and deploy API gateways:

Refer to Mesh Rules for additional information about configuring policies that enable you to interact with Consul API gateway configurations.

Define the gateway and listeners

Create an API gateway configuration entry that defines listeners and TLS certificates in the mesh.

Specify the following fields:
- Kind: Specifies the type of configuration entry to implement. This must be api-gateway.
- Name: Specify a name for the gateway configuration. The name is metadata that you can use to reference the configuration entry when performing Consul operations.
- Listeners: Specify a list of listener configurations. Each listener is map containing the following fields:
  - Port: Specifies the port that the listener receives traffic on.
  - Name: Specifies a unique name for the listener.
  - Protocol: You can set tcp, http, http2, or grpc. Refer to HTTP/2 and gRPC listeners for additional information.
  - TLS: Defines TLS encryption configurations for the listener.
Refer to the API gateway configuration entry reference for details on how to define fields in the Listeners block.
Configure any additional fields necessary for your use case, such as the namespace or admin partition. Refer to the API gateway configuration entry reference for additional information.
Save the configuration.

In the following example, the API gateway specifies an HTTP listener on port 8443. It also requires an inline-certificate configuration entry named my-certificate that contains a valid certificate and private key pair:

Kind = "api-gateway"
Name = "my-gateway"

// Each listener configures a port which can be used to access the Consul cluster
Listeners = [
    {
        Port = 8443
        Name = "my-http-listener"
        Protocol = "http"
        TLS = {
            Certificates = [
                {
                    Kind = "inline-certificate"
                    Name = "my-certificate"
                }
            ]
        }
    }
]

The following example shows gateway-level SDS with a listener-level SDS override:

Kind = "api-gateway"
Name = "my-gateway"

TLS = {
  SDS = {
    ClusterName = "sds-cluster"
    CertResource = "wildcard.example.internal"
  }
}
Listeners = [
  {
    Port = 8443
    Name = "my-http-listener"
    Protocol = "http"
    TLS = {
      SDS = {
        ClusterName = "sds-cluster"
        CertResource = "api.example.com"
      }
    }
  }
]

The following example enables Consul-managed TLS. The listener does not reference a certificate, so the gateway terminates HTTPS with its Consul service mesh leaf certificate:

Kind = "api-gateway"
Name = "my-gateway"

TLS = {
  Enabled = true
}
Listeners = [
  {
    Port = 8443
    Name = "my-https-listener"
    Protocol = "http"
  }
]

Refer to API Gateway Configuration Reference for information about all configuration fields.

Gateways and routes are eventually-consistent objects that provide feedback about their current state through a series of status conditions. As a result, you must manually check the route status to determine if the route bound to the gateway successfully.

Deploy the API gateway and listeners

Use the consul config write command to implement the API gateway configuration entry. The following command applies the configuration entry for the main gateway object:

$ consul config write gateways.hcl

Run the following command to deploy an API gateway instance:

$ consul connect envoy -gateway api -register -service my-api-gateway

Gateways and routes are eventually-consistent objects that expose status conditions. Verify that listeners and routes are accepted and bound after deployment.

HTTP/2 and gRPC listeners

Set the listener Protocol to http2 or grpc to serve HTTP/2 or gRPC traffic. The gateway accepts HTTP/2 connections from clients and uses HTTP/2 for the connection to the routed service, so streaming RPCs and other HTTP/2 features work from the client to the service. When you use the http protocol, the gateway uses HTTP/1.1 for the connection to the service.

HTTP/2 and gRPC listeners require Consul v2.1 or later.

Complete the following steps to route gRPC and HTTP/2 traffic through an API gateway:

Set the protocol of each backend service in a service defaults configuration entry. The following example sets the grpc-service protocol to grpc:
```
Kind     = "service-defaults"
Name     = "grpc-service"
Protocol = "grpc"
```
For an HTTP/2 service, set Protocol to http2.

Define the API gateway with grpc and http2 listeners:

Kind = "api-gateway"
Name = "my-gateway"

Listeners = [
  {
    Name     = "grpc-listener"
    Port     = 9999
    Protocol = "grpc"
  },
  {
    Name     = "http2-listener"
    Port     = 9998
    Protocol = "http2"
  }
]

Bind an http-route to each listener. An http-route can bind to http, http2, and grpc listeners. The following example routes traffic from the grpc-listener listener to the grpc-service service:

Kind = "http-route"
Name = "grpc-route"

Parents = [
  {
    Kind        = "api-gateway"
    Name        = "my-gateway"
    SectionName = "grpc-listener"
  }
]

Rules = [
  {
    Services = [
      {
        Name = "grpc-service"
      }
    ]
  }
]

Create service intentions that allow traffic from the gateway to each service, and apply the configuration entries with the consul config write command.

Listeners that share a port must use the same protocol. A tcp-route can only bind to a tcp listener.

Verify HTTP/2 and gRPC traffic

Complete the following steps to verify that the gateway uses HTTP/2 from the client to the service:

Check the gateway status conditions to confirm that the listeners are accepted and the routes are bound:
```
$ consul config read -kind api-gateway -name my-gateway
```

On the machine that runs the API gateway, query the Envoy admin interface to confirm that the upstream cluster for each service uses HTTP/2. By default, the Envoy admin interface listens on localhost:19000.

$ curl --silent localhost:19000/config_dump \
    | jq '.configs[]
      | select(."@type" | contains("ClustersConfigDump"))
      | .dynamic_active_clusters[]
      | select(.cluster.name | startswith("grpc-service."))
      | .cluster.typed_extension_protocol_options'

The output includes http2_protocol_options, which indicates that the gateway uses HTTP/2 for the connection to the service:

{
  "envoy.extensions.upstreams.http.v3.HttpProtocolOptions": {
    "@type": "type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions",
    "explicit_http_config": {
      "http2_protocol_options": {}
    }
  }
}

Send requests through the gateway. The following examples send an HTTP/2 request to the http2-listener listener and a gRPC request to the grpc-listener listener. Replace GATEWAY_ADDRESS with the address of the API gateway, and SERVICE/METHOD with a method that your gRPC service implements.
```
$ curl --http2-prior-knowledge http://GATEWAY_ADDRESS:9998/
$ grpcurl -plaintext GATEWAY_ADDRESS:9999 SERVICE/METHOD
```

Validation notes

When route or listener TLS.SDS is configured, CertResource is required.
Listener TLS.SDS overrides gateway TLS.SDS for that listener.
Route service overrides (Services[].TLS.SDS) can override listener/gateway defaults.
On a listener, TLS.Certificates and TLS.SDS are mutually exclusive.