You can point your domains at specific ports on Northflank services. To do this, you will need to link your domain to a port on a service.
Domains on Northflank can be configured using path-based routing. This means that every subdomain you add will have a base path /, which you can link to a port to handle all requests to the subdomain.
You can also add more paths to a subdomain to link a single subdomain to multiple ports and services, and configure how requests to paths and subpaths are handled.
You will need the following to get started:
- a verified subdomain added to your Northflank team
- a public or VPC-accessible port configured for a service
Choose public or VPC routing
Each subdomain uses one cluster ingress target: public or vpc. A port exposed on both paths can serve different subdomains on either target. A single subdomain cannot select both targets at once.
Backends are the service ports that receive requests. Every backend must support the chosen target, including all attached paths. VPC routing requires client connectivity to the VPC. See Public and VPC ingress for availability and cluster requirements.
Geographic routing requires Northflank CDN and cannot use VPC ingress. You cannot change a subdomain's routing mode after creation.
After linking a subdomain, open its configuration with the settings cog. Use the dropdown at the top of the page to choose the target. It shows Public load balancer or VPC private load balancer. Click Change load balancer in the confirmation dialog.
Use PUT /v1/domains/{domain}/subdomains to create or update a subdomain with an ingress target. Include name, such as app for app.example.com, to identify the subdomain. Set loadBalancer to public or vpc. The POST endpoint does not accept loadBalancer or certificateValidationMethod.
The PUT response uses loadBalancer for the ingress target. In GET /v1/domains/{domain}/subdomains/{subdomain}, clusterLoadBalancer reports that target. The GET response uses loadBalancer for a linked dedicated load balancer resource.
Defaults and assignment
A subdomain defaults to public unless it has an explicit or inherited target. Assigning a port with both exposure paths does not change that target. A new subdomain can use VPC ingress with a port exposed on both paths. Select VPC through the PUT endpoint above before linking that port.
A path assignment can select VPC automatically if all these conditions apply:
- The subdomain has no explicit or inherited target.
- The assigned port is VPC-only.
- No other path is assigned, and the subdomain has no enabled CDN.
- VPC routing is available for the account that owns the cluster.
This behavior applies to path assignment from the subdomain configuration or API. Service-port updates require a compatible target before you attach a port. Existing public routes do not move to VPC automatically.
Wildcard-redirect domains fix their target at creation. Their child subdomains inherit it and cannot override it.
Change exposure or move a domain
Every backend must support the destination exposure before you change a subdomain's target. Northflank rejects a target change if any attached backend lacks that exposure.
Move or unlink domains before removing the port exposure that they require. Routing and certificate changes take time and can interrupt access.
For a subdomain with path-based routing and no inherited target, use this sequence to move between public and VPC:
- Enable the destination ingress on the cluster.
- Wait until the ingress is ready.
- Enable both exposure paths on each affected HTTP or HTTP/2 port, or reassign incompatible routes.
- Before moving to VPC, disable Northflank's CDN on the subdomain.
- If certificate generation is in progress, wait until it finishes.
- Before moving to VPC, replace HTTP validation with DCV or another supported certificate method.
- If the method change starts certificate generation, wait until it finishes.
- Select the destination in the load balancer dropdown at the top of the subdomain configuration.
- Click Change load balancer in the confirmation dialog.
- Make sure that DNS, certificates, and requests work from the destination client network.
- After no attached domains require the old exposure, remove it.
A path-based subdomain cannot span incompatible regions or BYOC clusters. Before moving it, unlink other paths that remain assigned to the old region or cluster. Wildcard-redirect subdomains remain bound to the parent domain's cluster.
Link a domain in a deployment
The port must be public or VPC-accessible. To link a subdomain:
- Open Run → Networking in the service menu.
- Expand Custom domains & security rules for the port.
- Click Choose a domain.
- Select the subdomain or path to link to the port.
- Save the port changes.
If the subdomain is missing, click Manage domains to add it to your account. You can link multiple subdomains to the same port.
You can also choose to disable the default code.run domain generated by Northflank.
After saving, Northflank configures the route without a service restart. The subdomain needs the selected ingress target, DNS records, and a valid certificate before it can serve requests. VPC routing requires the VPC certificate workflow or a supported imported or wildcard certificate.
Link a domain in account settings
Open the domains page in your team and find the subdomain you want to link to a port. You can also search for the domain by name.
Find the subdomain listed in the domain entry and click the button to edit it.
In Backends, link the base path (/):
- Select Project.
- Select Service.
- Select Port.
- Click Update.
- If the VPC routing confirmation appears, click Assign backend.
If the subdomain has multiple paths, expand the base path and use Update path instead of Update.
Make sure that the port supports the selected ingress target. The route needs DNS and a valid certificate before it can serve requests. See certificates for VPC ingress for private routes.
