consul/website/content/docs/connect/gateways/api-gateway/usage.mdx

---
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
```