From 5c99be9b2a5261b2dd82d4d82764f15d7d403351 Mon Sep 17 00:00:00 2001 From: Shriram Rajagopalan Date: Mon, 14 Jan 2019 14:01:33 -0500 Subject: [PATCH] assorted doc updates Signed-off-by: Shriram Rajagopalan --- .../istio.networking.v1alpha3.pb.html | 207 +++++++++++++++++- networking/v1alpha3/sidecar.pb.go | 77 +++++-- networking/v1alpha3/sidecar.proto | 110 +++++----- 3 files changed, 303 insertions(+), 91 deletions(-) diff --git a/networking/v1alpha3/istio.networking.v1alpha3.pb.html b/networking/v1alpha3/istio.networking.v1alpha3.pb.html index 1face7462e..18540c5d6d 100644 --- a/networking/v1alpha3/istio.networking.v1alpha3.pb.html +++ b/networking/v1alpha3/istio.networking.v1alpha3.pb.html @@ -6,7 +6,7 @@ generator: protoc-gen-docs aliases: - /docs/reference/config/istio.routing.v1alpha1/ -number_of_entries: 60 +number_of_entries: 62 ---

Configuration affecting traffic routing. Here are a few terms useful to define in the context of traffic routing.

@@ -37,6 +37,47 @@ application code to decouple itself from the evolution of dependent services.

+

CaptureMode

+
+

CaptureMode describes how traffic to a listener is expected to be +captured. Applicable only when the listener is bound to an IP.

+ + + + + + + + + + + + + + + + + + + + + + +
NameDescription
DEFAULT +

The default capture mode defined by the environment

+ +
IPTABLES +

Capture traffic using IPtables redirection

+ +
NONE +

No traffic capture. When used in egress listener, the application is +expected to explicitly communicate with the listener port/unix +domain socket. When used in ingress listener, care needs to be taken +to ensure that the listener port is not in use by other processes on +the host.

+ +
+

ConfigScope

ConfigScope defines the visibility of an Istio configuration artifact in @@ -2151,12 +2192,43 @@

IstioEgressListener

+ +port +Port + +

The port associated with the listener. If using unix domain socket, +use 0 as the port number, with a valid protocol. The port if +specified, will be used as the default destination port associated +with the imported hosts. If the port is omitted, Istio will infer the +listener ports based on the imported hosts. Note that when multiple +egress listeners are specified, where one or more listeners have +specific ports while others have no port, the hosts exposed on a +listener port will be based on the listener with the most specific +port.

+ + + + +bind +string + +

The ip or the unix domain socket to which the listener should be bound +to. Port MUST be specified if bind is not empty. Format: x.x.x.x or +unix:///path/to/uds or unix://@foobar (Linux abstract namespace). If +omitted, Istio will autoconfigure the defaults based on imported +services, the workload to which this configuration is applied to and +the captureMode. If captureMode is NONE, bind will default to +127.0.0.1.

+ + + captureMode CaptureMode

When the bind address is an IP, the captureMode option dictates -how traffic to the listener is expected to be captured (or not).

+how traffic to the listener is expected to be captured (or not). +captureMode must be DEFAULT or NONE for unix domain socket binds.

@@ -2164,8 +2236,8 @@

IstioEgressListener

hosts string[] -

One or more services/virtualServices exposed by the listener in -namespace/dnsName format. Publicly scoped services and +

REQUIRED: One or more services/virtualServices exposed by the listener +in namespace/dnsName format. Publicly scoped services and VirtualServices from remote namespaces corresponding to the specified hosts will be imported. The service in a namespace can be a service in the service registry (e.g., a kubernetes or cloud foundry service) or @@ -2183,6 +2255,67 @@

IstioEgressListener

imported. Refer to the scope setting associated with VirtualService, DestinationRule, ServiceEntry, etc. for details.

+ + + + +
+

IstioIngressListener

+
+

IstioIngressListener specifies the properties of an inbound +traffic listener on the sidecar proxy attached to a workload.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -3652,8 +3785,9 @@

Sidecar

with a workload selector select the same workload.

The example below delcares a Sidecar resource in the prod-us1 namespace -that configures the sidecar to allow egress traffic to public services -in the prod-us1, prod-apis, and the istio-system namespaces.

+that configures the sidecars in the namespace to allow egress traffic to +public services in the prod-us1, prod-apis, and the istio-system +namespaces.

apiVersion: networking.istio.io/v1alpha3
 kind: Sidecar
@@ -3668,6 +3802,36 @@ 
Sidecar

     - "istio-system/*"
+

The example below delcares a Sidecar resource in the prod-us1 namespace +that accepts inbound HTTP traffic on port 9080 and forwards +it to the attached workload listening on a unix domain socket. In the +egress direction, in addition to the istio-system namespace, the sidecar +proxies only HTTP traffic bound for port 9080 for services in the +prod-us1 namespace.

+ +
apiVersion: networking.istio.io/v1alpha3
+kind: Sidecar
+metadata:
+  name: default
+  namespace: prod-us1
+spec:
+  ingress:
+  - port:
+      number: 9080
+      protocol: HTTP
+      name: somename
+    defaultEndpoint: unix:///var/run/someuds.sock
+  egress:
+  - hosts:
+    - "istio-system/*"
+  - port:
+      number: 9080
+      protocol: HTTP
+      name: egresshttp
+    hosts:
+    - "prod-us1/*"
+
+
FieldTypeDescription
portPort +

REQUIRED. The port associated with the listener. If using +unix domain socket, use 0 as the port number, with a valid +protocol.

+ +
bindstring +

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). If omitted, Istio will autoconfigure the defaults +based on imported services and the workload to which this +configuration is applied to.

+ +
captureModeCaptureMode +

When the bind address is an IP, the captureMode option dictates +how traffic to the listener is expected to be captured (or not). +captureMode must be DEFAULT or NONE for unix domain socket binds.

+ +
defaultEndpointstring +

REQUIRED: The loopback IP endpoint or unix domain socket to which +traffic should be forwarded to. This configuration can be used to +redirect traffic arriving at the bind point on the sidecar to a port +or unix domain socket where the application workload is listening for +connections. Format should be 127.0.0.1:PORT or unix:///path/to/socket

+
@@ -3677,6 +3841,29 @@

Sidecar

+ + + + + + + + + + @@ -4479,10 +4666,10 @@

WorkloadSelector

diff --git a/networking/v1alpha3/sidecar.pb.go b/networking/v1alpha3/sidecar.pb.go index 6c4e074c0f..0c2afe181a 100644 --- a/networking/v1alpha3/sidecar.pb.go +++ b/networking/v1alpha3/sidecar.pb.go @@ -43,7 +43,6 @@ func (x ConfigScope) String() string { } func (ConfigScope) EnumDescriptor() ([]byte, []int) { return fileDescriptorSidecar, []int{0} } -// $hide_from_docs // CaptureMode describes how traffic to a listener is expected to be // captured. Applicable only when the listener is bound to an IP. type CaptureMode int32 @@ -105,8 +104,9 @@ func (CaptureMode) EnumDescriptor() ([]byte, []int) { return fileDescriptorSidec // with a workload selector select the same workload. // // The example below delcares a Sidecar resource in the prod-us1 namespace -// that configures the sidecar to allow egress traffic to public services -// in the prod-us1, prod-apis, and the istio-system namespaces. +// that configures the sidecars in the namespace to allow egress traffic to +// public services in the prod-us1, prod-apis, and the istio-system +// namespaces. // // ```yaml // apiVersion: networking.istio.io/v1alpha3 @@ -122,14 +122,43 @@ func (CaptureMode) EnumDescriptor() ([]byte, []int) { return fileDescriptorSidec // - "istio-system/*" // ``` // +// The example below delcares a Sidecar resource in the prod-us1 namespace +// that accepts inbound HTTP traffic on port 9080 and forwards +// it to the attached workload listening on a unix domain socket. In the +// egress direction, in addition to the istio-system namespace, the sidecar +// proxies only HTTP traffic bound for port 9080 for services in the +// prod-us1 namespace. +// +// ```yaml +// apiVersion: networking.istio.io/v1alpha3 +// kind: Sidecar +// metadata: +// name: default +// namespace: prod-us1 +// spec: +// ingress: +// - port: +// number: 9080 +// protocol: HTTP +// name: somename +// defaultEndpoint: unix:///var/run/someuds.sock +// egress: +// - hosts: +// - "istio-system/*" +// - port: +// number: 9080 +// protocol: HTTP +// name: egresshttp +// hosts: +// - "prod-us1/*" +// ``` +// type Sidecar struct { - // $hide_from_docs // Criteria used to select the specific set of pods/VMs on which this // sidecar configuration should be applied. If omitted, the sidecar - // configuration will be applied to all workloads in the current config + // configuration will be applied to all workloads in the same config // namespace. WorkloadSelector *WorkloadSelector `protobuf:"bytes,1,opt,name=workload_selector,json=workloadSelector" json:"workload_selector,omitempty"` - // $hide_from_docs // Ingress specifies the configuration of the sidecar for processing // inbound traffic to the attached workload. If omitted, Istio will // autoconfigure the sidecar based on the information about the workload @@ -169,7 +198,6 @@ func (m *Sidecar) GetEgress() []*IstioEgressListener { return nil } -// $hide_from_docs // IstioIngressListener specifies the properties of an inbound // traffic listener on the sidecar proxy attached to a workload. type IstioIngressListener struct { @@ -185,11 +213,12 @@ type IstioIngressListener struct { Bind string `protobuf:"bytes,2,opt,name=bind,proto3" json:"bind,omitempty"` // When the bind address is an IP, the captureMode option dictates // how traffic to the listener is expected to be captured (or not). + // captureMode must be DEFAULT or NONE for unix domain socket binds. CaptureMode CaptureMode `protobuf:"varint,3,opt,name=capture_mode,json=captureMode,proto3,enum=istio.networking.v1alpha3.CaptureMode" json:"capture_mode,omitempty"` - // The loopback IP endpoint or unix domain socket to which traffic should - // be forwarded to by default. This configuration can be used to redirect - // traffic arriving at the bind point on the sidecar to a port or unix - // domain socket where the application workload is listening for + // REQUIRED: The loopback IP endpoint or unix domain socket to which + // traffic should be forwarded to. This configuration can be used to + // redirect traffic arriving at the bind point on the sidecar to a port + // or unix domain socket where the application workload is listening for // connections. Format should be 127.0.0.1:PORT or unix:///path/to/socket DefaultEndpoint string `protobuf:"bytes,4,opt,name=default_endpoint,json=defaultEndpoint,proto3" json:"default_endpoint,omitempty"` } @@ -230,7 +259,6 @@ func (m *IstioIngressListener) GetDefaultEndpoint() string { // IstioEgressListener specifies the properties of an outbound traffic // listener on the sidecar proxy attached to a workload. type IstioEgressListener struct { - // $hide_from_docs // The port associated with the listener. If using unix domain socket, // use 0 as the port number, with a valid protocol. The port if // specified, will be used as the default destination port associated @@ -241,19 +269,20 @@ type IstioEgressListener struct { // listener port will be based on the listener with the most specific // port. Port *Port `protobuf:"bytes,1,opt,name=port" json:"port,omitempty"` - // $hide_from_docs // The ip or the unix domain socket to which the listener should be bound - // to. Port MUST be specified if bind is not empty. Format: - // x.x.x.x or unix:///path/to/uds or unix://@foobar (Linux abstract - // namespace). If omitted, Istio will autoconfigure the defaults based on - // imported services and the workload to which this configuration is - // applied to. + // to. Port MUST be specified if bind is not empty. Format: x.x.x.x or + // unix:///path/to/uds or unix://@foobar (Linux abstract namespace). If + // omitted, Istio will autoconfigure the defaults based on imported + // services, the workload to which this configuration is applied to and + // the captureMode. If captureMode is NONE, bind will default to + // 127.0.0.1. Bind string `protobuf:"bytes,2,opt,name=bind,proto3" json:"bind,omitempty"` // When the bind address is an IP, the captureMode option dictates // how traffic to the listener is expected to be captured (or not). + // captureMode must be DEFAULT or NONE for unix domain socket binds. CaptureMode CaptureMode `protobuf:"varint,3,opt,name=capture_mode,json=captureMode,proto3,enum=istio.networking.v1alpha3.CaptureMode" json:"capture_mode,omitempty"` - // One or more services/virtualServices exposed by the listener in - // namespace/dnsName format. Publicly scoped services and + // REQUIRED: One or more services/virtualServices exposed by the listener + // in namespace/dnsName format. Publicly scoped services and // VirtualServices from remote namespaces corresponding to the specified // hosts will be imported. The service in a namespace can be a service in // the service registry (e.g., a kubernetes or cloud foundry service) or @@ -314,10 +343,10 @@ func (m *IstioEgressListener) GetHosts() []string { // specified, all conditions need to match in order for the workload to be // selected. Currently, only label based selection mechanism is supported. type WorkloadSelector struct { - // One or more labels that indicate a specific set of pods/VMs on which - // this sidecar configuration should be applied. The scope of label - // search is restricted to the configuration namespace in which the the - // resource is present. + // REQUIRED: One or more labels that indicate a specific set of pods/VMs + // on which this sidecar configuration should be applied. The scope of + // label search is restricted to the configuration namespace in which the + // the resource is present. Labels map[string]string `protobuf:"bytes,1,rep,name=labels" json:"labels,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"` } diff --git a/networking/v1alpha3/sidecar.proto b/networking/v1alpha3/sidecar.proto index 369b6be38c..f927fe919c 100644 --- a/networking/v1alpha3/sidecar.proto +++ b/networking/v1alpha3/sidecar.proto @@ -48,8 +48,9 @@ option go_package = "istio.io/api/networking/v1alpha3"; // with a workload selector select the same workload. // // The example below delcares a Sidecar resource in the prod-us1 namespace -// that configures the sidecar to allow egress traffic to public services -// in the prod-us1, prod-apis, and the istio-system namespaces. +// that configures the sidecars in the namespace to allow egress traffic to +// public services in the prod-us1, prod-apis, and the istio-system +// namespaces. // // ```yaml // apiVersion: networking.istio.io/v1alpha3 @@ -65,15 +66,44 @@ option go_package = "istio.io/api/networking/v1alpha3"; // - "istio-system/*" // ``` // +// The example below delcares a Sidecar resource in the prod-us1 namespace +// that accepts inbound HTTP traffic on port 9080 and forwards +// it to the attached workload listening on a unix domain socket. In the +// egress direction, in addition to the istio-system namespace, the sidecar +// proxies only HTTP traffic bound for port 9080 for services in the +// prod-us1 namespace. +// +// ```yaml +// apiVersion: networking.istio.io/v1alpha3 +// kind: Sidecar +// metadata: +// name: default +// namespace: prod-us1 +// spec: +// ingress: +// - port: +// number: 9080 +// protocol: HTTP +// name: somename +// defaultEndpoint: unix:///var/run/someuds.sock +// egress: +// - hosts: +// - "istio-system/*" +// - port: +// number: 9080 +// protocol: HTTP +// name: egresshttp +// hosts: +// - "prod-us1/*" +// ``` +// message Sidecar { - // $hide_from_docs // Criteria used to select the specific set of pods/VMs on which this // sidecar configuration should be applied. If omitted, the sidecar - // configuration will be applied to all workloads in the current config + // configuration will be applied to all workloads in the same config // namespace. WorkloadSelector workload_selector = 1; - // $hide_from_docs // Ingress specifies the configuration of the sidecar for processing // inbound traffic to the attached workload. If omitted, Istio will // autoconfigure the sidecar based on the information about the workload @@ -88,7 +118,6 @@ message Sidecar { repeated IstioEgressListener egress = 3; } -// $hide_from_docs // IstioIngressListener specifies the properties of an inbound // traffic listener on the sidecar proxy attached to a workload. message IstioIngressListener { @@ -106,12 +135,13 @@ message IstioIngressListener { // When the bind address is an IP, the captureMode option dictates // how traffic to the listener is expected to be captured (or not). + // captureMode must be DEFAULT or NONE for unix domain socket binds. CaptureMode capture_mode = 3; - // The loopback IP endpoint or unix domain socket to which traffic should - // be forwarded to by default. This configuration can be used to redirect - // traffic arriving at the bind point on the sidecar to a port or unix - // domain socket where the application workload is listening for + // REQUIRED: The loopback IP endpoint or unix domain socket to which + // traffic should be forwarded to. This configuration can be used to + // redirect traffic arriving at the bind point on the sidecar to a port + // or unix domain socket where the application workload is listening for // connections. Format should be 127.0.0.1:PORT or unix:///path/to/socket string default_endpoint = 4; } @@ -119,7 +149,6 @@ message IstioIngressListener { // IstioEgressListener specifies the properties of an outbound traffic // listener on the sidecar proxy attached to a workload. message IstioEgressListener { - // $hide_from_docs // The port associated with the listener. If using unix domain socket, // use 0 as the port number, with a valid protocol. The port if // specified, will be used as the default destination port associated @@ -131,21 +160,22 @@ message IstioEgressListener { // port. Port port = 1; - // $hide_from_docs // The ip or the unix domain socket to which the listener should be bound - // to. Port MUST be specified if bind is not empty. Format: - // x.x.x.x or unix:///path/to/uds or unix://@foobar (Linux abstract - // namespace). If omitted, Istio will autoconfigure the defaults based on - // imported services and the workload to which this configuration is - // applied to. + // to. Port MUST be specified if bind is not empty. Format: x.x.x.x or + // unix:///path/to/uds or unix://@foobar (Linux abstract namespace). If + // omitted, Istio will autoconfigure the defaults based on imported + // services, the workload to which this configuration is applied to and + // the captureMode. If captureMode is NONE, bind will default to + // 127.0.0.1. string bind = 2; // When the bind address is an IP, the captureMode option dictates // how traffic to the listener is expected to be captured (or not). + // captureMode must be DEFAULT or NONE for unix domain socket binds. CaptureMode capture_mode = 3; - // One or more services/virtualServices exposed by the listener in - // namespace/dnsName format. Publicly scoped services and + // REQUIRED: One or more services/virtualServices exposed by the listener + // in namespace/dnsName format. Publicly scoped services and // VirtualServices from remote namespaces corresponding to the specified // hosts will be imported. The service in a namespace can be a service in // the service registry (e.g., a kubernetes or cloud foundry service) or @@ -187,10 +217,10 @@ enum ConfigScope { // specified, all conditions need to match in order for the workload to be // selected. Currently, only label based selection mechanism is supported. message WorkloadSelector { - // One or more labels that indicate a specific set of pods/VMs on which - // this sidecar configuration should be applied. The scope of label - // search is restricted to the configuration namespace in which the the - // resource is present. + // REQUIRED: One or more labels that indicate a specific set of pods/VMs + // on which this sidecar configuration should be applied. The scope of + // label search is restricted to the configuration namespace in which the + // the resource is present. map labels = 1; // $hide_from_docs @@ -199,7 +229,6 @@ message WorkloadSelector { // etc. This has nothing to do with the request level authN etc. } -// $hide_from_docs // CaptureMode describes how traffic to a listener is expected to be // captured. Applicable only when the listener is bound to an IP. enum CaptureMode { @@ -216,36 +245,3 @@ enum CaptureMode { // the host. NONE = 2; } - -// $hide_from_docs -// The example below delcares a Sidecar resource in the prod-us1 namespace -// that accepts inbound HTTP traffic on port 9080 and forwards -// it to the attached workload listening on a unix domain socket. In the -// egress direction, in addition to the istio-system namespace, the sidecar -// proxies only HTTP traffic bound for port 9080 for services in the -// prod-us1 namespace. -// -// ```yaml -// apiVersion: networking.istio.io/v1alpha3 -// kind: Sidecar -// metadata: -// name: default -// namespace: prod-us1 -// spec: -// ingress: -// - port: -// number: 9080 -// protocol: HTTP -// name: somename -// defaultEndpoint: unix:///var/run/someuds.sock -// egress: -// - hosts: -// - "istio-system/*" -// - port: -// number: 9080 -// protocol: HTTP -// name: egresshttp -// hosts: -// - "prod-us1/*" -// ``` -//
workloadSelectorWorkloadSelector +

Criteria used to select the specific set of pods/VMs on which this +sidecar configuration should be applied. If omitted, the sidecar +configuration will be applied to all workloads in the same config +namespace.

+ +
ingressIstioIngressListener[] +

Ingress specifies the configuration of the sidecar for processing +inbound traffic to the attached workload. If omitted, Istio will +autoconfigure the sidecar based on the information about the workload +obtained from the orchestration platform (e.g., exposed ports, services, +etc.).

+ +
egress IstioEgressListener[] labels map<string, string> -

One or more labels that indicate a specific set of pods/VMs on which -this sidecar configuration should be applied. The scope of label -search is restricted to the configuration namespace in which the the -resource is present.

+

REQUIRED: One or more labels that indicate a specific set of pods/VMs +on which this sidecar configuration should be applied. The scope of +label search is restricted to the configuration namespace in which the +the resource is present.