Background
Customer report: Zendesk ticket #1187, OLB.
An API7 customer is using ADC in CI/CD to import OpenAPI definitions and sync services/routes. When two different services define routes with the same effective URI, and there is no host or service/path prefix to distinguish them, adc lint and adc sync both succeed. API7 Dashboard then shows two different services/routes with the same route URI, but the data plane can only match one of them, so one route is effectively shadowed.
This is a follow-up to an earlier "Duplicate routes are possible" ticket. Dashboard creation already calls a CP API to check route conflicts, but ADC sync currently does not appear to perform the same validation.
Customer workflow
The customer does not run adc dump in the pipeline, so preserving existing IDs via --with-id is not practical for their normal flow.
Current pipeline:
adc convert openapi --verbose 0 -f api-docs.yml -o apisix-api.yml
# add acl plugin to all routes in apisix-api.yml
# add additional labels to service in apisix-api.yml
adc lint -f apisix-api.yml
adc sync -f apisix-api.yml --label-selector source=OAS3_import,olb.de/api=$CI_PROJECT_PATH_SLUG --include-resource-type service
Reported versions:
- API7 Enterprise:
v3.8.23
- ADC:
0.20.0
Problem
If a service/route is created with the same effective route URI as an existing route under another service, ADC sync succeeds even though the resulting gateway behavior is ambiguous or incorrect.
Example class of collision:
- Service A route:
/v1/customers
- Service B route:
/v1/customers
- No distinct host, service prefix, or other route match condition that makes them unambiguous
Expected by the customer: this should not be deployed silently. They would prefer the sync operation to fail immediately, or at least provide a clear configurable behavior.
Prior art / reference
Kong handles this at the gateway layer with a configurable route_validation_strategy, allowing users to decide how route collisions are handled:
Possible approaches
- Reuse the existing CP route conflict check API from ADC during
sync, especially when creating/updating routes.
- Add ADC-side validation during
lint/sync for duplicate effective route signatures in the local file and/or against remote state.
- Introduce a configurable collision strategy for ADC sync, for example:
- fail on collision
- warn only
- allow existing behavior
- Consider whether this should be solved in gateway/CP instead, similar to Kong's
route_validation_strategy, so all write paths get the same behavior.
Acceptance criteria
- ADC can detect collisions between local routes and existing remote routes that would result in ambiguous data-plane matching.
- The check accounts for the effective route match conditions, not just the URI string, so routes with different hosts/methods/etc. are handled correctly.
adc sync can fail with a clear error message when a collision is detected.- If configurable behavior is added, the default and migration impact are documented.
adc lint behavior is clarified: either local-only collision detection is added, or docs explain that remote collision detection only happens during sync.
Notes
The customer specifically called out that "API management should use host/prefix conventions" is not enough for their case, because developers may independently create valid-looking routes such as /v1/customers in different services. They need tooling to prevent these from being deployed when they would collide at runtime.
Background
Customer report: Zendesk ticket #1187, OLB.
An API7 customer is using ADC in CI/CD to import OpenAPI definitions and sync services/routes. When two different services define routes with the same effective URI, and there is no host or service/path prefix to distinguish them,
adc lintandadc syncboth succeed. API7 Dashboard then shows two different services/routes with the same route URI, but the data plane can only match one of them, so one route is effectively shadowed.This is a follow-up to an earlier "Duplicate routes are possible" ticket. Dashboard creation already calls a CP API to check route conflicts, but ADC sync currently does not appear to perform the same validation.
Customer workflow
The customer does not run
adc dumpin the pipeline, so preserving existing IDs via--with-idis not practical for their normal flow.Current pipeline:
Reported versions:
v3.8.230.20.0Problem
If a service/route is created with the same effective route URI as an existing route under another service, ADC sync succeeds even though the resulting gateway behavior is ambiguous or incorrect.
Example class of collision:
/v1/customers/v1/customersExpected by the customer: this should not be deployed silently. They would prefer the sync operation to fail immediately, or at least provide a clear configurable behavior.
Prior art / reference
Kong handles this at the gateway layer with a configurable
route_validation_strategy, allowing users to decide how route collisions are handled:Possible approaches
sync, especially when creating/updating routes.lint/syncfor duplicate effective route signatures in the local file and/or against remote state.route_validation_strategy, so all write paths get the same behavior.Acceptance criteria
adc synccan fail with a clear error message when a collision is detected.adc lintbehavior is clarified: either local-only collision detection is added, or docs explain that remote collision detection only happens duringsync.Notes
The customer specifically called out that "API management should use host/prefix conventions" is not enough for their case, because developers may independently create valid-looking routes such as
/v1/customersin different services. They need tooling to prevent these from being deployed when they would collide at runtime.