What breaks when teams migrate Ingress traffic without a clear path for annotations and custom plugin configuration?

Why Ingress Migrations Break When Behavior Lives in Annotations

Ingress migrations are rarely just a syntax change. They often move teams from controller-specific annotations and embedded plugin logic into a gateway model that is stricter about where policy, routing, and extensibility live. If that translation step is skipped, the migration can silently drop security controls, alter request handling, or leave old behavior half-applied in the new path. The result is not only broken traffic flow but also broken trust in what the platform is actually enforcing.

For teams that have treated annotations as a convenient place to hold exceptions, the migration exposes how much routing intent was never documented outside the controller. That matters because annotation-driven behavior can include auth bypasses, header rewriting, rate limits, retries, and custom filters that are easy to overlook during cutover. In practice, many platform teams discover the hidden dependency only after traffic has already shifted and users begin seeing inconsistent behavior.

How the Failure Shows Up During Cutover

The core issue is that annotations are often controller-specific, while gateway migrations expect those behaviors to be expressed through a different configuration model. When the target platform does not support a one-to-one equivalent, teams have to decide whether a setting should become a route policy, a listener rule, a plugin, or a separate service control. That mapping is where migrations succeed or fail.

Common breakpoints include:

• Security annotations that never get re-implemented, so requests reach services without the intended checks.
• Custom plugin hooks that were attached to the old ingress controller but have no direct target in the gateway.
• Header, path, or rewrite rules that behave differently once they are expressed through a new processing chain.
• Conflicting defaults, where the new gateway applies a baseline policy that does not match the old ingress behavior.

This is why migration planning has to focus on behavior, not just configuration syntax. Teams need a complete inventory of every annotation, custom filter, and controller extension, then a documented mapping to the destination platform. When the old setup used unofficial conventions or relied on plugin order, the migration can also expose hidden coupling between policy and application design. For a useful reference on how machine-managed configuration and trust boundaries can become brittle when identity-bearing controls are scattered, see the OWASP Non-Human Identity Top 10.

The guidance breaks down when the source environment depends on controller-specific behavior that has no supported equivalent in the target gateway, because at that point the choice is redesign, not translation.

Where Teams Need to Draw the Line on Annotations and Plugins

Tighter migration discipline often increases short-term effort, requiring teams to balance faster cutover against faithful policy preservation.

One real edge case is when an annotation was never meant to be portable in the first place. Some annotations are operational shortcuts, not durable policy definitions, and those should be retired rather than recreated. The hard part is distinguishing tolerated drift from intentional exception handling. Where there is no clean equivalent, teams should treat the gap as a design decision, not a missed translation.

Another edge case appears when custom plugin logic performed multiple jobs at once, such as routing plus auth plus observability. Gateway platforms often separate those concerns, so a single old plugin may need to become several controls or be replaced by a service-side capability. That is normal, but it means migration scope can expand quickly if teams do not classify each behavior by function and owner.

There is no consensus that every annotation should survive migration. The better rule is to preserve only the behaviors that still make architectural sense and can be enforced consistently in the new model. Everything else should be redesigned, removed, or explicitly accepted as changed behavior.

Practitioner Guidance

What to prioritise: Build a control inventory before you move traffic. The highest-value question is not “does the route exist?” but “which behaviors disappear if this annotation is not translated?” That inventory should include policy, rewriting, auth, custom filters, and any controller-specific extension points.

Decision rule: If a behavior cannot be expressed cleanly in the target gateway model, do not assume the migration is still safe just because traffic routes successfully. Treat that as a functional control gap and decide whether to redesign, replace, or decommission the behavior.

What good looks like: The migrated path should produce the same observable policy outcome as the old path for the same request pattern, or a deliberately documented change. If operators cannot explain the difference in enforcement before cutover, they do not yet understand the migration well enough to trust it.

Practitioner takeaway: The migration risk is not the loss of YAML syntax, but the loss of hidden routing intent that was never separated from the old ingress controller in the first place.

Related resources from NHI Mgmt Group

• How should teams migrate from Ingress NGINX to Gateway API without breaking existing traffic?
• How should teams migrate ingress-nginx without breaking access policies?
• What breaks when security teams rely on MDR without clear identity ownership?
• What breaks when SOC teams rely on agentic AI without clear authority boundaries?