Consul integration

Consul is a widely used service mesh. Emissary-ingress natively supports service discovery and unauthenticated communication to services in Consul. Additionally, the Ambassador Consul Connector enables Emissary-ingress 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 Emissary-ingress is particularly useful when deploying Emissary-ingress in hybrid cloud environments where you deploy applications on VMs and Kubernetes. In this environment, Consul enables Emissary-ingress 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 Emissary-ingress, Emissary-ingress 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 Emissary-ingress 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.

1. 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)
   If you did not find your Kubernetes platform above, check the Consul documentation here to see if there are specific setup instructions for your platform.

2. Add the Hashicorp repository for installing Consul with Helm. If you do not have Helm installed, you can find an installation guide here.

3. Create a new consul-values.yaml YAML file for the Consul installation values and copy the values below into that file.

   Note: you are free to change the value of the datacenter field in the install values. This is the the name of your Consul Datacenter.

4. Install Consul with Helm using the consul-values.yaml values file you just created.

Installing Emissary-ingress

If you have not already installed Emissary-ingress 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 Emissary-ingress to look for services registered to Consul, registering a demo application with Consul, and configuring Emissary-ingress 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.

1. Configure Emissary-ingress to look for services registered to Consul by creating the ConsulResolver. Use kubectl to apply the following manifest:

   Note: If you changed the name of your datacenter in the Consul install values, make sure to change it in the resolver above to match the name of your datacenter.

   If you changed the name of the helm install from hashicorp to another value, make sure to update the value of the address field in your resolver to match it.

   If you are having trouble figuring out what your address field should be, it follow this format: http://{consul_server_pod}.{consul_server_service}.{namespace}.svc.cluster.local:{consul_port}. The default Consul port should be 8500 unless you changed it.

   This tells Emissary-ingress that Consul is a service discovery endpoint.

   You must set the resolver to your ConsulResolver on a per-Mapping basis, otherwise for that Mapping Emissary-ingress uses the default resolver. That is, in order for a Mapping to make use of a service registered in Consul, you need to add resolver: consul-dc1 to that Mapping.

   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).

2. Deploy the Quote demo application. Use kubectl to apply the following manifest:

   The SERVICE_NAME environment variable in the quote-consul Deployment specifies the service name for Consul. The default value is set to "quote-consul", so you only need to include it if you want to change the service name.

   The Quote application contains code to automatically register itself with Consul, using the CONSUL_IP and POD_IP environment variables specified within the quote-consul container spec.

   When you apply this manifest, it registers the Pod in the quote-consul Deployment as a Consul service with the name quote-consul and the IP address of the Pod.

   The "consul.hashicorp.com/connect-inject": "false" annotation tells Consul that for this Deployment you do not want to use the sidecar proxy that is part of Consul's Connect feature. Without Consul's sidecar, the service needs to include code to make a request to Consul to register the service. The manifest includes the environment variables CONSUL_IP, POD_IP, and SERVICE_NAME to provide the Quote service with enough information to build that request and send it to Consul. To see how this code works, see our our Git repo for the Quote service.

3. Verify the quote-consul Deployment's Pod 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.

   Port forwarding not working for you? Make sure the service name matches your Consul UI service by checking kubectl get svc -A

4. Configure Emissary-ingress to make use of this quote-consul service. Use kubectl to apply the following manifest:

   Note that in the above config:

   • service refers to the service name you specified in the quote-consulDeployment.
   • resolver must be set to the ConsulResolver that you created in the previous step.
   • load_balancer must be set to configure Emissary-ingress to route directly to the Quote application endpoints that are retrieved from Consul.

5. Send a request to the /quote-consul/ API endpoint in order to validate that Emissary-ingress 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 Emissary-ingress to authenticate to such services.

The following steps assume you've already set up Consul for service discovery, as detailed above.

1. The Ambassador Consul Connector retrieves the TLS certificate issued by the Consul CA and stores it in a Kubernetes Secret for Emissary-ingress to use. Deploy the Ambassador Consul Connector with kubectl:

   This installs in to your cluster:

   • RBAC resources.
   • The Ambassador Consul Connector service.
   • A TLSContext named ambassador-consul to load the ambassador-consul-connect Secret into Emissary-ingress.

2. Deploy a new version of the demo application, and configure it to inject the Consul Connect sidecar by setting "consul.hashicorp.com/connect-inject" to true. Note that in this version of the configuration, you do not have to configure environment variables for the location of the Consul server. Use kubectl to apply the following manifest:

   Note: Annotations are used to attach metadata to Kubernetes objects. You can use annotations to link external information to objects, working in a similar, yet different, fashion to labels. For more information on annotations, refer to the Annotating Kubernetes Services for Humans article, or get started with annotations in your own cluster with the Ambassador Cloud Quick start guide.

   This deploys a demo application Deployment called quote-connect (different than the quote-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 to true in this Deployment tells Consul that you want this Deployment 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.

3. Verify the quote-connect Deployment's Pod 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.

4. Create a Mapping to configure Emissary-ingress route to the quote-connect service in Consul. Use kubectl 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 with kubectl get svc -A it should follow the format of {service name}-sidecar-proxy.
   • resolver must be set to the ConsulResolver created when configuring Emissary-ingress.
   • tls must be set to the TLSContext storing the Consul mTLS certificates, which is ambassador-consul in the standard ambassador-consul-connector.yaml.
   • load_balancer must be set to configure Emissary-ingress 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.

5. Send a request to the /quote-connect/ API endpoint in order to validate that Emissary-ingress 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.

More information

For more about Emissary-ingress's integration with Consul, read the service discovery configuration documentation.