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.

In this tutorial, you will:

Create a local Kubernetes cluster using Kind
Install Consul using Helm or Consul K8s-CLI
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

»Clone GitHub repository

Clone the GitHub repository containing the configuration files and resources.

$ git clone https://github.com/hashicorp/learn-consul-kubernetes.git

$ git clone https://github.com/hashicorp/learn-consul-kubernetes.git

Change into the directory with the newly cloned repository.

$ cd learn-consul-kubernetes/

$ cd learn-consul-kubernetes/

Check out the v0.0.12 tag of the repository.

$ git checkout v0.0.12

$ git checkout v0.0.12

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

$ cd api-gateway/

$ cd api-gateway/

»Create a local cluster

Start Kind with the --config flag specifying the cluster.yaml configuration file.

$ kind create cluster --config=kind/cluster.yaml

$ kind create cluster --config=kind/cluster.yaml

The output will be similar to the following.

Creating cluster "kind" ...
 ✓ Ensuring node image (kindest/node:v1.21.1) 🖼 
 ✓ Preparing nodes 📦  
 ✓ Writing configuration 📜 
 ✓ Starting control-plane 🕹️ 
 ✓ Installing CNI 🔌 
 ✓ Installing StorageClass 💾 
Set kubectl context to "kind-kind"
You can now use your cluster with:

kubectl cluster-info --context kind-kind

Have a nice day! 👋

Creating cluster "kind" ... ✓ Ensuring node image (kindest/node:v1.21.1) 🖼  ✓ Preparing nodes 📦   ✓ Writing configuration 📜  ✓ Starting control-plane 🕹️  ✓ Installing CNI 🔌  ✓ Installing StorageClass 💾 Set kubectl context to "kind-kind"You can now use your cluster with:
kubectl cluster-info --context kind-kind
Have a nice day! 👋

»Create the Consul API Gateway Controller CRDs

Create the custom resource definitions (CRD) for the API Gateway Controller.

$ kubectl apply --kustomize "github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.1.0-beta"
customresourcedefinition.apiextensions.k8s.io/gatewayclassconfigs.api-gateway.consul.hashicorp.com created
customresourcedefinition.apiextensions.k8s.io/gatewayclasses.gateway.networking.k8s.io created
customresourcedefinition.apiextensions.k8s.io/gateways.gateway.networking.k8s.io created
customresourcedefinition.apiextensions.k8s.io/httproutes.gateway.networking.k8s.io created
customresourcedefinition.apiextensions.k8s.io/referencepolicies.gateway.networking.k8s.io created
customresourcedefinition.apiextensions.k8s.io/tcproutes.gateway.networking.k8s.io created
customresourcedefinition.apiextensions.k8s.io/tlsroutes.gateway.networking.k8s.io created
customresourcedefinition.apiextensions.k8s.io/udproutes.gateway.networking.k8s.io created

$ kubectl apply --kustomize "github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.1.0-beta"customresourcedefinition.apiextensions.k8s.io/gatewayclassconfigs.api-gateway.consul.hashicorp.com createdcustomresourcedefinition.apiextensions.k8s.io/gatewayclasses.gateway.networking.k8s.io createdcustomresourcedefinition.apiextensions.k8s.io/gateways.gateway.networking.k8s.io createdcustomresourcedefinition.apiextensions.k8s.io/httproutes.gateway.networking.k8s.io createdcustomresourcedefinition.apiextensions.k8s.io/referencepolicies.gateway.networking.k8s.io createdcustomresourcedefinition.apiextensions.k8s.io/tcproutes.gateway.networking.k8s.io createdcustomresourcedefinition.apiextensions.k8s.io/tlsroutes.gateway.networking.k8s.io createdcustomresourcedefinition.apiextensions.k8s.io/udproutes.gateway.networking.k8s.io created

»Install Consul with the official Helm chart

Add the HashiCorp Helm Chart repository:

$ helm repo add hashicorp https://helm.releases.hashicorp.com
"hashicorp" has been added to your repositories

$ helm repo add hashicorp https://helm.releases.hashicorp.com"hashicorp" has been added to your repositories

You can now deploy a complete Consul datacenter in your Kubernetes cluster using the official Consul Helm chart or the Consul K8S CLI. The chart comes with reasonable defaults, however, you will utilize a few custom values with the config.yaml file to help things go more smoothly with kind and enable useful features.

$ helm install --values consul/config.yaml consul hashicorp/consul --version "0.40.0"

$ helm install --values consul/config.yaml consul hashicorp/consul --version "0.40.0"

Note: You can review the official Helm chart values to learn more about the default settings.

Security Warning: This tutorial is not for production use. By default, the chart will install an insecure configuration of Consul. Refer to the Secure Consul and Registered Services on Kubernetes tutorial to learn how you can secure Consul on Kubernetes in production. Additionally, it is highly recommended you use a properly secured Kubernetes cluster or make sure that you understand and enable the recommended security features.

»Create environment

»Create the example application pods

Deploy the Hashicups and Echo applications:

$ kubectl apply --filename two-services/

$ kubectl apply --filename two-services/

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

$ kubectl get pods
NAME                                             READY   STATUS    RESTARTS   AGE
consul-api-gateway-controller-5c46947749-768tr   1/1     Running   1          3m1s
consul-client-n6b7g                              1/1     Running   0          3m1s
consul-connect-injector-5c6557976b-p4dbv         1/1     Running   0          3m1s
consul-connect-injector-5c6557976b-xwwqj         1/1     Running   0          3m1s
consul-controller-84b676b9bb-2bb8g               1/1     Running   0          3m1s
consul-server-0                                  1/1     Running   0          3m1s
consul-webhook-cert-manager-8595bff784-t79zh     1/1     Running   0          3m1s
echo-1-79b597d656-75x4q                          2/2     Running   0          76s
echo-2-94b68d65b-7djtg                           2/2     Running   0          77s
frontend-5c54674c4-j7nsp                         2/2     Running   0          76s
payments-77598ddb8f-c595l                        2/2     Running   0          76s
postgres-8479965456-4xb9q                        2/2     Running   0          77s
product-api-dcf898744-zp7s4                      2/2     Running   0          77s
public-api-7f67d79fb6-wj8r4                      2/2     Running   0          76s

$ kubectl get podsNAME                                             READY   STATUS    RESTARTS   AGEconsul-api-gateway-controller-5c46947749-768tr   1/1     Running   1          3m1sconsul-client-n6b7g                              1/1     Running   0          3m1sconsul-connect-injector-5c6557976b-p4dbv         1/1     Running   0          3m1sconsul-connect-injector-5c6557976b-xwwqj         1/1     Running   0          3m1sconsul-controller-84b676b9bb-2bb8g               1/1     Running   0          3m1sconsul-server-0                                  1/1     Running   0          3m1sconsul-webhook-cert-manager-8595bff784-t79zh     1/1     Running   0          3m1secho-1-79b597d656-75x4q                          2/2     Running   0          76secho-2-94b68d65b-7djtg                           2/2     Running   0          77sfrontend-5c54674c4-j7nsp                         2/2     Running   0          76spayments-77598ddb8f-c595l                        2/2     Running   0          76spostgres-8479965456-4xb9q                        2/2     Running   0          77sproduct-api-dcf898744-zp7s4                      2/2     Running   0          77spublic-api-7f67d79fb6-wj8r4                      2/2     Running   0          76s

»Inspect the API Gateway configuration file

The API Gateway Controller consists of multiple components that facilitate ingress into your Consul service mesh.

Inspect the api-gateway/api-gw/consul-api-gateway.yaml file contents in your project directory:

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: Gateway
metadata:
  name: example-gateway
spec:
  gatewayClassName: consul-api-gateway
  listeners:
  - protocol: HTTPS
    port: 8443
    name: https
    allowedRoutes:
      namespaces:
        from: Same
    tls:
      certificateRefs:
        - name: consul-server-cert

api-gateway/api-gw/consul-api-gateway.yaml

apiVersion: gateway.networking.k8s.io/v1alpha2kind: Gatewaymetadata:  name: example-gatewayspec:  gatewayClassName: consul-api-gateway  listeners:  - protocol: HTTPS    port: 8443    name: https    allowedRoutes:      namespaces:        from: Same    tls:      certificateRefs:        - name: consul-server-cert

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. To see more details about this type, see the Kubernetes Gateway documentation
GatewayClass - This object (deployed and configured by the Helm chart) describes a class of Gateways available to the user for creating Gateway resources. To see more details about this type, see the Kubernetes GatewayClass documentation
GatewayClassConfig - This object (deployed and configured by the Helm chart) describes additional Consul API Gateway related configuration parameters for the GatewayClass.

Note: Feel free to explore additional configuration details in the Consul API Gateway documentation.

»Inspect the Routes file

Routes tell your Consul API Controller how to handle traffic into your service mesh.

Inspect the api-gateway/api-gw/routes.yaml file contents in your project directory:

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: HTTPRoute
metadata:
  name: example-route-1
spec:
  parentRefs:
  - name: example-gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - kind: Service
      name: echo-1
      port: 8080
      weight: 50
    - kind: Service
      name: echo-2
      port: 8090
      weight: 50
---
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: HTTPRoute
metadata:
  name: example-route-2
spec:
  parentRefs:
  - name: example-gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - kind: Service
      name: frontend
      port: 80

api-gateway/api-gw/routes.yaml

apiVersion: gateway.networking.k8s.io/v1alpha2kind: HTTPRoutemetadata:  name: example-route-1spec:  parentRefs:  - name: example-gateway  rules:  - matches:    - path:        type: PathPrefix        value: /    backendRefs:    - kind: Service      name: echo-1      port: 8080      weight: 50    - kind: Service      name: echo-2      port: 8090      weight: 50---apiVersion: gateway.networking.k8s.io/v1alpha2kind: HTTPRoutemetadata:  name: example-route-2spec:  parentRefs:  - name: example-gateway  rules:  - matches:    - path:        type: PathPrefix        value: /    backendRefs:    - kind: Service      name: frontend      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. To see more details about this type, see the Kubernetes HTTPRoute documentation.
- 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 frontend service.

Note: Feel free to check out the Kubernetes HTTPRoute documentation for configuration options and details.

»Create the Consul API Gateway

Deploy the API Gateway.

$ kubectl apply --filename api-gw/consul-api-gateway.yaml
gateway.gateway.networking.k8s.io/example-gateway created

$ kubectl apply --filename api-gw/consul-api-gateway.yamlgateway.gateway.networking.k8s.io/example-gateway created

Deploy the associated HTTP Routes once the API gateway reaches a ready state.

$ kubectl wait --for=condition=ready gateway/example-gateway --timeout=90s && kubectl apply --filename api-gw/routes.yaml
gateway.gateway.networking.k8s.io/example-gateway condition met
httproute.gateway.networking.k8s.io/example-route-1 created
httproute.gateway.networking.k8s.io/example-route-2 created

$ kubectl wait --for=condition=ready gateway/example-gateway --timeout=90s && kubectl apply --filename api-gw/routes.yamlgateway.gateway.networking.k8s.io/example-gateway condition methttproute.gateway.networking.k8s.io/example-route-1 createdhttproute.gateway.networking.k8s.io/example-route-2 created

Run kubectl get pods to verify all pods have been properly created in your cluster. Your environment should look similar to the list below:

$ kubectl get pods
NAME                                             READY   STATUS    RESTARTS   AGE
consul-api-gateway-controller-5c46947749-768tr   1/1     Running   1          4m39s
consul-client-n6b7g                              1/1     Running   0          4m39s
consul-connect-injector-5c6557976b-p4dbv         1/1     Running   0          4m39s
consul-connect-injector-5c6557976b-xwwqj         1/1     Running   0          4m39s
consul-controller-84b676b9bb-2bb8g               1/1     Running   0          4m39s
consul-server-0                                  1/1     Running   0          4m39s
consul-webhook-cert-manager-8595bff784-t79zh     1/1     Running   0          4m39s
echo-1-79b597d656-75x4q                          2/2     Running   0          2m54s
echo-2-94b68d65b-7djtg                           2/2     Running   0          2m55s
example-gateway-d77749bf-fd7vm                   1/1     Running   0          30s
frontend-5c54674c4-j7nsp                         2/2     Running   0          2m54s
payments-77598ddb8f-c595l                        2/2     Running   0          2m54s
postgres-8479965456-4xb9q                        2/2     Running   0          2m55s
product-api-dcf898744-zp7s4                      2/2     Running   1          2m55s
public-api-7f67d79fb6-wj8r4                      2/2     Running   0          2m54s

$ kubectl get podsNAME                                             READY   STATUS    RESTARTS   AGEconsul-api-gateway-controller-5c46947749-768tr   1/1     Running   1          4m39sconsul-client-n6b7g                              1/1     Running   0          4m39sconsul-connect-injector-5c6557976b-p4dbv         1/1     Running   0          4m39sconsul-connect-injector-5c6557976b-xwwqj         1/1     Running   0          4m39sconsul-controller-84b676b9bb-2bb8g               1/1     Running   0          4m39sconsul-server-0                                  1/1     Running   0          4m39sconsul-webhook-cert-manager-8595bff784-t79zh     1/1     Running   0          4m39secho-1-79b597d656-75x4q                          2/2     Running   0          2m54secho-2-94b68d65b-7djtg                           2/2     Running   0          2m55sexample-gateway-d77749bf-fd7vm                   1/1     Running   0          30sfrontend-5c54674c4-j7nsp                         2/2     Running   0          2m54spayments-77598ddb8f-c595l                        2/2     Running   0          2m54spostgres-8479965456-4xb9q                        2/2     Running   0          2m55sproduct-api-dcf898744-zp7s4                      2/2     Running   1          2m55spublic-api-7f67d79fb6-wj8r4                      2/2     Running   0          2m54s

»Perform testing procedures

»Explore the Consul UI

Run kubectl get pods to verify all pods have been properly created in your cluster. Your environment should look similar to the list below:

Expose the Consul UI with kubectl port-forward using the consul-ui service name as the target.

$ kubectl port-forward svc/consul-ui 6443:443

$ kubectl port-forward svc/consul-ui 6443:443

Check out the Consul UI at https://localhost:6443. Since this environment uses a self-signed TLS certificate for it's resources, click to proceed through the certificate warnings.

When the API Gateway has been successfully deployed, the Hashicups and Echo services will appear as intentions here: https://localhost:6443/ui/dc1/services/test-gateway/intentions

»Explore the sample applications

The diagram below shows the structure of the Kubernetes cluster you have created. This includes the API Gateway Controller, the service mesh layer, and various pods.

The Consul API Gateway can be configured to handle ingress for multiple services using a variety of methods.

»Use Case 1: Ingress

The Consul API Gateway can easily be configured for 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 https://localhost:8443/hashicups. The Hashicups application is a collection of pods that together form a microservice application.

To review, this HTTPRoute code snippet from the api-gateway/api-gw/routes.yaml file is what enables the single-service ingress behavior to the frontend service.

---
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: HTTPRoute
metadata:
  name: example-route-2
spec:
  parentRefs:
  - name: example-gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - kind: Service
      name: frontend
      port: 80
---

---apiVersion: gateway.networking.k8s.io/v1alpha2kind: HTTPRoutemetadata:  name: example-route-2spec:  parentRefs:  - name: example-gateway  rules:  - matches:    - path:        type: PathPrefix        value: /    backendRefs:    - kind: Service      name: frontend      port: 80---

»Use Case 2: Load Balancing

The Consul API Gateway can also be used to load balance between multiple services within your 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 https://localhost:8443/echo to see that the API Gateway is 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 api-gateway/api-gw/routes.yaml file is what enables the load balancing behavior between the two echo services.

---
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: HTTPRoute
metadata:
  name: example-route-1
spec:
  parentRefs:
  - name: example-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/v1alpha2kind: HTTPRoutemetadata:  name: example-route-1spec:  parentRefs:  - name: example-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---

Note: For more information on accessing service mesh services via the Consul API Gateway, visit the Consul API Gateway documentation page.

»Clean up environment

Clean up the environment you just created:

$ kind delete cluster

$ kind delete cluster

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

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

Infrastructure

Security

Applications

Networking

cloud