docs: migrate traffic recipes to service model#9
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (3)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughMigrates three API7 EE recipe documents from upstream-centric to service-centric routing: replaces upstream/upstream_id/uri examples with service/service_id/paths, updates CLI commands and declarative configs, and revises rollout, verification, and troubleshooting content. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Review rate limit: 0/1 reviews remaining, refill in 60 minutes.Comment |
There was a problem hiding this comment.
Pull request overview
Migrates the recipe documentation for canary, blue-green, and API versioning to the service-backed model (using a7 service create + route service_id) instead of standalone upstream resources, while keeping traffic-split only for weighted/header-based overrides.
Changes:
- Update canary and blue-green recipes to create services and bind routes via
service_id. - Update API versioning recipe to model “one service per version” and use
paths+service_id. - Refresh Config Sync YAML examples to use
servicesand routepaths/service_id.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| skills/a7-recipe-canary/SKILL.md | Converts canary workflow to service-backed routing; uses inline upstream only inside traffic-split; updates Config Sync example. |
| skills/a7-recipe-blue-green/SKILL.md | Reworks blue/green recipe around swapping route service_id; keeps header-based testing via traffic-split inline upstream. |
| skills/a7-recipe-api-versioning/SKILL.md | Refactors versioning patterns to “service per version” with service-backed routes and updated Config Sync example. |
Comments suppressed due to low confidence (1)
skills/a7-recipe-canary/SKILL.md:19
metadata.a7_commandsis missinga7 route list, but the troubleshooting section later instructs runninga7 route list --service-id stable-service. Please adda7 route listto the command list so the skill metadata matches the documented workflow.
a7_commands:
- a7 service create
- a7 service update
- a7 route create
- a7 route update
- a7 route get
- a7 config sync
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| a7 route update route-v1 -g production -f - <<'EOF' | ||
| { | ||
| "service_id": "service-v1", | ||
| "plugins": { |
There was a problem hiding this comment.
In “Gradual Version Rollout”, the route-v1 route was created earlier with the proxy-rewrite plugin to strip the /v1 prefix. This update payload sets plugins to only traffic-split, which can inadvertently drop proxy-rewrite depending on how route updates are applied. Consider including both proxy-rewrite and traffic-split in the update payload (or explicitly documenting that the update preserves existing plugins) so the rewrite behavior remains intact during rollout.
| "plugins": { | |
| "plugins": { | |
| "proxy-rewrite": { | |
| "regex_uri": ["^/v1/(.*)", "/$1"] | |
| }, |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
skills/a7-recipe-blue-green/SKILL.md (1)
244-251: Minor: make verification commands gateway-group explicit.In the troubleshooting table you suggest:
Verify with a7 route get api -o jsonOther examples in the same file consistently use
--gateway-group default. For consistency (and to avoid “route not found” confusion), consider including--gateway-group defaultin that troubleshooting row as well.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/a7-recipe-blue-green/SKILL.md` around lines 244 - 251, Update the troubleshooting table row that currently shows the command "a7 route get api -o json" to include the gateway group flag so it reads "a7 route get api --gateway-group default -o json"; specifically edit the table cell containing "Verify with `a7 route get api -o json` and retry after propagation" to include "--gateway-group default" to match other examples and avoid "route not found" confusion.skills/a7-recipe-canary/SKILL.md (1)
181-213: Minor: add an explicit header example forx-canary: true.The “Header-Based Canary” section explains the match condition and says only requests with
x-canary: truego to canary, but it doesn’t show acurlexample to validate the exact header name/value (and whethertrueis treated as a string).Consider adding a short curl snippet similar to the blue-green recipe’s header test, e.g. hitting
/api/*with-H 'x-canary: true'.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/a7-recipe-canary/SKILL.md` around lines 181 - 213, Add a short curl example to the "Header-Based Canary" section demonstrating the exact header name and value used for the match (use the header key x-canary and the value true) so readers can validate whether true is treated as a string; place a one-line curl snippet similar to the blue-green recipe's header test (targeting the /api/* path and using -H 'x-canary: true') immediately after the explanation that "Only requests with `x-canary: true` go to canary."
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@skills/a7-recipe-api-versioning/SKILL.md`:
- Around line 195-238: The YAML example includes an unsupported top-level
gateway_group field; remove gateway_group from the config file and document that
the gateway group must be provided via the CLI flag (e.g., use "a7 config sync
-g production -f <file>") instead; update the example YAML to omit gateway_group
and, if applicable, adjust any references to the ConfigFile struct or parsing
code that might expect gateway_group so the ConfigFile struct remains the single
source of truth for file-based fields.
In `@skills/a7-recipe-canary/SKILL.md`:
- Around line 262-298: Remove the top-level gateway_group key from the Config
Sync YAML in SKILL.md so the example matches the ConfigFile schema; instead rely
on providing the gateway group via CLI/application context (e.g., using the a7
config sync -g/--gateway-group flag). Locate the YAML block containing
gateway_group: default and delete that line, leaving the rest of the
route/service definitions intact; ensure no other references to gateway_group
remain in the example.
---
Nitpick comments:
In `@skills/a7-recipe-blue-green/SKILL.md`:
- Around line 244-251: Update the troubleshooting table row that currently shows
the command "a7 route get api -o json" to include the gateway group flag so it
reads "a7 route get api --gateway-group default -o json"; specifically edit the
table cell containing "Verify with `a7 route get api -o json` and retry after
propagation" to include "--gateway-group default" to match other examples and
avoid "route not found" confusion.
In `@skills/a7-recipe-canary/SKILL.md`:
- Around line 181-213: Add a short curl example to the "Header-Based Canary"
section demonstrating the exact header name and value used for the match (use
the header key x-canary and the value true) so readers can validate whether true
is treated as a string; place a one-line curl snippet similar to the blue-green
recipe's header test (targeting the /api/* path and using -H 'x-canary: true')
immediately after the explanation that "Only requests with `x-canary: true` go
to canary."
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 10ff3b51-a046-4206-843c-53d60102e795
📒 Files selected for processing (3)
skills/a7-recipe-api-versioning/SKILL.mdskills/a7-recipe-blue-green/SKILL.mdskills/a7-recipe-canary/SKILL.md
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | Canary not receiving traffic | Match condition never true | Check header/cookie name and `a7 route get` output | | ||
| | Rollback not instant | Config has not propagated yet | Verify with `a7 route get` and retry after propagation | | ||
| | 502 from canary | Canary backend is unhealthy | Check canary service health before increasing weight | | ||
| | Weight changes have no effect | Editing wrong route | Verify route ID with `a7 route list --service-id stable-service` | |
There was a problem hiding this comment.
The troubleshooting command a7 route list --service-id stable-service will fail when the user doesn’t have a default gateway group set in their context (the CLI requires --gateway-group/-g or a configured default). Consider adding --gateway-group default (or mentioning that a default context gateway group must be set) to make the copy/paste instruction reliably runnable.
| | Weight changes have no effect | Editing wrong route | Verify route ID with `a7 route list --service-id stable-service` | | |
| | Weight changes have no effect | Editing wrong route | Verify route ID with `a7 route list --gateway-group default --service-id stable-service` | |
| | Can't rollback | Lost track of previous upstream | Always record current state before switching | | ||
| | Connections drop during switch | Long-running requests on old upstream | API7 EE handles in-flight requests gracefully; existing connections complete | | ||
| | 502 after switch | New environment not ready | Test health endpoint before switching; roll back if needed | | ||
| | Traffic still going to old env | Route update has not propagated yet | Verify with `a7 route get api -o json` and retry after propagation | |
There was a problem hiding this comment.
The troubleshooting suggestion a7 route get api -o json omits --gateway-group/-g, but a7 route get errors if no default gateway group is set in the user's context. Consider including --gateway-group default (or explicitly stating that a default gateway group must be configured) so the command works when copied as-is.
| | Traffic still going to old env | Route update has not propagated yet | Verify with `a7 route get api -o json` and retry after propagation | | |
| | Traffic still going to old env | Route update has not propagated yet | Verify with `a7 route get api --gateway-group "$GROUP" -o json` and retry after propagation | |
| | Canary not receiving traffic | Match condition never true | Check header/cookie name and `a7 route get` output | | ||
| | Rollback not instant | Config has not propagated yet | Verify with `a7 route get` and retry after propagation | |
There was a problem hiding this comment.
The troubleshooting rows that suggest verifying with a7 route get don’t include --gateway-group/-g. Since the CLI requires a gateway group (unless a default is configured in context), consider adding the gateway group flag here as well to avoid copy/paste failures.
| | Canary not receiving traffic | Match condition never true | Check header/cookie name and `a7 route get` output | | |
| | Rollback not instant | Config has not propagated yet | Verify with `a7 route get` and retry after propagation | | |
| | Canary not receiving traffic | Match condition never true | Check header/cookie name and `a7 route get --gateway-group default` output | | |
| | Rollback not instant | Config has not propagated yet | Verify with `a7 route get --gateway-group default` and retry after propagation | |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Summary
a7 upstreamresources.a7 service createplus routeservice_idfor default routing.servicesand routepaths/service_id.Validation
make validate-skillsmake test-skillsgit diff --checkSummary by CodeRabbit