OpenSandbox

English

简体中文

English

简体中文

Appearance

OpenSandbox Ingress ​

Overview ​

  • HTTP/WebSocket reverse proxy that routes to sandbox instances.
  • Watches sandbox CRs (BatchSandbox or AgentSandbox, chosen by --provider-type) in a target Namespace:
    • BatchSandbox: reads endpoints from sandbox.opensandbox.io/endpoints annotation.
    • AgentSandbox: reads status.serviceFQDN.
  • Exposes /status.ok health check; prints build metadata (version, commit, time, Go/platform) at startup.

Quick Start ​

bash
go run main.go \
  --namespace <target-namespace> \
  --provider-type <batchsandbox|agent-sandbox> \
  --mode <header|uri> \
  --port 28888 \
  --log-level info

Endpoints: / (proxy), /status.ok (health).

Routing Modes ​

The ingress supports two routing modes for discovering sandbox instances:

Header Mode (default: --mode header) ​

Routes requests based on the OpenSandbox-Ingress-To header or the Host header.

Format:

  • Header: OpenSandbox-Ingress-To: <sandbox-id>-<port>
  • Host: <sandbox-id>-<port>.<domain>

Example:

bash
# Using OpenSandbox-Ingress-To header
curl -H "OpenSandbox-Ingress-To: my-sandbox-8080" https://ingress.opensandbox.io/api/users

# Using Host header
curl -H "Host: my-sandbox-8080.example.com" https://ingress.opensandbox.io/api/users

Parsing logic:

  • Extracts sandbox ID and port from the format <sandbox-id>-<port>
  • The last segment after the last - is treated as the port
  • Everything before the last - is treated as the sandbox ID

URI Mode (--mode uri) ​

Routes requests based on the URI path structure.

Format:

/<sandbox-id>/<sandbox-port>/<path-to-request>

Example:

bash
# Request to sandbox "my-sandbox" on port 8080, forwarding to /api/users
curl https://ingress.opensandbox.io/my-sandbox/8080/api/users

# WebSocket example
wss://ingress.opensandbox.io/my-sandbox/8080/ws

Parsing logic:

  • First path segment: sandbox ID
  • Second path segment: sandbox port
  • Remaining path: forwarded to the target sandbox as the request URI
  • If no remaining path is provided, defaults to /

Use cases:

  • When you cannot modify HTTP headers
  • When you need path-based routing
  • For simpler client configuration without custom headers

Build ​

bash
cd components/ingress
make build
# override build metadata if needed
VERSION=1.2.3 GIT_COMMIT=$(git rev-parse HEAD) BUILD_TIME=$(date -u +"%Y-%m-%dT%H:%M:%SZ") make build

Docker Build ​

Dockerfile already wires ldflags via build args:

bash
docker build \
  --build-arg VERSION=$(git describe --tags --always --dirty) \
  --build-arg GIT_COMMIT=$(git rev-parse HEAD) \
  --build-arg BUILD_TIME=$(date -u +"%Y-%m-%dT%H:%M:%SZ") \
  -t opensandbox/ingress:local .

Multi-arch Publish Script ​

build.sh uses buildx to build/push linux/amd64 and linux/arm64:

bash
cd components/ingress
TAG=local VERSION=1.2.3 GIT_COMMIT=abc BUILD_TIME=2025-01-01T00:00:00Z bash build.sh

Runtime Requirements ​

  • Access to Kubernetes API (in-cluster or via KUBECONFIG).
  • If --provider-type=batchsandbox: BatchSandbox CRs in the specified Namespace with sandbox.opensandbox.io/endpoints annotation containing Pod IPs.
  • If --provider-type=agent-sandbox: AgentSandbox CRs with status.serviceFQDN populated.

Implementation Notes ​

Header Mode Behavior ​

  • Routing key priority: OpenSandbox-Ingress-To header first, otherwise Host parsing <sandbox-name>-<port>.*.
  • Sandbox name extracted from request is used to query the sandbox CR (BatchSandbox or AgentSandbox) via informer cache:
    • BatchSandbox → endpoints annotation.
    • AgentSandbox → status.serviceFQDN.
  • The original request path is preserved and forwarded to the target sandbox.

URI Mode Behavior ​

  • Routing information is extracted from the URI path: /<sandbox-id>/<sandbox-port>/<path-to-request>.
  • The sandbox ID and port are extracted from the first two path segments.
  • The remaining path (/<path-to-request>) is forwarded to the target sandbox as the request URI.
  • If no remaining path is provided, the request URI defaults to /.

Commons ​

  • Error handling:
    • ErrSandboxNotFound (sandbox resource not exists) → HTTP 404
    • ErrSandboxNotReady (not enough replicas, missing endpoints, invalid config) → HTTP 503
    • Other errors (K8s API errors, etc.) → HTTP 502
  • WebSocket path forwards essential headers and X-Forwarded-*; HTTP path strips OpenSandbox-Ingress-To before proxying (header mode only).

Development & Tests ​

bash
cd components/ingress
go test ./...

Key code:

  • main.go: entrypoint and handlers.
  • pkg/proxy/: HTTP/WebSocket proxy logic, sandbox endpoint resolution.
  • pkg/sandbox/: Sandbox provider abstraction and BatchSandbox implementation.
  • version/: build metadata output (populated via ldflags).

This page is sourced from: components/ingress/README.md