mirror of
https://github.com/status-im/consul.git
synced 2025-01-22 11:40:06 +00:00
166d7a39e8
Remove outdated usage of "Consul Connect" instead of Consul service mesh. The connect subsystem in Consul provides Consul's service mesh capabilities. However, the term "Consul Connect" should not be used as an alternative to the name "Consul service mesh".
212 lines
7.1 KiB
Plaintext
212 lines
7.1 KiB
Plaintext
---
|
|
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. Use the 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
|
|
```
|