Routes¶

A Route defines which incoming requests the Obsidian gateway accepts and which Service receives them. The Service describes the upstream destination; the Route describes the public request conditions that lead to that destination.

Every Route is linked to one Service, while one Service can have several Routes. Route-scoped plugins can add authentication, rate limiting, transformation, or logging behaviour to only the traffic matching that Route.

Understand request routing¶

For every incoming request, the gateway compares request properties with configured Routes. A Route can match on:

protocol;
host name;
URL path;
HTTP method;
one or more request headers;
TLS Server Name Indication (SNI); or
source and destination IP address or port for stream traffic.

When the request matches a Route, it is proxied to the linked Service. If several Routes could match, the gateway uses routing priority to choose the most specific applicable Route.

Client request
     │
     ▼
Route matching rules
  protocol + host + path + method + headers
     │
     ▼
Route-scoped plugins
     │
     ▼
Linked Service
     │
     ▼
Upstream application

How multiple matching fields work¶

Different fields work together as AND conditions. Multiple values inside one field work as OR choices.

For example, consider this Route:

Field	Values
Protocols	`https`
Hosts	`api.example.com`, `api.example.org`
Paths	`/orders`, `/returns`
Methods	`GET`

The following request matches because it satisfies every configured field:

GET /orders/123 HTTP/1.1
Host: api.example.com

These requests do not match:

POST /orders/123 — the method is not GET;
GET /customers/123 — the path does not match either configured prefix;
GET /orders/123 with host other.example.com — the host is not configured; or
the same request over HTTP — the Route only accepts HTTPS.

Configure only the criteria needed to identify the traffic. A Route with overly broad rules may capture requests intended for another Service, while an overly narrow Route can leave valid requests unmatched.

When to use Routes¶

Use Gateway Configuration > Routes when you need to:

expose a new Service through the gateway;
give one Service several public hosts, paths, or methods;
send different request patterns to different Services;
apply plugins to a specific public endpoint;
change how a matched path or Host header is sent upstream;
route TCP, TLS, gRPC, or gRPCS traffic; or
diagnose why a request reaches the wrong Service or no Service at all.

Create the Service before creating a standalone Route. A guided Workflow can create the Service and Route in sequence.

Understand the Routes list¶

Routes list

The list and grid layouts show:

Column	What it tells you
Name	The unique, case-sensitive Route name.
Service Name	The upstream Service that receives matching traffic. Select it to open the Service.
Hosts	Host header values that can match the Route.
Paths	URL paths or prefixes that can match the Route.
Protocols	The accepted protocol group.
Created	When the Route was created.
Actions	Edit and delete controls available to your role.

Search can match the beginning of a Route name, ID, Service name, host, path, protocol, or created date. Filters can find Routes that:

preserve the incoming Host header;
use request buffering;
are HTTP-only or HTTPS-only;
contain host matchers; or
contain path matchers.

Selected filters work together, so clear filter chips when an expected Route is missing.

Create a Route¶

Confirm that the destination Service exists and has the correct protocol, host, port, and path.
Open Gateway Configuration > Routes.
Select New Route.
Select the destination Service.
Enter a unique Route Name.
Select one compatible protocol group.
Add at least one matching criterion appropriate for that protocol.
Review Advanced Configuration before accepting its defaults.
Select Create Route.
Test both requests that should match and requests that should not match.

Basic Route configuration

Routes can also be created from a Service, where the Service is preselected, or from a Workflow, where the Route returns to the wizard after validation.

Basic Route Configuration¶

Service¶

The Service is the upstream destination for every request matching this Route. The selection is required during standalone creation. It cannot be changed accidentally from the normal edit form because the Service selector is hidden while editing.

Check the Service's upstream host and path before troubleshooting Route path behaviour.

Name¶

The name is required, unique, and case-sensitive. It can contain up to 128 characters using letters, numbers, dots, dashes, underscores, and tildes.

Use a predictable name that identifies the destination and public match, for example:

orders-api-v1-https

Do not encode passwords, customer personal information, or temporary incident details in a Route name.

Protocols¶

At least one protocol is required. The portal supports:

Protocol	Typical use	Available match fields
`http`	Unencrypted HTTP request routing.	Hosts, paths, methods, headers.
`https`	HTTP protected with TLS.	Hosts, paths, methods, headers, SNIs.
`tcp`	Raw TCP stream routing.	Source and destination IPs/ports.
`tls`	TLS stream terminated or inspected by the gateway.	Source, destination, and SNI.
`tls_passthrough`	TLS passed through without gateway termination.	SNI.
`grpc`	Unencrypted gRPC routing.	Hosts, paths, headers.
`grpcs`	gRPC protected with TLS.	Hosts, paths, headers, SNIs.

Compatible pairs such as http and https, tcp and tls, or grpc and grpcs can be used together. Protocol families are mutually exclusive; for example, an HTTP/HTTPS Route cannot also be a TCP/TLS Route. tls and tls_passthrough cannot be selected together.

Changing the protocol clears match fields that no longer apply. Review the whole form after changing it.

Hosts¶

Hosts match the incoming HTTP Host header. Add each hostname as a chip, for example api.example.com. Host values are case-sensitive in the portal configuration.

Use Hosts for public domain-based routing. Do not add the Host header again under Headers.

If DNS points to the gateway but the request does not match, verify the Host header actually sent by the client. Calling a gateway IP directly often sends the IP as the Host unless the client overrides it.

Paths¶

Paths must begin with /, for example /v1/orders. Plain paths normally act as prefixes, so /v1/orders/123 can match /v1/orders.

Use a path that is specific enough to distinguish the API without unnecessarily exposing implementation detail. When regular-expression routing is required, confirm the supported syntax and prefix for the environment and test conflicts carefully; regex Routes use Regex Priority.

Methods¶

The accepted values are:

GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD

Leave Methods empty when all HTTP methods should be eligible. Specify methods when different operations need different Services or Route-scoped plugins.

For example, two Routes can point to the same Service while applying stricter authentication and rate limiting to POST than to public GET requests.

Remember to include OPTIONS when browser CORS preflight traffic must match the same Route, unless another Route handles it.

Headers¶

Headers use this format:

name:value1,value2

For example:

X-API-Version:v1,v2

Multiple header names are AND conditions: the request must satisfy every configured header. Multiple values for one header are alternatives. Do not use Host here; use the dedicated Hosts field.

Header-based routing is useful for controlled versioning, tenants, or feature channels, but clients and intermediaries must preserve the header. Do not trust a freely supplied header as authentication.

Secure-protocol and stream match fields¶

SNIs¶

SNI is the hostname supplied during the TLS handshake. It is available for HTTPS, TLS, TLS passthrough, and gRPCS Routes. Add hostnames such as api.example.com.

SNI is established before an HTTP request and is different from the later HTTP Host header, although they are often the same hostname. Confirm that the relevant certificate covers the SNI.

Source IPs¶

Source matchers apply to TCP or TLS connections. Each entry can be:

an IP address;
a port; or
an IP and port separated by a colon, such as 192.0.2.10:8443.

Confirm whether load balancers or proxies change the source address visible to the gateway.

Destination IPs¶

Destination matchers use the IP address and/or port on which the incoming TCP/TLS connection reaches the gateway. Use the same ip, port, or ip:port format.

Do not confuse a Route destination matcher with the Service's upstream destination. The Route field describes the inbound connection; the Service describes where matched traffic is proxied.

Advanced Configuration¶

Advanced Route configuration

HTTPS Redirect Status Code¶

This value is used when the other Route conditions match but an HTTP request reaches a Route that requires HTTPS.

Code	Behaviour
`426`	Tells the client that a protocol upgrade is required. This is the portal default.
`301` or `308`	Permanent redirect. `308` preserves the original method and body.
`302` or `307`	Temporary redirect. `307` preserves the original method and body.

The gateway supplies a Location header for 301, 302, 307, and 308. Choose the code according to the API client behaviour; careless redirects can turn a non-GET request into a GET in some clients.

Strip Path¶

Strip Path is enabled by default for HTTP/HTTPS Routes. It removes the portion of the request path that matched the Route before proxying upstream.

Example:

Route path:       /public/orders
Incoming request: /public/orders/123
Strip Path:       On
Upstream suffix:  /123

With Strip Path off, the matching Route prefix remains in the upstream path. The final upstream path also depends on the path configured on the Service and Path Handling.

Strip Path is not offered for gRPC/gRPCS in the current portal.

Path Handling¶

Path Handling controls how the Service path, matched Route path, and remaining request path are joined.

v0 treats them as URL path segments, joins them with slashes, and is the current default.
v1 uses older joining behaviour where the Service path acts more like a raw prefix.

Keep v0 unless an existing integration was deliberately built around v1. Test trailing slashes and empty suffixes whenever this setting changes.

Preserve Host¶

When Preserve Host is off, the upstream Host header normally uses the host configured on the Service. When it is on, the gateway forwards the Host header supplied by the client.

Enable it only when the upstream server uses the public host for virtual-host routing, signature checks, or application logic. An upstream expecting its internal hostname can reject requests when the public host is preserved.

Regex Priority¶

Regex Priority is a non-negative number used when more than one regular-expression Route path matches. Higher values take priority. When matching regex Routes have the same priority, creation order can affect selection depending on the gateway router mode.

For plain paths, longer and more specific paths are normally preferred over shorter paths. Avoid solving every conflict with Regex Priority; first make the match rules unambiguous.

Request Buffering¶

Request Buffering is enabled by default. The gateway reads/buffers the incoming request body before or while forwarding it according to gateway behaviour. Disabling it can help streaming or chunked HTTP/1.1 uploads, but can affect plugins that need access to the complete body.

Response Buffering¶

Response Buffering is enabled by default. Disabling it can be appropriate for streaming or chunked responses, but transformation, logging, or other response plugins may rely on buffered content.

Change either buffering option only after checking the upstream protocol and Route plugins.

Tags¶

Tags are optional labels used to group and identify Routes. Add each tag once. Use an agreed convention such as environment, team, or API family; do not store secrets in tags.

Route priority and overlapping Routes¶

More specific Routes are generally considered before broader Routes. A Route that matches host, method, and path is normally more specific than one matching only the same host. Plain paths with longer prefixes normally take precedence over shorter ones, while regex paths use Regex Priority.

Before creating or changing a Route:

search for other Routes using the same host or path;
compare methods, headers, protocols, and SNIs;
identify which Route should win for every overlapping request; and
test both the specific Route and the broad fallback Route.

Avoid duplicate rules that depend only on creation order. They are difficult to understand and can behave differently after configuration migration.

Worked HTTP example¶

Assume the Service is configured with:

Protocol: https
Host: internal-orders.example.net
Port: 443
Path: /api

And the Route uses:

Protocols: https
Hosts: api.example.com
Paths: /orders
Methods: GET, POST
Strip Path: On
Path Handling: v0
Preserve Host: Off

This client request matches:

GET /orders/123 HTTP/1.1
Host: api.example.com

The gateway removes /orders, joins the remaining /123 to the Service path /api, and sends the request toward:

https://internal-orders.example.net:443/api/123

The upstream Host header is internal-orders.example.net because Preserve Host is off.

If Preserve Host were on, the upstream would receive Host: api.example.com. If Strip Path were off, the upstream path would retain the /orders segment.

Test a new or changed Route¶

Test in the approved environment before production rollout.

Positive tests¶

A valid host, path, method, protocol, and required header reaches the intended Service.
The upstream receives the expected path and Host header.
Authentication and other Route plugins behave correctly.
Request and response bodies work with the selected buffering settings.

Negative tests¶

A wrong host does not match.
A wrong path or method does not match.
HTTP is rejected or redirected as designed when HTTPS is required.
Missing or incorrect match headers do not reach the Service.
Requests intended for a neighbouring Route still reach that Route.

Record the Route name, request URL, method, headers, result status, and test time. Remove credentials and personal information before sharing evidence.

Edit a Route safely¶

Create a snapshot or record the current Route configuration.
Identify clients and other Routes that use the same host or path.
Change one routing concern at a time where possible.
Select Update Route.
Run the positive and negative tests again.
Check Dashboard errors, latency, and Audit Logs after rollout.

Changing a public host or path is an API contract change. Coordinate it with clients rather than treating it as an internal portal edit.

Delete a Route¶

Deleting a Route removes the public matching rule but does not delete its linked Service. Route-scoped plugin configurations can also be affected.

Before deletion, confirm that:

no active client uses the Route;
no fallback or hidden integration depends on it;
another Route provides the intended replacement where necessary; and
monitoring is ready to detect unmatched requests.

Prefer a controlled migration to a replacement Route before deletion.

Troubleshooting¶

The Create or Update button is disabled¶

Select a Service when creating outside a Workflow.
Enter a unique valid name of no more than 128 characters.
Add at least one accepted protocol.
Remove duplicate chips.
Correct invalid hosts, paths, headers, source/destination values, or SNIs.
Make sure the selected protocol family has the required compatible match fields.

The gateway reports no matching Route¶

Check the protocol, Host header, path, method, request headers, and SNI actually sent by the client.
Confirm that the Route was saved and appears in the list.
Check case and leading slashes.
Verify that the request reaches the correct gateway and environment.
Test without DNS ambiguity by explicitly supplying the intended Host only in an approved diagnostic tool.

The wrong Service receives the request¶

Search for Routes with overlapping hosts and paths.
Compare all match fields, not only the Route name.
Check plain-path length and Regex Priority.
Narrow the intended Route or the broader fallback Route.

The Route matches, but the upstream returns an error¶

401 or 403 often points to authentication, ACL, or upstream authorisation.
404 can mean the Route did not match, or that Strip Path/Service path created an upstream URL the application does not recognise.
413 can come from request-size controls.
429 can come from rate limiting or a custom service limit.
502, 503, or 504 often points to Service host, port, protocol, DNS, TLS, connectivity, or upstream availability.

Inspect the Route, linked Service, applicable plugins, Dashboard latency/errors, and Audit Logs together.

Browser requests fail but technical tests succeed¶

Check whether OPTIONS matches and whether the CORS plugin permits the browser origin, method, and headers. Browser CORS enforcement is separate from basic Route matching.

Warning

Route changes can redirect or interrupt live traffic immediately. Confirm the linked Service and test both matching and non-matching requests before and after saving.

The routing explanations follow the current portal implementation and the official Kong Route documentation. Exact priority behaviour can depend on the router mode configured for the Obsidian environment.