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.
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:
Run the following command to deploy an API gateway instance:
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
.
Create this configuration by saving it to a file called my-http-route.hcl
and using the command
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.
Create this configuration by saving it to a file called my-certificate.hcl
and using the command