discovery.proto (proto)

Warning: Derived from https://github.com/istio/ztunnel/blob/e36680f1534fae3d158964500ae9185495ec5d7b/proto/workload.proto with the following changes:

change go_package;
append bootstrap extension stub;

.istio.workload.Workload

[.istio.workload.Workload proto]

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.

{
  "uid": ...,
  "name": ...,
  "namespace": ...,
  "addresses": [],
  "hostname": ...,
  "network": ...,
  "tunnel_protocol": ...,
  "trust_domain": ...,
  "service_account": ...,
  "waypoint": {...},
  "network_gateway": {...},
  "node": ...,
  "canonical_name": ...,
  "canonical_revision": ...,
  "workload_type": ...,
  "workload_name": ...,
  "native_tunnel": ...,
  "application_tunnel": {...},
  "services": {...},
  "authorization_policies": [],
  "status": ...,
  "cluster_id": ...,
  "locality": {...},
  "network_mode": ...
}

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: (repeated bytes) 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: (.istio.workload.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: (.istio.workload.GatewayAddress) If present, the waypoint proxy for this workload. All incoming requests must go through the waypoint.

network_gateway: (.istio.workload.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: (.istio.workload.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: (.istio.workload.ApplicationTunnel) If an application, such as a sandwiched waypoint proxy, supports directly receiving information from zTunnel they can set application_protocol.

services: (.istio.workload.Workload.ServicesEntry) The services for which this workload is an endpoint. The key is the NamespacedHostname string of the format namespace/hostname.

authorization_policies: (repeated string) 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: (.istio.workload.WorkloadStatus)

cluster_id: (string) The cluster ID that the workload instance belongs to

locality: (.istio.workload.Locality) The Locality defines information about where a workload is geographically deployed

network_mode: (.istio.workload.NetworkMode)

.istio.workload.Locality

[.istio.workload.Locality proto]

{
  "region": ...,
  "zone": ...,
  "subzone": ...
}

region: (string)

zone: (string)

subzone: (string)

.istio.workload.PortList

[.istio.workload.PortList proto]

This represents the ports for a service

{
  "ports": []
}

ports: (repeated .istio.workload.Port)

.istio.workload.Port

[.istio.workload.Port proto]

{
  "service_port": ...,
  "target_port": ...
}

service_port: (uint32) Port the service is reached at (frontend).

target_port: (uint32) Port the service forwards to (backend).

.istio.workload.ApplicationTunnel

[.istio.workload.ApplicationTunnel proto]

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

{
  "protocol": ...,
  "port": ...
}

protocol: (.istio.workload.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

Enum .istio.workload.ApplicationTunnel.Protocol

[.istio.workload.ApplicationTunnel.Protocol proto]

NONE: (DEFAULT) ⁣Bytes are copied from the inner stream without modification.

PROXY: ⁣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

.istio.workload.GatewayAddress

[.istio.workload.GatewayAddress proto]

GatewayAddress represents the address of a gateway

{
  "hostname": {...},
  "address": {...},
  "hbone_mtls_port": ...
}

hostname

(.istio.workload.NamespacedHostname) TODO: add support for hostname lookup

address can either be a hostname (ex: gateway.example.com) or an IP (ex: 1.2.3.4).

Only one of hostname, address may be set.

address

(.istio.workload.NetworkAddress) address can either be a hostname (ex: gateway.example.com) or an IP (ex: 1.2.3.4).

Only one of hostname, address may be set.

hbone_mtls_port: (uint32) port to reach the gateway at for mTLS HBONE connections

.istio.workload.NetworkAddress

[.istio.workload.NetworkAddress proto]

NetworkAddress represents an address bound to a specific network.

{
  "network": ...,
  "address": ...
}

network: (string) Network represents the network this address is on.

address: (bytes) Address presents the IP (v4 or v6).

.istio.workload.NamespacedHostname

[.istio.workload.NamespacedHostname proto]

NamespacedHostname represents a service bound to a specific namespace.

{
  "namespace": ...,
  "hostname": ...
}

namespace: (string) The namespace the service is in.

hostname: (string) hostname (ex: gateway.example.com)

Enum .istio.workload.NetworkMode

[.istio.workload.NetworkMode proto]

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

STANDARD: (DEFAULT) ⁣STANDARD means that the workload is uniquely identified by its address (within its network).

HOST_NETWORK: ⁣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).