Skip to content

Configuring Istio Ambient Mode in Big Bang

WARNING: Ambient mode is currently in an beta state within Big Bang. It is not fully integrated and is not recommended for production use. Expect potential breaking changes in future releases.

NOTE: When istio.ambient.enabled is set to true, Big Bang deploys the required ambient infrastructure (ztunnel, istio-cni, gateway-api) and automatically opts all packages into ambient mode by applying the istio.io/dataplane-mode: ambient label to their namespaces.

Overview

Big Bang supports Istio Ambient Mode, a sidecar-less data plane architecture that provides mTLS and traffic management without requiring sidecar proxies in application pods. Instead of injecting Envoy sidecars, ambient mode uses a node-level ztunnel component to handle Layer 4 (L4) traffic.

Enabling Ambient Mode

To enable ambient mode globally, set the istio.ambient.enabled flag in your values:

istio:
  ambient:
    enabled: true

Packages Enabled by the Global Ambient Flag

When istio.ambient.enabled is set to true, Big Bang automatically enables the following packages:

Package Description
ztunnel The node-level proxy that handles L4 traffic and mTLS in ambient mode
istio-cni The CNI plugin required for traffic interception in ambient mode
gateway-api Kubernetes Gateway API CRDs used by ambient mode for traffic management

You do not need to explicitly enable these packages when using the global ambient flag.

Mission Applications

When Big Bang creates a namespace for an integrated package or an application declared through the packages key, it labels that namespace for ambient enrollment automatically. Applications managed by an external controller, such as Argo CD, must create or label their namespaces explicitly with istio.io/dataplane-mode: ambient.

Namespace enrollment only places workloads in the ambient data plane. A chart that is not integrated with bb-common can still require application-specific Kubernetes NetworkPolicy and Istio AuthorizationPolicy resources for HBONE traffic, health probes, ingress, metrics, and other callers.

Use the Mission Applications with Istio Ambient Mode tutorial series to prepare an application and deploy it through either the Big Bang packages key or Argo CD. If an application cannot yet run in ambient mode, use the sidecar-mode exception.

Example Configuration

A minimal configuration to enable ambient mode:

istio:
  ambient:
    enabled: true

# The following packages are automatically enabled,
# but you can still override their values if needed:
# ztunnel:
#   values: {}
# istioCNI:
#   values: {}
# gatewayAPI:
#   values: {}

Platform-Specific Configuration

istio-cni

When enabling ambient mode, istio-cni is automatically deployed. Depending on your Kubernetes platform, you may need to customize the CNI configuration. Common platforms that require specific settings include:

  • OpenShift: Requires specific CNI bin/conf directories
  • K3s/K3d: Uses non-standard CNI paths
  • GKE/EKS/AKS: May have platform-specific networking requirements

Refer to the upstream istio-cni values for available configuration options. Override these in your Big Bang values:

istioCNI:
  values:
    cni:
      cniBinDir: /opt/cni/bin       # Customize for your platform
      cniConfDir: /etc/cni/net.d    # Customize for your platform

Sidecar-Mode Exception for Mission Applications

Use sidecar mode only as a compatibility exception for an application that cannot yet run in ambient mode. The namespace must opt out of ambient enrollment and enable sidecar injection.

For a namespace managed outside Big Bang, apply these labels declaratively:

apiVersion: v1
kind: Namespace
metadata:
  name: <application-namespace>
  labels:
    istio.io/dataplane-mode: none
    istio-injection: enabled

For an application deployed through the Big Bang packages key, override the namespace labels:

packages:
  <package-name>:
    namespace:
      labels:
        istio.io/dataplane-mode: none
        istio-injection: enabled

Restart or roll the application workloads after changing namespace enrollment and confirm that each new pod contains an istio-proxy container. Do not apply both ambient enrollment and sidecar injection to the same namespace.

Additional Resources

Big Bang Documentation

Upstream Istio Documentation