Install agentgateway as a waypoint

EnterpriseAlpha

Install agentgateway and deploy it as a waypoint proxy in your ambient mesh.

This feature requires the following licenses. Contact your account representative to obtain valid licenses.

Your ambient mesh must be installed with the Solo distribution of Istio and an Enterprise-level license for Solo Enterprise for Istio.
A Solo Enterprise for agentgateway license.

The agentgateway waypoint feature is in the alpha state. Alpha features are likely to change, are not fully tested, and are not supported for production. For more information, see Solo feature maturity.

Deploy Solo Enterprise for agentgateway as a waypoint proxy in your ambient mesh by using the enterprise-agentgateway-waypoint GatewayClass. The agentgateway waypoint integrates with Istio’s HBONE protocol and supports the EnterpriseAgentgatewayPolicy CRD for CEL-based L7 policy enforcement. For more information, see the overview.

Before you begin

Install an ambient mesh that runs the Solo distribution of Istio 1.30 or later with an Enterprise-level Solo Enterprise for Istio license. To set up an ambient mesh, see the install guides for a single cluster or multicluster mesh.
Install the following CLI tools.
- kubectl, the Kubernetes command line tool. Download the kubectl version that is within one minor version of the EKS cluster you plan to use.
- helm, the Kubernetes package manager.
Save the following Solo Enterprise for agentgateway details.
- Version: Save the Solo Enterprise for agentgateway version for your Solo Enterprise for Istio release. To find available versions, see the supported versions matrix.
- License: Save your Solo Enterprise for agentgateway license key. Contact your account representative to obtain a valid license.
```
export AGENTGATEWAY_VERSION=v2026.6.0
export AGENTGATEWAY_LICENSE_KEY=<license_key>
```

Install Solo Enterprise for agentgateway

Single cluster

Install the Solo Enterprise for agentgateway CRDs.

helm install enterprise-agentgateway-crds \
  oci://us-docker.pkg.dev/solo-public/enterprise-agentgateway/charts/enterprise-agentgateway-crds \
  --version ${AGENTGATEWAY_VERSION} \
  -n agentgateway-system \
  --create-namespace

Install the Solo Enterprise for agentgateway Helm chart. For all available values, see the Helm reference.

helm install enterprise-agentgateway \
  oci://us-docker.pkg.dev/solo-public/enterprise-agentgateway/charts/enterprise-agentgateway \
  --version ${AGENTGATEWAY_VERSION} \
  --set licensing.licenseKey=${AGENTGATEWAY_LICENSE_KEY} \
  --set istio.autoEnabled=true \
  -n agentgateway-system

Make sure that the enterprise-agentgateway control plane is running.

kubectl get pods -n agentgateway-system

Example output:

NAME                                       READY   STATUS    RESTARTS   AGE
enterprise-agentgateway-1a2b3c4d5e-6f7g8   1/1     Running   0          19s

Multicluster

In a multicluster mesh, install the Solo Enterprise for agentgateway CRDs and control plane in each cluster. The controller in each cluster reconciles EnterpriseAgentgatewayPolicy and manages waypoint pods for that cluster.

Save the names, kubeconfig contexts, and Istio network names of each cluster. The network name is set during mesh installation and stored as a label on the istio-system namespace.

export cluster1=<cluster1_name>
export context1=<cluster1_context>
export cluster2=<cluster2_name>
export context2=<cluster2_context>

export network1=$(kubectl get namespace istio-system --context ${context1} \
  -o jsonpath='{.metadata.labels.topology\.istio\.io/network}')
export network2=$(kubectl get namespace istio-system --context ${context2} \
  -o jsonpath='{.metadata.labels.topology\.istio\.io/network}')
echo $network1 $network2

Install the Solo Enterprise for agentgateway CRDs on each cluster.

for context in ${context1} ${context2}; do
  helm install enterprise-agentgateway-crds \
    oci://us-docker.pkg.dev/solo-public/enterprise-agentgateway/charts/enterprise-agentgateway-crds \
    --version ${AGENTGATEWAY_VERSION} \
    -n agentgateway-system \
    --create-namespace \
    --kube-context ${context}
done

Install the Solo Enterprise for agentgateway Helm chart on each cluster. Each cluster gets its own istio.clusterId and istio.network values so that the controller injects the correct cluster identity into each gateway pod. For all available values, see the Helm reference.

helm install enterprise-agentgateway \
  oci://us-docker.pkg.dev/solo-public/enterprise-agentgateway/charts/enterprise-agentgateway \
  --version ${AGENTGATEWAY_VERSION} \
  --set licensing.licenseKey=${AGENTGATEWAY_LICENSE_KEY} \
  --set istio.autoEnabled=true \
  --set istio.clusterId=${cluster1} \
  --set istio.network=${network1} \
  -n agentgateway-system \
  --kube-context ${context1}

helm install enterprise-agentgateway \
  oci://us-docker.pkg.dev/solo-public/enterprise-agentgateway/charts/enterprise-agentgateway \
  --version ${AGENTGATEWAY_VERSION} \
  --set licensing.licenseKey=${AGENTGATEWAY_LICENSE_KEY} \
  --set istio.autoEnabled=true \
  --set istio.clusterId=${cluster2} \
  --set istio.network=${network2} \
  -n agentgateway-system \
  --kube-context ${context2}

Make sure that the enterprise-agentgateway control plane is running on each cluster.

kubectl get pods -n agentgateway-system --context ${context1}
kubectl get pods -n agentgateway-system --context ${context2}

Example output:

NAME                                       READY   STATUS    RESTARTS   AGE
enterprise-agentgateway-1a2b3c4d5e-6f7g8   1/1     Running   0          19s
NAME                                       READY   STATUS    RESTARTS   AGE
enterprise-agentgateway-1a2b3c4d5e-h9i0j   1/1     Running   0          12s

Deploy the waypoint

Single cluster

Save the name of the workload namespace where you want to deploy the waypoint.
```
export NAMESPACE=<ns>
```

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

Verify that the agentgateway waypoint pod is running and the Gateway is programmed.

kubectl get pods -n ${NAMESPACE} -l gateway.networking.k8s.io/gateway-name=agentgateway-waypoint
kubectl get gateway agentgateway-waypoint -n ${NAMESPACE}

Example output:

NAME                                     READY   STATUS    RESTARTS   AGE
agentgateway-waypoint-757fdbb564-44nz2   1/1     Running   0          11s

NAME                    CLASS                              ADDRESS         PROGRAMMED   AGE
agentgateway-waypoint   enterprise-agentgateway-waypoint   172.20.235.25   True         23s

Multicluster

In a multicluster mesh, cluster identity (cluster ID, network, and CA address) is configured at Helm install time. Only additionalTrustDomains, the set of trust domains from peer clusters that this waypoint accepts certificates from, is configured per gateway by referencing an EnterpriseAgentgatewayParameters resource with the trust domains.

Save the name of the workload namespace where you want to deploy the waypoint.
```
export NAMESPACE=<ns>
```
Get the Istio trust domain for each cluster. Each waypoint needs the other cluster’s trust domain in additionalTrustDomains to accept cross-cluster mTLS certificates.
additionalTrustDomains is required for cross-cluster routing. Without it, agentgateway rejects peer certificates that carry a different trust domain, causing connection failures between clusters.
The trust domain is set at mesh installation time and often differs from the cluster name, for example by having a .local suffix. Using the wrong value causes agentgateway to fail certificate verification with a SAN mismatch error.
```
export trust_domain1=$(kubectl get configmap istio -n istio-system --context ${context1} \
  -o jsonpath='{.data.mesh}' | grep trustDomain | awk '{print $2}')
export trust_domain2=$(kubectl get configmap istio -n istio-system --context ${context2} \
  -o jsonpath='{.data.mesh}' | grep trustDomain | awk '{print $2}')
echo $trust_domain1 $trust_domain2
```

Create an EnterpriseAgentgatewayParameters resource in ${NAMESPACE} on each cluster. Each cluster’s resource lists the other cluster’s trust domain in additionalTrustDomains. Cluster-wide settings such as cluster ID, network, and CA address are already configured via Helm values from the install step.

kubectl apply --context ${context1} -f - <<EOF
apiVersion: enterpriseagentgateway.solo.io/v1alpha1
kind: EnterpriseAgentgatewayParameters
metadata:
  name: agw-params
  namespace: ${NAMESPACE}
spec:
  istio:
    additionalTrustDomains:
    - ${trust_domain2}
EOF

kubectl apply --context ${context2} -f - <<EOF
apiVersion: enterpriseagentgateway.solo.io/v1alpha1
kind: EnterpriseAgentgatewayParameters
metadata:
  name: agw-params
  namespace: ${NAMESPACE}
spec:
  istio:
    additionalTrustDomains:
    - ${trust_domain1}
EOF

Create a Gateway resource using the enterprise-agentgateway-waypoint GatewayClass. Use the istio.io/waypoint-for: all label to handle both Kubernetes services and Istio resources, such as WorkloadEntries and ServiceEntries. Reference the EnterpriseAgentgatewayParameters resource via spec.infrastructure.parametersRef so that the additionalTrustDomains setting is applied to the waypoint pod.

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
  infrastructure:
    parametersRef:
      group: enterpriseagentgateway.solo.io
      kind: EnterpriseAgentgatewayParameters
      name: agw-params
  listeners:
  - name: mesh
    port: 15008
    protocol: HBONE
EOF

Verify that the agentgateway waypoint pod is running and the Gateway is programmed.

kubectl get pods -n ${NAMESPACE} -l gateway.networking.k8s.io/gateway-name=agentgateway-waypoint
kubectl get gateway agentgateway-waypoint -n ${NAMESPACE}

Example output:

NAME                                     READY   STATUS    RESTARTS   AGE
agentgateway-waypoint-757fdbb564-44nz2   1/1     Running   0          11s

NAME                    CLASS                              ADDRESS         PROGRAMMED   AGE
agentgateway-waypoint   enterprise-agentgateway-waypoint   172.20.235.25   True         23s

Enroll services

Label individual services or an entire namespace to route traffic through the agentgateway waypoint. Apply both labels: istio.io/use-waypoint to select the waypoint, and istio.io/ingress-use-waypoint=true to ensure ingress gateways also route through the waypoint rather than bypassing it.
- Service:
  kubectl label svc <name> -n ${NAMESPACE} \ istio.io/use-waypoint=agentgateway-waypoint \ istio.io/ingress-use-waypoint=true
- Namespace:
  kubectl label namespace ${NAMESPACE} \ istio.io/use-waypoint=agentgateway-waypoint \ istio.io/ingress-use-waypoint=true
In a peered multicluster environment, you only need to set istio.io/ingress-use-waypoint on the Service or namespace in the cluster where the workload runs. The peering controller automatically propagates the label to connected clusters via the auto-generated WorkloadEntry resources, so ingress gateways throughout the mesh route traffic through the waypoint without additional configuration. For details, see Ingress gateway considerations.
Mixed mesh only: If you run an interop mesh where some workloads still use sidecar proxies, restart those workloads to force new connections through the waypoint. Sidecar-established connections persist and bypass the waypoint until closed. Pure ambient workloads route through the waypoint automatically without a restart. If you have an ingress gateway, restart it as well so it picks up the istio.io/ingress-use-waypoint=true label.
```
kubectl rollout restart deploy/<sidecar_workload> -n ${NAMESPACE}
kubectl rollout restart deploy/<ingress_deployment> -n ${NAMESPACE}
```

After sending traffic to an enrolled service, verify that connections flow through the waypoint with mTLS. For more information about this command, see the CLI reference.

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

The PROTOCOL column shows HBONE for connections on the waypoint pod, confirming that all tunnels are mutually authenticated end-to-end.

Example output:

WORKLOAD                                                    DIRECTION   LOCAL              REMOTE             REMOTE TARGET   PROTOCOL   CONN ID
agentgateway-waypoint-757fdbb564-44nz2.<ns>                 Inbound     10.0.0.10:15008    10.0.0.3:54210     10.0.0.5:80     HBONE      1a2b3c4d
agentgateway-waypoint-757fdbb564-44nz2.<ns>                 Outbound    10.0.0.10:52100    10.0.0.5:80        10.0.0.5:80     HBONE      5e6f7g8h

Apply policies with agentgateway.
Route to AI provider backends.
Set up egress traffic with agentgateway.
For advanced agentgateway configuration, see the Solo Enterprise for agentgateway documentation.

Uninstall

If you no longer need the agentgateway waypoint, you can remove it and optionally uninstall Solo Enterprise for agentgateway.

Remove the waypoint enrollment labels from any services or namespaces you labeled.

Service:

kubectl label svc <name> -n ${NAMESPACE} istio.io/use-waypoint-

Namespace:

kubectl label namespace ${NAMESPACE} istio.io/use-waypoint-

Delete the Gateway resource.

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

Multicluster only: Delete the EnterpriseAgentgatewayParameters resource from each cluster.

for context in ${context1} ${context2}; do
  kubectl delete enterpriseagentgatewayparameters agw-params -n ${NAMESPACE} --context ${context}
done

Uninstall the Solo Enterprise for agentgateway Helm chart and CRDs.

Single cluster:

helm uninstall enterprise-agentgateway -n agentgateway-system
helm uninstall enterprise-agentgateway-crds -n agentgateway-system

Multicluster:

for context in ${context1} ${context2}; do
  helm uninstall enterprise-agentgateway -n agentgateway-system --kube-context ${context}
  helm uninstall enterprise-agentgateway-crds -n agentgateway-system --kube-context ${context}
done

About agentic mesh Policies

Install agentgateway as a waypoint

Before you begin

Install Solo Enterprise for agentgateway

Single cluster

Multicluster

Deploy the waypoint

Single cluster

Multicluster

Enroll services

Next

Uninstall