From b12265270b81f6f8a8d779b8295bc2efd9482e6d Mon Sep 17 00:00:00 2001 From: Frank Budinsky Date: Thu, 28 Feb 2019 16:21:18 -0500 Subject: [PATCH 1/3] Update gateway and sidecar hosts doc --- networking/v1alpha3/gateway.proto | 33 ++++++++++++++++++++----------- networking/v1alpha3/sidecar.proto | 30 ++++++++++++++-------------- 2 files changed, 36 insertions(+), 27 deletions(-) diff --git a/networking/v1alpha3/gateway.proto b/networking/v1alpha3/gateway.proto index 04c81cf2c50..35d0266e0c6 100644 --- a/networking/v1alpha3/gateway.proto +++ b/networking/v1alpha3/gateway.proto @@ -242,20 +242,29 @@ message Server { // abstract namespace). string bind = 4; - // REQUIRED. A list of hosts exposed by this gateway. At least one - // host is required. While typically applicable to - // HTTP services, it can also be used for TCP services using TLS with - // SNI. May contain a wildcard prefix for the bottom-level component of - // a domain name. For example `*.foo.com` matches `bar.foo.com` - // and `*.com` matches `bar.foo.com`, `example.com`, and so on. + // 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, opionally including + // a wildcard character in the left-most component (e.g., `prod/*.example.com`). + // Set the `dnsName` to `*` to select all services from the specified + // namespace (e.g.,`prod/*`). If no `namespace/` is specified, the service + // will be selected from any available namespace. + // Any associated `DestinationRule` in the same namespace will also be used. // - // **Note**: A `VirtualService` that is bound to a gateway must have one - // or more hosts that match the hosts specified in a server. The match + // A `VirtualService`, bound to the gateway, 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", - // VirtualServices with hosts dev.example.com, prod.example.com will - // match. However, VirtualServices with hosts example.com or - // newexample.com will not match. + // 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 exported virtual services from a + // namespace can be used. Private configurations will not be + // available. Refer to the `exportTo` setting in `VirtualService`, + // `DestinationRule`, and `ServiceEntry` configurations for details. repeated string hosts = 2; message TLSOptions { diff --git a/networking/v1alpha3/sidecar.proto b/networking/v1alpha3/sidecar.proto index 3fd1d7da743..a40105e2c96 100644 --- a/networking/v1alpha3/sidecar.proto +++ b/networking/v1alpha3/sidecar.proto @@ -178,24 +178,24 @@ message IstioEgressListener { // captureMode must be DEFAULT or NONE for Unix domain socket binds. CaptureMode capture_mode = 3; - // 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 - // a service specified via ServiceEntry configuration. In addition, any - // publicly scoped DestinationRule associated with the imported services - // will also be imported. + // REQUIRED: One or more service hosts exposed by the listener + // in `namespace/dnsName` format. Services in the specified namespace + // matching `dnsName` will be exposed. + // The corresponding service can be a service in the service registry + // (e.g., a Kubernetes or cloud foundry service) or a service specified + // using a `ServiceEntry` or `VirtualService` configuration. Any + // associated `DestinationRule` in the same namespace will also be used. // - // Set the namespace to * to import a particular service from any - // available namespace (e.g., "*/foo.example.com"). Set the dnsName field - // to * to import all services from the specified namespace (e.g., - // "prod/*"). The services should be specified using FQDN format. + // The `dnsName` should be specified using FQDN format, opionally including + // a wildcard character in the left-most component (e.g., `prod/*.example.com`). + // Set the `dnsName` to `*` to select all services from the specified namespace + // (e.g.,`prod/*`). The `namespace` can also be set to `*` to select a particular + // service from any available namespace (e.g., "*/foo.example.com"). // // NOTE: Only exported services and configuration artifacts from a - // namespace can be imported. Private services/configuration will not be - // imported. Refer to the scope setting associated with VirtualService, - // DestinationRule, ServiceEntry, etc. for details. + // namespace can be used. Private configurations will not be + // available. Refer to the `exportTo` setting in `VirtualService`, + // `DestinationRule`, and `ServiceEntry` configurations for details. repeated string hosts = 4; } From f3ed7fa29c063d427262b7ad3a52e0e6b88314da Mon Sep 17 00:00:00 2001 From: Frank Budinsky Date: Thu, 28 Feb 2019 16:25:24 -0500 Subject: [PATCH 2/3] regen --- networking/v1alpha3/gateway.pb.go | 33 +++++++++++++++++---------- networking/v1alpha3/gateway.pb.html | 35 ++++++++++++++++++----------- networking/v1alpha3/sidecar.pb.go | 30 ++++++++++++------------- networking/v1alpha3/sidecar.pb.html | 30 ++++++++++++------------- 4 files changed, 73 insertions(+), 55 deletions(-) diff --git a/networking/v1alpha3/gateway.pb.go b/networking/v1alpha3/gateway.pb.go index b66d6fca1c2..23c4cd7e57c 100644 --- a/networking/v1alpha3/gateway.pb.go +++ b/networking/v1alpha3/gateway.pb.go @@ -377,20 +377,29 @@ type Server struct { // to. Format: `x.x.x.x` or `unix:///path/to/uds` or `unix://@foobar` (Linux // abstract namespace). Bind string `protobuf:"bytes,4,opt,name=bind,proto3" json:"bind,omitempty"` - // REQUIRED. A list of hosts exposed by this gateway. At least one - // host is required. While typically applicable to - // HTTP services, it can also be used for TCP services using TLS with - // SNI. May contain a wildcard prefix for the bottom-level component of - // a domain name. For example `*.foo.com` matches `bar.foo.com` - // and `*.com` matches `bar.foo.com`, `example.com`, and so on. + // 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, opionally including + // a wildcard character in the left-most component (e.g., `prod/*.example.com`). + // Set the `dnsName` to `*` to select all services from the specified + // namespace (e.g.,`prod/*`). If no `namespace/` is specified, the service + // will be selected from any available namespace. + // Any associated `DestinationRule` in the same namespace will also be used. // - // **Note**: A `VirtualService` that is bound to a gateway must have one - // or more hosts that match the hosts specified in a server. The match + // A `VirtualService`, bound to the gateway, 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", - // VirtualServices with hosts dev.example.com, prod.example.com will - // match. However, VirtualServices with hosts example.com or - // newexample.com will not match. + // 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 exported virtual services from a + // namespace can be used. Private configurations will not be + // available. Refer to the `exportTo` setting in `VirtualService`, + // `DestinationRule`, and `ServiceEntry` configurations for details. Hosts []string `protobuf:"bytes,2,rep,name=hosts,proto3" json:"hosts,omitempty"` // Set of TLS related options that govern the server's behavior. Use // these options to control if all http requests should be redirected to diff --git a/networking/v1alpha3/gateway.pb.html b/networking/v1alpha3/gateway.pb.html index a01ff9d04cc..82a6cf99a0a 100644 --- a/networking/v1alpha3/gateway.pb.html +++ b/networking/v1alpha3/gateway.pb.html @@ -301,20 +301,29 @@

Server

hosts string[] -

REQUIRED. A list of hosts exposed by this gateway. At least one -host is required. While typically applicable to -HTTP services, it can also be used for TCP services using TLS with -SNI. May contain a wildcard prefix for the bottom-level component of -a domain name. For example *.foo.com matches bar.foo.com -and *.com matches bar.foo.com, example.com, and so on.

- -

Note: A VirtualService that is bound to a gateway must have one -or more hosts that match the hosts specified in a server. The match +

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, opionally including +a wildcard character in the left-most component (e.g., prod/*.example.com). +Set the dnsName to * to select all services from the specified +namespace (e.g.,prod/*). If no namespace/ is specified, the service +will be selected from any available namespace. +Any associated DestinationRule in the same namespace will also be used.

+ +

A VirtualService, bound to the gateway, 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”, -VirtualServices with hosts dev.example.com, prod.example.com will -match. However, VirtualServices with hosts example.com or -newexample.com will not match.

+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 exported virtual services from a +namespace can be used. Private configurations will not be +available. Refer to the exportTo setting in VirtualService, +DestinationRule, and ServiceEntry configurations for details.

diff --git a/networking/v1alpha3/sidecar.pb.go b/networking/v1alpha3/sidecar.pb.go index a098aa94e49..6e15d496c0d 100644 --- a/networking/v1alpha3/sidecar.pb.go +++ b/networking/v1alpha3/sidecar.pb.go @@ -326,24 +326,24 @@ type IstioEgressListener struct { // 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"` - // 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 - // a service specified via ServiceEntry configuration. In addition, any - // publicly scoped DestinationRule associated with the imported services - // will also be imported. + // REQUIRED: One or more service hosts exposed by the listener + // in `namespace/dnsName` format. Services in the specified namespace + // matching `dnsName` will be exposed. + // The corresponding service can be a service in the service registry + // (e.g., a Kubernetes or cloud foundry service) or a service specified + // using a `ServiceEntry` or `VirtualService` configuration. Any + // associated `DestinationRule` in the same namespace will also be used. // - // Set the namespace to * to import a particular service from any - // available namespace (e.g., "*/foo.example.com"). Set the dnsName field - // to * to import all services from the specified namespace (e.g., - // "prod/*"). The services should be specified using FQDN format. + // The `dnsName` should be specified using FQDN format, opionally including + // a wildcard character in the left-most component (e.g., `prod/*.example.com`). + // Set the `dnsName` to `*` to select all services from the specified namespace + // (e.g.,`prod/*`). The `namespace` can also be set to `*` to select a particular + // service from any available namespace (e.g., "*/foo.example.com"). // // NOTE: Only exported services and configuration artifacts from a - // namespace can be imported. Private services/configuration will not be - // imported. Refer to the scope setting associated with VirtualService, - // DestinationRule, ServiceEntry, etc. for details. + // namespace can be used. Private configurations will not be + // available. Refer to the `exportTo` setting in `VirtualService`, + // `DestinationRule`, and `ServiceEntry` configurations for details. Hosts []string `protobuf:"bytes,4,rep,name=hosts,proto3" json:"hosts,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` diff --git a/networking/v1alpha3/sidecar.pb.html b/networking/v1alpha3/sidecar.pb.html index 6c92d7d1f94..3d2cd0a55b3 100644 --- a/networking/v1alpha3/sidecar.pb.html +++ b/networking/v1alpha3/sidecar.pb.html @@ -180,24 +180,24 @@

IstioEgressListener

hosts string[] -

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 -a service specified via ServiceEntry configuration. In addition, any -publicly scoped DestinationRule associated with the imported services -will also be imported.

+

REQUIRED: One or more service hosts exposed by the listener +in namespace/dnsName format. Services in the specified namespace +matching dnsName will be exposed. +The corresponding service can be a service in the service registry +(e.g., a Kubernetes or cloud foundry service) or a service specified +using a ServiceEntry or VirtualService configuration. Any +associated DestinationRule in the same namespace will also be used.

-

Set the namespace to * to import a particular service from any -available namespace (e.g., “*/foo.example.com”). Set the dnsName field -to * to import all services from the specified namespace (e.g., -“prod/*”). The services should be specified using FQDN format.

+

The dnsName should be specified using FQDN format, opionally including +a wildcard character in the left-most component (e.g., prod/*.example.com). +Set the dnsName to * to select all services from the specified namespace +(e.g.,prod/*). The namespace can also be set to * to select a particular +service from any available namespace (e.g., “*/foo.example.com”).

NOTE: Only exported services and configuration artifacts from a -namespace can be imported. Private services/configuration will not be -imported. Refer to the scope setting associated with VirtualService, -DestinationRule, ServiceEntry, etc. for details.

+namespace can be used. Private configurations will not be +available. Refer to the exportTo setting in VirtualService, +DestinationRule, and ServiceEntry configurations for details.

From 12ec527309594a7a260c86e150d1bc4a8be4bc01 Mon Sep 17 00:00:00 2001 From: Frank Budinsky Date: Thu, 28 Feb 2019 18:02:23 -0500 Subject: [PATCH 3/3] review comments --- networking/v1alpha3/gateway.pb.go | 15 ++++++++------- networking/v1alpha3/gateway.pb.html | 15 ++++++++------- networking/v1alpha3/gateway.proto | 15 ++++++++------- networking/v1alpha3/sidecar.pb.go | 7 ++++--- networking/v1alpha3/sidecar.pb.html | 7 ++++--- networking/v1alpha3/sidecar.proto | 7 ++++--- 6 files changed, 36 insertions(+), 30 deletions(-) diff --git a/networking/v1alpha3/gateway.pb.go b/networking/v1alpha3/gateway.pb.go index 23c4cd7e57c..bb744c66619 100644 --- a/networking/v1alpha3/gateway.pb.go +++ b/networking/v1alpha3/gateway.pb.go @@ -383,21 +383,22 @@ type Server struct { // A host is specified as a `dnsName` with an optional `namespace/` prefix. // The `dnsName` should be specified using FQDN format, opionally including // a wildcard character in the left-most component (e.g., `prod/*.example.com`). - // Set the `dnsName` to `*` to select all services from the specified - // namespace (e.g.,`prod/*`). If no `namespace/` is specified, the service - // will be selected from any available namespace. + // Set the `dnsName` to `*` to select all `VirtualService` hosts from the + // specified namespace (e.g.,`prod/*`). If no `namespace/` is specified, + // the `VirtualService` hosts will be selected from any available namespace. // Any associated `DestinationRule` in the same namespace will also be used. // - // A `VirtualService`, bound to the gateway, must have one or more hosts - // that match the hosts specified in a server. The match + // 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 exported virtual services from a - // namespace can be used. Private configurations will not be + // 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. Hosts []string `protobuf:"bytes,2,rep,name=hosts,proto3" json:"hosts,omitempty"` diff --git a/networking/v1alpha3/gateway.pb.html b/networking/v1alpha3/gateway.pb.html index 82a6cf99a0a..a497747de16 100644 --- a/networking/v1alpha3/gateway.pb.html +++ b/networking/v1alpha3/gateway.pb.html @@ -307,21 +307,22 @@

Server

A host is specified as a dnsName with an optional namespace/ prefix. The dnsName should be specified using FQDN format, opionally including a wildcard character in the left-most component (e.g., prod/*.example.com). -Set the dnsName to * to select all services from the specified -namespace (e.g.,prod/*). If no namespace/ is specified, the service -will be selected from any available namespace. +Set the dnsName to * to select all VirtualService hosts from the +specified namespace (e.g.,prod/*). If no namespace/ is specified, +the VirtualService hosts will be selected from any available namespace. Any associated DestinationRule in the same namespace will also be used.

-

A VirtualService, bound to the gateway, must have one or more hosts -that match the hosts specified in a server. The match +

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 exported virtual services from a -namespace can be used. Private configurations will not be +

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.

diff --git a/networking/v1alpha3/gateway.proto b/networking/v1alpha3/gateway.proto index 35d0266e0c6..c943b3ff2ce 100644 --- a/networking/v1alpha3/gateway.proto +++ b/networking/v1alpha3/gateway.proto @@ -248,21 +248,22 @@ message Server { // A host is specified as a `dnsName` with an optional `namespace/` prefix. // The `dnsName` should be specified using FQDN format, opionally including // a wildcard character in the left-most component (e.g., `prod/*.example.com`). - // Set the `dnsName` to `*` to select all services from the specified - // namespace (e.g.,`prod/*`). If no `namespace/` is specified, the service - // will be selected from any available namespace. + // Set the `dnsName` to `*` to select all `VirtualService` hosts from the + // specified namespace (e.g.,`prod/*`). If no `namespace/` is specified, + // the `VirtualService` hosts will be selected from any available namespace. // Any associated `DestinationRule` in the same namespace will also be used. // - // A `VirtualService`, bound to the gateway, must have one or more hosts - // that match the hosts specified in a server. The match + // 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 exported virtual services from a - // namespace can be used. Private configurations will not be + // 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. repeated string hosts = 2; diff --git a/networking/v1alpha3/sidecar.pb.go b/networking/v1alpha3/sidecar.pb.go index 6e15d496c0d..df36f1e0fd7 100644 --- a/networking/v1alpha3/sidecar.pb.go +++ b/networking/v1alpha3/sidecar.pb.go @@ -340,9 +340,10 @@ type IstioEgressListener struct { // (e.g.,`prod/*`). The `namespace` can also be set to `*` to select a particular // service from any available namespace (e.g., "*/foo.example.com"). // - // NOTE: Only exported services and configuration artifacts from a - // namespace can be used. Private configurations will not be - // available. Refer to the `exportTo` setting in `VirtualService`, + // NOTE: Only services and configuration artifacts exported to the sidecar'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. Hosts []string `protobuf:"bytes,4,rep,name=hosts,proto3" json:"hosts,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` diff --git a/networking/v1alpha3/sidecar.pb.html b/networking/v1alpha3/sidecar.pb.html index 3d2cd0a55b3..0fc965186e5 100644 --- a/networking/v1alpha3/sidecar.pb.html +++ b/networking/v1alpha3/sidecar.pb.html @@ -194,9 +194,10 @@

IstioEgressListener

(e.g.,prod/*). The namespace can also be set to * to select a particular service from any available namespace (e.g., “*/foo.example.com”).

-

NOTE: Only exported services and configuration artifacts from a -namespace can be used. Private configurations will not be -available. Refer to the exportTo setting in VirtualService, +

NOTE: Only services and configuration artifacts exported to the sidecar’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.

diff --git a/networking/v1alpha3/sidecar.proto b/networking/v1alpha3/sidecar.proto index a40105e2c96..eb45b8b5be4 100644 --- a/networking/v1alpha3/sidecar.proto +++ b/networking/v1alpha3/sidecar.proto @@ -192,9 +192,10 @@ message IstioEgressListener { // (e.g.,`prod/*`). The `namespace` can also be set to `*` to select a particular // service from any available namespace (e.g., "*/foo.example.com"). // - // NOTE: Only exported services and configuration artifacts from a - // namespace can be used. Private configurations will not be - // available. Refer to the `exportTo` setting in `VirtualService`, + // NOTE: Only services and configuration artifacts exported to the sidecar'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. repeated string hosts = 4; }