Routes, clusters, and destinations

Clearplane represents proxying as three connected resources:

  1. A route matches an incoming request and selects one upstream cluster.
  2. A cluster defines how Clearplane communicates with a logical pool of upstreams.
  3. A destination is one concrete upstream address in that cluster.

Routes match requests

A route can match a host, path, and optional HTTP methods. It also carries an order for resolving overlapping matches: lower order values are evaluated first.

Route settings control request-facing behavior such as redirects, path rewriting, and policy assignments. Disabling a route removes that match from the active Edge configuration without deleting its cluster.

Wildcard hosts

Proxy routes accept exact DNS hosts and a leading wildcard such as *.example.com. A wildcard matches one subdomain level: it covers tenant.example.com, but excludes example.com and deep.tenant.example.com. List the apex separately when it should reach the same application. At equal route order, exact host matches take precedence over wildcard matches.

For Docker-discovered routes, use clearplane.proxy.host and the whitespace-separated clearplane.proxy.additional-hosts.

Routing and TLS coverage are separate. A wildcard certificate does not create a wildcard route, and a wildcard route needs a covering certificate for trusted HTTPS. See Enable HTTPS for DNS-01 profiles, certificate automation, and a complete label example.

Clusters group upstream behavior

A cluster owns one or more destinations and the behavior shared between them, including load balancing, health checks, timeouts, retries, and session affinity. Multiple routes can point to the same cluster when they should share the same upstream pool.

Destinations identify applications

Each enabled destination supplies a concrete upstream address. Edge selects an eligible destination from the route's cluster and proxies the request to it.

For a Docker-discovered service, Clearplane creates and maintains this route-and-cluster graph from the proxy labels and observed container address. Through the UI or REST API, you create the same ordinary resources directly. Both paths produce the same Edge routing model.

Request flow

Client request → matching route → upstream cluster → eligible destination

If no route matches, Edge returns a not-found response. If a route matches but no destination can serve the request, Edge returns an upstream failure response. Use Troubleshoot a service to work backward through that flow.