DocsEdge StackConsul integration
Consul integration
Contents
Consul is a widely used service mesh. Ambassador Edge Stack natively supports service discovery and unauthenticated communication to services in Consul. Additionally, the Ambassador Consul Connector enables Ambassador Edge Stack to encrypt and authenticate its communication via mTLS with services in Consul that make use of Consul's Connect feature.
Architecture overview
Using Consul with Ambassador Edge Stack is particularly useful when deploying Ambassador Edge Stack in hybrid cloud environments where you deploy applications on VMs and Kubernetes. In this environment, Consul enables Ambassador Edge Stack to securely route over TLS to any application regardless of where it is deployed.
In this architecture, Consul serves as the source of truth for your entire data center, tracking available endpoints, service configuration, and secrets for TLS encryption. New applications and services automatically register themselves with Consul using the Consul agent or API. When you send a request through Ambassador Edge Stack, Ambassador Edge Stack sends the request to an endpoint based on the data in Consul.
This guide first instructs you on registering a service with Consul and using Ambassador Edge Stack to dynamically route requests to that service based on Consul's service discovery data, and subsequently instructs you on using using the Ambassador Consul Connector to use Consul for authorizing and encrypting requests.
Installing Consul
If you already have Consul installed in your cluster, then go ahead and skip to the next section.
Before you install Consul, make sure to check the Consul documentation for any setup steps specific to your platform. Below you can find setup guides for some of the more popular Kubernetes platforms. This step is primarily to ensure you have the proper permissions to set up Consul. You can skip these guides if your cluster is already configured to grant you the necessary permissions.
- Microsoft Azure Kubernetes Service (AKS)
- Amazon Elastic Kubernetes Service (EKS)
- Google Kubernetes Engine (GKE)
Add the Hashicorp repository for installing Consul with Helm. If you do not have Helm installed, you can find an installation guide here.
Create a new
consul-values.yaml
YAML file for the Consul installation values and copy the values below into that file.Install Consul with Helm using the
consul-values.yaml
values file you just created.
Installing Ambassador Edge Stack
If you have not already installed Ambassador Edge Stack in to your cluster, then go to the quick start guide before continuing any further in this guide.
Using Consul for service discovery
This section of the guide instructs you on configuring Ambassador Edge Stack to look for services registered to Consul, registering a demo application with Consul, and configuring Ambassador Edge Stack to route to this application using endpoint data from Consul.
In this tutorial, you deploy the application in Kubernetes. However, this application can be deployed anywhere in your data center, such as on a VM.
Configure Ambassador Edge Stack to look for services registered to Consul by creating the
ConsulResolver
. Usekubectl
to apply the following manifest:This tells Ambassador Edge Stack that Consul is a service discovery endpoint.
You must set the resolver to your
ConsulResolver
on a per-Mapping
basis, otherwise for thatMapping
Ambassador Edge Stack uses the default resolver. That is, in order for aMapping
to make use of a service registered in Consul, you need to addresolver: consul-dc1
to thatMapping
.For more information about resolver configuration, see the resolver reference documentation. (If you're using Consul deployed elsewhere in your data center, make sure the
address
points to your Consul FQDN or IP address).Deploy the Quote demo application. Use
kubectl
to apply the following manifest:The Quote application contains code to automatically register itself with Consul, using the
CONSUL_IP
andPOD_IP
environment variables specified within thequote-consul
container spec.When you apply this manifest, it registers the
Pod
in thequote-consul
Deployment
as a Consul service with the namequote-consul
and the IP address of thePod
.Verify the
quote-consul
Deployment
'sPod
has been registered with Consul. You can verify this by accessing the Consul UI.First use
kubectl port-forward
to make the UI available on your local workstation:Then, while the port-forward is running, go to http://localhost:8500/ in a web browser. You should see a service named
quote-consul
.After you have verified that you see the
quote-consul
service in your web browser, you may kill the port-forward.Configure Ambassador Edge Stack to make use of this
quote-consul
service. Usekubectl
to apply the following manifest:Note that in the above config:
service
refers to the service name you specified in thequote-consul
Deployment
.resolver
must be set to theConsulResolver
that you created in the previous step.load_balancer
must be set to configure Ambassador Edge Stack to route directly to the Quote application endpoints that are retrieved from Consul.
Send a request to the
/quote-consul/
API endpoint in order to validate that Ambassador Edge Stack is now making use of that service:
Using Consul for authorization and encryption
In this part of the guide, you'll install a different version of the demo application that now uses Consul's Connect feature to authorize its incoming connections using mTLS, and install Ambassador Consul Connector to enable Ambassador Edge Stack to authenticate to such services.
The following steps assume you've already set up Consul for service discovery, as detailed above.
The Ambassador Consul Connector retrieves the TLS certificate issued by the Consul CA and stores it in a Kubernetes
Secret
for Ambassador Edge Stack to use. Deploy the Ambassador Consul Connector withkubectl
:This installs in to your cluster:
- RBAC resources.
- The Ambassador Consul Connector service.
- A
TLSContext
namedambassador-consul
to load theambassador-consul-connect
Secret
into Ambassador Edge Stack.
Deploy a new version of the demo application, and configure it to inject the Consul Connect sidecar by setting
"consul.hashicorp.com/connect-inject"
totrue
. Note that in this version of the configuration, you do not have to configure environment variables for the location of the Consul server. Usekubectl
to apply the following manifest:This deploys a demo application
Deployment
calledquote-connect
(different than thequote-consul
Deployment
in the previous section) with the Consul Connect sidecar proxy. The Connect sidecar registers the application with Consul, requires TLS to access the application, and exposes other Consul Service Segmentation features.The annotation
consul.hashicorp.com/connect-inject
being set totrue
in thisDeployment
tells Consul that you want thisDeployment
to use the Consul Connect sidecar. The sidecar proxies requests to the service that it is attached to. Keep this in mind mind when debug requests to the service.Verify the
quote-connect
Deployment
'sPod
has been registered with Consul. You can verify this by accessing the Consul UI.First use
kubectl port-forward
to make the UI available on your local workstation:Then, while the port-forward is running, open http://localhost:8500/ in a web browser. You should see a service named
quote-connect
.After you have verified that you see the
quote-connect
service in your web browser, you may kill the port-forward.Create a
Mapping
to configure Ambassador Edge Stack route to thequote-connect
service in Consul. Usekubectl
to apply the following manifest:Note that in the above config:
service
must be set to the name of the Consul sidecar service. You can view this withkubectl get svc -A
it should follow the format of{service name}-sidecar-proxy
.resolver
must be set to theConsulResolver
created when configuring Ambassador Edge Stack.tls
must be set to the TLSContext storing the Consul mTLS certificates, which isambassador-consul
in the standardambassador-consul-connector.yaml
.load_balancer
must be set to configure Ambassador Edge Stack to route directly to the application endpoints that are retrieved from Consul.
When you apply this manifest, it creates a Mapping that routes to the
quote-connect
service in Consul.Send a request to the
/quote-connect/
API endpoint in order to validate that Ambassador Edge Stack is now using mTLS to encrypt and authenticate communication with that service:
Environment variables
The Ambassador Consul Connector can be configured with the following environment variables. The defaults are best for most use-cases.
Environment Variable | Description | Default |
---|---|---|
_AMBASSADOR_ID | Set the Ambassador ID so multiple instances of this integration can run per-Cluster when there are multiple Ambassador Edge Stacks (Required if AMBASSADOR_ID is set in your Ambassador Edge Stack Deployment ) | "" |
_CONSUL_HOST | Set the IP or DNS name of the target Consul HTTP API server | 127.0.0.1 |
_CONSUL_PORT | Set the port number of the target Consul HTTP API server | 8500 |
_AMBASSADOR_TLS_SECRET_NAME | Set the name of the Kubernetes v1.Secret created by this program that contains the Consul-generated TLS certificate. | $AMBASSADOR_ID-consul-connect |
_AMBASSADOR_TLS_SECRET_NAMESPACE | Set the namespace of the Kubernetes v1.Secret created by this program. | (same Namespace as the Pod running this integration) |
More information
For more about Ambassador Edge Stack's integration with Consul, read the service discovery configuration documentation.