Skip to main content

Routes Configuration

Direct traffic to the right containers with flexible routing rules.

Overview​

Routes define how incoming requests are directed to your containers. SailOps supports multiple route types for different protocols and use cases.

Technical reference

The interface shows "HTTP route", "TCP route", "gRPC route" and "TLS route". On the API these are the unchanged Gateway API values HTTPRoute, TCPRoute, GRPCRoute and TLSRoute, which is what the tables below use.

Route Types​

HTTP route​

For standard web traffic and REST APIs:

  • HTTP/1.1 and HTTP/2 support
  • Path-based routing
  • Hostname-based matching
  • WebSocket support
ParameterValue
TypeHTTPRoute
Hostnamesapi.example.com
Path/api
Backendapi-service:8080

TCP route​

For raw TCP traffic:

  • Database connections
  • Custom protocols
  • Direct TCP forwarding
ParameterValue
TypeTCPRoute
Backenddatabase:5432

GRPC route​

For gRPC services:

  • gRPC protocol support
  • Service and method routing
  • gRPC health checks
ParameterValue
TypeGRPCRoute
Hostnamesgrpc.example.com
Backendgrpc-service:9090

TLS route​

For TLS passthrough:

  • TLS SNI-based routing
  • End-to-end encryption (no TLS termination at the gateway)
  • Direct passthrough to backend services
ParameterValue
TypeTLSRoute
Hostnamessecure.example.com
Backendtls-service:443

Creating a Route​

Step-by-Step​

  1. Go to your gateway
  2. Click the Routes tab
  3. Click Create Route
  4. Select the route type
  5. Configure:
FieldDescriptionExample
NameUnique identifierapi-route
TypeHTTPRoute, TCPRoute, GRPCRoute, or TLSRouteHTTPRoute
HostnamesDomain names for the routeapi.example.com
BackendService and portapi-service:8080
  1. Click Create
Backend validation

Backend services are validated against the project's endpoint catalog at creation and update time for all route types. Only declared customer endpoints are accepted — selecting an unknown service, a port the endpoint does not expose, or a route type it does not support will produce a validation error.

Backend service selector​

The backend selector displays every declared application endpoint in your project. Each entry shows the resource name, its type (container, PostgreSQL, MariaDB, Valkey, NATS, Kafka, Keycloak, Supabase, OpenSearch, custom service, or website), and its endpoint role. Resources with multiple endpoints — for example PostgreSQL read-write, read-only and replicas, or MariaDB primary and read — appear as separate entries under the same resource name.

Endpoints that are still provisioning, that belong to a service whose access policies prevent custom exposure, or that do not support the current route type are shown but disabled, with a reason displayed below the entry.

You can type in the search field to filter by name, type, or endpoint. Results are sorted alphabetically.

If a route already references a backend that no longer appears in the catalog, the selector keeps the existing reference read-only until you explicitly choose a replacement.

HTTP route configuration​

Path Matching​

HTTP routes support different path matching types:

Match TypeDescriptionExample
ExactMatches the path exactly/api matches only /api
PathPrefixMatches path prefixes/api matches /api, /api/users
RegularExpressionMatches using regex patterns/api/v[0-9]+ matches /api/v1, /api/v2

Path Prefix Examples​

Route PathMatchesDoesn't Match
/Everything-
/api/api, /api/users, /api/v1/data/application
/api//api/, /api/users/api (no trailing slash)

Multiple Hostnames​

A single route can handle multiple hostnames (up to 16 per route). Hostnames must be lowercase, may contain hyphens and dots, and optionally start with a wildcard prefix (*.):

ParameterValue
Namemulti-domain-route
Hostnamesexample.com, www.example.com, app.example.com
Backendfrontend:3000

Multiple Backends​

Route traffic to multiple containers for load balancing:

ParameterValue
Nameload-balanced-api
Hostnamesapi.example.com

Backends:

ServicePort
api-18080
api-28080
api-38080

Route Status​

DNS Status​

Each route hostname shows its DNS configuration status:

StatusDescription
DNS (green)Domain correctly points to gateway
DNS (red)Domain does not point to gateway
DNS (grey)Status check has not completed yet

TLS Certificate Status​

For HTTPS routes where the gateway terminates TLS:

StatusDescription
Cert (green)Certificate is valid and active
Cert (red)Certificate issue or provisioning
Cert (grey)Certificate status check has not completed yet

A TLS route uses passthrough mode, so SailOps does not provision or report the backend certificate. The backend must present and renew a certificate valid for every configured SNI hostname.

Managing Routes​

Route list details​

Each route in the list shows summary information at a glance:

  • Backends — the services the route forwards traffic to, with the target port
  • Paths — for HTTP routes, the first matched path and a count of additional paths (hover for the full list)
  • Timeouts — the request timeout (or the backend request timeout when no request timeout is set), with a count when multiple rules define different values
  • Attached policies — policy types directly attached to the route (access control, traffic & limits), excluding platform defaults applied by selector
  • DNS / TLS status — per-hostname DNS and certificate badges
  • Created — relative creation time

Filtering Routes​

Use the filter buttons to view routes by type:

  • All Routes - View all configured routes
  • HTTP routes - HTTP routes only
  • TCP routes - TCP routes only
  • gRPC routes - gRPC routes only
  • TLS routes - TLS routes only

Searching Routes​

Search by:

  • Route name
  • Hostname
  • Backend service name

Sorting Routes​

Sort routes by:

  • Name (A-Z or Z-A)
  • Created date (newest or oldest)

Editing a Route​

  1. Find the route in the list
  2. Click the edit icon
  3. Modify configuration
  4. Click Save

Changes take effect within seconds.

Deleting a Route​

  1. Find the route in the list
  2. Click the delete icon
  3. Confirm deletion
warning

Deleting a route immediately stops traffic for that route configuration.

Common Patterns​

API Versioning​

NameTypeHostnamePathBackend
api-v2HTTPRouteapi.example.com/v2api-v2:8080
api-v1HTTPRouteapi.example.com/v1api-v1:8080

Microservices Architecture​

NameTypeHostnamePathBackend
users-apiHTTPRouteapi.example.com/usersuser-service:8080
orders-apiHTTPRouteapi.example.com/ordersorder-service:8080
payments-apiHTTPRouteapi.example.com/paymentspayment-service:8080

Frontend + API​

NameTypeHostnamePathBackend
api-routeHTTPRouteapp.example.com/apiapi:8080
frontend-routeHTTPRouteapp.example.com/frontend:3000

gRPC Services​

NameTypeHostnameBackend
grpc-usersGRPCRoutegrpc.example.comuser-grpc:9090
grpc-ordersGRPCRoutegrpc.example.comorder-grpc:9090

Route Priority​

Automatic Priority​

Routes are automatically ordered by specificity:

  1. Longer paths match first
  2. Exact matches before prefix matches
  3. More specific rules before general

Example Priority Order​

Given these routes:

  1. /api/v2/users (most specific)
  2. /api/v2
  3. /api
  4. / (least specific)

A request to /api/v2/users/123 matches route #1.

Troubleshooting​

Route Not Matching​

  1. Check path spelling and format
  2. Verify hostname matches listener
  3. Check route priority order
  4. Test with curl for details:
curl -v https://api.example.com/your-path

Traffic Going to Wrong Backend​

  1. Review route order and specificity
  2. Check path prefix conflicts
  3. Verify hostname configuration

502 Bad Gateway​

The gateway cannot reach the container:

  • Container may have crashed
  • Port mismatch between route and container
  • Container not ready yet

504 Gateway Timeout​

Without a route request timeout, Envoy ends requests after 15 s. A streaming response cut after its headers keeps its 2xx status and counts only as a timeout. Set an appropriate request timeout, or 0s to disable this limit on streaming routes.