Connect External Services to Consul With Terminating Gateways
The Understand Terminating Gateways tutorial provides an overview of Consul's terminating gateways and their use cases.
In this tutorial you will configure a terminating gateway to secure and route communication to an external service. The external service will be in the same logical network as the service deployed in the Consul service mesh.
This use case represents scenarios where there are services that cannot be deployed with sidecar proxies to the Consul service mesh (e.g. services running on an OS not supported by Consul or managed services, such as Amazon RDS) but are registered within Consul's catalog as external services. The service must be registered with Consul so that it is discoverable with Consul DNS. Once registered, you can create Consul intentions for it like any other service.
Prerequisites
In order to deploy and test Consul terminating gateways, you will need the following resources deployed in a non-production environment.
A node hosting a legacy service. Consul does not need to be installed on this node.
Consul service mesh. A Consul datacenter with Consul service mesh functionality enabled. Check Secure Service-to-Service Communication for configuration help. To test the terminating gateways functionality, you will need at least two client nodes inside the service mesh:
- A node hosting a dashboard service that needs to communicate with a legacy service.
- A node for the terminating gateway. This node requires unrestricted and verified network connectivity between its host and the legacy serviceβs host.
When configuring the service mesh gRPC must be enabled on all client agents.
The following binaries are required on the different nodes:
Binary/Node | Consul server | Legacy node | Dashboard service | Terminating gateway |
---|---|---|---|---|
Consul v1.8.0+ | β | π« | β | β |
Envoy | β | π« | β | β |
Counting Service | π« | β | π« | π« |
Dashboard Service | π« | π« | β | π« |
NOTE Currently, Envoy is the only proxy with terminating gateway capabilities in Consul. See Secure Service-to-Service Communication for installation instruction.
Configure a terminating gateway for your service mesh
In this tutorial you will make an external service available inside your service mesh by performing the following steps:
- Register the external node and service with the Consul catalog.
- Register a client service inside the service mesh and starting an Envoy proxy as sidecar.
- Enable zero-trust networking with intentions. This is not strictly required for the functionality to work but is a recommended best practice.
- Configure and start the terminating gateway.
- Start the destination service and checking connectivity.
Register the external counting service
External services require you to also register the external node to be properly handled by Consul. The external node and service must be first registered in Consul before they can be reached through the terminating gateway.
Create a file named external.json
, on the Consul client, with the following contents.
This configuration defines a node named legacy_node
available at address
10.20.10.22
that provides a counter service with an ID of counting1
running
on port 9003
.
Register the external node and service using a PUT request to Consulβs
/catalog/register
HTTP API exposed on any Consul agent.
Query the /catalog/service/counting
endpoint to verify that the external
service registered with the catalog.
Register the dashboard service and start its Envoy sidecar
Register the dashboard service on the Consul client.
Create a file named dashboard.hcl
with the following content.
This configuration defines a service named dashboard
running on port 9002
.
The dashboard service is enabled for Consul service mesh, and has an upstream
dependency on the destination service counting
. The local sidecar proxy will
make this destination available on localhost
(127.0.0.1
) at port 5000
.
Register the service with the local Consul client agent.
Start the local sidecar proxy for the client service.
Finally, if you did not start the dashboard service yet, start it now.
Enable zero-trust networking with intentions
If you have Consul ACLs enabled, the default intentions policy is inherited
from the default_policy
. When the default_policy
is set to deny
, then the intention behavior is to deny all connections. If this is true for your Consul agents, skip to the next section to register and start your terminating gateway.
The first intention you will create changes from the default-allow approach where all traffic is allowed unless denied in specific rules to a default-deny approach where all traffic is denied and only specific connections are enabled.
First, create a file for a config entry definition named intention-config.hcl
.
From the same directory where you saved this file, run the following command on your terminal to initialize these intention rules.
Note To learn more about intentions, feel free to check out the Service Intentions Docs.
Register and start the terminating gateway
On the host where you will deploy the terminating gateway, create a file
named terminating-gateway.hcl
with the following contents.
This file defines configuration for a terminating gateway named
legacy-services-gateway
which acts as an egress proxy for traffic destined to
the service named counting
.
Apply the terminating gateway config entry in Consul.
Now that you have configured your terminating gateway, start it with the Consul CLI.
Start the legacy service and allow connectivity
You can now start the legacy counting service on the legacy node. In a more production oriented scenario this could represent your network team opening connectivity on the firewall from the terminating gateway host(s).
Open a browser and navigate to http://dashboard.node.dc1.consul:9002
.
In the configuration we used for this tutorial the Consul client node hosting
the client service dashboard
was reachable at dashboard.node.dc1.consul
.
Modify the URL in your test by using the node IP or a valid resolvable
hostname for your network.
Because of the zero-trust networking approach the connection indicator in the dashboard ui will show the word "Disconnected". This means you need to explicitly enable the connection across the two services.
Terminating gateways are not considered services and do not need to be considered when defining intentions. Destination services need to be defined in the intention instead of the gateway.
Modify your intentions to allow communication to the counting
service.
First, create a file for a config entry definition named intention-counting.hcl
.
From the same directory where you saved this file, run the following command on your terminal to initialize these intention rules.
Refresh your browser, the indicator in the top right that should turn green and show the word "Connected" when the dashboard service is in communication with the counting service.
Next steps
In this tutorial you enabled a service inside your service mesh to reach an
external service using the terminating gateway functionality. You registered the
external service and node using the
/catalog/register API
endpoint, you used global configuration to add a terminating-gateway
configuration
entry, and
started the terminating gateway sidecar proxy. Finally you enabled connectivity
to the external service using intentions.
Please check the Register External Services with Consul Service Discovery tutorial to learn how to monitor your external service from Consul using checks and Consul ESM.
Check the Consul documentation for more info on terminating gateways.