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.
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
| Parameter | Value |
|---|---|
| Type | HTTPRoute |
| Hostnames | api.example.com |
| Path | /api |
| Backend | api-service:8080 |
TCP route
For raw TCP traffic:
- Database connections
- Custom protocols
- Direct TCP forwarding
| Parameter | Value |
|---|---|
| Type | TCPRoute |
| Backend | database:5432 |
GRPC route
For gRPC services:
- gRPC protocol support
- Service and method routing
- gRPC health checks
| Parameter | Value |
|---|---|
| Type | GRPCRoute |
| Hostnames | grpc.example.com |
| Backend | grpc-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
| Parameter | Value |
|---|---|
| Type | TLSRoute |
| Hostnames | secure.example.com |
| Backend | tls-service:443 |
Creating a Route
Step-by-Step
- Go to your gateway
- Click the Routes tab
- Click Create Route
- Select the route type
- Configure:
| Field | Description | Example |
|---|---|---|
| Name | Unique identifier | api-route |
| Type | HTTPRoute, TCPRoute, GRPCRoute, or TLSRoute | HTTPRoute |
| Hostnames | Domain names for the route | api.example.com |
| Backend | Service and port | api-service:8080 |
- Click Create
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 Type | Description | Example |
|---|---|---|
| Exact | Matches the path exactly | /api matches only /api |
| PathPrefix | Matches path prefixes | /api matches /api, /api/users |
| RegularExpression | Matches using regex patterns | /api/v[0-9]+ matches /api/v1, /api/v2 |
Path Prefix Examples
| Route Path | Matches | Doesn'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 (*.):
| Parameter | Value |
|---|---|
| Name | multi-domain-route |
| Hostnames | example.com, www.example.com, app.example.com |
| Backend | frontend:3000 |
Multiple Backends
Route traffic to multiple containers for load balancing:
| Parameter | Value |
|---|---|
| Name | load-balanced-api |
| Hostnames | api.example.com |
Backends:
| Service | Port |
|---|---|
| api-1 | 8080 |
| api-2 | 8080 |
| api-3 | 8080 |
Route Status
DNS Status
Each route hostname shows its DNS configuration status:
| Status | Description |
|---|---|
| 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:
| Status | Description |
|---|---|
| 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
- Find the route in the list
- Click the edit icon
- Modify configuration
- Click Save
Changes take effect within seconds.
Deleting a Route
- Find the route in the list
- Click the delete icon
- Confirm deletion
Deleting a route immediately stops traffic for that route configuration.
Common Patterns
API Versioning
| Name | Type | Hostname | Path | Backend |
|---|---|---|---|---|
| api-v2 | HTTPRoute | api.example.com | /v2 | api-v2:8080 |
| api-v1 | HTTPRoute | api.example.com | /v1 | api-v1:8080 |
Microservices Architecture
| Name | Type | Hostname | Path | Backend |
|---|---|---|---|---|
| users-api | HTTPRoute | api.example.com | /users | user-service:8080 |
| orders-api | HTTPRoute | api.example.com | /orders | order-service:8080 |
| payments-api | HTTPRoute | api.example.com | /payments | payment-service:8080 |
Frontend + API
| Name | Type | Hostname | Path | Backend |
|---|---|---|---|---|
| api-route | HTTPRoute | app.example.com | /api | api:8080 |
| frontend-route | HTTPRoute | app.example.com | / | frontend:3000 |
gRPC Services
| Name | Type | Hostname | Backend |
|---|---|---|---|
| grpc-users | GRPCRoute | grpc.example.com | user-grpc:9090 |
| grpc-orders | GRPCRoute | grpc.example.com | order-grpc:9090 |
Route Priority
Automatic Priority
Routes are automatically ordered by specificity:
- Longer paths match first
- Exact matches before prefix matches
- More specific rules before general
Example Priority Order
Given these routes:
/api/v2/users(most specific)/api/v2/api/(least specific)
A request to /api/v2/users/123 matches route #1.
Troubleshooting
Route Not Matching
- Check path spelling and format
- Verify hostname matches listener
- Check route priority order
- Test with curl for details:
curl -v https://api.example.com/your-path
Traffic Going to Wrong Backend
- Review route order and specificity
- Check path prefix conflicts
- 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.