Enable API gateway for Kubernetes

The Consul API gateway ships with Consul and can be installed directly when you install Consul on Kubernetes.

Before Consul 2.0, API gateways were managed by the API group gateway.networking.k8s.io. This configuration is referred to as Standard API gateway.

Consul 2.0 introduces the Consul API gateway controller and the new API gateway CRDs under the API Group consul.hashicorp.com. This configuration is referred to as Consul API gateway.

Both controllers are supported by Consul's Helm chart.

If your environment supports it, we recommend the standard API gateway installation approach, which is the default installation choice.

Before you begin the installation process, verify that the environment you are deploying Consul and the API gateway in meets the requirements listed in the Technical Specifications. Refer to the Release Notes for any additional information about the version you are deploying.

Select your API gateway implementation

If your environment supports it, we recommend the standard API gateway installation approach, which is the default installation choice.

Use the Consul API gateway controller for the platforms that manage gateway CRDs under the API group gateway.networking.k8s.io in version v1 and is below 1.6.0 package version of the API group gateway.networking.k8s.io.

If the platform manages the gateway CRDs under the API group gateway.networking.k8s.io or if any other application or user externally installed these CRDs, set global.installK8sNetworkingCRDs: false.

Create a values.yaml file for configuring your Consul API gateway deployment and include the following settings:

values.yaml

global:
  installK8sNetworkingCRDs: true
  crds:
    enableTcpRoute: true
    consulapi:
      enabled: false
connectInject:
  enabled: true
  apiGateway:
    manageExternalCRDs: true

values.yaml

global:
  installK8sNetworkingCRDs: true
  openshift:
    enabled: true
    crds:
      enableTcpRoute: true
      consulapi:
        enabled: false
connectInject:
  enabled: true
  apiGateway:
    manageExternalCRDs: true
  cni:
    enabled: true
    logLevel: info
    multus: true
    cniBinDir: "/var/lib/cni/bin"
    cniNetDir: "/etc/kubernetes/cni/net.d"

values.yaml

global:
  installK8sNetworkingCRDs: false
  openshift:
    enabled: true
    crds:
      enableTcpRoute: false
      consulapi:
        enabled: false
connectInject:
  enabled: true
  apiGateway:
    manageExternalCRDs: true
  cni:
    enabled: true
    logLevel: info
    multus: true
    cniBinDir: "/var/lib/cni/bin"
    cniNetDir: "/etc/kubernetes/cni/net.d"

values.yaml

global:
  installK8sNetworkingCRDs: false
  openshift:
    enabled: true
    crds:
      enableTcpRoute: false
      consulapi:
        enabled: true
connectInject:
  enabled: true
  apiGateway:
    manageExternalCRDs: true
  cni:
    enabled: true
    logLevel: info
    multus: true
    cniBinDir: "/var/lib/cni/bin"
    cniNetDir: "/etc/kubernetes/cni/net.d"

By default, GKE Autopilot installs Gateway API resources.

The following working example enables both Consul service mesh and the Consul API gateway on GKE Autopilot. Refer to connectInject.agiGateway in the Helm chart reference for additional information. To support TCP route CRDs use Consul API gateway by setting global.crds.consulapi.enabled: true.

values.yaml

global:
  installK8sNetworkingCRDs: false
  crds:
    consulapi:
      enabled: false
connectInject:
  enabled: true
  apiGateway:
    manageExternalCRDs: false
    manageNonStandardCRDs: true

To support TCP route CRDs use Consul API gateway by setting global.crds.consulapi.enabled: true.

values.yaml

global:
  installK8sNetworkingCRDs: false
  crds:
    consulapi:
      enabled: false
connectInject:
  enabled: true
  apiGateway:
    manageExternalCRDs: false
    manageNonStandardCRDs: true

The Consul Helm chart deploys the Standard/Consul API gateway using the configuration specified in the values.yaml file.

Refer to Helm Chart Configuration - connectInject.apiGateway for information about the Helm chart configuration options.

API gateway reconciliation

Consul only reconciles API gateway resources that meet specific requirements. For Consul to manage an API gateway, the gateway must:

Include the required labels in the gateway metadata

labels:
  component: api-gateway

Specify the correct controller name that matches the gateway type.

Consul validates both criteria before reconciling the gateway object.

Standard API gateway

For the standard Kubernetes Gateway API that uses API Group gateway.networking.k8s.io/v1, the gateway must:

Set the gatewayClassName to reference a GatewayClass with controller name consul.hashicorp.com/gateway-controller
Include the label component: api-gateway in the metadata

Example configuration:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: api-gateway # can be modified 
  namespace: consul # can be modified
  labels:
    component: api-gateway # Do not modify this

Consul API gateway

For the Consul Gateway resource that uses API Group consul.hashicorp.com/v1beta1, the gateway must:

Set the gatewayClassName to reference a GatewayClass with controller name consul.hashicorp.com/gateway-controller-consul
Include the label component: api-gateway-consul in the metadata

Example configuration:

apiVersion: consul.hashicorp.com/v1beta1
kind: Gateway
metadata:
  name: api-gateway-consul # can be modified
  namespace: consul # can be modified
  labels:
    component: api-gateway-consul # Do not modify this