api7 / api7/aisix

docs: write a 'rotate provider key without client impact' tutorial, backed by an e2e test

Open
#271 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

documentation enhancement priority-normal
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

  1. An e2e test in tests/e2e/src/cases/provider-key-rotation-e2e.test.ts that:
    • 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
  2. 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.