feat(components/router): add kubernetes native common ingress component

Author: Pangjiping

.github/workflows/router-test.yaml

@@ -0,0 +1,38 @@
+name: Router Tests
+
+on:
+  pull_request:
+    branches: [ main ]
+    paths:
+      - 'components/router/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.24.0'
+
+      - name: Run golint
+        run: |
+          cd components/router
+          make golint
+
+      - name: Run Build
+        run: |
+          cd components/router
+          make build
+
+      - name: Run tests
+        run: |
+          cd components/router
+          make test

components/router/DEVELOPMENT.md

@@ -0,0 +1,47 @@
+# Development Guide (Quick)
+
+## Prerequisites
+- Go 1.24+
+- Docker (optional, for image build)
+- Access to a Kubernetes cluster if you want to exercise proxy behavior.
+
+## Install deps
+```bash
+cd components/router
+go mod tidy && go mod vendor
+```
+
+## Build & Run
+```bash
+make build          # binary at bin/router with ldflags version info
+./bin/router \
+  --namespace <ns> \
+  --ingress-label-key <label-key> \
+  --port 28888 \
+  --log-level info
+```
+
+## Tests & Lint
+```bash
+make test           # go test ./pkg/...
+go vet ./...        # included in make build
+```
+
+## Docker (with 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/router:dev .
+```
+
+## Key Paths
+- `main.go` — entrypoint, HTTP routes.
+- `pkg/proxy/` — HTTP/WebSocket proxy logic and pod watching.
+- `version/` — build metadata (ldflags).
+
+## Tips
+- Health check: `/status.ok`
+- Env overrides: `VERSION/GIT_COMMIT/BUILD_TIME` usable via Makefile and build.sh.
+

components/router/Dockerfile

@@ -16,13 +16,21 @@ FROM golang:1.24.0 AS builder
 
 WORKDIR /build
 
+ARG VERSION=dev
+ARG GIT_COMMIT=unknown
+ARG BUILD_TIME=unknown
+
 COPY go.mod go.sum ./
 
 RUN go mod download
 
 COPY . .
 
-RUN CGO_ENABLED=0 go build -o /build/router ./main.go
+RUN CGO_ENABLED=0 go build \
+    -ldflags "-X 'github.com/alibaba/opensandbox/router/version.Version=${VERSION}' \
+              -X 'github.com/alibaba/opensandbox/router/version.BuildTime=${BUILD_TIME}' \
+              -X 'github.com/alibaba/opensandbox/router/version.GitCommit=${GIT_COMMIT}'" \
+    -o /build/router ./main.go
 
 FROM alpine:latest
 

components/router/README.md

@@ -0,0 +1,61 @@
+# OpenSandbox Router
+
+## Overview
+- HTTP/WebSocket reverse proxy that routes to sandbox Pods by `OPEN-SANDBOX-INGRESS` header or Host.
+- Watches Pods in a target Namespace filtered by an ingress label, and routes only when exactly one ready Pod matches.
+- 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> \
+  --ingress-label-key <label-key> \
+  --port 28888 \
+  --log-level info
+```
+Endpoints: `/` (proxy), `/status.ok` (health).
+
+## Build
+```bash
+cd components/router
+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/router:local .
+```
+
+## Multi-arch Publish Script
+`build.sh` uses buildx to build/push linux/amd64 and linux/arm64:
+```bash
+cd components/router
+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).
+- Pods in the specified Namespace labeled with the configured ingress label; Pod IPs must be reachable.
+
+## Behavior Notes
+- Routing key priority: `OPEN-SANDBOX-INGRESS` header first, otherwise Host parsing `<ingress>-<port>.*`.
+- Multiple matching Pods → HTTP 409; no matching Pod → HTTP 404.
+- WebSocket path forwards essential headers and X-Forwarded-*; HTTP path strips `OPEN-SANDBOX-INGRESS` before proxying.
+
+## Development & Tests
+```bash
+cd components/router
+go test ./...
+```
+Key code:
+- `main.go`: entrypoint and handlers.
+- `pkg/proxy/`: HTTP/WebSocket proxy logic, pod watching, health check.
+- `version/`: build metadata output (populated via ldflags).
+

components/router/README_zh.md

@@ -0,0 +1,67 @@
+# OpenSandbox Router
+
+## 功能概览
+- 基于 Kubernetes Pod 标签的 HTTP / WebSocket 反向代理，按 `OPEN-SANDBOX-INGRESS` 或 Host 解析目标沙箱。
+- 自动监听目标 Namespace 内带有 `ingress-label-key` 标签的 Pod 列表，动态路由到单个可用实例，避免多实例冲突。
+- 提供 `/status.ok` 健康探针，启动时打印编译版本、时间、提交、Go/平台信息。
+
+## 启动与参数
+```bash
+go run main.go \
+  --namespace <目标命名空间> \
+  --ingress-label-key <标签键> \
+  --port 28888 \
+  --log-level info
+```
+- `--namespace`：监听的 Kubernetes 命名空间。
+- `--ingress-label-key`：用于匹配沙箱 Pod 的标签键。
+- `--port`：监听端口（默认 28888）。
+- `--log-level`：日志级别，遵循 zap 定义。
+
+入口：`/` 走代理，`/status.ok` 健康检查。
+
+## 构建与发布
+### 本地二进制
+```bash
+cd components/router
+make build
+# 可覆盖版本信息
+VERSION=1.2.3 GIT_COMMIT=$(git rev-parse HEAD) BUILD_TIME=$(date -u +"%Y-%m-%dT%H:%M:%SZ") make build
+```
+
+### Docker 镜像
+Dockerfile 支持编译期注入：
+```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/router:local .
+```
+
+### 多架构推送脚本
+`build.sh` 使用 buildx 构建并推送 amd64/arm64，多标签支持，传入同名环境变量即可覆盖：
+```bash
+cd components/router
+TAG=local VERSION=1.2.3 GIT_COMMIT=abc BUILD_TIME=2025-01-01T00:00:00Z bash build.sh
+```
+
+## 运行时依赖
+- 可访问的 Kubernetes API（集群内或 KUBECONFIG）。
+- 目标命名空间中按 `ingress-label-key` 标记的运行中 Pod，并确保 Pod IP 可直连。
+
+## 开发与测试
+```bash
+cd components/router
+go test ./...
+```
+主要代码位置：
+- `main.go`：入口与 HTTP 路由注册。
+- `pkg/proxy/`：HTTP/WebSocket 代理逻辑、Pod 监听、健康检查。
+- `version/`：版本信息输出（ldflags 注入）。
+
+## 常见行为说明
+- Header 优先：`OPEN-SANDBOX-INGRESS`，否则回退 Host 解析 `<ingress>-<port>.*`。
+- 多实例同 ingress 时返回 409；无可用 Pod 返回 404。
+- WebSocket 保留关键头并透传 X-Forwarded-*，HTTP 会移除 `OPEN-SANDBOX-INGRESS` 后再转发。
+

components/router/build.sh

@@ -16,6 +16,9 @@
 set -ex
 
 TAG=${TAG:-latest}
+VERSION=${VERSION:-$(git describe --tags --always --dirty 2>/dev/null || echo "dev")}
+GIT_COMMIT=${GIT_COMMIT:-$(git rev-parse HEAD 2>/dev/null || echo "unknown")}
+BUILD_TIME=${BUILD_TIME:-$(date -u +"%Y-%m-%dT%H:%M:%SZ")}
 
 docker buildx rm router-builder || true
 
@@ -28,6 +31,9 @@ docker buildx ls
 docker buildx build \
   -t opensandbox/router:${TAG} \
   -t sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/router:${TAG} \
+  --build-arg VERSION="${VERSION}" \
+  --build-arg GIT_COMMIT="${GIT_COMMIT}" \
+  --build-arg BUILD_TIME="${BUILD_TIME}" \
   --platform linux/amd64,linux/arm64 \
   --push \
   .

components/router/main.go

@@ -1,3 +1,17 @@
+// Copyright 2025 Alibaba Group Holding Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 package main
 
 import (

components/router/pkg/flag/flags.go

@@ -1,3 +1,17 @@
+// Copyright 2025 Alibaba Group Holding Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 package flag
 
 var (

components/router/pkg/flag/parser.go

@@ -1,3 +1,17 @@
+// Copyright 2025 Alibaba Group Holding Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 package flag
 
 import (

components/router/pkg/proxy/header.go

@@ -1,3 +1,17 @@
+// Copyright 2025 Alibaba Group Holding Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 package proxy
 
 import "net/http"