HashiConf Our community conference is taking place in San Francisco and online October 10-12. Register now
Consul
Service Mesh & Gateways

Control Access into the Service Mesh with Consul API Gateway

  • 15min

  • Consul

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:

  1. HCP-managed deployment with HashiCorp Cloud Platform (HCP) and Amazon Elastic Kubernetes Service (EKS)
  2. 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:

Clone GitHub repository

Clone the GitHub repository containing the configuration files and resources.

$ git clone https://github.com/hashicorp-education/learn-consul-api-gateway.git

$ git clone git@github.com:hashicorp-education/learn-consul-api-gateway.git

Change into the directory that contains the complete configuration files for this tutorial.

$ cd learn-consul-api-gateway/hcp/

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.

Terraform Deployment Architecture

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.

$ terraform init

Initializing the backend...

Initializing provider plugins...
...

Terraform has been successfully initialized!
...

Then, deploy the resources. Confirm the run by entering yes.

$ terraform apply

## ...
Do you want to perform these actions?
 Terraform will perform the actions described above.
 Only 'yes' will be accepted to approve.

 Enter a value: yes

## ...

Apply complete! Resources: 64 added, 0 changed, 0 destroyed.

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:

$ aws eks --region $(terraform output -raw region) update-kubeconfig --name $(terraform output -raw kubernetes_cluster_id)

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.

Application Architecture Diagram

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.

$ kubectl apply --filename two-services/

Check the pods to make sure they are all up and running.

$ kubectl get pods --all-namespaces
NAMESPACE     NAME                                             READY   STATUS    RESTARTS   AGE
default       consul-api-gateway-controller-74cb558c9c-bmb4l   1/1     Running   4          2m40s
default       consul-connect-injector-65f565cc74-jxddb         1/1     Running   0          2m39s
default       consul-webhook-cert-manager-85959989f-pwkjm      1/1     Running   0          2m40s
default       echo-1-58899795cd-646v5                          2/2     Running   0          70s
default       echo-2-656f4c578-twxms                           2/2     Running   0          69s
default       frontend-5d7f97456b-lcd22                        2/2     Running   0          68s
default       nginx-7445d8d8c4-l25zb                           2/2     Running   0          66s
default       payments-6888957c45-wp46d                        2/2     Running   0          65s
default       product-api-7fcf6cd96f-d8hf6                     2/2     Running   0          64s
default       product-api-db-855dbcc787-9wvkv                  2/2     Running   0          65s
default       public-api-7b985f985c-qpkn6                      3/3     Running   0          63s
kube-system   aws-node-pb9xv                                   1/1     Running   0          26m
kube-system   aws-node-rxm49                                   1/1     Running   0          26m
kube-system   aws-node-tq5s9                                   1/1     Running   0          26m
kube-system   coredns-66cb55d4f4-nvt9r                         1/1     Running   0          30m
kube-system   coredns-66cb55d4f4-wkhwg                         1/1     Running   0          30m
kube-system   kube-proxy-ftt58                                 1/1     Running   0          26m
kube-system   kube-proxy-nk5tf                                 1/1     Running   0          26m
kube-system   kube-proxy-qrpqc                                 1/1     Running   0          26m

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:

hcp/api-gw/consul-api-gateway.yaml
apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
 name: api-gateway
spec:
 gatewayClassName: consul-api-gateway
 listeners:
 - protocol: HTTP
   port: 80
   name: http
   allowedRoutes:
     namespaces:
       from: Same

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 the Gateway 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 the GatewayClass documentation for more information.

  • GatewayClassConfig - This object (deployed and configured by the Helm chart) describes additional Consul API Gateway related configuration parameters for the GatewayClass. Refer to the GatewayClassConfig 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.

hcp/api-gw/routes.yaml
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
 name: example-route-1
spec:
 parentRefs:
 - name: api-gateway
 rules:
 - matches:
   - path:
       type: PathPrefix
       value: /echo
   backendRefs:
   - kind: Service
     name: echo-1
     port: 8080
     weight: 50
   - kind: Service
     name: echo-2
     port: 8090
     weight: 50
---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
 name: example-route-2
spec:
 parentRefs:
 - name: api-gateway
 rules:
 - matches:
   - path:
       type: PathPrefix
       value: /
   backendRefs:
   - kind: Service
     name: nginx
     port: 80

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 the Route documentation for more information.

  • example-route-1 - This HTTPRoute defines the load balancer settings for the echo-1 and echo-2 services.

  • example-route-2 - This HTTPRoute defines the ingress settings for the nginx 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.

$ kubectl apply --filename api-gw/consul-api-gateway.yaml && \
    kubectl wait --for=condition=ready gateway/api-gateway --timeout=90s && \
    kubectl apply --filename api-gw/routes.yaml

Expected output:

gateway.gateway.networking.k8s.io/api-gateway created
gateway.gateway.networking.k8s.io/api-gateway condition met
httproute.gateway.networking.k8s.io/example-route-1 created
httproute.gateway.networking.k8s.io/example-route-2 created

Verify the API gateway service was created successfully.

$ kubectl get services api-gateway
NAME          TYPE           CLUSTER-IP      EXTERNAL-IP                                                              PORT(S)        AGE
api-gateway   LoadBalancer   172.20.55.140   a162b0fd63568487f93053e5fdfdbaf9-621046043.us-east-1.elb.amazonaws.com   80:31757/TCP   3m48s

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.

$ terraform output consul_addr && terraform output consul_token

Example output:

"https://hcp-learn.consul.98a0dcc3-5473-4e4d-a28e-6c343c498530.aws.hashicorp.cloud"
"aaf77be7-96d2-55e1-7a7b-d2da31fc8304"

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.

Consul UI Services Page

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.

Consul UI Intentions

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.

Application Architecture Diagram

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.

$ kubectl get services api-gateway
NAME          TYPE           CLUSTER-IP      EXTERNAL-IP                                                              PORT(S)        AGE
api-gateway   LoadBalancer   172.20.55.140   a162b0fd63568487f93053e5fdfdbaf9-621046043.us-east-1.elb.amazonaws.com   80:31757/TCP   3m48s

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.

HashiCups UI

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.

hcp/api-gw/routes.yaml
---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
 name: example-route-2
spec:
 parentRefs:
 - name: api-gateway
 rules:
 - matches:
   - path:
       type: PathPrefix
       value: /
   backendRefs:
   - kind: Service
     name: nginx
     port: 80
---

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.

Echo Server UI

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.

hcp/api-gw/routes.yaml
---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
 name: example-route-1
spec:
 parentRefs:
 - name: api-gateway
 rules:
 - matches:
   - path:
       type: PathPrefix
       value: /echo
   backendRefs:
   - kind: Service
     name: echo-1
     port: 8080
     weight: 50
   - kind: Service
     name: echo-2
     port: 8090
     weight: 50
---

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.

$ terraform destroy

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.

Back to Collection
Next

This tutorial also appears in:

  • 17 tutorials
    Service Mesh on Kubernetes
    Review production best practices for all Kubernetes installation types and learn cloud-specific configurations for deploying Consul on different cloud providers. Practice registering, securing, and observing services deployed with Kubernetes.
    • Consul