Source

This page is generated from devops-agent/eks-ingress-migration/references/ingress-resources.md. Edit the source, not this page.

Ingress Resource Analysis

Rating model: Express every finding as Impact 0–5 using the Impact Indicator rubric, weighing three dimensions in priority order: (1) business logic / revenue — the live traffic at stake · (2) security / reputation · (3) effort to remediate. Effort is NOT a severity driver — a fix being easy or hard never moves the score (it depends on who implements it). Presence is decided by estate state — absent controller / empty estate / orphaned dead config = non-event (0); a broken controller is tech debt (1) with zero bound routes or a suspected active outage (flagged outside the score) with bound routes; a running controller with a control-plane CVE counts even at zero routes. See ingress-discovery.md for the full presence/stacking rules. Band mapping is a starting point — 🟢 0 / 🟡 1–2 / 🟠 3–4 / 🔴 5 — but the Impact Indicator criteria set the final score (e.g. an easy-to-deploy prerequisite stays 🟡 low even if it blocks a path). All checks are read-only (Kubernetes API get/list, AWS Describe/List).

Purpose

Analyze existing Ingress resources to determine what must be converted to HTTPRoute and identify conversion complexity.

Checks to Execute

3.1 — Annotation Inventory & Gateway API Mapping

What to check:

• All annotations on every Ingress resource
• Which annotations have direct HTTPRoute equivalents
• Which require Gateway-level config, policy attachments, or AWS service substitution
• Which have no Gateway API equivalent (blockers)

How to check:

1. List all Ingress resources across all namespaces
2. For each, extract all annotations
3. Map each annotation to its Gateway API equivalent:

Annotation mapping to Gateway API:

Current Annotation	Gateway API Equivalent
nginx.ingress.kubernetes.io/rewrite-target	HTTPRoute filters[].urlRewrite
nginx.ingress.kubernetes.io/ssl-redirect	Gateway listener tls config
nginx.ingress.kubernetes.io/cors-*	No native equivalent — use AWS WAF or application-level
nginx.ingress.kubernetes.io/auth-url	No native equivalent — use ALB + Cognito/OIDC via ListenerRuleConfiguration.authenticateOIDCConfig
nginx.ingress.kubernetes.io/canary-*	HTTPRoute backendRefs[].weight (traffic splitting)
nginx.ingress.kubernetes.io/affinity	No native equivalent — use TargetGroupConfiguration target-group attributes
nginx.ingress.kubernetes.io/configuration-snippet	❌ No equivalent — redesign needed
nginx.ingress.kubernetes.io/server-snippet	❌ No equivalent — redesign needed
nginx.ingress.kubernetes.io/lua-resty-waf	❌ No equivalent — use AWS WAF
alb.ingress.kubernetes.io/scheme	LoadBalancerConfiguration spec.scheme — defaults to internal, so it must be set explicitly for a public ALB
alb.ingress.kubernetes.io/certificate-arn	LoadBalancerConfiguration spec.listenerConfigurations[].defaultCertificate (ACM ARN) — not the listener's tls.certificateRefs
alb.ingress.kubernetes.io/actions.*	HTTPRoute filters + backendRefs

alb.ingress.kubernetes.io/* annotations do not work on a Gateway. Their documented location is Ingress and Service only. On the Gateway API path the load balancer is configured through the LBC's own CRDs — LoadBalancerConfiguration (scheme, listeners, certificates, SSL policy, security groups), TargetGroupConfiguration (target type, health checks, target-group attributes) and ListenerRuleConfiguration (per-rule actions such as OIDC auth) — attached to the Gateway via spec.infrastructure.parametersRef. An annotation carried over from the Ingress is silently ignored, so the defaults apply: internal scheme and no certificate.

Impact (per Impact Indicator):

• 🟡 1–2 (Low): All annotations map to HTTPRoute features or the LBC Gateway configuration CRDs (LoadBalancerConfiguration / TargetGroupConfiguration / ListenerRuleConfiguration, attached via spec.infrastructure.parametersRef). Note this is not "maps to a Gateway annotation": alb.ingress.kubernetes.io/* annotations are ignored on a Gateway (see above).
• 🟠 3–4 (Medium): Most map cleanly, some need AWS service substitution (WAF, Cognito)
• 🔴 5 (High): Heavy use of nginx snippets/lua with no Gateway API equivalent
• ⬜ Unknown: Cannot parse annotations

3.2 — TLS Configuration

What to check:

• Ingress TLS sections (spec.tls)
• TLS termination strategy
• Certificate sources (K8s Secrets vs ACM)

How to check:

1. For each Ingress, check spec.tls entries
2. Check for ACM certificate ARN annotations
3. Check for SSL passthrough annotations

Gateway API TLS model:

• TLS termination is configured on the Gateway listener (tls.mode: Terminate), not on HTTPRoute
• ACM certificates: set on LoadBalancerConfiguration spec.listenerConfigurations[].defaultCertificate (plus certificates for SNI extras), or discovered from the listener hostname
• K8s Secret certs have no Gateway path on LBC — tls.certificateRefs is not supported on a Gateway listener, so a Secret-based cert must first be imported into ACM. This is a migration task, not a reference change; do not plan for a certificateRefs carry-over.
• SSL passthrough: use TLSRoute (not HTTPRoute)

Impact (per Impact Indicator):

• 🟡 1–2 (Low): Edge termination with ACM — maps directly to Gateway listener
• 🟠 3–4 (Medium): Using K8s Secrets — need cert-manager Gateway integration or migrate to ACM
• 🔴 5 (High): SSL passthrough required — needs TLSRoute, which is in the standard channel (graduated to v1 in Gateway API v1.5.0), so both CRD versions this skill pins (v1.5.0 / v1.6.0) carry it without an experimental install. The Impact is driven by the re-architecture, not by CRD availability.
• ⬜ Unknown: Cannot determine TLS configuration

Cutover-risk caveat — the migration action is not Low. Moving the cert store (K8s Secret → ACM) at the same time as the routing/class change risks SSL/TLS handshake failures or downtime if DNS lags or ACM domain validation hasn't completed. The "if-left-as-is" Impact may be low (the app serves TLS today), but the remediation step must be rated ≥ Medium and sequenced: (1) request/validate the ACM cert to ISSUED first, (2) keep the existing NGINX path live, (3) switch class / cut over DNS only after the new ALB + cert are verified. Never bundle "migrate TLS to ACM" into a Low/one-step task.

3.3 — Backend Service Compatibility

What to check:

• All backend services referenced by Ingress resources exist and are healthy
• Service types (ClusterIP preferred for Gateway API with IP target mode)
• Cross-namespace backends (need ReferenceGrant in Gateway API)

How to check:

1. For each Ingress, extract backend service references
2. Verify each Service exists with healthy endpoints
3. Flag any cross-namespace references — these need ReferenceGrant resources

Impact (per Impact Indicator):

• 🟡 1–2 (Low): All backends healthy, same-namespace, ClusterIP
• 🟠 3–4 (Medium): Some cross-namespace backends (need ReferenceGrant) or NodePort services
• 🔴 5 (High): Missing backends or services with no endpoints
• ⬜ Unknown: Cannot verify endpoint health

Routing data to collect: Record every Ingress→backend mapping in the Routing Topology table.