Configure waypoints

Deploy and configure community istio-waypoint proxies in your ambient mesh.

Deploy a waypoint

Waypoint proxies are Kubernetes Gateway API resources. You can deploy them using istioctl for convenience or by applying a Gateway resource directly.

The istio.io/waypoint-for label on the Gateway controls which resource types the waypoint handles:

`istio.io/waypoint-for` value	Waypoint handles traffic to
`service`	Kubernetes services only (default)
`workload`	Pod or VM IP addresses
`all`	Both service and workload traffic
`none`	No traffic (useful for testing)

Declarative resource

Apply a Gateway resource directly. This is the recommended approach for GitOps workflows and when you want to manage the waypoint alongside other Kubernetes resources.

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

After the waypoint deploys, enroll the resources whose traffic you want the waypoint to process. Enrollment tells ztunnel to redirect matching traffic through the waypoint for L7 processing, rather than forwarding it directly at L4. Without enrollment, the waypoint exists but receives no traffic.

To label a namespace to enroll all services in it:

kubectl label namespace <namespace> istio.io/use-waypoint=waypoint

To label an individual service to enroll only that service:

kubectl label service <service_name> -n default istio.io/use-waypoint=waypoint

Note

If you manage resources with GitOps, add the istio.io/use-waypoint label directly to the namespace or service manifest in your source repository rather than applying it with kubectl label.

Automatic deployment

Versions 1.25 and later of the Solo distribution of Istio support automatic waypoint deployment. When you label a namespace, service, or service entry with istio.io/use-waypoint=auto, istiod creates the waypoint automatically by using the istio-waypoint GatewayClass. To avoid collisions, apply this label at either the namespace level or the individual service level, but not both for the same service.

To label a namespace:

kubectl label namespace <namespace> istio.io/use-waypoint=auto

To label an individual service:

kubectl label service <service_name> -n default istio.io/use-waypoint=auto

Using istioctl

The istioctl waypoint subcommands generate and apply a waypoint Gateway resource.

istioctl waypoint apply -n default --for all --enroll-namespace

The --enroll-namespace flag labels the namespace with istio.io/use-waypoint automatically. To preview the generated resource without applying it, use istioctl waypoint generate.

istioctl waypoint generate --for all -n default

Configure resource enrollment

To apply a waypoint to namespaces, services, or pods, use the istio.io/use-waypoint label.

To apply a waypoint broadly to all services in a namespace, label the namespace.

kubectl label ns default istio.io/use-waypoint=waypoint

All in-mesh pod requests to services in that namespace traverse the waypoint for L7 processing. In a multicluster ambient mesh, deploy a waypoint to the namespace in each cluster where the service instances run.

To apply a waypoint to a specific service, deploy a dedicated waypoint and label the service.

istioctl waypoint apply -n default --name reviews-svc-waypoint
kubectl label service reviews istio.io/use-waypoint=reviews-svc-waypoint

To apply a waypoint to specific pods, deploy a workload-type waypoint and label the pods.

istioctl waypoint apply -n default --name reviews-v2-pod-waypoint --for workload
kubectl label pod -l version=v2,app=reviews istio.io/use-waypoint=reviews-v2-pod-waypoint

Canary waypoints

A canary waypoint lets you direct a configurable share of traffic to a secondary waypoint alongside the primary one, without any client changes. Use a canary waypoint to test a new waypoint configuration before fully committing to it. If the canary waypoint causes a problem, only the weighted share of traffic is affected. The primary waypoint handles the remaining traffic.

To enable canary routing, set both the istio.io/use-waypoint and istio.io/use-waypoint-canary labels on the Service. The istio.io/use-waypoint-canary-weight annotation on the same Service sets the percentage of traffic to send to the canary waypoint, as an integer from 0 to 100. The primary waypoint receives the remaining percentage.

Deploy a canary waypoint in the same namespace as the primary waypoint.

kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: waypoint-canary
  namespace: default
spec:
  gatewayClassName: istio-waypoint
  listeners:
  - name: mesh
    port: 15008
    protocol: HBONE
EOF

Add the istio.io/use-waypoint-canary label to the service.

kubectl label service <service_name> -n default istio.io/use-waypoint-canary=waypoint-canary

Set the traffic weight on the service. In this example, 20 percent of traffic goes to the canary waypoint and 80 percent goes to the primary.
```
kubectl annotate service <service_name> -n default istio.io/use-waypoint-canary-weight=20
```

To use a canary waypoint from a different namespace, set the istio.io/use-waypoint-canary-namespace label to the waypoint’s namespace.

You can also apply the canary configuration at the namespace level. Services in the namespace inherit the labels and annotation using the same rules as istio.io/use-waypoint. Service-level settings take precedence over namespace-level settings.

To disable the canary, remove the istio.io/use-waypoint-canary label from the service.

kubectl label service <service_name> -n default istio.io/use-waypoint-canary-

Note

If istiod cannot resolve the canary waypoint, it reports an error on the binding status and sends all traffic to the primary waypoint. Traffic is not lost.

Route ingress traffic through waypoints

By default, ingress gateways send traffic directly to backend pods, bypassing any waypoint configured for the destination service. To route ingress traffic through a waypoint instead, add the istio.io/ingress-use-waypoint label to the service or namespace. For conceptual background on this behavior and recommended architecture, see Ingress gateway considerations.

To route ingress traffic for a specific service through its waypoint:

kubectl label service <service_name> -n <namespace> istio.io/ingress-use-waypoint=true

To route ingress traffic for all services in a namespace through their waypoints:
```
kubectl label namespace <namespace> istio.io/ingress-use-waypoint=true
```

Note

In a peered multicluster environment with Solo Enterprise for Istio, 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.

Attach policies and routes

Gateway-level attachment

To apply a policy to an entire waypoint proxy, reference kind: Gateway in targetRefs.

apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: view-only
  namespace: default
spec:
  targetRefs:
  - kind: Gateway
    group: gateway.networking.k8s.io
    name: default
  action: ALLOW
  rules:
  - from:
    - source:
        namespaces: ["default", "istio-system"]
    to:
    - operation:
        methods: ["GET"]

Service-level attachment

To apply routes to a specific service, reference kind: Service in parentRefs.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: reviews
  namespace: default
spec:
  parentRefs:
  - group: ""
    kind: Service
    name: reviews
    port: 9080
  rules:
  - backendRefs:
    - name: reviews-v1
      port: 9080
      weight: 90
    - name: reviews-v2
      port: 9080
      weight: 10

Authorization policy considerations

When a waypoint proxy is deployed for a namespace or service, traffic from in-mesh sources reaches the backend with the waypoint’s identity, not the original source identity. Authorization policies on the backend must allow traffic from the waypoint’s service account principal, or the request is denied even if the original source would have been permitted.

Only one ExtensionProvider is permitted per waypoint proxy. In a sidecar setup, you can apply multiple policies with different providers to individual workloads. When you apply an AuthorizationPolicy with a custom ExtensionProvider to a waypoint, that provider applies to all workloads served by the waypoint.

Customize waypoint resources

When Istio provisions a waypoint, Istio generates a Deployment and Service with the same name as the Gateway resource (unlike ingress gateway classes, istio-waypoint does not append a class-name suffix). Use the spec.infrastructure field on the Gateway to customize labels, annotations, and deeper resource configuration without managing the generated resources directly.

Labels and annotations

Labels and annotations set under spec.infrastructure are copied to the generated Deployment and Service.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: waypoint
  namespace: default
spec:
  gatewayClassName: istio-waypoint
  listeners:
  - name: mesh
    port: 15008
    protocol: HBONE
  infrastructure:
    labels:
      team: payments
    annotations:
      custom-key: custom-value

ConfigMap-based customization

For deeper customization, reference a ConfigMap via spec.infrastructure.parametersRef. The ConfigMap must be in the same namespace as the Gateway. Each key in the ConfigMap is applied as a strategic merge patch on the corresponding generated resource.

Valid keys are: deployment, service, serviceAccount, horizontalPodAutoscaler, podDisruptionBudget.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: waypoint
  namespace: default
spec:
  gatewayClassName: istio-waypoint
  listeners:
  - name: mesh
    port: 15008
    protocol: HBONE
  infrastructure:
    parametersRef:
      group: ""
      kind: ConfigMap
      name: waypoint-options

apiVersion: v1
kind: ConfigMap
metadata:
  name: waypoint-options
  namespace: default
data:
  horizontalPodAutoscaler: |
    spec:
      minReplicas: 2
      maxReplicas: 5
  podDisruptionBudget: |
    spec:
      minAvailable: 1
  deployment: |
    spec:
      template:
        spec:
          containers:
          - name: istio-proxy
            resources:
              requests:
                cpu: 500m
                memory: 128Mi
  service: |
    spec:
      ports:
      - "$patch": delete
        port: 15021

Note

HorizontalPodAutoscaler and PodDisruptionBudget are not created by default. Including their key in the ConfigMap causes Istio to create them automatically.

The "$patch": delete directive removes the matching entry from a list during the strategic merge patch. Use it to delete a generated port from the Service spec, as shown in the service key example above.

GatewayClass defaults

To apply default customizations to all waypoints in the mesh, create a ConfigMap in the istio-system namespace with the label gateway.istio.io/defaults-for-class: istio-waypoint. This ConfigMap takes the same format as a per-Gateway ConfigMap. If both a GatewayClass default and a per-Gateway ConfigMap are present, the per-Gateway customization is applied on top of the class defaults.

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-waypoint-defaults
  namespace: istio-system
  labels:
    gateway.istio.io/defaults-for-class: istio-waypoint
data:
  horizontalPodAutoscaler: |
    spec:
      minReplicas: 2
      maxReplicas: 5
  deployment: |
    spec:
      template:
        spec:
          containers:
          - name: istio-proxy
            resources:
              requests:
                cpu: 500m

You can also set GatewayClass defaults at install time using Helm values. These settings are equivalent to creating the previous ConfigMap.

values:
  gatewayClasses:
    istio-waypoint:
      deployment:
        spec:
          replicas: 2

Scale waypoints

The recommended way to configure scaling is by using a ConfigMap referenced from spec.infrastructure.parametersRef, as shown in ConfigMap-based customization. You can also attach standalone HorizontalPodAutoscaler and PodDisruptionBudget resources directly to the generated Deployment if you prefer to manage them separately, such as the following.

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: waypoint-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: waypoint
  minReplicas: 2
  maxReplicas: 5
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 50
---
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: waypoint-pdb
spec:
  minAvailable: 1
  selector:
    matchLabels:
      gateway.networking.k8s.io/gateway-name: waypoint

Use waypoints across namespaces

By default, a waypoint serves resources in its own namespace. To allow resources in other namespaces to use a waypoint, configure allowedRoutes on the Gateway, such as the following.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: egress-gateway
  namespace: common-infrastructure
spec:
  gatewayClassName: istio-waypoint
  listeners:
  - name: mesh
    port: 15008
    protocol: HBONE
    allowedRoutes:
      namespaces:
        from: Selector
        selector:
          matchLabels:
            kubernetes.io/metadata.name: cross-namespace-waypoint-consumer

Then, label the resource with both the waypoint name and its namespace.

kubectl label serviceentry istio-site istio.io/use-waypoint=egress-gateway
kubectl label serviceentry istio-site istio.io/use-waypoint-namespace=common-infrastructure

Remove waypoints

To remove waypoints, delete the waypoint proxies and remove the enrollment label from the namespace.

istioctl waypoint delete --all -n default
kubectl label ns default istio.io/use-waypoint-

Overview