Skip to content

Authservice Ambient Mode📜

This document describes how the authservice policies are attached when running under Istio ambient mode.

Overview📜

In ambient mode, Istio replaces sidecars with ztunnel (L4) and optional waypoint proxies (L7). The authservice package does not create a waypoint of its own — per-application waypoints are managed downstream by bb-common. Regardless of whether istio.ambient.enabled is true or false, the authservice policies (jwt-authn, jwt-authz, authservice, shared-kiali-authz-policy) are created in the istio-system namespace with a protect: keycloak label selector.

Because istio-system is the Istio root namespace, the selector matches labeled pods mesh-wide. Labeling the istio ingress gateway pods with protect: keycloak attaches the policies there, so authentication is enforced at the gateway before traffic enters the mesh:

flowchart LR
    A[Request] --> B[Istio Gateway<br/>protect: keycloak<br/>ext_authz + JWT validation]
    B --> C[ztunnel]
    C --> D[Workload]

Running Authservice Under Ambient📜

There are two distinct paths to run authservice under ambient. Pick one:

Use the bb-common integration, which manages a per-application waypoint downstream. Enforcement happens at the waypoint in front of each protected application.

See Authservice-protected route (OIDC + ext_authz) in the bb-common docs for configuration.

Path 2: Without a waypoint📜

Enforce at the ingress gateway instead. Enable ambient and label the gateway pods with protect: keycloak so the authservice policies attach there. Because this package creates no waypoint of its own, protected services must have any waypoint routing labels stripped (if the exist) so traffic reaches the gateway. A complete, working reference for this configuration lives in tests/test-values-ambient-gateway.yaml.

istio:
  ambient:
    enabled: true

# Label the public ingress gateway pods so the authservice policies
# (selector protect=keycloak in istio-system) attach to the gateway
istioGateway:
  values:
    gateways:
      public:
        upstream:
          labels:
            protect: keycloak

addons:
  authservice:
    enabled: true

Protected services must not carry authservice waypoint routing labels, or ztunnel will try to route through a waypoint that this package no longer creates. If the Big Bang umbrella sets these labels on a service when ambient is enabled, strip them by setting the keys to null (Helm deletes keys explicitly set to null when coalescing values):

monitoring:
  values:
    upstream:
      prometheus:
        service:
          labels:
            istio.io/use-waypoint: null
            istio.io/use-waypoint-namespace: null
            istio.io/ingress-use-waypoint: null
      alertmanager:
        service:
          labels:
            istio.io/use-waypoint: null
            istio.io/use-waypoint-namespace: null
            istio.io/ingress-use-waypoint: null

Caveats📜

  • Only Envoy-based proxies can enforce these policies. The policies use a CUSTOM (ext_authz) action and JWT validation, which are L7 features. ztunnel is L4-only, so an ambient-enrolled application pod labeled protect: keycloak will not be protected — only gateway pods (full Envoy) enforce the policies. The gateway is the single enforcement point; traffic that bypasses the gateway (in-mesh service-to-service traffic) is not authenticated by authservice.
  • The selector is mesh-wide. Because the policies live in the root namespace, any pod in any namespace carrying the protect: keycloak label matches. Label only the gateway pods you intend to protect.

See Also📜