Istio Ambient Usage Guide

--- title: Istio Ambient Usage Guide description: Comprehensive guide to using Istio Ambient mesh and Ztunnel proxy. weight: 2 owner: istio/wg-networking-maintainers test: n/a --- ## Introduction Welcome to the Istio Ambient Usage Guide, a comprehensive resource for understanding and utilizing Istio's Ambient mesh and Ztunnel proxy. This guide will walk you through the functionality, installation, and various aspects of Ambient mesh, with a focus on Ztunnel and basic Layer-4 networking functions. ## Table of Contents 1. [Installation](#installation) 1. [Pre-requisites & Supported Topologies](#pre-requisites--supported-topologies) 2. [Understanding the Ztunnel Default Configuration](#understanding-the-ztunnel-default-configuration) 3. [Installation using istioctl](#installation-using-istioctl) 4. [Installation using Helm charts](#installation-using-helm-charts) 5. [Verifying Installation](#verifying-installation) 2. [Functional Overview](#functional-overview) - Architecture and Components - xDS API Overview - Multi-tenant Considerations 3. [Deploying an Application](#deploying-an-application) - Non-Istio Deployment - Enabling Ambient Mode 4. [Understanding Mutual-TLS in Istio Ambient](#understanding-mutual-tls-in-istio-ambient) - Differences from Sidecar-Based M-TLS - PeerAuthentication Policy - Monitoring M-TLS Signaling 5. [Layer-4 Authorization Policy](#l4-authorization-policy) - Configuration and Use Cases 6. [Monitoring and Telemetry with Ztunnel](#monitoring-and-telemetry-with-ztunnel) - Telemetry Considerations - Observability Strategies 7. [Co-existence of Ambient with Sidecar Proxies](#co-existence-of-ambient-with-sidecar-proxies) - Mixed Deployment Considerations - Using PeerAuthentication 8. [Troubleshooting](#troubleshooting) - Debugging Connectivity Issues - Diagnosing Traffic Flow - Common Error Scenarios 9. [Best Practices](#best-practices) - Namespace and Annotation Strategy - Certificates and Identity Management - Security Considerations 10. [Conclusion](#conclusion) - Recap and Next Steps ## 1. Installation ### 1.1 Pre-requisites & Supported Topologies ... ### 1.2 Understanding the Ztunnel Default Configuration ... ### 1.3 Installation using istioctl ... ### 1.4 Installation using Helm charts ... ### 1.5 Verifying Installation ... ## 2. Functional Overview ### Functional Overview The Ztunnel proxy is designed for secure connectivity and authentication within the Ambient mesh. It supports mTLS, authentication, L4 authorization, and telemetry, focusing on East-West mesh networking. Ztunnel forwards traffic to waypoint proxies, enabling Istio's full functionality. ## Installation ### Pre-requisites & Supported Topologies - Ztunnel proxies are installed with supported Istio Ambient mesh installation methods. - Minimum Istio version required: 1.18.0. - Ambient mode supported only on Kubernetes clusters. - Single-cluster deployments supported; limited multi-cluster support. - L4 networking supports Istio-native ingress/egress gateways and Kubernetes Gateway API. ## 3. Deploying an Application #### Deploying an Application - Istio admin user deploys Istio mesh in `ambient` mode. - Applications within Istio namespaces can access Istio's features. - Example deployment of HTTP client-server application without Istio integration. #### Pod selection logic for Ambient and Sidecar modes - Describe the logic of pod selection for `ambient` and sidecar modes. - Recommend using PeerAuthentication resource for mixed scenarios. ## 4. Understanding Mutual-TLS in Istio Ambient ### Mutual-TLS in Istio Ambient - Highlight differences in mutual-TLS for `ambient` and sidecar modes. - Explain how PeerAuthentication policies affect `ambient` mode. # Ztunnel and Layer-4 Networking Functions This section covers the core concepts, installation, and basic usage of Ztunnel and Layer-4 networking functions in Istio's Ambient mesh. ## 5. Layer-4 Authorization Policy ### Basic Layer-4 Networking Functions Explore the basics of Layer-4 networking in Istio's Ambient mesh, with a focus on Mutual-TLS. #### Minimum Istio Version Ensure you're using Istio 1.18.0 or later for the functionality described in this guide. #### Supported Deployments Understand the supported deployment scenarios for Ambient mode. #### Traffic Redirect Options Learn about traffic redirection options available in Ambient mode. #### Use of istioOperator Discover the role of istioOperator in Ambient mode installations. > - Here I will provide comprehensive guide on utilizing L4 authorization policies. > - Will Include examples and best practices for securing L4 traffic. > ## 6. Monitoring and Telemetry with Ztunnel > - Here I will discuss monitoring and telemetry setup with Ztunnel. > - We can cover Prometheus metrics, tracing, and other monitoring options. ### Ztunnel: Secure Workload Communication The Ztunnel (Zero Trust Tunnel) component is purpose-built for Istio ambient mesh, focusing on secure connections and authentication within the mesh. ### Understanding the Ztunnel Default Configuration - Ztunnel is configured out-of-the-box with minimal customization. - Use the `ambient` profile setting for initial configuration. - Future configurability options may be added. - Fixed default configurations for different networking setups. #### Installation Ztunnel proxies are automatically installed when Istio is deployed with the Ambient profile. ##### Installation using istioctl ##### Installation using Helm charts ##### Installation using istioOperator #### Verifying Istio Ambient Installation Learn how to confirm proper Istio installation and configuration in Ambient mode. ### Functional Overview Get a summarized architectural overview of the Ztunnel proxy and its function within Ambient mesh. ![Ztunnel Architecture](ztunnel-architecture.png) *Caption: Ztunnel architecture* ## 7. Co-existence of Ambient with Sidecar Proxies > - Will explore the co-existence of `ambient` Ztunnels and sidecar proxies. > - Will provide guidelines and best practices for mixed environments. ## 8. Troubleshooting ... ## 9. Best Practices ... ## 10. Conclusion ... ## Additional Topics (Future Guides) Here's a list of topics to explore in separate guides as the Ambient mode evolves: - Comprehensive Get Started Guide (completed) - Demo or Quickstart for Ambient Mesh (wip) - How to Operate Ambient Mesh Guide (wip) - How to Attach Policies to Waypoints (wip) - Waypoint Proxy Usage and L7 Policies (wip) - Transitioning from Sidecars: When to Choose (wip) - Monitoring and Telemetry with Ztunnel (wip) - Coexistence of Ambient and Sidecar Proxies (wip)