mirror of https://github.com/hashicorp/consul
212 lines
7.1 KiB
Markdown
212 lines
7.1 KiB
Markdown
---
|
|
layout: docs
|
|
page_title: API Gateways on Virtual Machines
|
|
description: Learn how to configure and Consul API gateways and gateway routes on virtual machines so that you can enable ingress requests to services in your service mesh in VM environments.
|
|
---
|
|
|
|
# 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](/consul/docs/api-gateway).
|
|
|
|
## Introduction
|
|
|
|
Consul API gateways provide a configurable ingress points for requests into a Consul network. Usethe following configuration entries to set up API gateways:
|
|
|
|
- [API gateway](/consul/docs/connect/gateways/api-gateway/configuration/api-gateway): Provides an endpoint for requests to enter the network. Define listeners that expose ports on the endpoint for ingress.
|
|
- [HTTP routes](/consul/docs/connect/gateways/api-gateway/configuration/http-route) and [TCP routes](/consul/docs/connect/gateways/api-gateway/configuration/tcp-route): The routes attach to listeners defined in the gateway and control how requests route to services in the network.
|
|
- [Inline certificates](/consul/docs/connect/gateways/api-gateway/configuration/inline-certificate): 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:
|
|
|
|
1. Create an API gateway configuration entry. The configuration entry includes
|
|
listener configurations and references to TLS certificates.
|
|
1. Deploy the API gateway configuration entry to create the listeners.
|
|
1. Create and deploy routes to bind to the gateway.
|
|
|
|
Refer to [API Gateway for Kubernetes](/consul/docs/api-gateway) 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`](/consul/docs/agent/config/config-files#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:
|
|
|
|
- `mesh: read`
|
|
- `mesh: write`
|
|
|
|
Refer [Mesh Rules](/consul/docs/security/acl/acl-rules#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.
|
|
|
|
```hcl
|
|
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](/consul/docs/connect/gateways/api-gateway/configuration/api-gateway) 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:
|
|
|
|
```shell-session
|
|
$ consul config write gateways.hcl
|
|
```
|
|
|
|
Run the following command to deploy an API gateway instance:
|
|
|
|
```shell-session
|
|
$ 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`.
|
|
|
|
```hcl
|
|
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
|
|
|
|
```shell-session
|
|
$ consul config write my-http-route.hcl
|
|
```
|
|
|
|
Refer to [HTTP Route Configuration Entry Reference](/consul/docs/connect/gateways/api-gateway/configuration/http-route)
|
|
and [TCP Route Configuration Entry Reference](/consul/docs/connect/gateways/api-gateway/configuration/tcp-route) for details about route configurations.
|
|
|
|
## Add a TLS certificate
|
|
|
|
Define an [`inline-certificate` configuration entry](/consul/docs/connect/gateways/api-gateway/configuration/inline-certificate) with a name matching the name in the [API gateway listener configuration](/consul/docs/connect/gateways/api-gateway/configuration/api-gateway#listeners) 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.
|
|
|
|
```hcl
|
|
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
|
|
|
|
```shell-session
|
|
$ consul config write my-certificate.hcl
|
|
```
|