package istio.workload

Get desktop application:
View/edit binary Protocol Buffers messages

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.

• oneof type

  • Workload workload = 1

    Workload represents an individual workload. This could be a single Pod, a VM instance, etc.

  • Service service = 2

    Service represents a service - a group of workloads that can be accessed together.

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

Used in: Workload

• ApplicationTunnel.Protocol protocol = 1

  A target natively handles this type of traffic.

• uint32 port = 2

  optional: if set, traffic should be sent to this port after the last zTunnel hop

Used in: ApplicationTunnel

• 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

GatewayAddress represents the address of a gateway

Used in: Service, Workload

• oneof destination

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

  • NamespacedHostname hostname = 1

    TODO: add support for hostname lookup

  • NetworkAddress address = 2

• uint32 hbone_mtls_port = 3

  port to reach the gateway at for mTLS HBONE connections

• uint32 hbone_single_tls_port = 4

  port to reach the gateway at for single tls HBONE connections used for sending unauthenticated traffic originating outside the mesh to a waypoint-enabled destination A value of 0 = unset

Used in: Service

• repeated LoadBalancing.Scope routing_preference = 1

  routing_preference defines what scopes we want to keep traffic within. The `mode` determines how these routing preferences are handled

• LoadBalancing.Mode mode = 2

  mode defines how we should handle the routing preferences.

Used in: LoadBalancing

• 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

Used in: LoadBalancing

• 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.

Used in: Workload

• string region = 1

• string zone = 2

• string subzone = 3

NamespacedHostname represents a service bound to a specific namespace.

Used in: GatewayAddress

• string namespace = 1

  The namespace the service is in.

• string hostname = 2

  hostname (ex: gateway.example.com)

NetworkAddress represents an address bound to a specific network.

Used in: GatewayAddress, Service

• string network = 1

  Network represents the network this address is on.

• bytes address = 2

  Address presents the IP (v4 or v6).

Used in: Workload

• 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).

Used in: PortList, Service

• uint32 service_port = 1

  Port the service is reached at (frontend).

• uint32 target_port = 2

  Port the service forwards to (backend).

PorList represents the ports for a service

Used in: Workload

• repeated Port ports = 1

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.

Used in: Address

• string name = 1

  Name represents the name for the service. For Kubernetes, this is the Service name.

• string namespace = 2

  Namespace represents the namespace for the service.

• string hostname = 3

  Hostname represents the FQDN of the service. For Kubernetes, this would be <name>.<namespace>.svc.<cluster domain>. TODO: support this field

• repeated NetworkAddress addresses = 4

  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 (TODO: support dual stack). For a headless kubernetes service, this list will be empty.

• repeated Port ports = 5

  Ports for the service. The target_port may be overridden on a per-workload basis.

• repeated string subject_alt_names = 6

  Optional; if set, the SAN to verify for TLS connections. Typically, this is not set and per-workload identity is used to verify TODO: support this field

• optional GatewayAddress waypoint = 7

  Waypoint is the waypoint proxy for this service. When set, all incoming requests must go through the waypoint.

• optional LoadBalancing load_balancing = 8

  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.

TunnelProtocol indicates the tunneling protocol for requests.

Used in: Workload

• 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.

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.

Used in: Address

• string uid = 20

  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"

• string name = 1

  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.

• string namespace = 2

  Namespace represents the namespace for the workload. This is just for debugging and may be elided as an optimization.

• repeated bytes addresses = 3

  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.

• string hostname = 21

  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. TODO: support this field

• string network = 4

  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*.

• TunnelProtocol tunnel_protocol = 5

  Protocol that should be used to connect to this workload.

• string trust_domain = 6

  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)

• string service_account = 7

  ServiceAccount of the workload. May be elided if this is "default"

• optional GatewayAddress waypoint = 8

  If present, the waypoint proxy for this workload. All incoming requests must go through the waypoint.

• optional GatewayAddress network_gateway = 19

  If present, East West network gateway this workload can be reached through. Requests from remote networks should traverse this gateway.

• string node = 9

  Name of the node the workload runs on

• string canonical_name = 10

  CanonicalName for the workload. Used for telemetry.

• string canonical_revision = 11

  CanonicalRevision for the workload. Used for telemetry.

• WorkloadType workload_type = 12

  WorkloadType represents the type of the workload. Used for telemetry.

• string workload_name = 13

  WorkloadName represents the name for the workload (of type WorkloadType). Used for telemetry.

• bool native_tunnel = 14

  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.

• optional ApplicationTunnel application_tunnel = 23

  If an application, such as a sandwiched waypoint proxy, supports directly receiving information from zTunnel they can set application_protocol.

• map<string, PortList> services = 22

  The services for which this workload is an endpoint. The key is the NamespacedHostname string of the format namespace/hostname.

• repeated string authorization_policies = 16

  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`.

• WorkloadStatus status = 17

• string cluster_id = 18

  The cluster ID that the workload instance belongs to

• optional Locality locality = 24

  The Locality defines information about where a workload is geographically deployed

• NetworkMode network_mode = 25

Used in: Workload

• HEALTHY = 0

  Workload is healthy and ready to serve traffic.

• UNHEALTHY = 1

  Workload is unhealthy and NOT ready to serve traffic.

Used in: Workload

• DEPLOYMENT = 0

• CRONJOB = 1

• POD = 2

• JOB = 3