Define API gateway routes on Kubernetes

This topic describes how to configure HTTP and TCP routes and attach them to Consul API gateway listeners in Kubernetes-orchestrated networks. Routes are rule-based configurations that allow external clients to send requests to services in the mesh. For information

Overview

The following steps describe the general workflow for defining and deploying routes:

Define a route configuration that specifies the protocol type, name of the gateway to attach to, and rules for routing requests.
Deploy the configuration to create the routes and attach them to the gateway.

Routes and the gateways they are attached to are eventually-consistent objects. They provide feedback about their current state through a series of status conditions. As a result, you must manually check the route status to determine if the route successfully bound to the gateway.

Requirements

Verify that your environment meets the requirements specified in Technical specifications for Kubernetes.

OpenShift

If your Kubernetes-orchestrated network runs on OpenShift, verify that OpenShift is enabled for your Consul installation. Refer to OpenShift requirements for additional information.

Define routes

Define route configurations and bind them to listeners configured on the gateway so that Consul can route incoming requests to services in the mesh.

Create a configuration file and specify the following fields:
- apiVersion: Specifies the Kubernetes API gateway version. This must be set to gateway.networking.k8s.io/v1beta1
- kind: Set to HTTPRoute or TCPRoute.
- metadata.name: Specify a name for the route. The name is metadata that you can use to reference the configuration when performing Consul operations.
- spec.parentRefs.name: Specifies a list of API gateways that the route binds to.
- spec. rules: Specifies a list of routing rules for constructing a routing table that maps listeners to services.
Refer to the Routes configuration reference for details about configuring route rules.
Configure any additional fields necessary for your use case, such as the namespace or admin partition.
Save the configuration.

The following example creates a route named example-route associated with a listener defined in example-gateway.

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: example-route
spec:
  parentRefs:
  - name: example-gateway
  rules:
  - backendRefs:
    - kind: Service
      name: echo
      port: 8080

Route to service subsets

When an HTTPRoute sends traffic to a single backend service, Consul API Gateway also evaluates the backend service's discovery chain. When the backend service has a ServiceRouter that routes matching requests to a ServiceResolver subset, the API gateway preserves that subset routing when it builds the gateway discovery chain.

You can expose an HTTP route at the gateway while using Consul service mesh traffic management, such as routing a subset of requests to a canary service version. Consul applies the HTTPRoute match and the ServiceRouter match. For example, a request must match the gateway route and the service-router rule before Consul routes it to the subset destination.

The following example routes requests with the x-version: canary header to the canary subset of the api service. All other requests that match the route use the stable default subset.

apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceResolver
metadata:
  name: api
spec:
  defaultSubset: stable
  subsets:
    stable:
      filter: Service.Meta.version == stable
    canary:
      filter: Service.Meta.version == canary
---
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceRouter
metadata:
  name: api
spec:
  routes:
    - match:
        http:
          header:
            - name: x-version
              exact: canary
      destination:
        service: api
        serviceSubset: canary
---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: api-route
spec:
  parentRefs:
  - name: example-gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api
    backendRefs:
    - kind: Service
      name: api
      port: 8080

TLS SDS backend override for HTTP routes

In Kubernetes, backend-level SDS certificate override for HTTP routes is configured with RouteTLSSDSFilter attached under HTTPRoute.rules[].backendRefs[].filters[].

Filter fields:

spec.sds.certResource (required)
spec.sds.clusterName (optional when inherited from listener/gateway SDS)

Behavior:

If clusterName is omitted, it can be inherited when exactly one listener-level/global SDS cluster is resolved from parent references.
If inherited clusterName is missing or ambiguous, the filter is rejected.
Rule-level filter placement (HTTPRoute.rules[].filters[]) is invalid for this override type.

Example: HTTPRoute backendRef override using RouteTLSSDSFilter

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: api-route-override
  namespace: default
spec:
  parentRefs:
  - name: sds-gateway
    sectionName: https
  hostnames:
  - b.example.test
  rules:
  - backendRefs:
    - name: svc-b
      port: 5678
      filters:
      - type: ExtensionRef
        extensionRef:
          group: consul.hashicorp.com
          kind: RouteTLSSDSFilter
          name: route-sds-override-http
---
apiVersion: consul.hashicorp.com/v1alpha1
kind: RouteTLSSDSFilter
metadata:
  name: route-sds-override-http
  namespace: default
spec:
  sds:
    clusterName: sds-cluster-2
    certResource: foo.example.com

Effective TLS SDS precedence

When configured, certificate selection precedence is:

Route service override TLS.SDS
Listener TLS.SDS
Gateway-level TLS.SDS

Troubleshooting checklist

Confirm RouteTLSSDSFilter is attached under backendRefs[].filters[].
Ensure spec.sds.certResource is non-empty.
Ensure clusterName is provided or can be inherited from listener/gateway SDS.
For hostname-based routing checks, verify hostnames and request host headers match expected values.

Deploy the route configuration

Apply the configuration to your cluster using the kubectl command. The following command applies the configuration to the consul namespace:

$ kubectl apply -f my-route.yaml -n consul