docs: migrate resilience recipes to service model#11
Conversation
|
Warning Rate limit exceeded
To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing. ⌛ 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: Pro Run ID: 📒 Files selected for processing (2)
✨ 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 58 minutes and 50 seconds.Comment |
There was a problem hiding this comment.
Pull request overview
This PR updates the “health check” and “circuit breaker” recipe skills to reflect the current API7 EE runtime model: define upstream + health checks on services, and bind traffic via service-backed routes (service_id), including updated Config Sync examples.
Changes:
- Migrates health-check recipe examples from standalone upstreams to
a7 service create+a7 route createwithservice_id. - Updates circuit-breaker recipe examples to create a service first and apply
api-breakeron a service-backed route. - Updates declarative (Config Sync) YAML examples to use
services+ routepaths/service_id.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| skills/a7-recipe-health-check/SKILL.md | Rewrites examples and Config Sync to use service-owned upstream health checks and service-backed routes. |
| skills/a7-recipe-circuit-breaker/SKILL.md | Reworks circuit breaker workflow to create services first and attach api-breaker to service-backed routes; updates Config Sync accordingly. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ### 3. Passive health check | ||
|
|
||
| ```bash | ||
| # Current a7 does not expose a standalone upstream-health command. | ||
| # Verify the upstream/route wiring and use gateway observability for node state. | ||
| a7 upstream get backend --gateway-group default --output json | ||
| a7 route list --gateway-group default --output json | ||
| ``` | ||
|
|
||
| ## Common Patterns | ||
|
|
||
| ### TCP health check (non-HTTP services) | ||
|
|
||
| ```json | ||
| a7 service create --gateway-group default -f - <<'EOF' | ||
| { | ||
| "checks": { | ||
| "active": { | ||
| "type": "tcp", | ||
| "healthy": { | ||
| "interval": 5, | ||
| "successes": 2 | ||
| }, | ||
| "unhealthy": { | ||
| "interval": 2, | ||
| "tcp_failures": 3, | ||
| "timeouts": 2 | ||
| "id": "backend-passive-service", | ||
| "name": "backend-passive-service", |
There was a problem hiding this comment.
The passive health check example creates backend-passive-service but never attaches a route to it. Because passive checks only evaluate real traffic and health checks generally only run when a service is referenced by at least one route, this example won’t actually demonstrate passive checking unless you also create a route (and send requests) for this service.
| ### 4. Combined active + passive checks | ||
|
|
||
| ```json | ||
| ```bash | ||
| a7 service create --gateway-group default -f - <<'EOF' | ||
| { | ||
| "checks": { | ||
| "active": { | ||
| "type": "http", | ||
| "http_path": "/internal/health", | ||
| "host": "health.internal", | ||
| "req_headers": [ | ||
| "Authorization: Bearer health-check-token", | ||
| "X-Health-Check: true" | ||
| ], | ||
| "healthy": { | ||
| "interval": 10, | ||
| "successes": 2 | ||
| "id": "production-backend-service", | ||
| "name": "production-backend-service", |
There was a problem hiding this comment.
The combined active+passive service (production-backend-service) is created but no runtime route is created/updated to reference it in the step-by-step flow. Since the Troubleshooting section notes health checks won’t run without a referencing route, consider adding a a7 route create (or updating the earlier route) to bind service_id: production-backend-service so the example is runnable end-to-end.
| | All nodes marked unhealthy | Health endpoint returns wrong status code | Verify `http_statuses` includes your health endpoint's response code | | ||
| | Node not recovering | Passive-only: no traffic reaches unhealthy node | Add active health checks for recovery | | ||
| | Probe hitting wrong endpoint | Default `http_path` is `/` | Set `http_path` to your actual health endpoint | | ||
| | Health checks not running | Route does not reference the service | Verify `service_id` with `a7 route get` | |
There was a problem hiding this comment.
The Troubleshooting table suggests verifying service_id with a7 route get, but this recipe otherwise uses a7 route list --service-id ... and doesn’t show route get usage. Consider switching this to a7 route list --service-id <service> (or add the route get example/command to keep the guidance consistent).
| | Health checks not running | Route does not reference the service | Verify `service_id` with `a7 route get` | | |
| | Health checks not running | Route does not reference the service | Verify `service_id` with `a7 route list --service-id <service>` | |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ### 3. Passive health check | ||
|
|
||
| ```bash | ||
| # Current a7 does not expose a standalone upstream-health command. | ||
| # Verify the upstream/route wiring and use gateway observability for node state. | ||
| a7 upstream get backend --gateway-group default --output json | ||
| a7 route list --gateway-group default --output json | ||
| ``` | ||
|
|
||
| ## Common Patterns | ||
|
|
||
| ### TCP health check (non-HTTP services) | ||
|
|
||
| ```json | ||
| a7 service create --gateway-group default -f - <<'EOF' | ||
| { | ||
| "checks": { | ||
| "active": { | ||
| "type": "tcp", | ||
| "healthy": { | ||
| "interval": 5, | ||
| "successes": 2 | ||
| }, | ||
| "unhealthy": { | ||
| "interval": 2, | ||
| "tcp_failures": 3, | ||
| "timeouts": 2 | ||
| "id": "backend-passive-service", | ||
| "name": "backend-passive-service", | ||
| "upstream": { | ||
| "type": "roundrobin", | ||
| "nodes": [ | ||
| {"host": "backend-1", "port": 8080, "weight": 1}, | ||
| {"host": "backend-2", "port": 8080, "weight": 1} | ||
| ], | ||
| "checks": { | ||
| "passive": { | ||
| "type": "http", | ||
| "unhealthy": { | ||
| "http_failures": 3, | ||
| "http_statuses": [500, 502, 503], | ||
| "timeouts": 3 | ||
| }, | ||
| "healthy": { | ||
| "successes": 5, | ||
| "http_statuses": [200, 201, 202, 203, 204] | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| EOF | ||
| ``` |
There was a problem hiding this comment.
The passive health check example creates backend-passive-service but never creates/updates any route that references this service. In API7 EE, passive checks only observe real traffic on routes bound to the service, so as written the check won’t run or won’t see any responses. Add a route (or an update to an existing route) that uses service_id: backend-passive-service, and mention generating traffic to exercise passive checks.
| ### 4. Combined active + passive checks | ||
|
|
||
| ```json | ||
| ```bash | ||
| a7 service create --gateway-group default -f - <<'EOF' | ||
| { | ||
| "checks": { | ||
| "active": { | ||
| "type": "http", | ||
| "http_path": "/internal/health", | ||
| "host": "health.internal", | ||
| "req_headers": [ | ||
| "Authorization: Bearer health-check-token", | ||
| "X-Health-Check: true" | ||
| ], | ||
| "healthy": { | ||
| "interval": 10, | ||
| "successes": 2 | ||
| "id": "production-backend-service", | ||
| "name": "production-backend-service", | ||
| "upstream": { | ||
| "type": "roundrobin", | ||
| "nodes": [ | ||
| {"host": "backend-1", "port": 8080, "weight": 1}, | ||
| {"host": "backend-2", "port": 8080, "weight": 1}, | ||
| {"host": "backend-3", "port": 8080, "weight": 1} | ||
| ], | ||
| "checks": { | ||
| "active": { | ||
| "type": "http", | ||
| "http_path": "/health", | ||
| "healthy": { | ||
| "interval": 5, | ||
| "successes": 2, | ||
| "http_statuses": [200] | ||
| }, | ||
| "unhealthy": { | ||
| "interval": 2, | ||
| "http_failures": 3, | ||
| "timeouts": 2, | ||
| "http_statuses": [500, 502, 503, 504] | ||
| } | ||
| }, | ||
| "unhealthy": { | ||
| "interval": 5, | ||
| "http_failures": 3 | ||
| "passive": { | ||
| "type": "http", | ||
| "unhealthy": { | ||
| "http_failures": 3, | ||
| "http_statuses": [500, 502, 503], | ||
| "timeouts": 3 | ||
| }, | ||
| "healthy": { | ||
| "successes": 3, | ||
| "http_statuses": [200, 201, 204] | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| EOF | ||
| ``` |
There was a problem hiding this comment.
The combined active+passive example creates production-backend-service but doesn’t show any route referencing it. Since health checks are only activated for services that are attached to at least one route, this example is incomplete and may lead readers to think checks should run immediately. Either add a route creation step (or explicitly say to reuse/update the route from step 2 with service_id: production-backend-service).
| Health checks run for upstream nodes that are reachable through active | ||
| configuration. Verify route wiring with: |
There was a problem hiding this comment.
This sentence is misleading/inconsistent with the troubleshooting note below: health checks aren’t gated by nodes being “reachable through active configuration”; they’re triggered by the service being referenced by at least one route (and passive checks additionally require traffic). Consider rephrasing to explicitly tie health-check execution to route→service binding (e.g., “Health checks run only for services that are referenced by at least one route”).
| Health checks run for upstream nodes that are reachable through active | |
| configuration. Verify route wiring with: | |
| Health checks run only for services that are referenced by at least one | |
| route. Verify route wiring with: |
| @@ -151,78 +120,46 @@ a7 route create --gateway-group default -f - <<'EOF' | |||
| }, | |||
| "max_breaker_sec": 60 | |||
| } | |||
| }, | |||
| "upstream": { | |||
| "type": "roundrobin", | |||
| "nodes": { | |||
| "backend:8080": 1 | |||
| } | |||
| } | |||
| } | |||
| EOF | |||
There was a problem hiding this comment.
a7 route update <id> -f performs a full PUT replacement (not a merge/patch). This example only supplies service_id and plugins, so it will likely wipe fields like paths/uri/name, potentially making the route invalid or no longer match any requests. Update the example to send a complete route definition (including existing paths and other required fields), or show a workflow like a7 route get ... --output json → edit → a7 route update ... -f.
Summary
a7 upstreamresources.service_id.api-breakeron service-backed routes.servicesand routepaths/service_id.Validation
make validate-skillsmake test-skillsgit diff --check