feat(etcd): periodic auth token refresh to prevent expiry

[okaybase]

Summary

The etcd auth token acquired at connect time was never refreshed. Once it expired (default 300s --auth-token-ttl), every subsequent Admin API write and etcd watch operation failed with etcdserver: invalid auth token.

Changes

• aisix-etcd: add start_token_refresh_task — a background Tokio task that calls Client::refresh_token on a configurable interval (default 240s, leaving a 60s margin below etcd's default 300s TTL). No-ops when no credentials are configured, or when called outside a Tokio runtime.
• aisix-core: add EtcdConfig.auth_token_refresh_secs field (default 240). Documented in config.example.yaml and config.managed.yaml.
• aisix-server: thread auth_token_refresh_secs from config through EtcdConfigProvider::connect and EtcdConfigStore::new.
• aisix-admin: EtcdConfigStore::new now spawns the refresh task for the admin write-path client, preventing Admin API writes from failing after token expiry.
• Dependency: bump etcd-client from 0.14 to 0.19 to pick up Client::refresh_token and the merged WatchStream (no longer requires a separate Watcher handle).
• Tests: add admin_write_survives_token_expiry and token_refresh_prevents_auth_expiry regression tests against an auth-enabled etcd with a 5s TTL, exercising the refresh loop.
• CI: add etcd-auth service container (short TTL) and "Enable auth on etcd-auth" step to run the token-refresh tests.

Verification

• cargo test --workspace passes
• cargo clippy --workspace -- -D warnings clean
• CI rust-unit job runs the new token-refresh tests against the auth-enabled etcd container
• Manual: start gateway with etcd.user + password_env, verify Admin API writes still succeed after 5+ minutes

Summary by CodeRabbit

• New Features

  • Added configurable etcd authentication-token refresh intervals.
  • The default refresh interval is 240 seconds and can be overridden in configuration.
  • Authenticated etcd connections now refresh tokens automatically to remain available across token expiry.

• Bug Fixes

  • Improved reliability for admin requests and watch operations using authenticated etcd connections.

• Tests

  • Added integration coverage validating token refresh across authentication expiry.

[CLAassistant]

All committers have signed the CLA.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: e13a2fa7-0e64-49ca-b626-5e4b6493075d

📥 Commits

Reviewing files that changed from the base of the PR and between 30829d6 and c608c7c.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (11)

• .github/workflows/ci.yml
• Cargo.toml
• config.example.yaml
• config.managed.yaml
• crates/aisix-admin/src/etcd_store.rs
• crates/aisix-admin/tests/etcd_integration.rs
• crates/aisix-core/src/config.rs
• crates/aisix-etcd/src/etcd_provider.rs
• crates/aisix-etcd/src/lib.rs
• crates/aisix-etcd/tests/watch_integration.rs
• crates/aisix-server/src/main.rs

---

📝 Walkthrough

Walkthrough

The change adds configurable etcd authentication-token refresh, updates provider and application wiring, upgrades etcd-client, adds authenticated integration tests, and provisions an auth-enabled etcd service in CI.

Changes

etcd authentication refresh

Layer / File(s)	Summary
Refresh configuration contract Cargo.toml, crates/aisix-core/src/config.rs, config*.yaml	Adds auth_token_refresh_secs with a default of 240 seconds, YAML override coverage, documented examples, and updates etcd-client to 0.19.
Provider refresh and watch behavior crates/aisix-etcd/src/etcd_provider.rs, crates/aisix-etcd/src/lib.rs, crates/aisix-etcd/tests/watch_integration.rs	Adds configurable background token refresh, updates provider signatures and exports, adjusts watch-stream ownership, and tests refresh across token expiry.
Application and admin-store wiring crates/aisix-server/src/main.rs, crates/aisix-admin/src/etcd_store.rs, crates/aisix-admin/tests/etcd_integration.rs	Passes refresh configuration through server and admin-store construction and verifies authenticated admin writes after token expiry.
Authenticated etcd CI environment .github/workflows/ci.yml	Adds an auth-enabled etcd service, credentials and endpoints, and authentication bootstrap commands for integration tests.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Server
  participant EtcdConfigProvider
  participant EtcdClient
  participant AdminStore
  Server->>EtcdConfigProvider: connect with refresh interval
  EtcdConfigProvider->>EtcdClient: authenticate and start refresh task
  EtcdConfigProvider->>AdminStore: provide connected client
  AdminStore->>EtcdClient: write admin configuration
  EtcdConfigProvider->>EtcdClient: refresh token periodically

Loading

Possibly related PRs

• api7/aisix#238: Overlaps with the EtcdWatchStream watcher-lifetime changes.
• api7/aisix#258: Overlaps with watch-stream buffering and multi-event handling.

Suggested reviewers: kayx23

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: periodic etcd auth token refresh to prevent expiry.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
E2e Test Quality Review	✅ Passed	PASS: The new admin and provider regression tests hit real etcd services over HTTP/gRPC, are well named/commented, and CI wires the auth-enabled container explicitly.
Security Check	✅ Passed	No security regressions found: the new auth-refresh path doesn't log/return secrets, credentials stay test-only, and no authz/TLS or secret-storage logic changed.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}