Migrate egress controls from sidecar to ambient

Map sidecar egress patterns to their ambient equivalents when migrating workloads to an ambient mesh.

Sidecar and ambient meshes enforce egress controls differently. To migrate without losing coverage, review the following mappings of common sidecar egress patterns to their ambient equivalents. For more information about migration, see Migrate from a sidecar mesh.

Behavioral differences

Before migrating, review the following behavioral changes that affect egress configuration in an ambient mesh.

outboundTrafficPolicy: REGISTRY_ONLY is not enforced in ambient

In sidecar mode, setting outboundTrafficPolicy: REGISTRY_ONLY in MeshConfig blocks traffic from sidecar proxies to any external destination not registered in the service registry. In an ambient mesh, ztunnel does not read outboundTrafficPolicy. Traffic to unregistered destinations passes through by default.

exportTo is not supported in ambient

In sidecar mode, exportTo: ["."] on a ServiceEntry limits its visibility to the originating namespace. Workloads in other namespaces cannot resolve or route to that service entry.

In ambient mode, exportTo is ignored. All ServiceEntry resources are globally visible regardless of the exportTo field. Namespace-scoped access control must be expressed through AuthorizationPolicy resources that target the ServiceEntry or the egress gateway.

Sidecar egress gateways require reconfiguration

Sidecar egress gateways use VirtualService and DestinationRule to steer traffic through an Envoy-based gateway deployment. In ambient mode, the same Envoy-based gateway can serve as an L7 egress waypoint, but the binding mechanism changes: instead of a VirtualService route, you add istio.io/use-waypoint and istio.io/use-waypoint-namespace labels to the ServiceEntry that registers the external destination. Ztunnel routes matched traffic to the gateway automatically without a VirtualService.

Migration paths

Choose the path that matches your current sidecar egress configuration. Some migrations require more than one path.

To identify your patterns, check your MeshConfig for outboundTrafficPolicy, your VirtualService and DestinationRule resources for external destinations, and your ServiceEntry resources for exportTo fields.

Migrate from sidecar egress gateways

If you use a sidecar-based egress gateway with VirtualService and DestinationRule routing, choose the ambient egress approach that matches your enforcement requirements.

The key configuration change in both cases is the binding mechanism. In sidecar mode, a VirtualService routes traffic from the source sidecar to the egress gateway. In ambient mode, you add istio.io/use-waypoint and istio.io/use-waypoint-namespace labels to the ServiceEntry that registers the external destination. Ztunnel routes matched traffic to the gateway automatically without a VirtualService.

To migrate from an existing sidecar egress gateway:

1. Create a ServiceEntry for each external destination, adding istio.io/use-waypoint labels to bind it to the ambient egress gateway. For L7 waypoint egress, the gateway uses the istio-waypoint GatewayClass.

2. Apply AuthorizationPolicy resources targeting the ServiceEntry and the egress Gateway to control which source namespaces and service accounts can use each external service. DestinationRule resources remain valid in ambient for TLS origination when using L7 waypoint egress.

3. Verify that ambient-enrolled workloads are routing correctly through the new gateway.

4. Remove the VirtualService resources that previously routed traffic through the sidecar egress gateway. Removing the VirtualService after the ambient binding is in place avoids a routing gap where sidecar workloads lose their egress route before the ambient path is established.

Migrate from exportTo-scoped ServiceEntries

In sidecar mode, a team might publish a ServiceEntry with exportTo: ["."] to limit visibility to their own namespace and prevent other teams from routing to the same external host. In ambient mode, exportTo is not enforced. Replace exportTo namespace scoping with AuthorizationPolicy.

Sidecar pattern of namespace-scoped ServiceEntry:

apiVersion: networking.istio.io/v1
kind: ServiceEntry
metadata:
  name: external-api
  namespace: team-a
spec:
  hosts:
  - api.example.com
  ports:
  - number: 443
    name: https
    protocol: TLS
  resolution: DNS
  location: MESH_EXTERNAL
  exportTo:
  - "."

Ambient equivalent of global ServiceEntry with AuthorizationPolicy scoping:

apiVersion: networking.istio.io/v1
kind: ServiceEntry
metadata:
  name: external-api
  namespace: team-a
  labels:
    istio.io/use-waypoint: egress-waypoint
    istio.io/use-waypoint-namespace: istio-egress
spec:
  hosts:
  - api.example.com
  ports:
  - number: 443
    name: https
    protocol: TLS
  resolution: DNS
  location: MESH_EXTERNAL
---
apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: allow-team-a-to-external-api
  namespace: team-a
spec:
  targetRefs:
  - kind: ServiceEntry
    group: networking.istio.io
    name: external-api
  action: ALLOW
  rules:
  - from:
    - source:
        namespaces: ["team-a"]

The AuthorizationPolicy denies all namespaces except team-a from reaching api.example.com through this ServiceEntry. Because the ServiceEntry is in the team-a namespace, workloads in other namespaces cannot resolve it through the gateway without an explicit ALLOW policy.