API gateways on virtual machines

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

Introduction

Consul API gateways provide a configurable ingress points for requests into a Consul network. Use the following configuration entries to set up API gateways:

API gateway: Provides an endpoint for requests to enter the network. Define listeners that expose ports on the endpoint for ingress.
HTTP routes and TCP routes: The routes attach to listeners defined in the gateway and control how requests route to services in the network.
Inline certificates: Makes TLS certificates available to gateways so that requests between the user and the gateway endpoint are encrypted.

You can configure and reuse configuration entries separately. You can define and attach routes and inline certificates to multiple gateways.

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.
Create and deploy routes to bind to the gateway.

Refer to API Gateway for Kubernetes for information about using Consul API gateway on Kubernetes.

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

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

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

Create the API gateway configuration

Create an API gateway configuration that defines listeners and TLS certificates in the mesh. In the following example, the API gateway specifies an HTTP listener on port 8443 that routes can use to connect external traffic to services in the mesh.

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"
                }
            ]
        }
    }
]

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

Use the consul config write command to implement the API gateway configuration entries. 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

The command directs Consul to configure Envoy as an API gateway.

Route requests

Define route configurations and bind them to listeners configured on the gateway so that Consul can route incoming requests to services in the mesh. Create HTTP or TCP routes by setting the Kind parameter to http-route or tcp-route and configuring rules that define request traffic flows.

The following example routes requests from the listener on the API gateway at port 8443 to services in Consul based on the path of the request. When an incoming request starts at path /, Consul forwards 90 percent of the requests to the ui service and 10 percent to experimental-ui. Consul also forwards requests starting with /api to api.

Kind = "http-route"
Name = "my-http-route"

// Rules define how requests will be routed
Rules = [
  // Send all requests to UI services with 10% going to the "experimental" UI
  {
    Matches = [
      {
        Path = {
          Match = "prefix"
          Value = "/"
        }
      }
    ]
    Services = [
      {
        Name = "ui"
        Weight = 90
      },
      {
        Name = "experimental-ui"
        Weight = 10
      }
    ]
  },
  // Send all requests that start with the path `/api` to the API service
  {
    Matches = [
      {
        Path = {
          Match = "prefix"
          Value = "/api"
        }
      }
    ]
    Services = [
      {
        Name = "api"
      }
    ]
  }
]

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

Create this configuration by saving it to a file called my-http-route.hcl and using the command

$ consul config write my-http-route.hcl

Refer to HTTP Route Configuration Entry Reference and TCP Route Configuration Entry Reference for details about route configurations.

Add a TLS certificate

Define an inline-certificate configuration entry with a name matching the name in the API gateway listener configuration to bind the certificate to that listener. The inline certificate configuration entry takes a public certificate and private key in plaintext.

The following example defines a certificate named my-certificate. API gateway configurations that specify inline-certificate in the Certificate.Kind field and my-certificate in the Certificate.Name field are able to use the certificate.

Kind = "inline-certificate"
Name = "my-certificate"

Certificate = <<EOF
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
EOF

PrivateKey = <<EOF
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----
EOF

Create this configuration by saving it to a file called my-certificate.hcl and using the command

$ consul config write my-certificate.hcl