Layer 7 Waypoint Management

warning

Before getting started, ensure that you have followed the procedures described in the Installation section and have set up your Management Plane and Control Plane with the correct settings.

Waypoints are required for Layer 7 traffic management features in ambient mode. TSB provides automated waypoint management through the ControlPlane configuration, allowing you to control waypoint deployment at both cluster and namespace levels.

Automatic Waypoint Management

By default, TSB deploys one waypoint per namespace for ambient-enabled workloads. TSB's XCP (Cross Cluster Platform) component automatically creates, updates, and deletes waypoints to match your ambient workloads and TSB configuration requirements.

Waypoint Deployment Patterns

Pattern 1: Default Behavior (Recommended)

• Enable cluster-level waypoints
• TSB automatically deploys waypoints in all ambient namespaces
• XCP manages waypoint labels automatically

Pattern 2: Selective Waypoint Deployment

• Disable cluster-level waypoints
• Enable waypoints only for specific namespaces that need Layer 7 features
• Reduces resource overhead for namespaces that only need Layer 4

Both patterns can be customized using overlays to modify waypoint deployments, resource requirements, labels, annotations, and horizontal pod autoscaling configuration.

Configuring Waypoint Deployment

Basic Waypoint Configuration:

apiVersion: install.tetrate.io/v1alpha1
kind: ControlPlane
metadata:
  name: controlplane
  namespace: istio-system
spec:
  components:
    istio:
      ambient:
        enable: true
        waypoints:
          clusterLevel:
            enable: true  # Enable waypoints cluster-wide (default: true)

Pattern 1: Cluster-Level Waypoint Configuration

Cluster-level settings apply to all ambient-enabled namespaces that don't have specific namespace-level configurations:

apiVersion: install.tetrate.io/v1alpha1
kind: ControlPlane
metadata:
  name: controlplane
  namespace: istio-system
spec:
  components:
    istio:
      ambient:
        enable: true
        waypoints:
          clusterLevel:
            enable: true
            disableLabelManagement: false  # XCP manages istio.io/use-waypoint labels

Pattern 2: Namespace-Level Waypoint Configuration

For selective deployment, configure waypoints for specific namespaces. Namespace-level configurations take precedence over cluster-level settings:

apiVersion: install.tetrate.io/v1alpha1
kind: ControlPlane
metadata:
  name: controlplane
  namespace: istio-system
spec:
  components:
    istio:
      ambient:
        enable: true
        waypoints:
          clusterLevel:
            enable: false  # Disable cluster-wide waypoints
          namespaceLevel:
          - name: echo  # Target specific namespace
            config:
              enable: true

Waypoint Customization with Overlays

Both deployment patterns support customization through overlays. Use overlays to modify waypoint deployments, services, and horizontal pod autoscalers:

Basic Customization:

apiVersion: install.tetrate.io/v1alpha1
kind: ControlPlane
metadata:
  name: controlplane
  namespace: istio-system
spec:
  components:
    istio:
      ambient:
        enable: true
        waypoints:
          clusterLevel:
            overlays:
              istio-waypoint:
                deployment:
                  metadata:
                    annotations:
                      cluster-wide: "managed-by-tsb"

Advanced Customization with Resource Management:

apiVersion: install.tetrate.io/v1alpha1
kind: ControlPlane
metadata:
  name: controlplane
  namespace: istio-system
spec:
  components:
    istio:
      ambient:
        enable: true
        waypoints:
          clusterLevel:
            overlays:
              istio-waypoint:
                deployment:
                  spec:
                    template:
                      spec:
                        containers:
                        - name: istio-proxy
                          resources:
                            requests:
                              cpu: 100m
                              memory: 128Mi
                            limits:
                              cpu: 500m
                              memory: 512Mi
                horizontalPodAutoscaler:
                  spec:
                    maxReplicas: 5
                    minReplicas: 2
                    targetCPUUtilizationPercentage: 70

Namespace-Specific Customization:

apiVersion: install.tetrate.io/v1alpha1
kind: ControlPlane
metadata:
  name: controlplane
  namespace: istio-system
spec:
  components:
    istio:
      ambient:
        enable: true
        waypoints:
          namespaceLevel:
          - name: echo
            config:
              enable: true
              overlays:
                istio-waypoint:
                  deployment:
                    metadata:
                      annotations:
                        namespace-specific: "echo-waypoint"
                  horizontalPodAutoscaler:
                    spec:
                      maxReplicas: 3
                      minReplicas: 1

Waypoint Label Management

One of the key challenges with ambient mode is its dependency on precise labeling across various Kubernetes resources to ensure correct traffic flow. Misconfigured or missing labels can easily break traffic routing, making it difficult for application teams to avoid configuration errors and challenging for platform teams to maintain traffic path correctness across multiple workloads and namespaces.

TSB's ambient support addresses this complexity by automatically managing ambient labels to ensure proper traffic flow through waypoints. This includes:

• istio.io/use-waypoint - Namespace label that directs namespace traffic through waypoints
• istio.io/ingress-use-waypoint - Workload/service label that ensures traffic from gateways goes through waypoints

Recommendation: Keep automatic label management enabled (the default behavior). TSB's XCP component handles all necessary waypoint labeling automatically, eliminating the risk of manual labeling errors and ensuring consistent traffic routing across your ambient mesh.

For advanced users who need manual control, you can disable automatic management of the istio.io/use-waypoint label:

Advanced Configuration:

apiVersion: install.tetrate.io/v1alpha1
kind: ControlPlane
metadata:
  name: controlplane
  namespace: istio-system
spec:
  components:
    istio:
      ambient:
        enable: true
        waypoints:
          clusterLevel:
            disableLabelManagement: true  # Advanced: disable automatic labeling

When automatic label management is disabled, you must manually apply waypoint redirection labels:

# Manually enable waypoint redirection for a namespace kubectl label namespace echo istio.io/use-waypoint=waypoint

# Remove waypoint redirection
kubectl label namespace echo istio.io/use-waypoint-

For detailed information about waypoint configuration and traffic routing, see the Istio Waypoint documentation

Verifying Waypoint Deployment

Check waypoint status and configuration: Commands:

# List waypoints in the cluster 
kubectl get gateways.gateway.networking.k8s.io -A

# Check waypoint pod status
kubectl get pods -l gateway.istio.io/managed=istio.io-gateway-controller

# Verify waypoint configuration
kubectl describe gateway waypoint -n echo

This automated waypoint management ensures that your ambient workloads have the necessary Layer 7 capabilities while providing flexibility to optimize resource usage based on your specific requirements.