Protocol Documentation

ca_ztunnel.proto
workload_ztunnel.proto
zds_ztunnel.proto
Scalar Value Types

ca_ztunnel.proto

IstioCertificateRequest

Certificate request message. The authentication should be based on:

Bearer tokens carried in the side channel;
Client-side certificate via Mutual TLS handshake. Note: the service implementation is REQUIRED to verify the authenticated caller is authorize to all SANs in the CSR. The server side may overwrite any requested certificate field based on its policies.

Field	Type	Description
csr	string	PEM-encoded certificate request. The public key in the CSR is used to generate the certificate, and other fields in the generated certificate may be overwritten by the CA.
validity_duration	int64	Optional: requested certificate validity period, in seconds.
metadata	google.protobuf.Struct	$hide_from_docs Optional: Opaque metadata provided by the XDS node to Istio. Supported metadata: WorkloadName, WorkloadIP, ClusterID

IstioCertificateResponse

Certificate response message.

Field	Type	Label	Description
cert_chain	string	repeated	PEM-encoded certificate chain. The leaf cert is the first element, and the root cert is the last element.

IstioCertificateService

Service for managing certificates issued by the CA.

Method Name	Request Type	Response Type	Description
CreateCertificate	IstioCertificateRequest	IstioCertificateResponse	Using provided CSR, returns a signed certificate.

workload_ztunnel.proto

Address

Address represents a unique address.

Address joins two sub-resources, Workload and Service, to support querying by IP address. Address is intended to be able to be looked up on-demand, allowing a client to answer a question like "what is this IP address", similar to a reverse DNS lookup.

Each resource will have a mesh-wide unique opaque name, defined in the individual messages. In addition, to support lookup by IP address, they will have alias names for each IP the resource represents. There may be multiple aliases for the same resource (examples: service in multiple networks, or a dual-stack workload). Aliases are keyed by network/IP address. Example: "default/1.2.3.4".

In some cases, we do not know the IP address of a Workload. For instance, we may simply know that there is a workload behind a gateway, and rely on the gateway to handle the rest. In this case, the key format will be "resource-uid". The resource can be a Pod, WorkloadEntry, etc. These resources cannot be looked up on-demand.

In some cases, we do not know the IP address of a Service. These services cannot be used for matching outbound traffic, as we only have L4 attributes to route based on. However, they can be used for Gateways. In this case, the key format will be "network/hostname". These resources cannot be looked up on-demand.

Field	Type	Label	Description
workload	Workload		Workload represents an individual workload. This could be a single Pod, a VM instance, etc.
service	Service		Service represents a service - a group of workloads that can be accessed together.

ApplicationTunnel

ApplicationProtocol specifies a workload (application or gateway) can consume tunnel information.

Field	Type	Label	Description
protocol	ApplicationTunnel.Protocol		A target natively handles this type of traffic.
port	uint32		optional: if set, traffic should be sent to this port after the last zTunnel hop

Extension

Extension provides a mechanism to attach arbitrary additional configuration to an object.

Field	Type	Label	Description
name	string		name provides an opaque name for the extension. This may have semantic meaning or used for debugging. This should be unique amongst all extensions attached to an item.
config	google.protobuf.Any		config provides some opaque configuration.

GatewayAddress

GatewayAddress represents the address of a gateway

Field	Type	Description
hostname	NamespacedHostname	TODO: add support for hostname lookup
address	NetworkAddress
hbone_mtls_port	uint32	port to reach the gateway at for mTLS HBONE connections

LoadBalancing

Field	Type	Label	Description
routing_preference	LoadBalancing.Scope	repeated	routing_preference defines what scopes we want to keep traffic within. The `mode` determines how these routing preferences are handled
mode	LoadBalancing.Mode		mode defines how we should handle the routing preferences.
health_policy	LoadBalancing.HealthPolicy		health_policy defines how we should filter endpoints

Locality

Field	Type	Label	Description
region	string
zone	string
subzone	string

NamespacedHostname

NamespacedHostname represents a service bound to a specific namespace.

Field	Type	Label	Description
namespace	string		The namespace the service is in.
hostname	string		hostname (ex: gateway.example.com)

NetworkAddress

NetworkAddress represents an address bound to a specific network.

Field	Type	Label	Description
network	string		Network represents the network this address is on.
address	bytes		Address presents the IP (v4 or v6).

Port

Field	Type	Label	Description
service_port	uint32		Port the service is reached at (frontend).
target_port	uint32		Port the service forwards to (backend).

PortList

PorList represents the ports for a service

Field	Type	Label	Description
ports	Port	repeated

Service

Service represents a service - a group of workloads that can be accessed together. The xds primary key is "namespace/hostname". Secondary (alias) keys are the unique network/IP pairs that the service can be reached at.

Field	Type	Label	Description
name	string		Name represents the name for the service. For Kubernetes, this is the Service name.
namespace	string		Namespace represents the namespace for the service.
hostname	string		Hostname represents the FQDN of the service. For Kubernetes, this would be <name>.<namespace>.svc.<cluster domain>.
addresses	NetworkAddress	repeated	Address represents the addresses the service can be reached at. There may be multiple addresses for a single service if it resides in multiple networks, multiple clusters, and/or if it's dual stack. For a headless kubernetes service, this list will be empty.
ports	Port	repeated	Ports for the service. The target_port may be overridden on a per-workload basis.
subject_alt_names	string	repeated	Optional; if set, the SAN to verify for TLS connections. Typically, this is not set and per-workload identity is used to verify
waypoint	GatewayAddress		Waypoint is the waypoint proxy for this service. When set, all incoming requests must go through the waypoint.
load_balancing	LoadBalancing		Load balancing policy for selecting endpoints. Note: this applies only to connecting directly to the workload; when waypoints are used, the waypoint's load_balancing configuration is used.
ip_families	IPFamilies		IP families provides configuration about the IP families this service supports.
extensions	Extension	repeated	Extension provides a mechanism to attach arbitrary additional configuration to an object.

Workload

Workload represents a workload - an endpoint (or collection behind a hostname). The xds primary key is "uid" as defined on the workload below. Secondary (alias) keys are the unique network/IP pairs that the workload can be reached at.

Field	Type	Label	Description
uid	string		UID represents a globally unique opaque identifier for this workload. For k8s resources, it is recommended to use the more readable format:

cluster/group/kind/namespace/name/section-name

As an example, a ServiceEntry with two WorkloadEntries inlined could become two Workloads with the following UIDs: - cluster1/networking.istio.io/v1alpha3/ServiceEntry/default/external-svc/endpoint1 - cluster1/networking.istio.io/v1alpha3/ServiceEntry/default/external-svc/endpoint2

For VMs and other workloads other formats are also supported; for example, a single UID string: "0ae5c03d-5fb3-4eb9-9de8-2bd4b51606ba" | | name | string | | Name represents the name for the workload. For Kubernetes, this is the pod name. This is just for debugging and may be elided as an optimization. | | namespace | string | | Namespace represents the namespace for the workload. This is just for debugging and may be elided as an optimization. | | addresses | bytes | repeated | Address represents the IPv4/IPv6 address for the workload. This should be globally unique. This should not have a port number. Each workload must have at least either an address or hostname; not both. | | hostname | string | | The hostname for the workload to be resolved by the ztunnel. DNS queries are sent on-demand by default. If the resolved DNS query has several endpoints, the request will be forwarded to the first response.

At a minimum, each workload must have either an address or hostname. For example, a workload that backs a Kubernetes service will typically have only endpoints. A workload that backs a headless Kubernetes service, however, will have both addresses as well as a hostname used for direct access to the headless endpoint. | | network | string | | Network represents the network this workload is on. This may be elided for the default network. A (network,address) pair makeup a unique key for a workload at a point in time. | | tunnel_protocol | TunnelProtocol | | Protocol that should be used to connect to this workload. | | trust_domain | string | | The SPIFFE identity of the workload. The identity is joined to form spiffe://<trust_domain>/ns/<namespace>/sa/<service_account>. TrustDomain of the workload. May be elided if this is the mesh wide default (typically cluster.local) | | service_account | string | | ServiceAccount of the workload. May be elided if this is "default" | | waypoint | GatewayAddress | | If present, the waypoint proxy for this workload. All incoming requests must go through the waypoint. | | network_gateway | GatewayAddress | | If present, East West network gateway this workload can be reached through. Requests from remote networks should traverse this gateway. | | node | string | | Name of the node the workload runs on | | canonical_name | string | | CanonicalName for the workload. Used for telemetry. | | canonical_revision | string | | CanonicalRevision for the workload. Used for telemetry. | | workload_type | WorkloadType | | WorkloadType represents the type of the workload. Used for telemetry. | | workload_name | string | | WorkloadName represents the name for the workload (of type WorkloadType). Used for telemetry. | | native_tunnel | bool | | If set, this indicates a workload expects to directly receive tunnel traffic. In ztunnel, this means: * Requests from this workload do not need to be tunneled if they already are tunneled by the tunnel_protocol. * Requests to this workload, via the tunnel_protocol, do not need to be de-tunneled. | | application_tunnel | ApplicationTunnel | | If an application, such as a sandwiched waypoint proxy, supports directly receiving information from zTunnel they can set application_protocol. | | services | Workload.ServicesEntry | repeated | The services for which this workload is an endpoint. The key is the NamespacedHostname string of the format namespace/hostname. | | authorization_policies | string | repeated | A list of authorization policies applicable to this workload. NOTE: this only includes Selector based policies. Namespace and global polices are returned out of band. Authorization policies are only valid for workloads with addresses rather than hostname. | | status | WorkloadStatus | | | | cluster_id | string | | The cluster ID that the workload instance belongs to | | locality | Locality | | The Locality defines information about where a workload is geographically deployed | | network_mode | NetworkMode | | | | extensions | Extension | repeated | Extension provides a mechanism to attach arbitrary additional configuration to an object. | | capacity | google.protobuf.UInt32Value | | Capacity for this workload. This represents the amount of traffic the workload can handle, relative to other workloads If unset, the capacity is default to 1. |

Workload.ServicesEntry

Field	Type	Label	Description
key	string
value	PortList

ApplicationTunnel.Protocol

Name	Number	Description
NONE	0	Bytes are copied from the inner stream without modification.
PROXY	1	Prepend PROXY protocol headers before copying bytes Standard PROXY source and destination information is included, along with potential extra TLV headers: 0xD0 - The SPIFFE identity of the source workload 0xD1 - The FQDN or Hostname of the targeted Service

IPFamilies

Name	Number	Description
AUTOMATIC	0	AUTOMATIC is inferred from the configured addresses.
IPV4_ONLY	1	Only IPv4 is supported
IPV6_ONLY	2	Only IPv6 is supported
DUAL	3	Both IPv4 and IPv6 is supported

LoadBalancing.HealthPolicy

Name	Number	Description
ONLY_HEALTHY	0	Only select healthy endpoints
ALLOW_ALL	1	Include all endpoints, even if they are unhealthy.

LoadBalancing.Mode

Name	Number	Description
UNSPECIFIED_MODE	0
STRICT	1	In STRICT mode, only endpoints that meets all of the routing preferences will be considered. This can be used, for instance, to keep traffic ONLY within the same cluster/node/region. This should be used with caution, as it can result in all traffic being dropped if there is no matching endpoints, even if there are endpoints outside of the preferences.
FAILOVER	2	In FAILOVER mode, endpoint selection will prefer endpoints that match all preferences, but failover to groups of endpoints that match less (or, eventually, none) preferences. For instance, with `[NETWORK, REGION, ZONE]`, we will send to: 1. Endpoints matching `[NETWORK, REGION, ZONE]` 2. Endpoints matching `[NETWORK, REGION]` 3. Endpoints matching `[NETWORK]` 4. Any endpoints

LoadBalancing.Scope

Name	Number	Description
UNSPECIFIED_SCOPE	0
REGION	1	Prefer traffic in the same region.
ZONE	2	Prefer traffic in the same zone.
SUBZONE	3	Prefer traffic in the same subzone.
NODE	4	Prefer traffic on the same node.
CLUSTER	5	Prefer traffic in the same cluster.
NETWORK	6	Prefer traffic in the same network.

NetworkMode

NetworkMode indicates how the addresses of the workload should be treated.

Name	Number	Description
STANDARD	0	STANDARD means that the workload is uniquely identified by its address (within its network).
HOST_NETWORK	1	HOST_NETWORK means the workload has an IP address that is shared by many workloads. The data plane should avoid attempting to lookup these workloads by IP address (which could return the wrong result).

TunnelProtocol

TunnelProtocol indicates the tunneling protocol for requests.

Name	Number	Description
NONE	0	NONE means requests should be forwarded as-is, without tunneling.
HBONE	1	HBONE means requests should be tunneled over HTTP. This does not dictate HTTP/1.1 vs HTTP/2; ALPN should be used for that purpose.

Future options may include things like QUIC/HTTP3, etc. |

WorkloadStatus

Name	Number	Description
HEALTHY	0	Workload is healthy and ready to serve traffic.
UNHEALTHY	1	Workload is unhealthy and NOT ready to serve traffic.

WorkloadType

Name	Number	Description
DEPLOYMENT	0
CRONJOB	1
POD	2
JOB	3

zds_ztunnel.proto

Ack

Ztunnel ack message. If error is not empty, this is an error message.

Field	Type	Label	Description
error	string

AddWorkload

Add a workload to the ztunnel. This will be accompanied by ancillary data containing the workload's netns file descriptor.

Field	Type	Label	Description
uid	string
workload_info	WorkloadInfo

DelWorkload

Delete a workload from the ztunnel. Ztunnel should shutdown the workload's proxy.

Field	Type	Label	Description
uid	string

KeepWorkload

Keep workload that we can't find in the fd cache. This can only be sent before SnapshotSent is sent to signal ztunnel to not delete the workload if it has it.

Field	Type	Label	Description
uid	string

SnapshotSent

Let ztunnel know that a full snapshot was sent. Ztunnel should reconcile its internal state and remove internal entries that were not sent.

WorkloadInfo

Field	Type	Label	Description
name	string
namespace	string
service_account	string

WorkloadRequest

Sent from CNI to ztunnel

Field	Type	Label	Description
add	AddWorkload
keep	KeepWorkload
del	DelWorkload
snapshot_sent	SnapshotSent

WorkloadResponse

Sent from ztunnel to CNI

Field	Type	Label	Description
ack	Ack

ZdsHello

Field	Type	Label	Description
version	Version

Version

Name	Number	Description
NOT_USED	0
V1	1

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
<a name="double" /> double		double	double	float	float64	double	float	Float
<a name="float" /> float		float	float	float	float32	float	float	Float
<a name="int32" /> int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
<a name="int64" /> int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
<a name="uint32" /> uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
<a name="uint64" /> uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
<a name="sint32" /> sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
<a name="sint64" /> sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
<a name="fixed32" /> fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
<a name="fixed64" /> fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
<a name="sfixed32" /> sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
<a name="sfixed64" /> sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
<a name="bool" /> bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
<a name="string" /> string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
<a name="bytes" /> bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)

Protocol Documentation

Protocol Documentation

Table of Contents

ca_ztunnel.proto

IstioCertificateRequest

IstioCertificateResponse

IstioCertificateService

workload_ztunnel.proto

Address

ApplicationTunnel

Extension

GatewayAddress

LoadBalancing

Locality

NamespacedHostname

NetworkAddress

Port

PortList

Service

Workload

Workload.ServicesEntry

ApplicationTunnel.Protocol

IPFamilies

LoadBalancing.HealthPolicy

LoadBalancing.Mode

LoadBalancing.Scope

NetworkMode

TunnelProtocol

WorkloadStatus

WorkloadType

zds_ztunnel.proto

Ack

AddWorkload

DelWorkload

KeepWorkload

SnapshotSent

WorkloadInfo

WorkloadRequest

WorkloadResponse

ZdsHello

Version

Scalar Value Types