# Ztunnel

This document provides an overview of the architecture and design decisions around Ztunnel, the node-proxy component in ambient mode.

## Background and motivation

Motivations to implement ztunnel generally came from two areas.

First, and most importantly, it serves as a means to implement the real goal: waypoints.

This can be reading from Kubernetes and writing other objects back, writing to proxies over XDS, etc.

Unfortunately, writing controllers is very error prone, even for seemingly simple cases.
To work around this, Istio has a variety of abstractions meant to make writing controllers easier.

## Clients

### Writing controllers

  // otherwise identical (parallel requests, requests when earlier requests did not modify etc)
  // The UID is meant to track the round trip (request/response) between the KAS and the WebHook, not the user request.
  // It is suitable for correlating log entries between the webhook and apiserver, for either auditing or debugging.
  optional string uid = 1;

  // request. Valid values are:
  // - All: all dry run stages will be processed
  // +optional
  repeated string dryRun = 5;
}

// Duration is a wrapper around time.Duration which supports correct
// marshaling to YAML and JSON. In particular, it marshals into strings, which
// can be used as map keys in json.
message Duration {
  optional int64 duration = 1;
}

  // The number of seats that other levels can borrow from this level, known
  // as this level's LendableConcurrencyLimit (LendableCL), is defined as follows.
  //
  // LendableCL(i) = round( NominalCL(i) * lendablePercent(i)/100.0 )
  //
  // +optional
  optional int32 lendablePercent = 3;

  // `borrowingLimitPercent`, if present, configures a limit on how many

  // The number of seats that other levels can borrow from this level, known
  // as this level's LendableConcurrencyLimit (LendableCL), is defined as follows.
  //
  // LendableCL(i) = round( NominalCL(i) * lendablePercent(i)/100.0 )
  //
  // +optional
  optional int32 lendablePercent = 3;

  // `borrowingLimitPercent`, if present, configures a limit on how many

  // If no system-wide time zone database can be found a bundled version of the database is used instead.
  // If the time zone name becomes invalid during the lifetime of a CronJob or due to a change in host
  // configuration, the controller will stop creating new new Jobs and will create a system event with the
  // reason UnknownTimeZone.

  // +optional
  optional bool allowVolumeExpansion = 6;

  // volumeBindingMode indicates how PersistentVolumeClaims should be
  // provisioned and bound.  When unset, VolumeBindingImmediate is used.
  // This field is only honored by servers that enable the VolumeScheduling feature.
  // +optional
  optional string volumeBindingMode = 7;

  optional PersistentVolumeClaimSpec spec = 2;
}

// PersistentVolumeClaimVolumeSource references the user's PVC in the same namespace.
// This volume finds the bound PV and mounts that volume for the pod. A
// PersistentVolumeClaimVolumeSource is, essentially, a wrapper around another
// type of volume that is owned by someone else (the system).
message PersistentVolumeClaimVolumeSource {