Authservice Ambient Mode

This document describes the additional configuration required to make protected workloads (like the monitoring chart) function with Istio ambient mode.

Overview

In ambient mode, Istio uses waypoint proxies instead of sidecars to enforce L7 policies. Authservice creates a waypoint gateway (authservice-waypoint) that handles JWT validation and authorization for protected workloads.

flowchart TD
    subgraph "Sidecar Mode"
        A1[Request] --> B1[Sidecar Proxy]
        B1 --> C1[Workload]
    end

    subgraph "Ambient Mode"
        A2[Request] --> B2[ztunnel]
        B2 --> C2[Waypoint Proxy]
        C2 --> D2[Workload]
    end

Key Differences from Sidecar Mode

Aspect	Sidecar Mode	Ambient Mode
Policy attachment	selector.matchLabels	targetRef to Gateway
L7 enforcement	Sidecar proxy	Waypoint proxy
Network path	Direct to pod	ztunnel → waypoint → pod
Waypoint port	N/A	15008 (HBONE)

Waypoint Gateway

When istio.ambient.enabled: true, authservice creates:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: authservice-waypoint
  namespace: authservice
spec:
  gatewayClassName: istio-waypoint
  listeners:
  - name: mesh
    port: 15008
    protocol: HBONE
    allowedRoutes:
      namespaces:
        from: All

Workloads opt-in to use this waypoint by adding labels to their Service:

labels:
  istio.io/use-waypoint: authservice-waypoint
  istio.io/use-waypoint-namespace: authservice
  istio.io/ingress-use-waypoint: "true"

Network Policies for Monitoring

For protected workloads in the monitoring namespace to function with ambient mode, network policies must allow traffic between the waypoint and the workload. Policies must include both the application port and port 15008 (HBONE).

1. Egress from Waypoint to Prometheus

The authservice waypoint needs egress to prometheus pods on both the application port and HBONE:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-egress-from-authservice-waypoint-to-ns-monitoring-pod-prometheus-tcp-port-9090
  namespace: authservice
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: authservice-waypoint
  policyTypes:
    - Egress
  egress:
    - to:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: monitoring
          podSelector:
            matchLabels:
              app.kubernetes.io/name: prometheus
      ports:
        - port: 9090
          protocol: TCP
        - port: 15008
          protocol: TCP

2. Ingress to Prometheus from Waypoint

The monitoring namespace needs to allow ingress from the authservice waypoint:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-ingress-to-prometheus-tcp-port-9090-from-ns-authservice-pod-authservice-waypoint
  namespace: monitoring
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: prometheus
  policyTypes:
    - Ingress
  ingress:
    - from:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: authservice
          podSelector:
            matchLabels:
              app.kubernetes.io/name: authservice-waypoint
      ports:
        - port: 9090
          protocol: TCP
        - port: 15008
          protocol: TCP

3. Ingress to Waypoint from Gateway

The istio gateway needs to reach the waypoint on HBONE:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-ingress-to-authservice-waypoint-tcp-port-15008-from-ns-istio-gateway-any-pod
  namespace: authservice
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: authservice-waypoint
  policyTypes:
    - Ingress
  ingress:
    - from:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: istio-gateway
          podSelector: {}
      ports:
        - port: 15008
          protocol: TCP

Authorization Policies

In ambient mode, AuthorizationPolicies must allow the waypoint to access the protected workload. This can be done via namespace or principal matching:

apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: allow-ingress-to-prometheus-tcp-port-9090-from-ns-authservice
  namespace: monitoring
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: prometheus
  action: ALLOW
  rules:
    - from:
        - source:
            namespaces:
              - authservice
      to:
        - operation:
            ports:
              - "9090"

For more restrictive configurations, use principal-based matching:

apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: allow-waypoint-to-prometheus
  namespace: monitoring
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: prometheus
  action: ALLOW
  rules:
    - from:
        - source:
            principals:
              - cluster.local/ns/authservice/sa/authservice-waypoint
      to:
        - operation:
            ports:
              - "9090"

Configuring via Big Bang Values

These network policies are configured via bb-common values.

Authservice Chart (values.yaml defaults)

The authservice chart includes waypoint network policies by default:

networkPolicies:
  ingress:
    to:
      # Ingress to waypoint from gateway
      authservice-waypoint:15008:
        from:
          k8s:
            "istio-gateway/*": true
  egress:
    from:
      # Egress from waypoint to prometheus
      authservice-waypoint:
        to:
          k8s:
            monitoring/prometheus:9090: true

Monitoring Chart Configuration

The monitoring chart needs to allow ingress from the waypoint and label the prometheus service:

monitoring:
  enabled: true
  sso:
    enabled: true
  values:
    # Ingress to prometheus from waypoint
    networkPolicies:
      ingress:
        to:
          prometheus:9090:
            from:
              k8s:
                authservice/authservice-waypoint: true

    # Labels to route traffic through authservice waypoint
    upstream:
      prometheus:
        service:
          labels:
            istio.io/use-waypoint: authservice-waypoint
            istio.io/use-waypoint-namespace: authservice
            istio.io/ingress-use-waypoint: "true"

HBONE Port Injection

When istio.ambient.enabled: true, bb-common automatically adds port 15008 (HBONE) to network policies. This is indicated by the label:

ambient.istio.network-policies.bigbang.dev/hbone-injected: "true"

Traffic Flow in Ambient Mode

In ambient mode, all traffic flows through ztunnel (the L4 component). When a service has waypoint labels, ztunnel routes traffic through the waypoint for L7 policy enforcement.

sequenceDiagram
    participant Browser
    participant Gateway as Istio Gateway
    participant ztunnel1 as ztunnel (node)
    participant Waypoint as authservice-waypoint
    participant Authservice
    participant ztunnel2 as ztunnel (prometheus node)
    participant Prometheus

    Browser->>Gateway: GET https://prometheus.dev.bigbang.mil
    Gateway->>ztunnel1: Route to prometheus service

    Note over ztunnel1: Service has waypoint label<br/>Route via waypoint

    ztunnel1->>Waypoint: HBONE (port 15008)

    Note over Waypoint: CUSTOM policy triggers<br/>ext_authz to authservice

    Waypoint->>Authservice: Authorization check
    Authservice-->>Waypoint: OK + JWT header

    Note over Waypoint: RequestAuthentication validates JWT<br/>AuthorizationPolicy allows request

    Waypoint->>ztunnel2: Forward to prometheus
    ztunnel2->>Prometheus: Request with JWT
    Prometheus-->>Browser: Response

Troubleshooting

Request denied with no matching policy

Ensure the AuthorizationPolicy allows the waypoint service account:

kubectl get authorizationpolicy -n monitoring -o yaml
# Look for: principals: ["cluster.local/ns/authservice/sa/authservice-waypoint"]

Connection timeout to monitoring

Check network policies allow HBONE traffic:

# Verify egress from waypoint
kubectl get networkpolicy -n authservice -o yaml

# Verify ingress to monitoring
kubectl get networkpolicy -n monitoring -o yaml

Waypoint not receiving traffic

Verify the service has the correct labels:

kubectl get svc -n monitoring monitoring-monitoring-kube-prometheus -o yaml | grep -A5 labels
# Should include:
#   istio.io/use-waypoint: authservice-waypoint
#   istio.io/use-waypoint-namespace: authservice

See Also

• POLICIES.md - Policy enforcement details
• FLOW.md - Authorization flow diagrams
• Istio Ambient Mode Documentation