# Routing Mechanisms of the OpenSandbox Ingress Gateway: Wildcard, URI, and Header-Based Routing

> Explore OpenSandbox Ingress Gateway routing mechanisms: wildcard, URI, and header-based routing. Expose sandbox services efficiently on Kubernetes.

- Repository: [Alibaba/OpenSandbox](https://github.com/alibaba/OpenSandbox)
- Tags: deep-dive
- Published: 2026-03-08

---

**The OpenSandbox Ingress Gateway supports three distinct routing mechanisms—wildcard subdomain, URI path, and HTTP header-based routing—to expose sandbox services externally when deploying on Kubernetes with `ingress.mode` set to `gateway`.**

The alibaba/OpenSandbox project provides a flexible Ingress Gateway that routes external traffic to sandboxed services based on configuration defined in `IngressConfig.gateway`. When deploying on Kubernetes with `ingress.mode` configured as `gateway`, operators can select between wildcard subdomain routing, URI path routing, or custom header-based routing to match their existing DNS and load balancing infrastructure. Each mechanism is implemented in the `format_ingress_endpoint` function within [`server/src/services/helpers.py`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/services/helpers.py) and validated through `IngressConfig` in [`server/src/config.py`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/config.py).

## Overview of Ingress Gateway Configuration

The gateway configuration resides in the `IngressConfig.gateway` field and requires two critical components: an `address` field specifying the entry point, and a `route.mode` field defining the routing strategy. The system recognizes three route modes defined as constants: `GATEWAY_ROUTE_MODE_WILDCARD`, `GATEWAY_ROUTE_MODE_URI`, and `GATEWAY_ROUTE_MODE_HEADER`.

When `route.mode` is set to `wildcard`, the address must follow the `*.domain.com` pattern. For `uri` and `header` modes, the address must be a valid domain, IP address, or IP:port combination without wildcard characters.

## Wildcard-Based Routing

Wildcard routing generates unique subdomains for each sandbox endpoint, enabling DNS-based traffic separation without requiring additional path or header configuration.

Configuration example:

```toml
[ingress]
mode = "gateway"

[ingress.gateway]
address = "*.example.com"
route = { mode = "wildcard" }

```

Implementation details from [`server/src/services/helpers.py`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/services/helpers.py) (lines 74-77):

```python
if route_mode == GATEWAY_ROUTE_MODE_WILDCARD:
    base = address[2:] if address.startswith("*.") else address
    return Endpoint(endpoint=f"{sandbox_id}-{port}.{base}")

```

The logic strips the leading `*.` from the configured address and constructs the endpoint as `{sandbox_id}-{port}.{base_domain}`. For example, a sandbox with ID `sid` exposing port `8080` receives the endpoint `sid-8080.example.com`.

## URI-Based Routing

URI routing appends sandbox identifiers to the path component of a fixed base address, suitable for scenarios where subdomain management is impractical or when operating behind path-based reverse proxies.

Configuration example:

```toml
[ingress.gateway]
address = "gateway.example.com"
route = { mode = "uri" }

```

Implementation from [`server/src/services/helpers.py`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/services/helpers.py) (lines 78-80):

```python
if route_mode == GATEWAY_ROUTE_MODE_URI:
    return Endpoint(endpoint=f"{address}/{sandbox_id}/{port}")

```

This produces endpoints in the format `gateway.example.com/{sandbox_id}/{port}`. Unlike wildcard routing, this approach requires no DNS wildcard records but may necessitate path-aware load balancing or URL rewriting at the proxy layer.

## Header-Based Routing

Header-based routing directs traffic through a fixed gateway address while using HTTP headers to identify the target sandbox, compatible with API gateways and reverse proxies that route based on header inspection rather than URL structure.

Configuration example:

```toml
[ingress.gateway]
address = "gateway.example.com"
route = { mode = "header" }

```

Implementation from [`server/src/services/helpers.py`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/services/helpers.py) (lines 81-86):

```python
if route_mode == GATEWAY_ROUTE_MODE_HEADER:
    header_value = f"{sandbox_id}-{port}"
    return Endpoint(
        endpoint=address,
        headers={OPEN_SANDBOX_INGRESS_HEADER: header_value},
    )

```

The `OPEN_SANDBOX_INGRESS_HEADER` constant is defined in [`server/src/services/constants.py`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/services/constants.py) (line 22) as `OpenSandbox-Ingress-To`. Clients must include this header with a value formatted as `{sandbox_id}-{port}` to reach the correct sandbox instance.

## Configuration Validation

The `IngressConfig` class in [`server/src/config.py`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/config.py) enforces strict validation through the `validate_ingress_mode` method (lines 131-158). This validation ensures:

- The `gateway` configuration block is mandatory when `ingress.mode` is set to `gateway`.
- Wildcard addresses must match the `_WILDCARD_DOMAIN_RE` regex pattern (e.g., `*.example.com`).
- Non-wildcard addresses must not contain asterisks and must conform to valid domain, IP, or IP:port formats.

Validation failures raise `ValueError` exceptions during configuration loading, preventing the server from starting with inconsistent gateway settings.

## Summary

- **OpenSandbox Ingress Gateway routing** supports three distinct mechanisms: wildcard subdomain, URI path, and HTTP header-based routing.
- **Wildcard routing** generates unique subdomains (`{sandbox_id}-{port}.{domain}`) and requires DNS wildcard records configured in the `address` field.
- **URI routing** constructs paths (`{address}/{sandbox_id}/{port}`) on a fixed host, suitable for path-based load balancers.
- **Header-based routing** uses a fixed address with the `OpenSandbox-Ingress-To` HTTP header to identify targets, implemented in `format_ingress_endpoint` within [`server/src/services/helpers.py`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/services/helpers.py).
- **Configuration validation** in [`server/src/config.py`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/config.py) ensures address formats match the selected routing mode before server startup.

## Frequently Asked Questions

### What is the default routing mode for the OpenSandbox Ingress Gateway?

OpenSandbox does not provide a default routing mode; operators must explicitly set `ingress.gateway.route.mode` to `wildcard`, `uri`, or `header`. The configuration validator in [`server/src/config.py`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/config.py) will reject any undefined or missing route mode when `ingress.mode` is set to `gateway`.

### How does wildcard routing handle ports in the sandbox ID?

Wildcard routing automatically appends the port number to the sandbox ID using a hyphen separator. According to the implementation in [`server/src/services/helpers.py`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/services/helpers.py), the endpoint format is `{sandbox_id}-{port}.{base_domain}`. For example, sandbox `abc123` with port `8080` becomes `abc123-8080.example.com`.

### Can I use header-based routing with a layer 4 load balancer?

No, header-based routing requires a layer 7 (HTTP) load balancer or reverse proxy capable of inspecting HTTP headers. The `OpenSandbox-Ingress-To` header must be read and acted upon by the gateway or proxy to route traffic to the correct sandbox backend. Layer 4 load balancers operate at the transport level and cannot inspect HTTP headers.

### Where is the routing logic implemented in the OpenSandbox source code?

The core routing logic resides in [`server/src/services/helpers.py`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/services/helpers.py) within the `format_ingress_endpoint` function (lines 55-88). This function handles all three routing modes—wildcard, URI, and header—by inspecting the `route.mode` configuration and constructing the appropriate endpoint URL or headers. Configuration validation occurs in [`server/src/config.py`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/config.py) in the `validate_ingress_mode` method.