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.

Used in: Port

• UNKNOWN = 0

• HTTP11 = 1

• HTTP2 = 2

• GRPC = 3

• TCP = 4

• TLS = 5

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

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

Used in: security.Authorization, security.Match, Service, Workload

• string name = 1

  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.

• optional google.protobuf.Any config = 2

  config provides some opaque configuration.

GatewayAddress represents the address of a gateway

Used in: Service, WeightedWaypoint, 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

Used in: Service

• 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

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.

• LoadBalancing.HealthPolicy health_policy = 3

  health_policy defines how we should filter endpoints

Used in: LoadBalancing

• ONLY_HEALTHY = 0

  Only select healthy endpoints

• ALLOW_ALL = 1

  Include all endpoints, even if they are unhealthy.

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

• PASSTHROUGH = 3

  In PASSTHROUGH mode, endpoint selection will not be done and traffic passes directly through to the original desitnation address.

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

• optional uint32 length = 3

  CIDR prefix length. If absent, this is a host address (/32 or /128). If present, this represents a CIDR range (e.g., 24 for /24).

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

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

• AppProtocol app_protocol = 3

  Application level protocol

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

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

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

• IPFamilies ip_families = 9

  IP families provides configuration about the IP families this service supports.

• repeated Extension extensions = 10

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

• bool canonical = 11

  canonical marks this Service as taking priority during hostname lookups, when there is not a match in the namespace of the client.

• bool ingress_use_waypoint = 12

  ingress_use_waypoint indicates that ingress gateways should send traffic destined for this service through the service's waypoint proxy. This is controlled by the istio.io/ingress-use-waypoint label on the Service or its namespace.

• repeated WeightedWaypoint weighted_waypoints = 13

  weighted_waypoints, when non-empty, describes a weighted set of waypoints for this service, and the client dataplane selects one waypoint per connection proportional to each entry's weight. This is used to shift a configurable share of a service's in-mesh connections from one waypoint to another (for example, a canary migration between two waypoint revisions or implementations). When this is empty, the single `waypoint` field is used exactly as before. When it is set, `waypoint` remains populated with the primary waypoint so that dataplanes which do not understand this field continue to send all traffic to the primary.

• Service.Visibility visibility = 14

  visibility controls which clients this service is resolvable by. When unset it defaults to PUBLIC. Services that a mesh administrator has scoped to no visibility at all are simply not sent, so they do not appear here.

Visibility controls which clients can resolve and send traffic to a service.

Used in: Service

• PUBLIC = 0

  Visible to every client the control plane serves. This is the default, and matches the behavior before this field was introduced.

• NAMESPACE = 1

  Visible only to clients in the same namespace as the service.

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.

• LEGACY_ISTIO_MTLS = 2

  The workload supports the legacy "istio" mTLS (without HBONE tunnel). Note: ztunnel does not support sending legacy Istio mTLS.

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

WeightedWaypoint is a single waypoint together with the relative weight for selecting it out of a weighted set (see Service.weighted_waypoints).

Used in: Service

• optional GatewayAddress destination = 1

  The waypoint address, in the same form as Service.waypoint. The destination identity is resolved from the waypoint's own workload record at connect time, exactly as for the single-waypoint field; this message adds no identity.

• uint32 weight = 2

  Relative weight for selecting this waypoint. The realized share of connections sent to this waypoint is weight / (sum of weights in the set). A weight of 0 means the waypoint is described (and may be validated/reported) but receives no traffic.

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.

• 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

• repeated Extension extensions = 26

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

• optional google.protobuf.UInt32Value capacity = 27

  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.

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