Control Access into the Service Mesh with Consul API Gateway
Consul API Gateway is a dedicated ingress solution for intelligently routing traffic to applications running on your HashiCorp Consul service mesh. This provides a consistent method for handling inbound requests to the service mesh from external clients.
The Consul API Gateway takes all API calls from clients, then routes them to the appropriate microservice with request routing, composition, and protocol translation. This eliminates the need to install another dedicated application. Once Consul API Gateway becomes available for your services, you gain the ability to have a platform-agnostic API Gateway that is built into Consul.
Consul API Gateway is an enhancement to Ingress Controller and uses a different schema. The Consul API Gateway Controller deploys an API Gateway pod and configures the gateway, listeners, and the routes to services. If TLS is enabled on a listener, the controller will load the certificate from the Kubernetes Secrets storage. If the certificate is rotated, the Gateway Controller will automatically update the listener.
Other features of the Consul API Gateway include load balancing, modifying HTTP headers, and splitting traffic between multiple services based on weighted ratios.
This tutorial features two learning paths:
- HCP-managed deployment with HashiCorp Cloud Platform (HCP) and Amazon Elastic Kubernetes Service (EKS)
- Self-managed deployment with local Kubernetes in Docker (Kind)
Select your learning path by clicking one of the following tabs.
In this tutorial, you will:
- Deploy a HashiCorp Cloud Platform (HCP) Consul cluster and an Elastic Kubernetes Service (EKS) cluster with Terraform
- Deploy example applications HashiCups and Echo Server
- Deploy Consul API Gateway
- Explore Ingress into the service mesh with HashiCups
- Explore Load Balancing with Echo Server
Prerequisites
The tutorial assumes that you are familiar with Consul and its core functionality. If you're new to Consul, refer to the Consul Getting Started tutorials collection.
For this tutorial, you will need:
- An HCP account configured for use with Terraform
- An AWS account configured for use with Terraform
- kubectl >= 1.21
- git >= 2.0
- aws-cli >= 2.0
- terraform >= 1.0
Clone GitHub repository
Clone the GitHub repository containing the configuration files and resources.
Change into the directory that contains the complete configuration files for this tutorial.
Create Consul cluster
In this section, you will create a Consul cluster that provides service mesh functionality for enabling API Gateway ingress. Choose between a HCP-managed deployment with Terraform, EKS, and HCP, or a self-managed local deployment with Kind.
The Terraform configuration files used in this tutorial deploy resources that enable your managed service mesh.
Below is the purpose of each Terraform configuration file.
modules/eks-client.tf
- Amazon EKS module for creating customized Consul client resources.modules/variables.tf
- Parameter definitions used to customize unique user environment attributes for the Amazon EKS module.eks-cluster.tf
- Amazon EKS cluster deployment resources.hcp-consul.tf
- HCP Consul and network peering resources.hcp-hvn.tf
- HashiCorp Virtual Network (HVN) deployment resources.api-gw-kustomization.tf
- Consul API Gateway custom resource definition (CRD) deployment resources.outputs.tf
- Unique values output after Terraform successfully completes a deployment.providers.tf
- AWS and HCP provider definitions for Terraform.variables.tf
- Parameter definitions used to customize unique user environment attributes.vpc.tf
- AWS Virtual Private Cloud (VPC) deployment resources.
Note
By default, this tutorial creates a "development" size tier
HCP Consul Cluster. Development tiers are single-server Consul datacenters recommended for testing or evaluation purposes only. For production, we recommend using the "standard" or "plus" tier because each Consul datacenter will have the recommended three server nodes.
Deploy the HCP and EKS resources
With these Terraform configuration files, you are ready to deploy your infrastructure.
Initialize your Terraform configuration to download the necessary providers and modules.
Then, deploy the resources. Confirm the run by entering yes
.
Note
The deploy
could take up to 15 minutes to complete. Feel free to explore the next sections of this tutorial while waiting for the cluster to complete initialization or learn more about the Raft protocol in a fun, interactive way.
Configure your terminal to communicate with EKS
Kubernetes stores cluster connection information in a file called kubeconfig
. You can retrieve the Kubernetes configuration settings for your EKS cluster and merge them into your local kubeconfig
file by issuing the following command:
Deploy sample applications and Consul API Gateway
The diagram below represents the architecture of the services you will deploy to your Kubernetes cluster. This includes the Consul API Gateway, the service mesh layer, and microservice application pods.
Deploy sample applications
Now that your Consul service mesh is operational in your cluster, you will deploy two sample applications that you will use to explore Consul API Gateway's ingress features.
Deploy the HashiCups and Echo applications.
Check the pods to make sure they are all up and running.
Review the configuration and deploy the Consul API Gateway
A complete Consul API Gateway deployment consists of an API Gateway configuration and a routing configuration. In this section you will review these respective configuration details then deploy the Consul API Gateway.
Inspect the Consul API Gateway configuration file
The Consul API Gateway consists of multiple components that facilitate ingress into your Consul service mesh. The configuration file specifies how Consul API Gateway will handle API calls from clients and how it will route them to the respective services with request routing, composition, and protocol translation.
Inspect the hcp/api-gw/consul-api-gateway.yaml
file contents in your project directory:
This configuration file uses the following components:
Gateway
- This object is the main infrastructure resource that links all other related configuration information together. The spec itself defines listener and address details. Refer to theGateway
documentation for more information.GatewayClass
- This object (deployed and configured by the Helm chart) describes a class of Gateways available to the user for creating Gateway resources. Refer to theGatewayClass
documentation for more information.GatewayClassConfig
- This object (deployed and configured by the Helm chart) describes additional Consul API Gateway related configuration parameters for theGatewayClass
. Refer to theGatewayClassConfig
documentation for more information.
Explore additional configuration details by visiting the Consul API Gateway documentation.
Inspect the Routes file
Routes tell your Consul API Controller how to handle traffic into your service mesh.
The hcp/api-gw/routes.yaml
file defines two routes. One route directs traffic from /echo
to the echo-1
and echo-2
services. The other route directs traffic from /
to the nginx
service, where the HashiCups demo application runs.
Inspect the hcp/api-gw/routes.yaml
file contents in your project directory.
This configuration file uses the following components:
HTTPRoute
- This object specifies routing behavior of HTTP requests from a Gateway listener to a Service. Rules and matches within this type define conditions used for matching an HTTP request. Refer to theRoute
documentation for more information.example-route-1
- ThisHTTPRoute
defines the load balancer settings for theecho-1
andecho-2
services.example-route-2
- ThisHTTPRoute
defines the ingress settings for thenginx
service.
Refer to the Kubernetes HTTPRoute documentation for a complete list of configuration options and details.
Deploy the Consul API Gateway resources
Deploy the Consul API Gateway and associated HTTP Routes.
Expected output:
Verify the API gateway service was created successfully.
Explore the Consul UI
In this section you will view your Consul UI to explore the details of the sample applications and API Gateway components.
Retrieve your HCP Consul public URL and ACL token from Terraform.
Example output:
Copy and paste the Consul public URL into your browser to visit the Consul UI. Since HCP Consul is secure by default, you must authenticate to use the Consul UI — click Login then enter the ACL token into the Consul authentication prompt.
Once you have authenticated, click the Services tab on the left navigation pane to review your deployed services.
In the left navigation pane, click the Intentions tab. Here you will find intentions for the API Gateway, HashiCups, and Echo services. These intentions follow the "least privilege" principle to enable communication between the services.
Explore the sample applications
The diagram below shows the structure of the Kubernetes cluster you have created. This includes the Consul API Gateway, the service mesh layer, and microservice application pods.
The Consul API Gateway can be configured to handle ingress for multiple services using a variety of methods. Since you configured Consul API Gateway for deployment on Amazon EKS in this case, an AWS load balancer is automatically created to handle network ingress. Feel free to explore the API Gateway documentation to learn more about network configuration options.
Retrieve your AWS load balancer DNS address (EXTERNAL-IP
) and copy it to your clipboard for use in the next sections.
Use Case 1: Ingress
You can configure Consul API Gateway to handle ingress into your service mesh applications.
In this tutorial, the Consul API Gateway provides ingress to the HashiCups service. You can access the HashiCups frontend UI through the API Gateway at http://your-aws-load-balancer-dns-name
. The HashiCups application is a collection of pods that together form a microservice application.
To review, this HTTPRoute code snippet from the hcp/api-gw/routes.yaml
file is what enables the single-service ingress behavior into HashiCups via the nginx
service.
Use Case 2: Load Balancing
You can use Consul API Gateway to load balance between services within your Consul service mesh.
In this tutorial, the Consul API Gateway load balances between two separate Echo Server services. Check out the Echo Server frontend UI at http://your-aws-load-balancer-dns-name/echo
to find the API Gateway successfully routing traffic into the service mesh. Reload the page several times to notice how the load balancer alternates requests between the two different pods.
To review, this HTTPRoute code snippet from the hcp/api-gw/routes.yaml
file is what enables the load balancing behavior between the two echo
services.
For more information on accessing service mesh services via the Consul API Gateway, visit the Consul API Gateway documentation page.
Clean up environment
Destroy the Terraform resources to clean up your environment. Enter yes
to confirm the destroy operation.
Note
Due to race conditions with the various cloud resources created in this tutorial, you may need to run the destroy
operation twice to ensure all resources have been properly removed.
Next Steps
In this tutorial, you used the Consul API Gateway as an ingress solution for routing traffic to the applications running on your HashiCorp Consul service mesh. The environment you created in this tutorial highlighted the benefits of using the API Gateway for secure traffic ingress to multiple services as well as load-balancing.
Using Consul API Gateway as your dedicated ingress solution eliminates the need to install and manage additional applications for handling traffic ingress. Once Consul API Gateway becomes available for your services, you gain the ability to have a platform-agnostic API Gateway that is built into Consul.
Feel free to explore these tutorials and collections to learn more about Consul service mesh, microservices, and Kubernetes security.