API gateway for Kubernetes technical specifications

This topic describes the requirements and technical specifications associated with using Consul API gateway.

Datacenter requirements

Your datacenter must meet the following requirements prior to configuring the Consul API gateway:

HashiCorp Consul Helm chart v1.2.0 and later

TCP port requirements

The following table describes the TCP port requirements for each component of the API gateway.

Port	Description	Component
20000	Kubernetes readiness probe	Gateway instance pod
Configurable	Port for scraping Prometheus metrics. Disabled by default.	Gateway controller pod

OpenShift requirements

You can deploy API gateways to Kubernetes clusters managed by Red Hat OpenShift, which is a security-conscious, opinionated wrapper for Kubernetes. To enable OpenShift support, add the following parameters to your Consul values file and apply the configuration:

  openshift:
    enabled: true

Refer to the following topics for additional information:

Security context constraints

OpenShift requires a security context constraint (SCC) configuration, which restricts pods to specific groups. You can create a custom SCC or use one of the default constraints. Refer to the OpenShift documentation for additional information.

By default, the SCC is set to restricted-v2 for the managedGatewayClass that Consul automatically creates. The restricted-v2 SCC is one of OpenShifts default SCCs, but you can specify a different SCC in the openshiftSCCName parameter:

connectInject:
  apiGateway:
    managedGatewayClass:
      openshiftSCCName: "restricted-v2"

Privileged container ports

Containers cannot use privileged ports when OpenShift is enabled. Privileged ports are 1 through 1024, and serving applications from that range is a security risk.

To allow gateway listeners to use privileged port numbers, specify an integer value in the mapPrivilegedContainerPorts field of your Consul values configuration. Consul adds the value to listener port numbers that are set to a number in the privileged container range. Consul maps the configured port number to the total port number so that traffic sent to the configured port number is correctly forwarded to the service.

For example, if a gateway listener is configured to port 80 and the mapPrivilegedContainerPorts field is configured to 2000, then the actual port number on the underlying container is 2080.

You can set the mapPrivilegedContainerPorts parameter in the following map in your Consul values file:

connectInject:
  apiGateway:
    managedGatewayClass:
      mapPrivilegedContainerPorts: <value>

Supported versions of the Kubernetes gateway API specification

Refer to the release notes for your version of Consul.

Supported Kubernetes gateway specification features

Consul API gateways for Kuberentes support a subset of the Kubernetes Gateway API specification. For a complete list of features, including the list of gateway and route statuses and an explanation on how they are used, refer to the documentation in our GitHub repo:

`GatewayClass`

The GatewayClass resource describes a class of gateway configurations to use a template for creating Gateway resources. You can also specify custom API gateway configurations in a GatewayClassConfig CRD and attach them to resource to the GatewayClass using the parametersRef field.

You must specify the "hashicorp.com/consul-api-gateway-controller" controller so that Consul can manage gateways generated by the GatewayClass. Refer to the Kubernetes GatewayClass documentation for additional information.

`Gateway`

The Gateway resource is the core API gateway component. Gateways have one or more listeners that can route HTTP, HTTPS, or TCP traffic. You can define header-based hostname matching for listeners, but SNI is not supported.

You can apply filters to add, remove, and set header values on incoming requests. Gateways support the terminate TLS mode and core/v1/Secret TLS certificates. Extended option support includes TLS version and cipher constraints. Refer to the Kubernetes Gateway documentation for additional information.

`HTTPRoute`

HTTPRoute configurations determine HTTP paths between listeners defined on the gateway and services in the mesh. You can specify weights to load balance traffic, as well as define rules for matching request paths, headers, queries, and methods to ensure that traffic is routed appropriately. You can apply filters to add, remove, and set header values on requests sent through th route.

Routes support the following backend types:

core/v1/Service backend types when the route maps to service registered with Consul.
api-gateway.consul.hashicorp.com/v1alpha1/MeshService.

Refer to Kubernetes HTTPRoute documentation for additional information.

`TCPRoute`

TCPRoute configurations determine TCP paths between listeners defined on the gateway and services in the mesh. Routes support the following backend types:

core/v1/Service backend types when the route maps to service registered with Consul.
api-gateway.consul.hashicorp.com/v1alpha1/MeshService.

Refer to Kubernetes TCPRoute documentation for additional information.

`ReferenceGrant`

ReferenceGrant resources allow resources to reference resources in other namespaces. They are required to allow references from a Gateway to a Kubernetes core/v1/Secret in a different namespace. Without a ReferenceGrant, backendRefs attached to the gateway may not be permitted. As a result, the ReferenceGrant sets a ResolvedRefs status to False with the reason InvalidCertificateRef, which prevents the gateway from becoming ready.

ReferenceGrant resources are also required for references from an HTTPRoute or TCPRoute to a Kubernetes core/v1/Service in a different namespace. Without a ReferenceGrant, backendRefs attached to the route may not be permitted. As a result, Kubernetes sets a ResolvedRefs status to False with the reason RefNotPermitted, which causes the gateway listener to reject the route.

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.

Refer to the Kubernetes ReferenceGrant documentation for additional information.

Consul server deployments

Consul Enterprise and the free community edition are both supported.
Supported Consul Server deployment types:
- Self-Managed
- HCP Consul

Consul feature support

API gateways on Kubernetes support all Consul features, but you can only route traffic between multiple datacenters through peered connections. Refer to Route Traffic to Peered Services for additional information. WAN federation is not supported.

Deployment Environments

Consul API gateway can be deployed in the following Kubernetes-based environments:

Standard Kubernetes environments
AWS Elastic Kubernetes Service (EKS)
Google Kubernetes Engine (GKE)
Azure Kubernetes Service (AKS)

Resource allocations

The following resources are allocated for each component of the API gateway.

Gateway controller pod

CPU: None. Either the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration.
Memory: None. Either the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration.

Gateway instance pod

CPU: None. Either the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration.
Memory: None. Either the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration.