Define API gateway routes on virtual machines

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

Overview

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

Define routes in an HTTP or TCP configuration entry. The configuration entry includes rules for routing requests, target services in the mesh for the traffic, and the name of the gateway to attach to.
Deploy the configuration entry 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 is bound to the gateway successfully.

Requirements

The following requirements must be satisfied to use API gateways on VMs:

Consul 1.15 or later
A Consul cluster with service mesh enabled. Refer to connect
Network connectivity between the machine deploying the API Gateway and a Consul cluster agent or server

ACL requirements

If ACLs are enabled, you must present a token with the following permissions to configure Consul and deploy API gateway routes:

Refer Mesh Rules for additional information about configuring policies that enable you to interact with Consul API gateway configurations.

Define the 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 route configuration entry file and specify the following settings:
- Kind: Set to http or tcp.
- Name: Specify a name for the route. The name is metadata that you can use to reference the configuration when performing Consul operations.
- Parents: Specifies a list of API gateways that the route binds to.
- Rules: If you are configuring HTTP routes, define a list of routing rules for constructing a routing table that maps listeners to services. Each member of the list is a map that may containing the following fields:
Refer to the HTTP route configuration entry and TCP route configuration entry reference for details about configuring routes.
Configure any additional fields necessary for your use case, such as the namespace or admin partition.
Save the configuration.

The following example routes requests from the listener on the API gateway at port 8443 to services in Consul based on the path of the request. When an incoming request starts at path /, Consul forwards 90 percent of the requests to the ui service and 10 percent to experimental-ui. Consul also forwards requests starting with /api to api.

Kind = "http-route"
Name = "my-http-route"

// Rules define how requests will be routed
Rules = [
  // Send all requests to UI services with 10% going to the "experimental" UI
  {
    Matches = [
      {
        Path = {
          Match = "prefix"
          Value = "/"
        }
      }
    ]
    Services = [
      {
        Name = "ui"
        Weight = 90
      },
      {
        Name = "experimental-ui"
        Weight = 10
      }
    ]
  },
  // Send all requests that start with the path `/api` to the API service
  {
    Matches = [
      {
        Path = {
          Match = "prefix"
          Value = "/api"
        }
      }
    ]
    Services = [
      {
        Name = "api"
      }
    ]
  }
]

Parents = [
  {
    Kind = "api-gateway"
    Name = "my-gateway"
    SectionName = "my-http-listener"
  }
]

Route to service subsets

When an http-route sends traffic to a single backend service, Consul API Gateway also evaluates the backend service's discovery chain. When the backend service has a service-router that routes matching requests to a service-resolver 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 http-route match and the service-router 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.

Kind          = "service-resolver"
Name          = "api"
DefaultSubset = "stable"
Subsets = {
  stable = {
    Filter = "Service.Meta.version == stable"
  }
  canary = {
    Filter = "Service.Meta.version == canary"
  }
}

Kind = "service-router"
Name = "api"
Routes = [
  {
    Match {
      HTTP {
        Header = [
          {
            Name  = "x-version"
            Exact = "canary"
          },
        ]
      }
    }

    Destination {
      Service       = "api"
      ServiceSubset = "canary"
    }
  },
]

Kind = "http-route"
Name = "api-route"

Rules = [
  {
    Matches = [
      {
        Path = {
          Match = "prefix"
          Value = "/api"
        }
      }
    ]
    Services = [
      {
        Name = "api"
      }
    ]
  }
]

Parents = [
  {
    Kind        = "api-gateway"
    Name        = "my-gateway"
    SectionName = "my-http-listener"
  }
]

TLS SDS service overrides

Route services can override listener/gateway default certificates by setting TLS.SDS.

HTTP route service override

Use Rules[].Services[].TLS.SDS in http-route.

CertResource is required when SDS is set.
ClusterName is optional and inherited from effective listener/gateway SDS cluster when omitted.
Hostnames must be set on the HTTP route when using service TLS.SDS overrides.

Kind = "http-route"
Name = "api-route"

Parents = [
  {
    Kind = "api-gateway"
    Name = "my-gateway"
    SectionName = "my-http-listener"
  }
]

Hostnames = ["foo.example.com", "bar.example.com"]

Rules = [
  {
    Services = [
      {
        Name = "svc-foo"
        TLS = {
          SDS = {
            CertResource = "foo.example.com"
          }
        }
      },
      {
        Name = "svc-bar"
      }
    ]
  }
]

TCP route service override

Use Services[].TLS.SDS in tcp-route.

CertResource is required when SDS is set.
ClusterName is optional and inherited from effective listener/gateway SDS cluster when omitted.
TCP routes currently support at most one service.
A TCP listener can only have one distinct effective TCP SDS override; conflicting overrides are rejected.

Kind = "tcp-route"
Name = "my-tcp-route"

Parents = [
  {
    Kind = "api-gateway"
    Name = "my-gateway"
    SectionName = "my-tcp-listener"
  }
]

Services = [
  {
    Name = "payments"
    TLS = {
      SDS = {
        CertResource = "payments.internal.example.com"
      }
    }
  }
]

Effective precedence

Certificate selection precedence is:

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

Deploy the route configuration

Run the consul config write command to attach the routes to the specified gateways. The following example writes a configuration called my-http-route.hcl:

$ consul config write my-http-route.hcl