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

Wildcard 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 the host 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