---
layout: docs
page_title: Create and manage ingress gateways on virtual machines
description: Learn how to create and manage an ingress gateway on virtual machines. Ingress gateways are Consul service mesh constructs that listen for requests from external network locations and route authorized traffic to destinations in the service mesh.
---

# Create and manage ingress gateways on virtual machines

This topic describes how to add ingress gateways to your Consul service mesh in virtual machine (VM) environments. Refer to [Create and manage ingress gateways on Kubernetes](/consul/docs/north-south/ingress-gateway/k8s) for instructions on how to implement ingress gateways in Kubernetes environments.

<Note>

Ingress gateways are deprecated and will no longer be updated. Ingress gateways are fully supported
in this version, but we will remove them in a future release of Consul. Use [Consul API gateways](/consul/docs/north-south/api-gateway) instead.

</Note>

## Overview

Ingress gateways enable services outside the service mesh to send traffic to services in the mesh. Refer to [Ingress gateways overview](/consul/docs/north-south/ingress-gateway/) for additional information about ingress gateways.

Complete the following steps to set up an ingress gateway:

1. Define listeners and the services they expose in an ingress gateway configuration entry.
1. Register the ingress gateway configuration entry to Consul.
1. Create a service definition for the ingress gateway proxy service and deploy it to the mesh.
1. Start the ingress gateway. This step deploys the Envoy proxy that functions as the ingress gateway.

After specifying listeners and services in the ingress gateway configuration entry, you can register the gateway service and start Envoy with a single CLI command instead of completing these steps separately. Refer [Register an ingress service on Envoy startup](#register-an-ingress-service-on-envoy-startup).

## Requirements

- Service mesh must be enabled for all agents. Set the [`connect.enabled` parameter](/consul/docs/reference/agent/configuration-file/service-mesh#connect) to `true` to enable service mesh.
- The gRPC port must be configured for all server agents in the datacenter. Specify the gRPC port in the [`ports.grpc` parameter](/consul/docs/reference/agent/configuration-file/general#grpc_port). We recommend setting the port to `8502` to simplify configuration when ACLs are enabled. Refer to [ACL requirements](#acl-requirements) for additional information.
- You must use Envoy for sidecar proxies in your service mesh. Refer to [Configure and deploy sidecar proxies](/consul/docs/connect/proxy/sidecar) for additional information.

### ACL requirements

If ACLs are enabled, you must present a token when registering ingress gateways that grant the following permissions:

- `service:write` for the ingress gateway's service name
- `service:read` for all services in the ingress gateway's configuration entry
- `node:read` for all nodes of the services in the ingress gateway's configuration entry.

These privileges authorize the token to route communications to other services in the mesh. If the Consul client agent on the gateway's node is not configured to use the default `8502` gRPC port, then the gateway's token must also provide `agent:read` for its node's name in order to discover the agent's gRPC port. gRPC is used to expose Envoy's xDS API to Envoy proxies.

## Define listeners

Specify listener configurations in an ingress gateway configuration entry. Listener configurations are traffic entry points to the service mesh that map to upstream services. When you register an ingress gateway proxy that matches the configuration entry name, Consul applies the settings specified in the configuration entry. Configure the following fields:

- [`Kind`](/consul/docs/reference/config-entry/ingress-gateway#kind): Set the value to `ingress-gateway`.
- [`Name`](/consul/docs/reference/config-entry/ingress-gateway#name): Consul applies the configuration entry settings to ingress gateway proxies with names that match the `Name` field.
- [`Listeners`](/consul/docs/reference/config-entry/ingress-gateway#listeners): Specify one or more listeners.
    - [`Listeners.Port`](/consul/docs/reference/config-entry/ingress-gateway#listeners-port): Specify a port for the listener. Each listener is uniquely identified by its port number.
    - [`Listeners.Protocol`](/consul/docs/reference/config-entry/ingress-gateway#listeners-protocol): The default protocol is `tcp`, but you must specify the protocol used by the services you want to allow traffic from.
    - [`Listeners.Services`](/consul/docs/reference/config-entry/ingress-gateway#listeners-services): The `Services` field contains the services that you want to expose to upstream services. The field contains several options and sub-configurations that enable granular control over ingress traffic, such as health check and TLS configurations.

For Consul Enterprise service meshes, you may also need to configure the [`Partition`](/consul/docs/reference/config-entry/ingress-gateway#partition) and [`Namespace`](/consul/docs/reference/config-entry/ingress-gateway#namespace) fields for the gateway and for each exposed service.

Refer to [Ingress gateway configuration entry reference](/consul/docs/reference/config-entry/ingress-gateway) for details about the supported parameters.

##  Register the ingress gateway

You can either use the [`consul config` command](/consul/commands/config) or call the [`/config` API endpoint](/consul/api-docs/config) to register the gateway configuration entry.
The following example command registers an ingress gateway configuration entry named `public-ingress.hcl` that is stored on the local system:

```shell-session
$ consul config write public-ingress.hcl
```

## Deploy an ingress gateway service

To deploy an ingress gateway service, create a service definition and register it with Consul.

You can also define an ingress gateway service and register it with Consul while starting an Envoy proxy from the command line. Refer to [Register an ingress service on Envoy startup](#register-an-ingress-service-on-envoy-startup) for details.

### Create a service definition for the ingress gateway

Consul applies the settings defined in the ingress gateway configuration entry to ingress gateway services that match the configuration entry name. Refer to [Define services](/consul/docs/register/service/vm/define) for additional information about defining services in Consul.

The following fields are required for the ingress gateway service definition:

- [`Kind`](/consul/docs/reference/service#kind): The field must be set to `ingress-gateway`.
- [`Name`](/consul/docs/reference/service#name): The name should match the value specified for the `Name` field in the configuration entry.

All other service definition fields are optional, but we recommend defining health checks to verify the health of the gateway. Refer to [Services configuration reference](/consul/docs/reference/service) for information about defining services.

### Register the ingress gateway proxy service

You can register the ingress gateway using API or CLI. Refer to [Register services and health checks](/consul/docs/register/service/vm/) for instructions on registering services in Consul.

The following example registers an ingress gateway defined in `ingress-gateway.hcl` from the Consul CLI:

```shell-session
$ consul services register ingress-service.hcl
```

## Start an Envoy proxy

Run the `consul connect envoy` command to start Envoy. Specify the name of the ingress gateway service and include the `-gateway=ingress` flag. Refer to [Consul Connect Envoy](/consul/commands/connect/envoy) for details about using the command.

The following example starts Envoy for the `ingress-service` gateway service:

```shell-session
$ consul connect envoy -gateway=ingress ingress-service
```

### Register an ingress service on Envoy startup

You can also automatically register the ingress gateway service when starting the Envoy proxy. Specify the following flags with the `consul connect envoy` command:

- `-gateway=ingress`
- `-register`
- `-service=<name of the service>`

The following example starts Envoy and registers an ingress gateway service named `ingress-service` bound to the agent address at port `8888`:

```shell-session
$ consul connect envoy -gateway=ingress -register \
   -service ingress-service \
   -address '{{ GetInterfaceIP "eth0" }}:8888'
```
You cannot register the ingress gateway service and start the proxy at the same time if you configure the gateway to retrieve and serve TLS certificates from their external downstreams. Refer to [Serve custom TLS certificates from an external service](/consul/docs/north-south/ingress-gateway/external) for more information.

## Additional Envoy configurations

Ingress gateways support additional Envoy gateway options and escape-hatch
overrides. Specify gateway options in the ingress gateway service definition to
use them. To use escape-hatch overrides, you must add them to your global proxy
defaults configuration entry. Refer to the [Envoy configuration
reference](/consul/docs/reference/proxy/envoy) for additional information.
