package istio.networking.v1alpha3

Get desktop application:
View/edit binary Protocol Buffers messages

Gateway describes a load balancer operating at the edge of the mesh receiving incoming or outgoing HTTP/TCP connections. <!-- go code generation tags +kubetype-gen +kubetype-gen:groupVersion=networking.istio.io/v1alpha3 +genclient +k8s:deepcopy-gen=true -->

• repeated Server servers = 1

  REQUIRED: A list of server specifications.

• map<string, string> selector = 2

  REQUIRED: One or more labels that indicate a specific set of pods/VMs on which this gateway configuration should be applied. The scope of label search is restricted to the configuration namespace in which the the resource is present. In other words, the Gateway resource must reside in the same namespace as the gateway workload instance.

Port describes the properties of a specific port of a service.

Used in: Server, ServiceEntry

• uint32 number = 1

  REQUIRED: A valid non-negative integer port number.

• string protocol = 2

  REQUIRED: The protocol exposed on the port. MUST BE one of HTTP|HTTPS|GRPC|HTTP2|MONGO|TCP|TLS. TLS implies the connection will be routed based on the SNI header to the destination without terminating the TLS connection.

• string name = 3

  Label assigned to the port.

`Server` describes the properties of the proxy on a given load balancer port. For example, ```yaml apiVersion: networking.istio.io/v1alpha3 kind: Gateway metadata: name: my-ingress spec: selector: app: my-ingress-gateway servers: - port: number: 80 name: http2 protocol: HTTP2 hosts: - "*" ``` Another example ```yaml apiVersion: networking.istio.io/v1alpha3 kind: Gateway metadata: name: my-tcp-ingress spec: selector: app: my-tcp-ingress-gateway servers: - port: number: 27018 name: mongo protocol: MONGO hosts: - "*" ``` The following is an example of TLS configuration for port 443 ```yaml apiVersion: networking.istio.io/v1alpha3 kind: Gateway metadata: name: my-tls-ingress spec: selector: app: my-tls-ingress-gateway servers: - port: number: 443 name: https protocol: HTTPS hosts: - "*" tls: mode: SIMPLE serverCertificate: /etc/certs/server.pem privateKey: /etc/certs/privatekey.pem ```

Used in: Gateway

• optional Port port = 1

  REQUIRED: The Port on which the proxy should listen for incoming connections.

• string bind = 4

  $hide_from_docs The ip or the Unix domain socket to which the listener should be bound to. Format: `x.x.x.x` or `unix:///path/to/uds` or `unix://@foobar` (Linux abstract namespace). When using Unix domain sockets, the port number should be 0.

• repeated string hosts = 2

  REQUIRED. One or more hosts exposed by this gateway. While typically applicable to HTTP services, it can also be used for TCP services using TLS with SNI. A host is specified as a `dnsName` with an optional `namespace/` prefix. The `dnsName` should be specified using FQDN format, optionally including a wildcard character in the left-most component (e.g., `prod/*.example.com`). Set the `dnsName` to `*` to select all `VirtualService` hosts from the specified namespace (e.g.,`prod/*`). The `namespace` can be set to `*` or `.`, representing any or the current namespace, respectively. For example, `*/foo.example.com` selects the service from any available namespace while `./foo.example.com` only selects the service from the namespace of the sidecar. The default, if no `namespace/` is specified, is `*/`, that is, select services from any namespace. Any associated `DestinationRule` in the selected namespace will also be used. A `VirtualService` must be bound to the gateway and must have one or more hosts that match the hosts specified in a server. The match could be an exact match or a suffix match with the server's hosts. For example, if the server's hosts specifies `*.example.com`, a `VirtualService` with hosts `dev.example.com` or `prod.example.com` will match. However, a `VirtualService` with host `example.com` or `newexample.com` will not match. NOTE: Only virtual services exported to the gateway's namespace (e.g., `exportTo` value of `*`) can be referenced. Private configurations (e.g., `exportTo` set to `.`) will not be available. Refer to the `exportTo` setting in `VirtualService`, `DestinationRule`, and `ServiceEntry` configurations for details.

• optional Server.TLSOptions tls = 3

  Set of TLS related options that govern the server's behavior. Use these options to control if all http requests should be redirected to https, and the TLS modes to use.

• string default_endpoint = 5

  The loopback IP endpoint or Unix domain socket to which traffic should be forwarded to by default. Format should be `127.0.0.1:PORT` or `unix:///path/to/socket` or `unix://@foobar` (Linux abstract namespace).

Used in: Server

• bool https_redirect = 1

  If set to true, the load balancer will send a 301 redirect for all http connections, asking the clients to use HTTPS.

• TLSOptions.TLSmode mode = 2

  Optional: Indicates whether connections to this port should be secured using TLS. The value of this field determines how TLS is enforced.

• string server_certificate = 3

  REQUIRED if mode is `SIMPLE` or `MUTUAL`. The path to the file holding the server-side TLS certificate to use.

• string private_key = 4

  REQUIRED if mode is `SIMPLE` or `MUTUAL`. The path to the file holding the server's private key.

• string ca_certificates = 5

  REQUIRED if mode is `MUTUAL`. The path to a file containing certificate authority certificates to use in verifying a presented client side certificate.

• string credential_name = 10

  The credentialName stands for a unique identifier that can be used to identify the serverCertificate and the privateKey. The credentialName appended with suffix "-cacert" is used to identify the CaCertificates associated with this server. Gateway workloads capable of fetching credentials from a remote credential store such as Kubernetes secrets, will be configured to retrieve the serverCertificate and the privateKey using credentialName, instead of using the file system paths specified above. If using mutual TLS, gateway workload instances will retrieve the CaCertificates using credentialName-cacert. The semantics of the name are platform dependent. In Kubernetes, the default Istio supplied credential server expects the credentialName to match the name of the Kubernetes secret that holds the server certificate, the private key, and the CA certificate (if using mutual TLS). Set the `ISTIO_META_USER_SDS` metadata variable in the gateway's proxy to enable the dynamic credential fetching feature.

• repeated string subject_alt_names = 6

  A list of alternate names to verify the subject identity in the certificate presented by the client.

• repeated string verify_certificate_spki = 11

  An optional list of base64-encoded SHA-256 hashes of the SKPIs of authorized client certificates. Note: When both verify_certificate_hash and verify_certificate_spki are specified, a hash matching either value will result in the certificate being accepted.

• repeated string verify_certificate_hash = 12

  An optional list of hex-encoded SHA-256 hashes of the authorized client certificates. Both simple and colon separated formats are acceptable. Note: When both verify_certificate_hash and verify_certificate_spki are specified, a hash matching either value will result in the certificate being accepted.

• TLSOptions.TLSProtocol min_protocol_version = 7

  Optional: Minimum TLS protocol version.

• TLSOptions.TLSProtocol max_protocol_version = 8

  Optional: Maximum TLS protocol version.

• repeated string cipher_suites = 9

  Optional: If specified, only support the specified cipher list. Otherwise default to the default cipher list supported by Envoy.

TLS protocol versions.

Used in: TLSOptions

• TLS_AUTO = 0

  Automatically choose the optimal TLS version.

• TLSV1_0 = 1

  TLS version 1.0

• TLSV1_1 = 2

  TLS version 1.1

• TLSV1_2 = 3

  TLS version 1.2

• TLSV1_3 = 4

  TLS version 1.3

TLS modes enforced by the proxy

Used in: TLSOptions

• PASSTHROUGH = 0

  The SNI string presented by the client will be used as the match criterion in a VirtualService TLS route to determine the destination service from the service registry.

• SIMPLE = 1

  Secure connections with standard TLS semantics.

• MUTUAL = 2

  Secure connections to the downstream using mutual TLS by presenting server certificates for authentication.

• AUTO_PASSTHROUGH = 3

  Similar to the passthrough mode, except servers with this TLS mode do not require an associated VirtualService to map from the SNI value to service in the registry. The destination details such as the service/subset/port are encoded in the SNI value. The proxy will forward to the upstream (Envoy) cluster (a group of endpoints) specified by the SNI value. This server is typically used to provide connectivity between services in disparate L3 networks that otherwise do not have direct connectivity between their respective endpoints. Use of this mode assumes that both the source and the destination are using Istio mTLS to secure traffic.

• ISTIO_MUTUAL = 4

  Secure connections from the downstream using mutual TLS by presenting server certificates for authentication. Compared to Mutual mode, this mode uses certificates, representing gateway workload identity, generated automatically by Istio for mTLS authentication. When this mode is used, all other fields in `TLSOptions` should be empty.

ServiceEntry enables adding additional entries into Istio's internal service registry. <!-- go code generation tags +kubetype-gen +kubetype-gen:groupVersion=networking.istio.io/v1alpha3 +genclient +k8s:deepcopy-gen=true -->

• repeated string hosts = 1

  REQUIRED. The hosts associated with the ServiceEntry. Could be a DNS name with wildcard prefix. 1. The hosts field is used to select matching hosts in VirtualServices and DestinationRules. 2. For HTTP traffic the HTTP Host/Authority header will be matched against the hosts field. 3. For HTTPs or TLS traffic containing Server Name Indication (SNI), the SNI value will be matched against the hosts field. Note that when resolution is set to type DNS and no endpoints are specified, the host field will be used as the DNS name of the endpoint to route traffic to.

• repeated string addresses = 2

  The virtual IP addresses associated with the service. Could be CIDR prefix. For HTTP traffic, generated route configurations will include http route domains for both the `addresses` and `hosts` field values and the destination will be identified based on the HTTP Host/Authority header. If one or more IP addresses are specified, the incoming traffic will be identified as belonging to this service if the destination IP matches the IP/CIDRs specified in the addresses field. If the Addresses field is empty, traffic will be identified solely based on the destination port. In such scenarios, the port on which the service is being accessed must not be shared by any other service in the mesh. In other words, the sidecar will behave as a simple TCP proxy, forwarding incoming traffic on a specified port to the specified destination endpoint IP/host. Unix domain socket addresses are not supported in this field.

• repeated Port ports = 3

  REQUIRED. The ports associated with the external service. If the Endpoints are Unix domain socket addresses, there must be exactly one port.

• ServiceEntry.Location location = 4

  Specify whether the service should be considered external to the mesh or part of the mesh.

• ServiceEntry.Resolution resolution = 5

  REQUIRED: Service discovery mode for the hosts. Care must be taken when setting the resolution mode to NONE for a TCP port without accompanying IP addresses. In such cases, traffic to any IP on said port will be allowed (i.e. 0.0.0.0:<port>).

• repeated ServiceEntry.Endpoint endpoints = 6

  One or more endpoints associated with the service.

• repeated string export_to = 7

  A list of namespaces to which this service is exported. Exporting a service allows it to be used by sidecars, gateways and virtual services defined in other namespaces. This feature provides a mechanism for service owners and mesh administrators to control the visibility of services across namespace boundaries. If no namespaces are specified then the service is exported to all namespaces by default. The value "." is reserved and defines an export to the same namespace that the service is declared in. Similarly the value "*" is reserved and defines an export to all namespaces. For a Kubernetes Service, the equivalent effect can be achieved by setting the annotation "networking.istio.io/exportTo" to a comma-separated list of namespace names. NOTE: in the current release, the `exportTo` value is restricted to "." or "*" (i.e., the current namespace or all namespaces).

• repeated string subject_alt_names = 8

  The list of subject alternate names allowed for workload instances that implement this service. This information is used to enforce [secure-naming](https://istio.io/docs/concepts/security/#secure-naming). If specified, the proxy will verify that the server certificate's subject alternate name matches one of the specified values.

Endpoint defines a network address (IP or hostname) associated with the mesh service.

Used in: ServiceEntry

• string address = 1

  REQUIRED: Address associated with the network endpoint without the port. Domain names can be used if and only if the resolution is set to DNS, and must be fully-qualified without wildcards. Use the form unix:///absolute/path/to/socket for Unix domain socket endpoints.

• map<string, uint32> ports = 2

  Set of ports associated with the endpoint. The ports must be associated with a port name that was declared as part of the service. Do not use for `unix://` addresses.

• map<string, string> labels = 3

  One or more labels associated with the endpoint.

• string network = 4

  Network enables Istio to group endpoints resident in the same L3 domain/network. All endpoints in the same network are assumed to be directly reachable from one another. When endpoints in different networks cannot reach each other directly, an Istio Gateway can be used to establish connectivity (usually using the AUTO_PASSTHROUGH mode in a Gateway Server). This is an advanced configuration used typically for spanning an Istio mesh over multiple clusters.

• string locality = 5

  The locality associated with the endpoint. A locality corresponds to a failure domain (e.g., country/region/zone). Arbitrary failure domain hierarchies can be represented by separating each encapsulating failure domain by /. For example, the locality of an an endpoint in US, in US-East-1 region, within availability zone az-1, in data center rack r11 can be represented as us/us-east-1/az-1/r11. Istio will configure the sidecar to route to endpoints within the same locality as the sidecar. If none of the endpoints in the locality are available, endpoints parent locality (but within the same network ID) will be chosen. For example, if there are two endpoints in same network (networkID "n1"), say e1 with locality us/us-east-1/az-1/r11 and e2 with locality us/us-east-1/az-2/r12, a sidecar from us/us-east-1/az-1/r11 locality will prefer e1 from the same locality over e2 from a different locality. Endpoint e2 could be the IP associated with a gateway (that bridges networks n1 and n2), or the IP associated with a standard service endpoint.

• uint32 weight = 6

  The load balancing weight associated with the endpoint. Endpoints with higher weights will receive proportionally higher traffic.

Location specifies whether the service is part of Istio mesh or outside the mesh. Location determines the behavior of several features, such as service-to-service mTLS authentication, policy enforcement, etc. When communicating with services outside the mesh, Istio's mTLS authentication is disabled, and policy enforcement is performed on the client-side as opposed to server-side.

Used in: ServiceEntry

• MESH_EXTERNAL = 0

  Signifies that the service is external to the mesh. Typically used to indicate external services consumed through APIs.

• MESH_INTERNAL = 1

  Signifies that the service is part of the mesh. Typically used to indicate services added explicitly as part of expanding the service mesh to include unmanaged infrastructure (e.g., VMs added to a Kubernetes based service mesh).

Resolution determines how the proxy will resolve the IP addresses of the network endpoints associated with the service, so that it can route to one of them. The resolution mode specified here has no impact on how the application resolves the IP address associated with the service. The application may still have to use DNS to resolve the service to an IP so that the outbound traffic can be captured by the Proxy. Alternatively, for HTTP services, the application could directly communicate with the proxy (e.g., by setting HTTP_PROXY) to talk to these services.

Used in: ServiceEntry

• NONE = 0

  Assume that incoming connections have already been resolved (to a specific destination IP address). Such connections are typically routed via the proxy using mechanisms such as IP table REDIRECT/ eBPF. After performing any routing related transformations, the proxy will forward the connection to the IP address to which the connection was bound.

• STATIC = 1

  Use the static IP addresses specified in endpoints (see below) as the backing instances associated with the service.

• DNS = 2

  Attempt to resolve the IP address by querying the ambient DNS, during request processing. If no endpoints are specified, the proxy will resolve the DNS address specified in the hosts field, if wildcards are not used. If endpoints are specified, the DNS addresses specified in the endpoints will be resolved to determine the destination IP address. DNS resolution cannot be used with Unix domain socket endpoints.