Migrate ALB-served Ingress and ALB Rules to Gateway API
TOC
OverviewMigration modelStep 1: Inventory the existing configurationStep 2: Create or select a GatewayStep 3: Convert ALB-served Ingress to HTTPRouteStep 4: Convert ALB RulesMatch conditionsBackends and weightsRewritesRequest and response headersDynamic header values from nginx variablesRedirectsCORSTimeoutsSession affinityHTTPS backendsStep 5: Handle behavior that has no direct conversionMigrate L4 trafficStep 6: Validate before cutoverStep 7: Cut over and roll backListener limits and large ALB migrationsExceed 63 listeners with ListenerSetShare a VIP across GatewaysRelated documentationOverview
ALB is deprecated. Envoy Gateway (Gateway API) and Ingress NGINX are the recommended ingress controllers. New ALB instances cannot be created, and ALB is no longer available in the Web Console. Existing ALB instances in a cluster upgraded from an earlier version keep running so that their traffic can be migrated. This guide describes how to migrate L7 HTTP/HTTPS traffic from ALB to Gateway API managed by Envoy Gateway.
Plan the migration on the target ACP release, not on the source release, because Gateway API CRDs and Envoy Gateway capabilities differ between releases. See Gateway API CRD versions.
ALB receives L7 traffic in two forms. Identify which form a workload uses before you start:
Gateway API is a new configuration model. It does not provide runtime compatibility for ALB rules, Ingress annotations, or ALB dslx expressions. Migration means creating equivalent Gateway, HTTPRoute, and policy resources, validating them, and then moving traffic.
ALB is deprecated. Use Ingress NGINX Operator only when an application requires Ingress-specific behavior that Gateway API cannot represent. For new L7 traffic, use Envoy Gateway and Gateway API.
This guide covers L7 HTTP/HTTPS traffic. For ALB TCP/UDP frontends and rules, see Migrate L4 traffic and evaluate TCPRoute/UDPRoute support in the installed Envoy Gateway version.
Migration model
Step 1: Inventory the existing configuration
Export the ALB objects and the Ingress resources:
For a first-pass conversion of the exported ALB2, Frontend, Rule, related Namespace, and source Ingress YAML, see the ALB2/Frontend/Rule to Gateway API migration helper. The helper produces Gateway API YAML plus a conversion report. Treat its output as a first-pass draft: it does not apply resources, and every warning and gap in its report must be reviewed against this guide before cutover.
Find generated rules and their source Ingress:
For every source object, record:
- frontend port and protocol, and the certificate Secret;
- hostnames, path matches, and ALB rule priority;
- backend Service, port, weight, protocol (HTTP, HTTPS, or gRPC), and upstream Host override (
vhost); - rewrites, request and response header changes, redirects, CORS, and timeouts;
- session affinity and load-balancing method;
- Ingress annotations and Rule annotations.
The Rule spec is a useful starting point for the field mapping: dslx describes matches, serviceGroup describes backends, and config, rewrite_base, rewrite_target, certificate_name, and backendProtocol describe actions. The generated dslx also shows how ALB interpreted each Ingress path (STARTS_WITH or REGEX), which determines whether the HTTPRoute needs PathPrefix or RegularExpression.
Step 2: Create or select a Gateway
Create a Gateway with one listener per ALB frontend port. ACP recommends one dedicated EnvoyProxy per Gateway; this is also what the Web Console creates by default. See EnvoyProxy (Deployment Configuration) and reference that EnvoyProxy from Gateway.spec.infrastructure.parametersRef. The following example terminates TLS and exposes HTTP and HTTPS:
Replace envoy-gateway-operator-cpaas-default with the GatewayClass created by your EnvoyGatewayCtl.
A listener without hostname accepts every hostname on that port. Put hostnames in HTTPRoute.spec.hostnames unless you need a different certificate per hostname. If one HTTPS port serves several certificates, list all certificate Secrets in tls.certificateRefs and let Envoy Gateway select the certificate by SNI.
Use allowedRoutes deliberately. from: Same restricts routes to the Gateway namespace; from: All permits routes from every namespace; from: Selector permits only namespaces matching the selector. If a certificate Secret is in another namespace, create a ReferenceGrant in that namespace.
allowedRoutes is also the recommended way to preserve ALB project assignment and port-project isolation. Use one listener per project port and set the listener's allowedRoutes to the project namespace (from: Same when the Gateway is in that namespace), a project label selector (from: Selector), or from: All only for intentionally shared listeners.
Confirm that the Gateway has been programmed before creating routes:
The Gateway should report Programmed=True and its status should contain an address that clients can reach.
Most ALB instances expose fewer than 63 ports. If the source ALB exposes more than 63 ports, see Listener limits and large ALB migrations at the end of this guide.
Step 3: Convert ALB-served Ingress to HTTPRoute
When the source is an Ingress served by ALB, migrate the Ingress. The generated Rule resources are recreated by the ALB controller and are not a stable migration input.
An Ingress with a host, prefix path, and Service backend can be represented as follows:
The conversion rules are:
- map
spec.rules[].hosttohostnames; - map
pathType: PrefixtoPathPrefixandpathType: ExacttoExact; - for
pathType: ImplementationSpecific, inspect the generated Ruledslx. ALB usesSTARTS_WITHwhen the path has no regex metacharacters andREGEXotherwise. Map a plain path toPathPrefixand a regex path toRegularExpression; - ALB regexes are search or prefix matches, while Envoy Gateway
RegularExpressionmust match the whole path. Append.*or(/.*)?unless the original pattern ends with$; PathPrefixmatches path elements:/v1matches/v1and/v1/...but not/v1beta, while ALBSTARTS_WITH /v1also matches/v1beta;- map the Ingress backend Service and port to
backendRefs; - replace
ingressClassNamewith the appropriateparentRefsand listenersectionName; - keep one source Ingress as one
HTTPRoutewhere possible, with one rule for each path; - split a route only when a policy or compatibility behavior needs a narrower attachment scope.
Keep Ingress annotations at the same scope after migration. An annotation on the Ingress applies to the whole Ingress; an HTTPRoute filter can apply to a single rule, a whole route, or the Gateway. Do not copy every Ingress annotation to every HTTPRoute rule.
Read Configure Gateway API Route for route attachment and match behavior.
Step 4: Convert ALB Rules
For a Rule created directly, map each part of the Rule spec to an HTTPRoute.
Match conditions
dslx entries of different types are combined with AND. Multiple values inside one entry are combined with OR.
ALB reads X-Real-IP first, then the leftmost X-Forwarded-For entry, then the peer address. Envoy Gateway supports one of customHeader (for X-Real-IP) or xForwardedFor with numTrustedHops counted from the right. ClientTrafficPolicy applies to the whole Gateway or listener, not to a single route. Do not trust a client-supplied leftmost X-Forwarded-For value for an allowlist.
For example, a rule that matches api.example.com/v1 and forwards to api:8080 becomes:
When one ALB rule contains several URL values, create one matches[] entry for each value. When one rule combines several types, put all conditions of one combination into the same match.
ALB rule priority has no direct Gateway API field. Do not rely on the order of rules in a YAML file. Make overlapping routes unambiguous: use Exact for the route that must win, and keep broader prefix or regex routes from capturing the same request. EnvoyProxy.spec.preserveRouteOrder can preserve rule order for the whole Gateway as a last resort, but it changes precedence for every route on that Gateway; use it only when match specificity cannot express the original priority.
Backends and weights
Map serviceGroup.services to backendRefs and preserve the weights:
When the backend Service is in another namespace, add a ReferenceGrant in the backend namespace.
Rewrites
ALB rewrite_base and rewrite_target are a regex match and substitution pair. Standard Gateway API URLRewrite only supports ReplaceFullPath and ReplacePrefixMatch; it cannot express regex capture groups.
For a simple prefix rewrite, use the standard filter:
For a rule that depends on capture groups, use an Envoy Gateway HTTPRouteFilter with ReplaceRegexMatch:
Check the following when converting a rewrite:
- Only add a rewrite filter to rules that actually change the path. A no-op rewrite such as
^/(console-portal)(/|$)(.*)$to/$1$2$3is unnecessary; HTTPRoute forwards the original path when no rewrite is configured. - Use a strict boundary such as
(/|$)instead of(.|$). A pattern such asbusiness-1(.|$)can also matchbusiness-10. - Do not treat an ALB wildcard path as a regex.
/dex/*becomesPathPrefix /dex/, not a regular expression. - Convert nginx regexes to RE2 carefully. Capture references and lookarounds may need a different expression.
Request and response headers
Use RequestHeaderModifier and ResponseHeaderModifier for static header changes:
An ALB rewrite-response uses ngx.header[key] = value, which replaces the header. Use set, not add, when that behavior matters.
If the same response headers apply to every Ingress behind the Gateway, a Gateway-level ClientTrafficPolicy with lateResponseHeaders avoids duplicating the filter on every route:
Use a Gateway-level policy only when every route needs the same headers. If different Ingress resources set different values, attach the policy or filter to the affected routes.
Dynamic header values from nginx variables
ALB rewrite-request also supports headers_var and headers_add_var. Their values are nginx variables, not static strings:
A standard RequestHeaderModifier cannot evaluate an nginx variable because it only sets static values. For this pattern, use an EnvoyExtensionPolicy with a Lua filter that reads the request, extracts the value, and sets the target header. The following example copies the HTTP method into the X-Original-Method header:
Attach the policy only to the routes that need the dynamic header; attaching it to the whole Gateway changes unrelated applications. Use handle:headers():replace(...) for headers_var, which replaces the header, and handle:headers():add(...) for headers_add_var, which appends. If the value is static, use RequestHeaderModifier instead of Lua.
Redirects
Do not migrate an ALB redirect rule as a normal backend route. ALB redirect rules often point at a placeholder backend such as none:8080; keeping that backend produces an Envoy 500 error and hides the real path.
Use the standard RequestRedirect filter:
Check that the redirect route does not shadow an existing application route. A catch-all PathPrefix / redirect must not be attached to a listener that also serves real application routes.
CORS
ALB enableCORS, corsAllowOrigin, and corsAllowHeaders can be mapped to SecurityPolicy.spec.cors or the route-level CORS filter:
Split comma-separated ALB origin and header lists into separate list items. Envoy Gateway origins support exact values, a single wildcard label, and a global *; they do not support an arbitrary regex or a value that reflects the request origin dynamically. An ALB origin with a wildcard port, such as http://172.21.4.4:*, needs an explicit port. If the ALB used $http_origin, verify the resulting behavior or change the application.
Timeouts
ALB timeouts are configured in .spec.config.timeout:
For a per-route timeout, use the standard HTTPRoute fields:
For a timeout that applies to every route on a Gateway, use BackendTrafficPolicy or ClientTrafficPolicy. Do not set both a route timeout and a conflicting policy timeout without checking which one takes effect.
Session affinity
ALB session_affinity_policy does not map to a single field. Choose the equivalent explicitly:
-
For cookie-based affinity, use
HTTPRoute.spec.rules[].sessionPersistence: -
For header-based affinity, use a
BackendTrafficPolicywith consistent hashing on the client-supplied header. Do not usesessionPersistence.type: Header: it makes the gateway write an encoded upstream address into the response header, while ALB hashes the value the client already sends. -
For source-IP hash (ALB
sip-hash), use aBackendTrafficPolicywith consistent hashing:
Validate the affinity behavior with a real client. The hash input and the cookie behavior are not identical between ALB and Envoy Gateway.
HTTPS backends
HTTPRoute uses HTTP when it forwards to a Service unless a backend TLS policy is configured. If the ALB rule has backendProtocol: https, create a BackendTLSPolicy:
targetRefs.sectionName must be the actual Service port name, not the port number. validation.hostname must match a SAN in the backend certificate; it is not always the Service name. If the backend uses a private CA, reference the appropriate Secret or ConfigMap instead of wellKnownCACertificates. ACP 4.3 and later serve BackendTLSPolicy v1; ACP 4.2 serves v1alpha3, which uses the same targetRefs and validation fields, so change only the apiVersion; ACP 4.1 and earlier use the older v1alpha2 schema with targetRef (singular) and tls.*.
Step 5: Handle behavior that has no direct conversion
ALB rewrite-request and rewrite-response are covered by RequestHeaderModifier and ResponseHeaderModifier for static values, and by EnvoyExtensionPolicy with Lua for headers_var and headers_add_var. Do not mark a route migrated until each of the remaining behaviors has an explicit replacement or an accepted product limitation:
- regex rewrites and
ImplementationSpecificpaths that depend on PCRE features not available in RE2; - custom load-balancing algorithms such as EWMA;
- WAF features not provided by the installed Envoy Gateway policy;
SRC_IPused as a routing condition to select different backends;- redirects whose target depends on dynamic nginx variables;
- ALB session affinity that must be preserved bit-for-bit.
ALB project assignment and port-project isolation do not have a direct HTTPRoute field. Use Gateway.spec.listeners[].allowedRoutes.namespaces to preserve them: from: Same limits routes to the Gateway namespace, from: Selector matches project namespaces by label, and from: All permits every namespace. Apply this per listener so that a project can only attach routes to the listeners that belong to it. Confirm the required isolation behavior before removing the ALB.
Migrate L4 traffic
ALB TCP and UDP frontends are not migrated with HTTPRoute. A directly created L4 Frontend can carry its own spec.serviceGroup instead of a separate Rule. For each L4 frontend, its embedded serviceGroup, and any directly created Rule, evaluate:
- a
LoadBalancerService when the traffic does not need Gateway API routing; TCPRouteorUDPRoutewhen the installed Envoy Gateway version supports the route type;- keeping ALB for the L4 ports if the installed version does not support the required route type.
Map the Frontend or Rule serviceGroup.services to the TCPRoute or UDPRoute backendRefs. Do not create an HTTPRoute for a TCP or UDP frontend. Check the backend port and the session-affinity behavior separately; ALB sip-hash on an L4 rule is not the same as HTTP session persistence.
Step 6: Validate before cutover
Apply the new resources without deleting the old ones:
Check status at every layer:
Verify all of the following:
- The Gateway reports
Programmed=True. - Each HTTPRoute has
Accepted=TrueandResolvedRefs=Trueunderstatus.parents. - Each referenced Service, Secret, policy, and extension resource is resolved.
- HTTP and HTTPS requests return the expected status, headers, redirects, and response body.
- Regex paths, rewritten paths, session persistence, CORS, authentication, and backend TLS work as expected.
- The test hostname reaches the new Gateway address and does not reach the old ALB.
- Response time, error rate, and throughput are acceptable for the workload.
Use curl with an explicit Host header when testing before DNS changes:
Some applications do not support HEAD; use a real GET request for the final functional check.
Step 7: Cut over and roll back
After validation, move traffic in a controlled way:
- Lower the DNS TTL before the change.
- Point a test or small traffic slice at the Gateway address.
- Monitor request errors, latency, backend health, and Gateway/HTTPRoute status.
- Update the production DNS record or external load-balancer target.
- Keep the old ALB or Ingress configuration available during the observation window.
If the new path fails, restore DNS or the external load-balancer target to the old address, then inspect the route and policy status before retrying. Do not scale down or delete the old ALB until the rollback window has ended and the new path has passed the agreed monitoring period.
Listener limits and large ALB migrations
Most ALB instances expose fewer than 63 ports and do not need this section. Use it only when the source ALB has a large number of listeners.
Listener limits depend on the ACP release. ACP supports up to 63 listeners per Gateway and per ListenerSet. When the source ALB exposes more ports than one object can hold, use ListenerSets or split the listeners across Gateways.
The 63-listener limit is per Gateway and per ListenerSet, not per cluster. Multiple ListenerSets can attach to the same Gateway. On ACP 4.4, the migration is fully supported through YAML; the missing Web Console support only affects how you create and review ListenerSets.
For the current ListenerSet procedure, see Configure Gateway API ListenerSet. For the CRD version installed by each release, see Gateway API CRD versions.
Exceed 63 listeners with ListenerSet
If one ALB exposes more than 63 ports, keep the first 63 listeners on the Gateway and create a ListenerSet for the additional ports. The parent Gateway must allow ListenerSets. The following example shows only the http listener and the new allowedListeners field; add allowedListeners to the Gateway from Step 2 instead of replacing its full listener list. It reuses the EnvoyProxy from Step 2:
Attach a Route to a ListenerSet listener by setting parentRefs[].kind: ListenerSet and sectionName to the listener name. For the complete procedure, see Configure Gateway API ListenerSet.
On ACP 4.4, create and edit ListenerSets through YAML. In ACP 4.5 and later, the Web Console also provides the ListenerSet creation page.
Share a VIP across Gateways
On releases without ListenerSet, or when you prefer not to use ListenerSet, you can split the listeners across multiple Gateways and use MetalLB IP sharing to expose all of them through one VIP. Each Gateway still has its own EnvoyProxy and its own Envoy data-plane Service.
This is a workaround, not the default migration path. Prefer ListenerSet when it is available.
The following example creates two Gateways that share one VIP:
Create gw-b the same way, with its own EnvoyProxy, the same allow-shared-ip key and VIP, and a different listener port:
Use the following rules:
- Every Gateway must have its own
EnvoyProxyand data-plane Service. Do not try to put listeners from different Gateways into one Service. - Set
externalTrafficPolicy: Clusteron every Service that shares the VIP. WithLocal, MetalLB's sharing backend key includes the Service selector; each Gateway has its own selector, so the second Service stays<pending>with a backend-key mismatch.Localcan also drop traffic on nodes without a local endpoint. - The ports of the Services that share the VIP must not overlap. MetalLB checks the
protocol/portpair: two Services cannot both exposeTCP/8080on the same VIP. If two Gateways must serve the same port, this workaround does not apply; use one listener withHTTPRoutehostnames, or use ListenerSet. - Set
IPAddressPool.spec.autoAssign: falseand request the VIP explicitly withmetallb.io/loadBalancerIPs. WithautoAssign: true, an unrelated pendingLoadBalancerService can take the VIP first. - Set the annotations through
EnvoyProxy.spec.provider.kubernetes.envoyService.annotations, not by editing the Envoy data-plane Service directly; the operator reconciles the Service. - Do not use
Gateway.spec.addressesto pin the VIP. Envoy Gateway maps that field toService.spec.externalIPs, not to the MetalLB load balancer IP.
MetalLB 0.15 also accepts the deprecated metallb.universe.tf/ prefix. Use the prefix that your MetalLB version documents; do not mix prefixes for the same annotation.
externalTrafficPolicy: Cluster can lose the original client source IP because kube-proxy may SNAT the connection. ClientTrafficPolicy.clientIPDetection can only read an address that an upstream load balancer or proxy has already put into X-Forwarded-For, a custom header, or the PROXY protocol; it cannot recover an address that was SNATed away. If the application depends on the client IP, keep a single Gateway with ListenerSet and Local, or make sure an upstream device adds one of those headers. This also affects ConsistentHash: SourceIP and source-IP authorization, which will see the node or proxy IP instead of the client.
Verify that both Services received the same VIP and that both Gateways are programmed:
The Envoy data-plane Service is created in the namespace of the EnvoyGatewayCtl, not necessarily in the Gateway namespace.
If one Service stays in <pending>, check the MetalLB controller events for an allocation failure. A port conflict reports port TCP/<port> is already in use on "<vip>"; a Local sharing conflict reports a backend-key mismatch.
This workaround does not provide cross-Gateway health checking or failover. Each Gateway is an independent data plane; monitor each Gateway and its own backend health.
Related documentation
- Configure Gateway API Gateway
- Configure Gateway API ListenerSet
- Configure Gateway API Route
- Configure Gateway API Policy
- Tasks for Envoy Gateway
- Configure Ingresses
- Configure ALB
- Migrate from OCP Route to Gateway API Route
- ALB2/Frontend/Rule to Gateway API migration helper
- Gateway API: Migrating from Ingress