边缘轮换

其他 社区

技能解读

当前原文的自动摘译,尚未人工审校。

为什么现在这么短

早期的多步骤过程之所以存在,是因为 CFN 模板将 EIP 视为堆栈管理的资源(AWS::EC2::EIP + EIPAssociation 和 Retain)。手动 EIP 交换然后使 template-vs-live 不同步,并需要分离 + IMPORT 才能恢复;该恢复序列(特别是 EIAssociation 上的 IMPORT 步骤)是静默断开 SSM 代理的原因

一次规范调用

edge_id将deploy/aws/stage0/edge-targets.json中的键与deployable=true匹配(规范化edge-uk1→uk1)。如果边缘是 Lightsail 权威的(uk1 / us2 / … 在 edge-targets-lightsail.json 中),

还剩两个操作员步骤(有意)

Porkbun(或您的提供商)的 DNS:将api-<id>.tokenkey.dev 的 A 记录更改为新 IP。工作流程不会自动执行此操作,因为 Porkbun API 令牌不在存储库机密中;运行摘要打印确切的转换。将已停用的 IP 附加到

首次迁移(每个堆栈)

仍具有 v1 形状的堆栈(ElasticIP + EIPAssociation 与 Retain,无 EipAllocationId 参数)尚无法接受 operation=rotate_egress_ip。迁移一次:迁移保持相同的物理 EIP - 公共 IP 不会改变。它仅将CFN表示从“EIP在模板中”转换为“EIP

停线规则

工作流本身强制执行数据平面不变量。在以下情况下,此技能仍必须拒绝: 规范化的 edge_id 不是 deploy/aws/stage0/edge-targets.json 和 deployable=true 中的关键,或者边是 Lightsail 中的权威

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
通用
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@youxuanxue · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
即装即用
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
网络行为
允许外网请求
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# TokenKey: rotate an edge gateway's egress EIP

**EC2/CFN only.** Lightsail Static IP 轮换见 `tokenkey-stage0-edge-lightsail-ip-rotation`(**uk1 已迁 Lightsail**,勿对本 skill  dispatch `rotate_egress_ip`)。

**v2 (OPC).** Replaces the v1 manual multi-step nano-probe / CFN-IMPORT runbook.
The deploy workflow now owns rotation end-to-end; this skill is a thin wrapper
that decides _which workflow input to pass_, not a sequence of bash commands.

Polluted IP registry:
[`deploy/aws/stage0/edge-polluted-ips.json`](../../../deploy/aws/stage0/edge-polluted-ips.json)
(human-readable table in
[`docs/deploy/tokenkey-edge-ip-history.md`](../../../docs/deploy/tokenkey-edge-ip-history.md)).

## Why this is short now

The earlier multi-step procedure existed because the CFN template treated the
EIP as a stack-managed resource (`AWS::EC2::EIP` + `EIPAssociation` with
`Retain`). Manual EIP swaps then desynced template-vs-live and required
detach + IMPORT to recover; that recovery sequence (specifically the IMPORT
step on the EIPAssociation) is what silently disconnected the SSM agent on
edge-uk1 on 2026-05-22.

The template has since been refactored so the EIP is an external
`EipAllocationId` _parameter_, not a resource. CloudFormation does
disassociate-old + associate-new natively when the parameter changes — the
instance, its IAM profile, and its SSM agent are never touched. The entire
class of "drift" disappears, and so does this skill's previous bulk.

## One canonical invocation

```bash
gh workflow run deploy-edge-stage0.yml \
  -f edge_id=<id> \
  -f operation=rotate_egress_ip \
  -f confirm_stack=tokenkey-edge-<id>-stage0 \
  -f rotation_reason='<short reason>' \
  [-f candidate_allocation_id=eipalloc-XXXX]
```

`edge_id` matches a key in
[`deploy/aws/stage0/edge-targets.json`](../../../deploy/aws/stage0/edge-targets.json)
with **`deployable=true`** (normalize `edge-uk1` → `uk1`). If the edge is
Lightsail-authoritative (uk1 / us2 / … in
[`edge-targets-lightsail.json`](../../../deploy/aws/lightsail/edge-targets-lightsail.json)),
stop and use `tokenkey-stage0-edge-lightsail-ip-rotation` instead.
`rotation_reason` is required and ends up on
the new EIP's `tokenkey:replaces-reason` tag and in the run summary's
`edge-polluted-ips.json` snippet.

`candidate_allocation_id` is optional. If unset, the workflow allocates a
fresh EIP and refuses any allocation that lands on a known-polluted IP. Set
it only when the operator has pre-vetted a specific allocation outside the
workflow (rare — only useful if the auto path keeps drawing dirty IPs).

What the workflow does, in order:
1. Reads the stack's current `EipAllocationId` (= rollback target).
2. Allocates a fresh EIP unless `candidate_allocation_id` is set; cross-checks against [`edge-polluted-ips.json`](../../../deploy/aws/stage0/edge-polluted-ips.json) and re-allocates if dirty.
3. `aws cloudformation deploy --parameter-overrides EipAllocationId=<new>` — atomic CFN swap.
4. Polls `ssm:DescribeInstanceInformation` until `PingStatus=Online` (post-mutation invariant; uk1-2026-05-22 was the incident that motivated this gate).
5. Runs the pollution probe via SSM **on the edge itself** (no throwaway nano): confirms outbound IP, then curls Anthropic / OpenAI / Google with dummy keys looking for `403 + Cloudflare HTML` (= polluted) vs `401/400 + provider-shaped JSON` (= clean).
6. On polluted → automatic revert (CFN update-stack back to OLD_ALLOC) + release the freshly-allocated EIP (only if the workflow itself allocated it).
7. On clean → curl `https://<domain>/health` via `--resolve <domain>:443:<new_ip>` to prove the data plane survives end-to-end on the new IP before DNS propagation.
8. Emits a step summary with: old/new IP, retired-IP JSON snippet ready to paste into [`edge-polluted-ips.json`](../../../deploy/aws/stage0/edge-polluted-ips.json), and the Porkbun A-record change to make.

## Two operator steps left (intentional)

1. **DNS at Porkbun (or your provider)**: change the A record for
   `api-<id>.tokenkey.dev` to the new IP. The workflow does not automate this
   because the Porkbun API token is not in repo secrets; the run summary
   prints the exact transition.
2. **Append the retired IP to
   [`edge-polluted-ips.json`](../../../deploy/aws/stage0/edge-polluted-ips.json)**
   so future rotations refuse to re-allocate it. The run summary prints a
   paste-ready JSON entry. After DNS has propagated (~1 hour) you may
   `aws ec2 release-address` the old allocation and set `released_on`.

Everything else is mechanized.

## First-time migration (per stack)

A stack that still has the v1 shape (ElasticIP + EIPAssociation with Retain,
no `EipAllocationId` parameter) cannot accept `operation=rotate_egress_ip`
yet. Migrate it once:

```bash
# Dry run (read-only):
bash deploy/aws/stage0/migrate-edge-eip-to-parameter.sh <edge_id>

# Apply (changes live CFN):
bash deploy/aws/stage0/migrate-edge-eip-to-parameter.sh <edge_id> --apply
```

The migration keeps the same physical EIP — the public IP does NOT change.
It only converts the CFN representation from "EIP is in the template" to "EIP
is referenced by allocation-id parameter". After the migration, the stack
accepts `operation=rotate_egress_ip` and the rest of this skill is in force.

## Stop-the-line rules

The workflow itself enforces the data-plane invariants. This skill must still
refuse when:

1. The normalized `edge_id` is not a key in
   [`deploy/aws/stage0/edge-targets.json`](../../../deploy/aws/stage0/edge-targets.json)
   with **`deployable=true`**, or the edge is Lightsail-authoritative in
   `edge-targets-lightsail.json` (use lightsail-ip-rotation skill).
2. `rotation_reason` is empty or only whitespace.
3. The target stack has not been migrated yet (`describe-stacks` shows no
   `EipAllocationId` parameter) — direct the operator to
   `migrate-edge-eip-to-parameter.sh` first.
4. `operation=rotate_egress_ip` is requested against `tokenkey-prod-stage0`
   (the production gateway). Prod IP rotation has different blast radius
   (active client connections) and is intentionally not covered by this
   skill.

The workflow handles the rest as mechanical gates — operator does not need
this skill to babysit candidate allocation, probe results, or revert.

## Reporting contract

The workflow's step summary is the contract. Nothing else needs to be
produced. If you need to summarize for a chat caller, mirror the values from
the summary:

```text
edge_id: <id>
region: <aws-region>
old_ip / old_alloc: <ip> / <eipalloc-…>
new_ip / new_alloc: <ip> / <eipalloc-…>
status: rotated | reverted-polluted | revert-failed
follow_up:
  - update DNS A-record at Porkbun: <domain> → <new_ip>
  - append retired IP entry to deploy/aws/stage0/edge-polluted-ips.json
  - (after ~1h DNS propagation) aws ec2 release-address --allocation-id <old_alloc>
```

## Out of scope

- Production gateway IP rotation (`tokenkey-prod-stage0`).
- Cross-region "clean EIP pool" maintenance. If the auto path repeatedly
  draws polluted IPs in a region, the answer is a different region (or an
  upstream Trust & Safety ticket), not a pre-warmed pool — adding a pool is
  premature.
- DNS automation (Porkbun API). Documented as a known follow-up; would be a
  separate skill + a separate secret if/when wanted.

## v1 (legacy) reference

Retired polluted IPs are recorded in
[`edge-polluted-ips.json`](../../../deploy/aws/stage0/edge-polluted-ips.json)
when dispatching `rotate_egress_ip` (same PR as the rotation).

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。