Specifying host for your service
When we deploy services, we often want to put them behind a well-defined recognizable URL instead of load balancer URLs or IP addresses. For e.g. https://app.your-organization.com
or https://your-site.your-organization.com/app/v1/
. To do this we can configure domains already owned by our organisation and construct endpoint URLs on top of them.
First, let's look at the two types of base URLs possible.
Wildcard Domain vs Regular Domain
A record that answers DNS requests for any subdomain you haven't already defined. You can create a wildcard domain by entering an asterisk (*) in the Host field when creating a DNS record.
For example:
*.your-organization.com
*.example.com
Regular Domain
A single domain that answers DNS requests for only the host provided.
For example:
your-site.your-organization.com
example.com
staging.example.com
www.example.com
Adding Base Domain URLs to a Cluster
We can configure one or more domain names in the cluster settings in the Integrations
Tab
An org might want to use multiple domain names for different teams or environments (staging, production).
Once configured, a Service can choose one of these domains for routing.
Routing to Ports of a Service
Here is an example where we add a host
and (optionally) path
for the port 8080
of the service.
from servicefoundry import Build, Service, Port, BasicAuthCreds, GitSource, DockerFileBuild
svc = Service(
name="fastapi",
image=Build(
build_source=GitSource(
repo_url="https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker",
branch_name="master",
ref="01201e19470c1da7618fa9ab361fe7e5d041b147"
),
build_spec=DockerFileBuild(
dockerfile_path="./docker-images/python3.11-slim.dockerfile",
build_context_path="./docker-images/"
)
),
env={"PORT": 8080},
ports=[
Port(
port=8080,
# Uses subdomain based routing
host="fastapi-my-workspace-8080.your-organization.com",
# Alternatively we can use path based routing - E.g.
# host="your-site.your-organization.com",
path="/fastapi/v1/"
)
]
)
type: service
name: fastapi
image:
type: build
build_spec:
type: dockerfile
dockerfile_path: ./docker-images/python3.11-slim.dockerfile
build_context_path: ./docker-images/
build_source:
type: git
repo_url: https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker
branch_name: master
ref: 01201e19470c1da7618fa9ab361fe7e5d041b147
env:
PORT: '8080'
ports:
- expose: true
port: 8080
protocol: TCP
app_protocol: http
host: fastapi-my-workspace-8080.workload-plane-example.truefoundry.com
In this example, the application will be available at https://fastapi-my-workspace-8080.your-organization.com
routing the requests to port 8080
Two Types of Routing
There are two kinds of endpoints we can construct for routing traffic:
- Subdomain based
- Path-based
Subdomain Based Routing
Subdomain-based routing refers to routing requests to different resources based on the subdomain component of the URL. For example, if a user requests users.example.com
, the web server might route that request to a different resource than if the user requested posts.example.com
Configuring Base Domain URLs
For Subdomain Based Routing , add a Wildcard Domain in the base domain URLs.
Let's create the following routing scenario

E.g, We configure the ports
section of the two Applications as follows:
Application 1
from servicefoundry import Service, Port
svc = Service(
name="app1",
...
ports=[
Port(
port=8080,
host="app1.your-organization.com",
path="/v1/api/"
)
]
)
type: service
name: app1
...
ports:
- expose: true
port: 8080
protocol: TCP
app_protocol: http
host: your-site.your-organization.com
path: /app1/
Application 2
from servicefoundry import Service, Port
svc = Service(
name="app2",
...
ports=[
Port(
port=8080,
host="app2.your-organization.com",
path="/v2/api/"
)
]
)
type: service
name: app2
...
ports:
- expose: true
port: 8080
protocol: TCP
app_protocol: http
host: your-site.your-organization.com
path: /app2/
With these deployed, https://app1.your-organization.com/v1/api/
will point to port 8080
of app1
and https://app2.your-organization.com/v2/api/
will point to port 8080
of app2
.
Note
The
path
field is optional because the routing decisions are made on the value of thehost
field.
Path-Based Routing
Path-based routing refers to routing requests to different resources based on the path component of the URL. For example, if a user requests example.com/users
, the web server might route that request to a different resource than if the user requested example.com/posts
. The host example.com
stays the same between the two.
Configuring Base Domain URLs
To enable Path Based Routing, add a Regular Domain in the base domain URLs.
Let's create the following routing scenario:

E.g, We configure the ports
section of the two Applications as follows:
Application 1
from servicefoundry import Service, Port
svc = Service(
name="app1",
...
ports=[
Port(
port=8080,
host="your-site.your-organization.com",
path="/app1/"
)
]
)
type: service
name: app1
...
ports:
- expose: true
port: 8080
protocol: TCP
app_protocol: http
host: your-site.your-organization.com
path: /app1/
Application 2
from servicefoundry import Service, Port
svc = Service(
name="app2",
...
ports=[
Port(
port=8080,
host="your-site.your-organization.com",
path="/app2/"
)
]
)
type: service
name: app2
...
ports:
- expose: true
port: 8080
protocol: TCP
app_protocol: http
host: your-site.your-organization.com
path: /app2/
With these deployed, https://your-site.your-organization.com/app1/
will point to port 8080
of app1
and https://your-site.your-organization.com/app2/
will point to port 8080
of app2
.
Configuring Endpoints from UI
Endpoints can be configured in the ports section
Subdomain Based Routing
- Scroll Down to the
Ports
section - Choose a Wildcard Domain
- Add a subdomain value
- Optionally add a path value
Path based routing
- Scroll Down to the
Ports
section - Choose a Regular Domain
- Add a path value
Updated 2 days ago