For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Run Istio and agentgateway waypoints alongside each other in the same mesh, and migrate services from one to the other using a label flip or a weighted canary.

You can run an Istio waypoint (istio-waypoint GatewayClass) and an agentgateway waypoint (enterprise-agentgateway-waypoint GatewayClass) in the same namespace or mesh without interference. Each service routes exclusively through its own configured waypoint, and policies that are attached to one waypoint do not apply to traffic through the other. Coexistence means that you can migrate services from Istio waypoints to agentgateway waypoints one at a time, without any coupling between them.

Two migration approaches are available:

• Label flip: Change the service’s istio.io/use-waypoint label to point to the agentgateway waypoint in a single step. Use this approach when an immediate switch is acceptable.
• Weighted canary: Gradually shift a configurable percentage of the service’s in-mesh connections to the agentgateway waypoint while keeping the rest of the connections on the Istio waypoint. Use this approach when you need to validate the agentgateway waypoint before fully committing.

Before you begin

1. Install Solo Enterprise for agentgateway as a waypoint.

2. Ensure that you have an Istio waypoint with at least one enrolled service. For more information, see Configure waypoints.

Deploy the agentgateway waypoint

Both migration approaches require an agentgateway waypoint to be running alongside the existing Istio waypoint.

1. Save the namespace, service name, and gateway name of the existing Istio waypoint.

   export NAMESPACE=<namespace>
   export SERVICE=<service-name>
   export ISTIO_WAYPOINT=<existing-istio-waypoint-name>

2. Deploy the agentgateway waypoint in the same namespace.

   kubectl apply -f - <<EOF
   apiVersion: gateway.networking.k8s.io/v1
   kind: Gateway
   metadata:
     name: agentgateway-waypoint
     namespace: ${NAMESPACE}
     labels:
       istio.io/waypoint-for: all
   spec:
     gatewayClassName: enterprise-agentgateway-waypoint
     listeners:
     - name: mesh
       port: 15008
       protocol: HBONE
   EOF

3. Confirm that the waypoint’s PROGRAMMED status is True.

   kubectl wait gateway agentgateway-waypoint -n ${NAMESPACE} \
     --for=condition=Programmed --timeout=60s

4. Apply L7 policies on the agentgateway waypoint that are equivalent to the policies that are applied to the Istio waypoint. Use EnterpriseAgentgatewayPolicy resources that target the service. For details, see Apply policies with agentgateway.

Migrate with a label flip

A label flip switches the service to the agentgateway waypoint in one operation. After the control plane propagates the change, all new in-mesh connections open through the agentgateway waypoint.

1. Reassign the service to the agentgateway waypoint by relabeling it.

   kubectl label svc ${SERVICE} -n ${NAMESPACE} \
     istio.io/use-waypoint=agentgateway-waypoint --overwrite

2. Verify that the service’s WaypointBound status is True and that it names the agentgateway waypoint.

   kubectl get svc ${SERVICE} -n ${NAMESPACE} -o yaml

   Example output:

   status:
     conditions:
     - message: Successfully attached to waypoint ${NAMESPACE}/agentgateway-waypoint
       reason: WaypointAccepted
       status: "True"
       type: istio.io/WaypointBound

3. Confirm that in-mesh connections flow through the agentgateway waypoint. For inbound connections to your service pod, the agentgateway waypoint pod appears in the REMOTE column with HBONE in the PROTOCOL column.

   istioctl ztunnel-config connections --workload-namespace ${NAMESPACE}

   Example output:

   WORKLOAD                                    DIRECTION   LOCAL                               REMOTE                                              PROTOCOL   CONN ID
   <service-pod>.<namespace>                   Inbound     <service-pod>.<namespace>:<port>    agentgateway-waypoint-<hash>.<namespace>:<port>     HBONE      <id>

4. After you confirm that the service is healthy, delete the old Istio waypoint.

   kubectl delete gateway ${ISTIO_WAYPOINT} -n ${NAMESPACE}

Migrate with a weighted canary

A weighted canary gradually shifts a configurable percentage of the service’s in-mesh connections to the agentgateway waypoint. Use this approach to validate the agentgateway waypoint’s behavior and policy coverage before promoting it. For a conceptual overview of canary waypoints, see Canary waypoints.

The canary is configured by adding two labels and one annotation to the service. The following fields control the canary:

The split is sampled per connection at the source ztunnel. Each connection routes entirely through one waypoint. The realized percentage converges across the ztunnel fleet over time.

Start the canary in pre-flight mode

1. Add the canary label and set the weight to 0. The control plane resolves the canary waypoint, but sends no traffic to it yet.

   kubectl label svc ${SERVICE} -n ${NAMESPACE} \
     istio.io/use-waypoint-canary=agentgateway-waypoint
   kubectl annotate svc ${SERVICE} -n ${NAMESPACE} \
     istio.io/use-waypoint-canary-weight=0

2. Confirm that the agentgateway waypoint has a populated address.

   kubectl get gateway agentgateway-waypoint -n ${NAMESPACE}

   Example output:

   NAME                    CLASS                              ADDRESS        PROGRAMMED   AGE
   agentgateway-waypoint   enterprise-agentgateway-waypoint   10.96.74.145   True         60s

   Note

   If the ADDRESS field is empty or PROGRAMMED is not True, ztunnel cannot resolve the canary waypoint. Check the agentgateway controller logs in the agentgateway-system namespace.

Ramp traffic to the canary

1. Update the weight annotation to increase the portion of connections routed to the agentgateway waypoint. Start with a small value such as 5.

   kubectl annotate svc ${SERVICE} -n ${NAMESPACE} \
     istio.io/use-waypoint-canary-weight=5 --overwrite

2. Verify that connections flow through both waypoints as configured.

   istioctl ztunnel-config connections --workload-namespace ${NAMESPACE}

3. Watch the agentgateway waypoint access logs to confirm that the waypoint processes requests correctly and applies policies.

   kubectl logs -n ${NAMESPACE} \
     -l gateway.networking.k8s.io/gateway-name=agentgateway-waypoint -f

4. Repeat the annotation update at each ramp step (for example, 5 → 25 → 50 → 100), running steps 2–3 after each update before proceeding to the next.

Promote and clean up

After the canary validates at weight 100, promote the agentgateway waypoint to primary and remove the canary configuration.

1. Reassign istio.io/use-waypoint to the agentgateway waypoint and remove the canary label and annotation.

   kubectl label svc ${SERVICE} -n ${NAMESPACE} \
     istio.io/use-waypoint=agentgateway-waypoint \
     istio.io/use-waypoint-canary- --overwrite
   kubectl annotate svc ${SERVICE} -n ${NAMESPACE} \
     istio.io/use-waypoint-canary-weight-

2. Verify that the WaypointBound condition reports only the agentgateway waypoint.

   kubectl get svc ${SERVICE} -n ${NAMESPACE} -o yaml

   Example output:

   status:
     conditions:
     - message: Successfully attached to waypoint ${NAMESPACE}/agentgateway-waypoint
       reason: WaypointAccepted
       status: "True"
       type: istio.io/WaypointBound

3. Delete the old Istio waypoint.

   kubectl delete gateway ${ISTIO_WAYPOINT} -n ${NAMESPACE}

Roll back a canary

To stop the canary and return all traffic to the Istio waypoint, remove the canary label and annotation from the service.

kubectl label svc ${SERVICE} -n ${NAMESPACE} istio.io/use-waypoint-canary-
kubectl annotate svc ${SERVICE} -n ${NAMESPACE} istio.io/use-waypoint-canary-weight-

The control plane removes the weighted set and restores the single-waypoint path through the primary Istio waypoint.

Next steps

• Apply policies with agentgateway.
• Route to AI provider backends.
• Set up ingress traffic with agentgateway.