配置 Sidecar

legate-sidecar 在可信节点运行一个 Workspace 的本地数据面。它需要稳定实例身份、Sidecar Token、三个 Central Base URL，以及可持久化的 telemetry state dir。

最小启动

先在 Console “Sidecar → 令牌”创建 sc-leg-...，完整值只显示一次：

docker run --rm \
  --name legate-sidecar \
  --publish 127.0.0.1:8081:8081 \
  --volume legate-sidecar-telemetry:/var/lib/legate-sidecar/telemetry \
  ghcr.io/bit-fortress/legate-sidecar:edge \
  --listen=:8081 \
  --control-plane=https://legate.example.com \
  --central-gateway=https://legate.example.com \
  --telemetry-base-url=https://legate.example.com \
  --workspace=team-a \
  --token="$LEGATE_SIDECAR_TOKEN" \
  --instance-id=cluster-a-gateway

edge 只适合验证，长期运行应替换为精确镜像标签。--instance-id 必填并应跨容器重启保持稳定；Token 和 Workspace 必须匹配，Central 不会回退到 default。Telemetry volume 与 instance ID 必须一起保留。

Endpoint 与身份参数

参数	默认值	说明
--listen	:8081	Sidecar 模型代理与 health 监听地址
--control-plane	http://127.0.0.1:8080	快照和 artifact Base URL
--central-gateway	空，必填	reference 请求转发 Base URL
--telemetry-base-url	空，必填	invocation event 上传 Base URL
--workspace	default	同步的精确 Workspace slug
--token	空，必填	Sidecar Token
--instance-id	空，必填	稳定实例 ID
--sync-interval	30s	快照拉取和实例状态周期

三个 Base URL 可以相同，也可以指向不同的受控入口。必须是绝对 HTTP(S) URL，生产使用 HTTPS；central-gateway 与 telemetry-base-url 不会自动从 control plane 推导。

快照预算

参数	默认值
--snapshot-max-compressed-bytes	16,777,216
--snapshot-max-uncompressed-bytes	67,108,864

Sidecar 同时限制压缩 body、解压表示和 resident snapshot。超限、schema/Workspace/revision 不一致、artifact digest 错误或 Bind 失败都会拒绝新 generation，并保留最后一个完整 generation。

请求重放预算

Buffered 故障转移和图片 multipart 需要可重放 body。小 body 保留内存，大 body写入 --replay-temp-dir：

参数	默认值
--replay-json-max-bytes	16,777,216
--replay-multipart-max-bytes	67,108,864
--replay-memory-threshold	8,388,608
--replay-max-in-flight-bytes	536,870,912
--replay-max-concurrent-captures	32
--replay-max-spool-bytes	402,653,184
--replay-max-spool-files	48
--replay-max-open-fds	64
--replay-temp-dir	操作系统临时目录

这些值存在严格关系：memory threshold ≤ JSON ≤ multipart ≤ spool；单请求上限、进程总字节、capture、文件和 FD 同时生效。临时目录应位于 owner-only、容量受控的本地文件系统。

文本流预算

Sidecar 与 Central 使用同一组默认值和语义：

参数	默认值
--text-stream-max-upstream-bytes	67,108,864
--text-stream-max-protocol-bytes	67,108,864
--text-stream-max-events	1,000,000
--text-stream-idle-timeout	2m
--text-stream-max-duration	1h
--text-stream-max-active	32
--text-stream-max-active-per-workspace	8
--text-stream-max-retained-bytes	3,221,225,472
--text-stream-max-retained-bytes-per-workspace	805,306,368

入口代理的 read timeout 必须大于 --text-stream-idle-timeout，并关闭会破坏实时事件的响应缓冲。

遥测队列

Sidecar 把 Request/Attempt 事件先放入有界内存队列，再分批上传：

参数	默认值
--telemetry-state-dir	/var/lib/legate-sidecar/telemetry
--telemetry-active-requests	10,000
--telemetry-queue-events	10,000
--telemetry-queue-bytes	67,108,864
--telemetry-batch-events	500
--telemetry-batch-bytes	1,048,576
--telemetry-flush-events	500
--telemetry-flush-bytes	1,048,576
--telemetry-flush-interval	10s
--telemetry-flush-jitter	0.1
--telemetry-operation-timeout	30s
--telemetry-drain-timeout	10s

state dir 保存 incarnation，必须持久化且同一时刻只属于一个实例进程。队列满会累积 dropped counter；Console 会把相关时间窗口标为不完整。

Redis

参数	默认值	说明
--redis-addr	空	共享 circuit breaker 状态
--redis-prefix	legate	Redis key prefix

当前没有 Endpoint 容量租约。只有希望 Central 与 Sidecar 共享 Endpoint/Mapping breaker 时才需要 Redis；所有参与进程必须使用相同地址和 prefix。

Kubernetes 示例

apiVersion: apps/v1
kind: Deployment
metadata:
  name: legate-sidecar
spec:
  replicas: 1
  selector:
    matchLabels: {app: legate-sidecar}
  template:
    metadata:
      labels: {app: legate-sidecar}
    spec:
      containers:
        - name: sidecar
          image: ghcr.io/bit-fortress/legate-sidecar:sha-a7ac839
          args:
            - --listen=:8081
            - --control-plane=https://legate.example.com
            - --central-gateway=https://legate.example.com
            - --telemetry-base-url=https://legate.example.com
            - --workspace=team-a
            - --instance-id=team-a-cluster-1
            - --token=$(LEGATE_SIDECAR_TOKEN)
          env:
            - name: LEGATE_SIDECAR_TOKEN
              valueFrom:
                secretKeyRef: {name: legate-sidecar, key: token}
          ports:
            - {name: http, containerPort: 8081}
          volumeMounts:
            - {name: telemetry-state, mountPath: /var/lib/legate-sidecar/telemetry}
      volumes:
        - name: telemetry-state
          persistentVolumeClaim: {claimName: legate-sidecar-telemetry}

一个稳定 instance-id 不应同时运行多个副本。横向扩容时为每个副本分配独立稳定 ID 与独立 telemetry state volume。

验证与排障

curl -fsS http://127.0.0.1:8081/api/healthz

健康只代表 HTTP 进程存活。还要在 Console 核对：

1. 实例 online、version 与 sync interval 正确；
2. last pull success，schema 与 revision 非空且持续推进；
3. full 组所需 artifact 已下载并 Bind；
4. telemetry last reported / covered through 正常推进；
5. queue depth 没有持续增长，dropped counter 为零；
6. 真实调用的 execution location 和 Sidecar instance ID 符合预期。

full 节点持有上游 credential，安全等级应与 Central 相同；reference 也持有 API Key hash 和 forwarding 身份，不能部署到不受信任主机。