signadot-validate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Signadot: Validate Microservice Changes

Signadot：验证微服务变更

Use Signadot to validate code changes against real cluster dependencies without building an image unless the service cannot run locally. Prefer a local-mapped sandbox: run the changed service locally, route cluster traffic to it with a routing key, and iterate until the full validation path passes.

使用Signadot针对真实集群依赖项验证代码变更，除非服务无法在本地运行，否则无需构建镜像。优先使用本地映射沙箱：在本地运行已更改的服务，通过路由键将集群流量路由到该服务，反复迭代直至完整验证路径通过。

Reference Map

参考映射

Load these one-hop references only when the workflow reaches that topic:

references/sandbox-setup.md: cluster and workload resolution, sandbox reuse/create/update, devbox detection, env var reconstruction, process startup, and port rules.
references/validation-types.md: how to run integration tests, existing e2e suites, ad-hoc browser automation, and existing tagged Signadot plans with routing-key injection.
references/troubleshooting.md: fast diagnostics for 503s, baseline-looking responses, browser blanks, propagation failures, async hops, process exits, and gRPC DNS delays.
references/worked-example.md: an end-to-end example of validating a UI change through a local sandbox.

仅当工作流涉及对应主题时，才加载以下单跳参考文档：

references/sandbox-setup.md：集群与工作负载解析、沙箱复用/创建/更新、开发环境检测、环境变量重构、进程启动及端口规则。
references/validation-types.md：如何运行集成测试、现有端到端测试套件、临时浏览器自动化测试，以及注入路由键的现有标记Signadot计划。
references/troubleshooting.md：针对503错误、基线响应、浏览器空白、传播失败、异步跳转、进程退出及gRPC DNS延迟的快速诊断方法。
references/worked-example.md：通过本地沙箱验证UI变更的端到端示例。

Core Workflow

核心工作流

The workflow has four phases: A (before coding), B (set up the sandbox), C (run validation), D (iterate). Steps are numbered for sequence; each links to the reference that owns its detail.

Define what "validated" means before coding (Phase A). If the user did not specify the validation type, ask one question and offer these choices: integration tests, existing e2e suite, ad-hoc browser automation, or existing tagged Signadot plan. The validation type affects implementation shape, sandbox ports, and routing-key plumbing. If they name another tool, such as Locust, Postman, or a custom Cypress script, use the same principle: find where its HTTP/gRPC client lives and how it will send the routing key. See references/validation-types.md.
Resolve cluster and workload (Phase B). Use the Signadot MCP server when available; otherwise use the CLI. Resolve names through tools or repo-owned Signadot specs, not guesses. If a tool response asks for confirmation because there are multiple clusters, workloads, or devboxes, ask the user to choose. See references/sandbox-setup.md.
Reuse before creating (Phase B). Look for a live sandbox for the same user and workload before making a new one. Reuse keeps the routing key stable across local test env vars, curls, and browser automation. See references/sandbox-setup.md.
Create or update the sandbox (Phase B). Use the existing repo spec under
```
.signadot/
```
when one matches. Otherwise create the smallest local-mapped sandbox that contains only the service(s) changed or needed to follow the changed user-visible path. See references/sandbox-setup.md for required fields, port rules, and the preview-endpoints policy.
Pull env and start the service (Phase B). Read the repo's normal run commands first. Export every required env var, especially service-to-service addresses, secrets, and feature flags. Build before backgrounding, then verify the process is alive and its port is listening. See references/sandbox-setup.md and the "Starting The Service" section.
Validate through the cluster URL (Phase C). Send traffic to
```
http://<svc>.<namespace>.svc:<service-port>/...
```
with routing-key headers. Do not validate by calling
```
localhost:<port>
```
directly. See references/validation-types.md for the subsection matching the type chosen in Phase A.
Iterate on failures (Phase D). Read the exact failure, fix the smallest cause, restart affected services, and re-run the same validation against the same sandbox. Do not report success until the agreed validation path passes. See references/troubleshooting.md.
Close out cleanly. Report the sandbox name, cluster, routing key, target URL, validation command or browser path, and local processes stopped. Leave the sandbox up by default; surface the delete command as an option only.

工作流包含四个阶段：A（编码前）、B（沙箱设置）、C（运行验证）、D（迭代优化）。步骤按顺序编号，每个步骤链接到对应细节的参考文档。

编码前定义“验证通过”的标准（阶段A）。若用户未指定验证类型，询问并提供以下选项：集成测试、现有端到端测试套件、临时浏览器自动化测试或现有标记Signadot计划。验证类型会影响实现方式、沙箱端口及路由键配置。若用户提及其他工具（如Locust、Postman或自定义Cypress脚本），遵循相同原则：确定其HTTP/gRPC客户端位置及路由键传递方式。详见references/validation-types.md。
解析集群与工作负载（阶段B）。若Signadot MCP服务器可用则使用它，否则使用CLI。通过工具或代码库自带的Signadot规范解析名称，而非猜测。若工具因存在多个集群、工作负载或开发环境而要求确认，请让用户选择。详见references/sandbox-setup.md。
优先复用沙箱（阶段B）。在创建新沙箱前，查找同一用户和工作负载对应的活跃沙箱。复用沙箱可确保本地测试环境变量、curl请求及浏览器自动化测试的路由键保持稳定。详见references/sandbox-setup.md。
创建或更新沙箱（阶段B）。若代码库下的
```
.signadot/
```
目录中有匹配的现有规范，则使用该规范。否则创建最小化的本地映射沙箱，仅包含已更改的服务或跟踪用户可见变更路径所需的服务。关于必填字段、端口规则及预览端点策略，详见references/sandbox-setup.md。
拉取环境变量并启动服务（阶段B）。先读取代码库的常规运行命令。导出所有必需的环境变量，尤其是服务间地址、密钥及功能标志。启动后台进程前先构建，然后验证进程是否存活且端口处于监听状态。详见references/sandbox-setup.md及“启动服务”章节。
通过集群URL进行验证（阶段C）。向
```
http://<svc>.<namespace>.svc:<service-port>/...
```
发送带有路由键头的流量。请勿直接调用
```
localhost:<port>
```
进行验证。针对阶段A中选择的验证类型，详见references/validation-types.md对应的小节。
针对失败进行迭代优化（阶段D）。读取具体失败信息，修复最小成因，重启受影响的服务，并针对同一沙箱重新运行相同的验证。直至约定的验证路径通过，方可报告成功。详见references/troubleshooting.md。
干净收尾。报告沙箱名称、集群、路由键、目标URL、验证命令或浏览器路径，以及已停止的本地进程。默认保留沙箱运行；仅将删除命令作为选项提供。

MCP And CLI Use

MCP与CLI使用

If a Signadot MCP server is available, use it for control-plane work: list and inspect clusters, sandboxes, routegroups, workloads, endpoints, and devboxes; create or update sandboxes when the side-effect policy below permits it. Search by intent, load tool schemas before calling tools, and prefer tool output over memory.

If MCP is unavailable, use CLI fallbacks:

bash

signadot cluster list -o json
signadot sandbox list -o json
signadot sandbox get <name> -o json
signadot sandbox apply -f <spec.yaml>
signadot sandbox get-env <name>
signadot sandbox get-files <name>

Use

kubectl get <kind> <name> -n <ns> -o yaml

only when MCP cannot fetch the same workload, ConfigMap, Secret, or Service data and the local environment has cluster access.

若Signadot MCP服务器可用，使用它完成控制平面工作：列出并检查集群、沙箱、路由组、工作负载、端点及开发环境；在符合以下副作用策略的情况下创建或更新沙箱。按意图搜索，调用工具前加载工具架构，优先使用工具输出而非内存数据。

若MCP不可用，使用CLI替代方案：

bash

signadot cluster list -o json
signadot sandbox list -o json
signadot sandbox get <name> -o json
signadot sandbox apply -f <spec.yaml>
signadot sandbox get-env <name>
signadot sandbox get-files <name>

仅当MCP无法获取相同的工作负载、ConfigMap、Secret或Service数据，且本地环境具备集群访问权限时，才使用

kubectl get <kind> <name> -n <ns> -o yaml

。

Signal Inventory

信号清单

Signal	Use
Local process receives real cluster traffic	Default first choice for validating changed services without an image build
Cluster DNS/IP is resolvable locally	`signadot local connect` or a devbox makes `.svc` names reachable
Local stdout/stderr streams during routed requests	Watch requests land in changed code, see panics, attach a debugger
Sandbox readiness, forks, routing state, and tunnel connection	Confirm the sandbox can route before testing code
Preview endpoints, when explicitly requested	Deterministically hit a fork without manual routing headers, but may expose a public `*.preview.signadot.com` URL
Routing-key isolation	Prove keyed traffic hits the sandbox while unkeyed traffic stays on baseline
`signadot local proxy`	Diagnose dependency reachability; not a validation result

信号	用途
本地进程接收真实集群流量	无需构建镜像即可验证已更改服务的默认首选方式
集群DNS/IP可在本地解析	`signadot local connect` 或开发环境使 `.svc` 名称可达
路由请求期间的本地标准输出/标准错误流	观察请求是否进入已更改的代码、查看崩溃信息、附加调试器
沙箱就绪状态、分支、路由状态及隧道连接	测试代码前确认沙箱可进行路由
预览端点（明确请求时使用）	无需手动添加路由头即可确定性地命中分支，但可能暴露公开的 `*.preview.signadot.com` URL
路由键隔离	验证带键流量命中沙箱，而无键流量保留在基线服务
`signadot local proxy`	诊断依赖项可达性；并非验证结果

Side-Effect Policy

副作用策略

Action	Default behavior
Read clusters, workloads, endpoints, sandboxes, routegroups	Do autonomously
Create an isolated sandbox for this task	Do autonomously when cluster/workload are unambiguous
Update a sandbox clearly owned by this task	Do autonomously
Update a shared sandbox or routegroup	Ask first
Add public preview endpoints such as `defaultRouteGroup.endpoints`	Ask first
Delete a sandbox	Ask first; default is leave it up
Run `sudo signadot local connect --cluster <cluster>` or `signadot local disconnect`	Ask the user to run it; it modifies the local network stack and may require sudo
Run `signadot local status` or `signadot local proxy`	Do autonomously when useful; proxy is diagnostic, not proof of validation

操作	默认行为
读取集群、工作负载、端点、沙箱、路由组	自主执行
为此任务创建隔离沙箱	当集群/工作负载明确时自主执行
更新明确归属于此任务的沙箱	自主执行
更新共享沙箱或路由组	先询问用户
添加公开预览端点（如 `defaultRouteGroup.endpoints` ）	先询问用户
删除沙箱	先询问用户；默认保留运行
运行 `sudo signadot local connect --cluster <cluster>` 或 `signadot local disconnect`	让用户自行运行；此操作会修改本地网络堆栈，可能需要sudo权限
运行 `signadot local status` 或 `signadot local proxy`	有用时自主执行；proxy仅用于诊断，并非验证依据

Routing Rules

路由规则

Two Ports Matter

两个关键端口

Keep the two port concepts separate:

Context	Port to use	How to resolve
Sandbox local mapping	Workload/container port	MCP workload-port resolver such as `resolve_workload_port` , or workload spec
Validation traffic to `.svc` URL	Kubernetes Service port	Endpoint resolver such as `resolve_endpoints` , Service object, or repo Signadot spec

The sandbox can be

ready: true

with a connected tunnel even when its mapping uses the wrong container port; requests then fall through to baseline. If routing looks broken, check for a virtual host entry such as

<sandbox>-<mapping>-*.<namespace>.svc

/etc/hosts

区分以下两个端口概念：

上下文	使用的端口	解析方式
沙箱本地映射	工作负载/容器端口	MCP工作负载端口解析器（如 `resolve_workload_port` ）或工作负载规范
发往 `.svc` URL的验证流量	Kubernetes Service端口	端点解析器（如 `resolve_endpoints` ）、Service对象或代码库Signadot规范

即使沙箱映射使用错误的容器端口，沙箱仍可能显示

ready: true

且隧道已连接；此时请求会回退到基线服务。若路由看似异常，检查

/etc/hosts

中是否存在

<sandbox>-<mapping>-*.<namespace>.svc

这样的虚拟主机条目。

Always Hit The Cluster URL

始终访问集群URL

Validation traffic must target the cluster service URL, not the local process:

bash

curl -sS "http://<svc>.<namespace>.svc:<service-port>/<path>" \
  -H "baggage: sd-routing-key=<routing-key>" \
  -H "tracestate: sd-routing-key=<routing-key>"

For gRPC:

bash

grpcurl -plaintext \
  -H "baggage: sd-routing-key=<routing-key>" \
  -H "tracestate: sd-routing-key=<routing-key>" \
  -d '{"field":"value"}' \
  <svc>.<namespace>.svc:<service-port> package.Service/Method

baggage

and

tracestate

with key name

sd-routing-key

are always accepted. If

clusterConfig.routing.customHeaders

lists additional headers, inject every listed header with the routing key as the value. Use query-param routing only when the surface cannot set headers.

signadot local proxy

can help debug whether a cluster dependency is reachable from the machine, but a localhost proxy URL bypasses the same end-to-end routing path and is not a validation result.

验证流量必须指向集群服务URL，而非本地进程：

bash

curl -sS "http://<svc>.<namespace>.svc:<service-port>/<path>" \
  -H "baggage: sd-routing-key=<routing-key>" \
  -H "tracestate: sd-routing-key=<routing-key>"

对于gRPC：

bash

grpcurl -plaintext \
  -H "baggage: sd-routing-key=<routing-key>" \
  -H "tracestate: sd-routing-key=<routing-key>" \
  -d '{"field":"value"}' \
  <svc>.<namespace>.svc:<service-port> package.Service/Method

始终接受带有

sd-routing-key

键名的

baggage

和

tracestate

头。若

clusterConfig.routing.customHeaders

列出了额外的头，需注入所有列出的头并将路由键作为值。仅当无法设置头时才使用查询参数路由。

signadot local proxy

可帮助调试集群依赖项是否可从本地机器访问，但localhost代理URL会绕过相同的端到端路由路径，因此不能作为验证结果。

Forward The Key Across Hops

跨跳转传递路由键

The routing key reaches a sandboxed downstream service only if every hop propagates it. Raw HTTP/gRPC clients, custom proxy handlers, and async producers often drop the key unless the code explicitly copies it. When adding a new forwarder, copy the incoming

baggage

header onto outbound requests or use the service's existing instrumented client.

只有当每个跳转都传播路由键时，路由键才能到达下游沙箱服务。原始HTTP/gRPC客户端、自定义代理处理程序及异步生产者通常会丢弃路由键，除非代码显式复制它。添加新的转发器时，将传入的

baggage

头复制到出站请求，或使用服务现有的已 instrumentation 客户端。

Secrets And Env Vars

密钥与环境变量

When reconstructing env vars from workload specs, ConfigMaps, or Secrets:

Resolve every required value before blaming the code. Missing DB addresses, credentials, and feature flags often appear as first-request 500s.
Do not print secret values in chat, logs, or summaries. Redact them as
```
<redacted>
```
and avoid pasting decoded Secret contents.
Prefer exporting secrets directly into the process environment. If an env file is necessary, write it with restrictive permissions and remove it during cleanup.
For service addresses, grep the code for config lookups such as
```
*_ADDR
```
,
```
*_HOST
```
,
```
*_URL
```
, and language-specific helpers. Defaults that work inside a pod may not work from a local process.

从工作负载规范、ConfigMap或Secret重构环境变量时：

在归咎于代码之前，解析所有必需的值。缺失的数据库地址、凭据及功能标志通常会导致首次请求出现500错误。
请勿在聊天、日志或摘要中打印密钥值。将其替换为
```
<redacted>
```
，避免粘贴解码后的Secret内容。
优先将密钥直接导出到进程环境中。若需要环境文件，请以严格权限写入并在清理时删除。
对于服务地址，在代码中搜索配置查找项（如
```
*_ADDR
```
、
```
*_HOST
```
、
```
*_URL
```
及特定语言的辅助工具）。在Pod内部有效的默认值可能无法在本地进程中使用。

Validation Type Picker

验证类型选择器

Integration tests: run the language-native test command against the cluster
```
.svc
```
URL, injecting routing headers in the test client or a shared transport.
Existing e2e suite: use the repo's existing command and config. Point its base URL at the
```
.svc
```
URL and attach routing headers at the framework HTTP layer.
Ad-hoc browser automation: drive the UI from a browser to exercise the change end-to-end. Use whatever browser-automation tooling is available (Playwright is the common one); inject routing headers on every request, clear previous routes first when browser state persists, and drive the full UI path.
Existing tagged Signadot plan: pick a tag by
```
selectionHint
```
and run it against the sandbox. For everything else about plans — params, secrets, logs/outputs, authoring, tagging — defer to the
```
signadot-plan
```
skill.

Read references/validation-types.md before running the chosen type.

集成测试：针对集群
```
.svc
```
URL运行语言原生测试命令，在测试客户端或共享传输中注入路由头。
现有端到端测试套件：使用代码库现有的命令和配置。将其基础URL指向
```
.svc
```
URL，并在框架HTTP层附加路由头。
临时浏览器自动化测试：通过浏览器驱动UI以端到端验证变更。使用可用的浏览器自动化工具（常用为Playwright）；在每个请求中注入路由头，若浏览器状态持久则先清除之前的路由，并驱动完整的UI路径。
现有标记Signadot计划：按
```
selectionHint
```
选择标签并针对沙箱运行。关于计划的其他所有内容（参数、密钥、日志/输出、创作、标记），请参考
```
signadot-plan
```
Skill。

运行所选验证类型前，请阅读references/validation-types.md。

Failure Loop

故障循环

When validation fails, do not stop at "validation failed." Continue the loop:

Quote the exact failure: status code, error message, stack trace, missing UI element, bad field, or empty browser state.
Identify whether the likely cause is app code, sandbox shape, missing env, stale process, wrong port, routing-key propagation, or a changed downstream consumer that must also run locally.
Apply the smallest fix, rebuild and restart affected processes, and re-run the same validation with the same routing key and target URL.
Stop to ask only when the fix requires a judgment call that cannot be made without the user — for example, choosing between fixing forward, making a change backward-compatible, or accepting an intentional break. Do not ask permission for mechanical fixes such as typos, missing env vars, or restarting a stopped process; just apply them and continue the loop.

Before declaring done, consider whether the verified behavior should be codified as a Signadot plan. Do this when the bug is deterministic, important, and not covered elsewhere. Skip it for typos, infra flakes, exploratory checks, and non-deterministic failure modes. The sandbox is still up — running the new plan against it once confirms it catches the bug (or passes for the fixed code) before tagging.

验证失败时，不要仅停留在“验证失败”的结论。继续执行以下循环：

引用具体的失败信息：状态码、错误消息、堆栈跟踪、缺失的UI元素、错误字段或空白浏览器状态。
确定可能的原因：应用代码问题、沙箱配置问题、缺失环境变量、进程过期、端口错误、路由键传播问题，或下游消费者已变更且必须在本地运行。
应用最小修复，重新构建并重启受影响的进程，使用相同的路由键和目标URL重新运行相同的验证。
仅当修复需要用户判断（例如选择向前修复、向后兼容变更或接受有意中断）时，才停止并询问用户。对于拼写错误、缺失环境变量或重启已停止进程等机械性修复，无需请求许可，直接应用并继续循环。

在宣布完成前，考虑是否应将已验证的行为编写为Signadot计划。当错误具有确定性、重要性且未被其他测试覆盖时，执行此操作。对于拼写错误、基础设施故障、探索性检查及非确定性故障模式，可跳过此步骤。沙箱仍在运行——针对沙箱运行新计划可确认其能捕获错误（或在代码修复后通过），然后再标记。

Quick Diagnostics

快速诊断

Symptom	Likely cause	First check
Envoy 503 from devbox but pod is healthy	Hit container port instead of Service port	Service object / endpoint resolver
Response looks like old baseline behavior	Routing key dropped or localhost target used	Target URL and all routing headers
Sandbox ready and tunnel connected but local process gets no traffic	Wrong sandbox mapping port	`/etc/hosts` virtual sandbox entry
Local process starts, then first real request returns 500	Missing env var or unresolved dependency address	Config lookups and exported env
Browser body or accessibility tree empties after interaction	SPA runtime error	Browser console errors and `page.content().length`
Background process exits soon after start	Shell job received SIGHUP or port conflict	Process status, listener, log file
gRPC dial stalls around DNS timeout	Go gRPC SRV lookup delay	`passthrough:///` target and connection reuse

Read references/troubleshooting.md for detailed signals and fixes.

症状	可能原因	首次检查项
开发环境返回Envoy 503错误，但Pod运行正常	访问了容器端口而非Service端口	Service对象/端点解析器
响应与旧基线行为一致	路由键丢失或使用了localhost目标	目标URL及所有路由头
沙箱就绪且隧道已连接，但本地进程未收到流量	沙箱映射端口错误	`/etc/hosts` 中的虚拟沙箱条目
本地进程启动后，首次真实请求返回500错误	缺失环境变量或未解析依赖项地址	配置查找项及导出的环境变量
交互后浏览器内容或可访问性树为空	SPA运行时错误	浏览器控制台错误及 `page.content().length`
后台进程启动后很快退出	Shell作业收到SIGHUP信号或端口冲突	进程状态、监听程序、日志文件
gRPC拨号在DNS超时附近停滞	Go gRPC SRV查找延迟	`passthrough:///` 目标及连接复用

详细的信号与修复方法，请阅读references/troubleshooting.md。

Final Report

最终报告

Include:

Validation type and command/tool path used
Cluster, sandbox name, routing key, and service URL
What passed, including browser/user path when relevant
Any local process PIDs or ports stopped
Sandbox teardown command as an option, not an action:

bash

signadot sandbox delete <sandbox-name>

If the user ran local network connect, remind them that they can later run:

bash

signadot local disconnect

需包含：

使用的验证类型及命令/工具路径
集群、沙箱名称、路由键及服务URL
通过的验证内容，包括相关的浏览器/用户路径
已停止的本地进程PID或端口
沙箱销毁命令（作为选项，而非执行操作）：

bash

signadot sandbox delete <sandbox-name>

若用户运行了本地网络连接，提醒他们之后可运行：

bash

signadot local disconnect