API gateways on Kubernetes overview

This topic provides overview information about API gateways for Consul on Kubernetes.

Introduction

API gateways enable external network clients to access applications and services running in a Consul datacenter. API gateways can also forward requests from clients to specific destinations based on path or request protocol. Systems that access services in the mesh may be internal or external to your organizational network. North-south traffic is a common term to describe this type of network traffic.

API gateway implements the Kubernetes Gateway API specification. For more information, refer to the official Kubernetes documentation

There are two API gateway controllers:

• Standard API gateway, API group gateway.networking.k8s.io
• Consul API gateway, API group consul.hashicorp.com

Standard API gateway

The Standard API gateway is the default implementation. Developed under the gateway.networking.k8s.io is already used in previous Consul releases, tested, and accepted by the Kubernetes community.

We recommend the Standard API gateway for every new installation except when your Kubernetes platform manages the Gateway CRDs, supports only stable API versions (v1), and your applications use TCPRoute.

In this case, use the Consul API Gateway instead, as the Standard API Gateway does not support TCPRoute under these constraints.

Consul API gateway

Consul API Gateway is a Consul-specific API gateway developed under the consul.hashicorp.com API group. Use the Consul API gateway for platforms where gateway CRDs are managed externally and supporting only the stable v1 API version.

Use the Consul API gateway when your application requires TCPRoute, and either of the following conditions applies:

1. The platform manages the gateway CRDs, and the CRDs support only the stable v1 API version for gateways, gateway classes, and HTTP routes, and the v1beta1 API version for reference grants.
2. An external application or user installed the gateway CRDs, and the CRDs support only the stable v1 API version for gateways, gateway classes, and HTTP routes, and the v1beta1 API version for reference grants.

Example manifests

apiVersion: v1
items:
- apiVersion: gateway.networking.k8s.io/v1
  kind: Gateway
  metadata:
    labels:
      component: api-gateway
    name: api-gateway
    namespace: consul
  spec:
    gatewayClassName: consul
    listeners:
    - allowedRoutes:
        namespaces:
          from: All
      name: http
      port: 80
      protocol: HTTP
    - allowedRoutes:
        namespaces:
          from: All
      name: tcp-8090
      port: 8090
      protocol: TCP

apiVersion: v1
items:
- apiVersion: consul.hashicorp.com/v1beta1
  kind: Gateway
  metadata:
    labels:
      component: api-gateway-consul
    name: api-gateway-consul
    namespace: consul
  spec:
    gatewayClassName: consul-custom-class
    listeners:
    - allowedRoutes:
        namespaces:
          from: All
      name: http
      port: 80
      protocol: HTTP
    - allowedRoutes:
        namespaces:
          from: All
      name: tcp-8090
      port: 8090
      protocol: TCP

Workflow

To use an API gateway on Consul:

1. Verify technical specifications for your cluster. OpenShift users in particular must verify specific parameters in the Helm chart.
2. Configure the API gateway to enable it.
3. Configure gateway scaling if you want to manage static replicas or controller-managed HPA behavior for individual gateways.
4. Deploy listeners. Configure one or more listeners to serve as ingress points for requests to services in Consul's service mesh.
5. Define a route so that the listener can forward the request to the service in the mesh. Routes can be tuned to define complex traffic shaping. For example, you can Reroute HTTP requests to define URL rewrite rules for the services in your Kubernetes cluster.

Consul API gateway reference objects

Refer to the following table for the Consul API gateway resource details:

Guidance

The following resources are available to help you use Consul API gateways on Kubernetes.

Tutorials

• Enable external traffic ingress into Consul service mesh
• Control access into the service mesh with Consul API gateway

Usage documentation

• Scale API gateways on Kubernetes
• Deploy API gateway listeners to Kubernetes
• Deploy API gateway routes to Kubernetes
• Reroute HTTP requests in Kubernetes
• Route traffic to peered services in Kubernetes
• Use JWTs to verify requests to API gateways on Kubernetes

Reference documentation

To use Consul API gateway on Kubernetes, you must configure the following custom resource definitions (CRDs).

Troubleshooting

API gateway on Kubernetes error messages can help you troubleshoot the most common API gateway errors on Kubernetes.