docs: write a 'rotate provider key without client impact' tutorial, backed by an e2e test
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 157
- Forks
- 32
- Avg merge
- 1h 25m
- Merged PRs (30d)
- 145
Description
Context
docs/tutorials/rotate-provider-key-without-client-impact.md was added as a 24-line skeleton in #249 but did not include executable steps or a verification section. It was removed in the docs-rebuild-batch-1 follow-up because no existing e2e test pins the "rotation under live traffic" contract — writing the tutorial without that anchor would risk drift between the documented steps and real product behavior.
What we need
- An e2e test in
tests/e2e/src/cases/provider-key-rotation-e2e.test.tsthat:- creates a `ProviderKey` PK1, a `Model` pointing at PK1, an `ApiKey` allowed to use that model
- sends N chat requests, asserts all succeed
- issues `PUT /admin/v1/provider_keys/:id` to update PK1's `secret` (and optionally `api_base`) — same `id`, different upstream credential
- sends another N requests with the same caller bearer + same model alias
- asserts: all requests succeed, revision on the resource bumped, the caller-facing key + model alias were never re-issued
- Once the test lands, restore `docs/tutorials/rotate-provider-key-without-client-impact.md` to a Kong-cookbook-tier walkthrough modeled on the test (see `docs/tutorials/build-a-virtual-model-with-failover.md` for the shape).
Why not write the tutorial against just the resource API
`PUT /admin/v1/provider_keys/:id` exists and the handler tests cover the update path, but "client traffic stays intact across rotation" is a cross-component invariant (admin write → etcd watch → proxy snapshot → in-flight dispatch). Only an e2e test exercises that full path.
Reference
- Mechanism: `crates/aisix-admin/src/provider_keys_handlers.rs::update_provider_key`
- Propagation: `crates/aisix-etcd/` watch supervisor + `aisix-server` snapshot apply
- Verification model: same shape as `cache-policy-e2e.test.ts` and `routing-strategies-e2e.test.ts`
Definition of done
- e2e test added and green in CI
- `docs/tutorials/rotate-provider-key-without-client-impact.md` restored, Kong-tier shape, citing the new e2e test as the contract anchor
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with tests/e2e/src/cases/provider-key-rotation-e2e.test.ts and compare the verification shape in cache-policy-e2e.test.ts and routing-strategies-e2e.test.ts. Read update_provider_key in crates/aisix-admin/src/provider_keys_handlers.rs, then trace the referenced etcd watch and aisix-server snapshot paths. Done means the e2e test is green in CI and docs/tutorials/rotate-provider-key-without-client-impact.md is restored as a Kong-cookbook-tier walkthrough anchored to that test.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust, typescript
- Domain
- backend, documentation, testing
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 52/100