added documentation about TCP Egress Rules, CIDR notation (#346)

Author: vadimeisenbergibm

routing/v1alpha1/egress_rule.pb.go

@@ -21,11 +21,14 @@ package istio.routing.v1alpha1;
 option go_package = "istio.io/api/routing/v1alpha1";
 
 // Egress rules describe the properties of a service outside Istio. When transparent proxying
-// is used, egress rules signify a white listed set of domains that microserves in the mesh
+// is used, egress rules signify a white listed set of external services that microserves in the mesh
 // are allowed to access. A subset of routing rules and all destination policies can be applied
-// on the service targeted by an egress rule. The destination of an egress rule is allowed to
-// contain wildcards (e.g., *.foo.com). Currently, only HTTP-based services can be expressed
-// through the egress rule. If TLS origination from the sidecar is desired, the protocol
+// on the service targeted by an egress rule. TCP services and HTTP-based services can be expressed
+// by an egress rule. The destination of an egress rule for HTTP-based services must be an IP or a domain name,
+// optionally with a wildcard prefix  (e.g., *.foo.com). For TCP based services, the destination of an
+// egress rule must be an IP or a block of IPs in CIDR notation.
+//
+// If TLS origination from the sidecar is desired, the protocol
 // associated with the service port must be marked as HTTPS, and the service is expected to
 // be accessed over HTTP (e.g., http://gmail.com:443). The sidecar will automatically upgrade
 // the connection to TLS when initiating a connection with the external service.
@@ -44,6 +47,18 @@ option go_package = "istio.io/api/routing/v1alpha1";
 //         - port: 443
 //           protocol: https
 //
+// The following egress rule describes the set of services accessed by a block of IPs
+//
+//     kind: EgressRule
+//     metadata:
+//       name: bar-egress-rule
+//     spec:
+//       destination:
+//         service: 92.198.174.192/27
+//       ports:
+//         - port: 111
+//           protocol: tcp
+//
 message EgressRule {
   // Port describes the properties of a specific TCP port of an external service.
   message Port {
@@ -54,14 +69,20 @@ message EgressRule {
     string protocol = 2;
   }
 
-  // REQUIRED: Hostname or a wildcard domain name associated with the external service.
-  // ONLY the "service" field of destination will be taken into consideration. Name,
+  // REQUIRED: A domain name, optionally with a wildcard prefix, or an IP, or a block of IPs
+  // associated with the external service.
+  // ONLY the "service" field of "destination" will be taken into consideration. Name,
   // namespace, domain and labels are ignored. Routing rules and destination policies that
   // refer to these external services must have identical specification for the destination
-  // as the corresponding egress rule. Wildcard domain specifications must conform to format
+  // as the corresponding egress rule.
+  //
+  // The "service" field of "destination" for HTTP-based services must be an IP or a domain name,
+  // optionally with a wildcard prefix. Wildcard domain specifications must conform to format
   // allowed by Envoy's Virtual Host specification, such as “*.foo.com” or “*-bar.foo.com”.
   // The character '*' in a domain specification indicates a non-empty string. Hence, a wildcard
   // domain of form “*-bar.foo.com” will match “baz-bar.foo.com” but not “-bar.foo.com”.
+  //
+  // The "service" field of "destination" for TCP services must be an IP or a block of IPs in CIDR notation.
   IstioService destination = 1;
 
   // REQUIRED: list of ports on which the external service is available.

routing/v1alpha1/egress_rule.proto

@@ -483,11 +483,14 @@ <h2 id="DestinationWeight">DestinationWeight</h2>
 <h2 id="EgressRule">EgressRule</h2>
 <section>
 <p>Egress rules describe the properties of a service outside Istio. When transparent proxying
-is used, egress rules signify a white listed set of domains that microserves in the mesh
+is used, egress rules signify a white listed set of external services that microserves in the mesh
 are allowed to access. A subset of routing rules and all destination policies can be applied
-on the service targeted by an egress rule. The destination of an egress rule is allowed to
-contain wildcards (e.g., *.foo.com). Currently, only HTTP-based services can be expressed
-through the egress rule. If TLS origination from the sidecar is desired, the protocol
+on the service targeted by an egress rule. TCP services and HTTP-based services can be expressed
+by an egress rule. The destination of an egress rule for HTTP-based services must be an IP or a domain name,
+optionally with a wildcard prefix  (e.g., *.foo.com). For TCP based services, the destination of an
+egress rule must be an IP or a block of IPs in CIDR notation.</p>
+
+<p>If TLS origination from the sidecar is desired, the protocol
 associated with the service port must be marked as HTTPS, and the service is expected to
 be accessed over HTTP (e.g., http://gmail.com:443). The sidecar will automatically upgrade
 the connection to TLS when initiating a connection with the external service.</p>
@@ -507,6 +510,19 @@ <h2 id="EgressRule">EgressRule</h2>
       protocol: https
 </code></pre>
 
+<p>The following egress rule describes the set of services accessed by a block of IPs</p>
+
+<pre><code>kind: EgressRule
+metadata:
+  name: bar-egress-rule
+spec:
+  destination:
+    service: 92.198.174.192/27
+  ports:
+    - port: 111
+      protocol: tcp
+</code></pre>
+
 <table class="message-fields">
 <thead>
 <tr>
@@ -520,15 +536,21 @@ <h2 id="EgressRule">EgressRule</h2>
 <td><code>destination</code></td>
 <td><code><a href="#IstioService">IstioService</a></code></td>
 <td>
-<p>REQUIRED: Hostname or a wildcard domain name associated with the external service.
-ONLY the &ldquo;service&rdquo; field of destination will be taken into consideration. Name,
+<p>REQUIRED: A domain name, optionally with a wildcard prefix, or an IP, or a block of IPs
+associated with the external service.
+ONLY the &ldquo;service&rdquo; field of &ldquo;destination&rdquo; will be taken into consideration. Name,
 namespace, domain and labels are ignored. Routing rules and destination policies that
 refer to these external services must have identical specification for the destination
-as the corresponding egress rule. Wildcard domain specifications must conform to format
+as the corresponding egress rule.</p>
+
+<p>The &ldquo;service&rdquo; field of &ldquo;destination&rdquo; for HTTP-based services must be an IP or a domain name,
+optionally with a wildcard prefix. Wildcard domain specifications must conform to format
 allowed by Envoy&rsquo;s Virtual Host specification, such as “<em>.foo.com” or “</em>-bar.foo.com”.
 The character &lsquo;<em>&rsquo; in a domain specification indicates a non-empty string. Hence, a wildcard
 domain of form “</em>-bar.foo.com” will match “baz-bar.foo.com” but not “-bar.foo.com”.</p>
 
+<p>The &ldquo;service&rdquo; field of &ldquo;destination&rdquo; for TCP services must be an IP or a block of IPs in CIDR notation.</p>
+
 </td>
 </tr>
 <tr id="EgressRule.ports">