docs(managed-mode): document cert-bundle bootstrap path + fix image tag - #181
Conversation
The README's "what's shipped" headline calls out the cert-bundle
bootstrap path (no `/dp/register` round-trip) as a first-class
managed-mode option, but `docs/managed-mode.md` had zero coverage of
it. An operator following the doc could only set up the
register-based path, missing the recommended one entirely.
This PR fills in the gap. Source-of-truth:
`crates/aisix-server/src/cert_bundle.rs` and
`crates/aisix-core/src/config.rs`.
Changes:
1. New "First boot — pre-provisioned cert bundle (recommended)"
section. Covers the three required PEMs, both inline and
file-path env-var variants, and how `env_id` + `dp_id` are parsed
out of the leaf cert's URI SAN to scope etcd reads to
`/aisix/<env_id>/`.
2. Re-titled the existing "First boot — register against the
control plane" to "Alternative: register against the control
plane" so the recommended path leads.
3. Added `AISIX_MANAGED__CP_ETCD_ENDPOINT`,
`AISIX_MANAGED__CP_CA_CERT_FILE`, and the six cert-bundle
`CP_{CERT,KEY,CA}_{PEM,FILE}` env vars to the override table.
4. Updated "Restart semantics" to handle three first-boot branches
(cert-bundle / register / fail-fast) instead of two, and noted
that `env_id` is persisted alongside `dp_id` in the bundle dir.
5. Image tag corrected from `ghcr.io/moonming/ai-gateway:main` →
`ghcr.io/api7/ai-gateway:main` to match the README and the
actual published image.
|
Warning Rate limit exceeded
You’ve run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Free Run ID: 📒 Files selected for processing (1)
Note 🎁 Summarized by CodeRabbit FreeYour organization has reached its limit of developer seats under the Pro Plan. For new users, CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please add seats to your subscription by visiting https://app.coderabbit.ai/login.If you believe this is a mistake and have available seats, please assign one to the pull request author through the subscription management page using the link above. Comment |
There was a problem hiding this comment.
Pull request overview
This PR updates docs/managed-mode.md to document the managed-mode “pre-provisioned cert bundle” bootstrap path (minted cert/key/CA provided via env vars or mounted files), reorders/retitles the legacy register flow as an alternative, expands the env-var override table and restart semantics, and fixes the managed-mode image reference to the correct GHCR org.
Changes:
- Added a new “First boot — pre-provisioned cert bundle (recommended)” section documenting the PEM inputs and SAN-derived
env_id/dp_idbehavior. - Reframed the existing
/dp/registerbootstrap flow as an alternative path and updated restart semantics to includeenv_id. - Fixed the Docker image tag from
ghcr.io/moonming/ai-gateway:maintoghcr.io/api7/ai-gateway:mainand expanded the env-var overrides table.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| -e AISIX_MANAGED__CP_CERT_PEM="$(cat leaf.crt)" \ | ||
| -e AISIX_MANAGED__CP_KEY_PEM="$(cat leaf.key)" \ | ||
| -e AISIX_MANAGED__CP_CA_PEM="$(cat ca.crt)" \ | ||
| -e AISIX_MANAGED__CP_ETCD_ENDPOINT=https://dp-manager.aisix.cloud:7943 \ |
| | `AISIX_MANAGED__CP_ETCD_ENDPOINT` | `managed.cp_etcd_endpoint` | unset; required for cert-bundle path | | ||
| | `AISIX_MANAGED__CP_CA_CERT_FILE` | `managed.cp_ca_cert_file` | unset; optional override for the dp-manager trust anchor | | ||
| | `AISIX_MANAGED__CP_CERT_PEM` / `_FILE` | `managed.cp_cert_pem` / `cp_cert_file` | unset (cert-bundle path; one of the two must be set) | | ||
| | `AISIX_MANAGED__CP_KEY_PEM` / `_FILE` | `managed.cp_key_pem` / `cp_key_file` | unset (cert-bundle path; one of the two must be set) | | ||
| | `AISIX_MANAGED__CP_CA_PEM` / `_FILE` | `managed.cp_ca_pem` / `cp_ca_file` | unset (cert-bundle path; one of the two must be set) | |
…ample Audit on PR #181 returned BLOCK with 3 HIGH and 3 MEDIUM. Address the verified ones (one HIGH was based on a stale workflow comment — the published image really is `ghcr.io/api7/ai-gateway`): H2: Cert-bundle docker example was missing `CP_BASE_URL`. Boot would fail at `crates/aisix-server/src/main.rs:154` ("managed.cp_base_url required when cert bundle is provided") — cert-bundle path skips `/dp/register` but the heartbeat worker still needs the CP origin. Added the env var and rewrote the "what each flag does" entry to clarify the heartbeat dependency. H3: `CP_ETCD_ENDPOINT` value had `https://` prefix; `main.rs:173` formats it as `format!("https://{cp_etcd}")`, so `https://https://...` would have been the actual endpoint. Strip the scheme; doc-comment on `cfg.managed.cp_etcd_endpoint` (`config.rs:161`) already requires bare host:port. M1: Env-var table row for `CP_ETCD_ENDPOINT` was inverted. Code: register path strict-requires it (main.rs:213); cert-bundle path falls back to `cp_base_url`'s host:port (main.rs:161-166). Swap the description. M2: "Verifying" log block fabricated a `gateway_id=aigg_xxx` field the code never emits (main.rs:167-171 for cert-bundle, register.rs for register path — both write `dp_id`, `env_id`, `etcd`). Replace with the actual emitted fields and split into cert-bundle vs register branches so operators can match either. M3: Restart-semantics step #1 implied cert-bundle env vars trump bundle-on-disk; main.rs gates cert-bundle on `if !bundle_on_disk && bundle_provided` (line 130). Reword to "no bundle on disk yet" so the precedence reads bundle-on-disk → cert-bundle → register.
Audit responseIndependent audit on commit `1dc0fec` returned BLOCK (3 HIGH, 3 MEDIUM). Addressed in commit `8487dbd`:
|
Summary
The README's "what's shipped" line calls out the cert-bundle bootstrap path (no `/dp/register` round-trip, PEMs supplied as env vars) as a first-class managed-mode option, but `docs/managed-mode.md` had zero coverage of it. An operator following the doc could only set up the register-based path and would miss the recommended one entirely.
This PR fills that gap. Source-of-truth: `crates/aisix-server/src/cert_bundle.rs` and `crates/aisix-core/src/config.rs`.
Changes
New "First boot — pre-provisioned cert bundle (recommended)" section. Three required PEMs, both inline and file-path env-var variants, and how `env_id` + `dp_id` are parsed out of the leaf cert's URI SAN (`x-aisix://env/<env_id>`, `x-aisix://dp/<dp_id>`) to scope etcd reads to `/aisix/<env_id>/`.
Re-titled the existing register section to "Alternative: register against the control plane" so the recommended path is documented first.
Env-var override table gained:
Restart semantics now covers three first-boot branches (cert-bundle / register / fail-fast) instead of two, and notes that `env_id` is persisted alongside `dp_id` (the doc previously listed only `dp_id`).
Image tag corrected from `ghcr.io/moonming/ai-gateway:main` → `ghcr.io/api7/ai-gateway:main` to match the README and the actual published image.
Out of scope
Companion PRs in the doc-drift series: #179 (architecture metric names + Cohere), #180 (testing.md npm→pnpm + CI diagram). Still to come: `api-admin.md` schema-truth pass and `api-proxy.md` error/header drift (latter stacked behind #178).
Test plan
🤖 Generated with Claude Code