Use path-based routing

You can configure subdomains to route ingress traffic to different services and ports based on the path. You can route paths on a subdomain to multiple ports on the same service, ports on different services, as well as services in different projects.

When you add a new subdomain it will have the base path (/) added by default. You can link the subdomain to a service's port with no extra configuration required.

If you add multiple paths for a subdomain you may need to set their priority to ensure the correct routing is used.

You can configure as many paths for a subdomain as you need.

Navigate to your domains page and select add path on the entry for the subdomain you want to add path routing to.

Click add path in the paths section of your subdomain settings to add a new path.

Enter the URI as either plain text or regex and select the routing mode.

You can further configure the path by expanding advanced options. Advanced options can be edited after creating a path, but not the path URI or routing mode.

When you add a path you will need to select a routing mode to determine how Northflank should handle requests. You can enter a path as either plain text or as a regular expression. Paths take precedence based on their priority.

Exact

Will route requests only to the given path, and not any subpaths. For example, a path with the URI /path and the routing mode set to exact will route requests to /path to the assigned port, but not /path/subpath.

Requests to paths that include /path as a prefix will be routed to another path that matches, if any exists.

Prefix

Will route any paths beginning with the given URI to the assigned port. For example /path and /path/subpath will route to the assigned port, but not /acme/subpath.

RegEx

Will route paths that match the regex supplied as the URI. For example, /path|/acme will route requests to /path or /acme to the assigned port, but not /path/subpath or /blog.

You can configure more settings for each path in advanced options.

Priority

Paths will be matched based on their priority in descending order. A higher priority means the path will overrule any other matching paths of lower priority. By default, the base path will be added with priority 0 and other paths with priority 1.

For example, in the configuration below, any paths starting with /api/v1/ will be routed according to the rules set for that path. Any requests to the path /api without the subpath /v1 will be routed according to the configuration for /api, and all other requests will be routed according to /.

If, however, we changed the priority of / to 3, all requests would be routed according to the rules for /, including requests to the paths /api and /api/v1.

Ignore URI case

By default, paths are case-sensitive. This means a request to the route /API will not match a path added as /api unless ignore URI case is selected.

This is not relevant if you add a path as regex which matches both cases.

Timeout

You can configure custom HTTP request timeout settings by path. The timeout can be set in seconds (s) or milliseconds (ms), for example 250ms or 1s.

Rewrite

You can rewrite paths before the request is forwarded to the assigned port.

URI rewrite will replace the requested path with the new URI provided in the rewrite setting. For example, the rewrite /api for the prefix path /api/v1 would rewrite a request to /api/v1/health as /api/health.

Regex rewrite can replace any specific parts of the path which matches the given regex. For example the regex ^/acme/([^/]+)(/.*)$ with rewrite /api/\1/\2 would alter the path /acme/v1/health to /api/v1/health.

Headers

You can add or modify HTTP request and response headers for the path as key/value pairs. You can also remove headers by key.

CORS policy

You can configure the Cross-Origin Resource Sharing (CORS) policy for the path. If enabled, you can set the allowed origins, methods, and headers, whether to allow credentials in the request, and the max age of cached preflight request results.

Retries

You can configure specific retry policies for paths, including whether to allow retries, how many retries to allow, and the time to wait between attempts.

You can assign which service and port a path will route to after it has been added to the subdomain.

In the subdomain settings

Select a service from the dropdown menu, then select an existing port from the service. Update path and Northflank will begin routing requests for the path to the selected port. If the service has no ports, or the expected port is not listed, you can click the button to view the service and update the ports.

In a service

Open the ports & DNS page for a service and expand the custom domains and security rules for the port you want to use. Add custom domain and select the subdomain with the path you want to route to the port. Save the changes and Northflank will begin routing requests for the path to the selected port.