A new platform for documentation and tutorials is launching soon.

We are migrating Consul documentation into HashiCorp Developer, our new developer experience.

Join Now
Type '/' to Search

»Consul API Gateway Overview

This topic provides an overview of the Consul API Gateway.

»What is Consul API Gateway?

Consul API Gateway is an add-on for Consul that helps users control access to services running within a Consul service mesh. The API gateway enables external network clients to access applications and services running in a Consul datacenter. This type of network traffic is commonly referred to as "north-south" network traffic as it refers to the flow of data into and out of a specific environment. Requests from clients can also be forwarded based on path or request protocol.

Consul API Gateway solves the following primary use cases:

  • Controlling access at the point of entry: Consul API Gateway allows users to set the protocols of external connection requests and provide clients with TLS certificates from trusted providers (e.g., Verisign, Let's Encrypt).
  • Simplifying traffic management: The Consul API Gateway can load balance requests across services and route traffic to the appropriate service by matching one or more criteria, such as hostname, path, header presence or value, and HTTP Method type (e.g., GET, POST, PATCH).

»How Does Consul API Gateway Work?

Consul API Gateway can be deployed on Kubernetes-based runtime environments and requires that Consul service mesh be deployed on the Kubernetes cluster.

API Gateway routes traffic to services connected to the same service mesh. Those services can be running on the same Kubernetes cluster as the API Gateway, a different Kubernetes cluster, or another runtime, as long as they are connected to the same service mesh deployment and reachable over the network.

Consul API Gateway implements and is configured through the Kubernetes Gateway API Specification. This specification defines a set of custom resource definitions (CRD) that can create logical gateways which route traffic based on a client request's path or protocol.

»Supported Kubernetes Gateway Specification Features

The Consul API Gateway supports a subset of the Kubernetes v1alpha2 Gateway API specification. The following table describes the supported features of the specification. For a complete list of features, including the list of gateway and route statuses and an explanation on how they are used, see the documentation in our GitHub repo.

Kubernetes ObjectDescription
GatewayClass
  • Parameter specification via GatewayClassConfig CRD
  • Controller matching on "hashicorp.com/consul-api-gateway-controller"
Gateway
  • Supported protocols: HTTP, HTTPS, TCP
  • Header-based hostname matching (no SNI support)
  • Supported filters: header addition, removal, and setting
  • TLS modes supported: terminate
  • Certificate types supported: core/v1/Secret
  • Extended options: TLS version and cipher constraints
HTTPRoute
  • Weight-based load balancing
  • Supported rules: path, header, query, and method-based matching
  • Supported filters: header addition, removal, and setting
  • Supported backend types:
    1. core/v1/Service (must map to a registered Consul service)
    2. api-gateway.consul.hashicorp.com/v1alpha1/MeshService
TCPRoute
  • Supported backend types:
    1. core/v1/Service (must map to a registered Consul service)
    2. api-gateway.consul.hashicorp.com/v1alpha1/MeshService
ReferenceGrant
  • Required to allow any reference from a Gateway to a Kubernetes core/v1/Secret in a different namespace.
    • A Gateway with an unpermitted certificateRefs caused by the lack of a ReferenceGrant sets a ResolvedRefs status to False with the reason InvalidCertificateRef. The Gateway will not become ready in this case.
  • Required to allow any reference from an HTTPRoute or TCPRoute to a Kubernetes core/v1/Service in a different namespace.
    • A route with an unpermitted backendRefs caused by the lack of a ReferenceGrant sets a ResolvedRefs status to False with the reason RefNotPermitted. The gateway listener rejects routes with an unpermitted backendRefs.
    • WARNING: If a route backendRefs becomes unpermitted, the entire route is removed from the gateway listener.
      • A backendRefs can become unpermitted when you delete a ReferenceGrant or add a new unpermitted backendRefs to an existing route.

»Additional Resources

You can learn more about using Consul API Gateway by completing the Consul API Gateway tutorial.