Update reference docs. (#3624)

content/docs/reference/commands/pilot-agent/index.html

@@ -110,6 +110,10 @@ number_of_entries: 5
 <td>The time in seconds that Envoy will drain connections during a hot restart  (default `45s`)</td>
 </tr>
 <tr>
+<td><code>--envoyMetricsServiceAddress &lt;string&gt;</code></td>
+<td>Host and Port of an Envoy Metrics Service API implementation (e.g. metrics-service:15000)  (default ``)</td>
+</tr>
+<tr>
 <td><code>--id &lt;string&gt;</code></td>
 <td>Proxy unique ID. If not provided uses ${POD_NAME}.${POD_NAMESPACE} from environment variables  (default ``)</td>
 </tr>

content/docs/reference/config/istio.mesh.v1alpha1/index.html

@@ -488,6 +488,14 @@ Fallback to old identity format(without trust domain) if not set.</p>
 <td>
 <p>Locality based load balancing distribution or failover settings.</p>
 
+</td>
+</tr>
+<tr id="MeshConfig-dns_refresh_rate">
+<td><code>dnsRefreshRate</code></td>
+<td><code><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">google.protobuf.Duration</a></code></td>
+<td>
+<p>Configures DNS refresh rate for Envoy clusters of type STRICT_DNS</p>
+
 </td>
 </tr>
 </tbody>

content/docs/reference/config/networking/v1alpha3/gateway/index.html

@@ -14,12 +14,12 @@ describes a set of ports that should be exposed, the type of protocol to
 use, SNI configuration for the load balancer, etc.</p>
 
 <p>For example, the following Gateway configuration sets up a proxy to act
-as a load balancer exposing port 80 and 9080 (http), 443 (https), and
+as a load balancer exposing port 80 and 9080 (http), 443 (https),
-port 2379 (TCP) for ingress.  The gateway will be applied to the proxy
+9443(https) and port 2379 (TCP) for ingress.  The gateway will be
-running on a pod with labels <code>app: my-gateway-controller</code>. While Istio
+applied to the proxy running on a pod with labels <code>app:
-will configure the proxy to listen on these ports, it is the
+my-gateway-controller</code>. While Istio will configure the proxy to listen
-responsibility of the user to ensure that external traffic to these
+on these ports, it is the responsibility of the user to ensure that
-ports are allowed into the mesh.</p>
+external traffic to these ports are allowed into the mesh.</p>
 
 <pre><code class="language-yaml">apiVersion: networking.istio.io/v1alpha3
 kind: Gateway
@@ -50,6 +50,15 @@ spec:
       mode: SIMPLE # enables HTTPS on this port
       serverCertificate: /etc/certs/servercert.pem
       privateKey: /etc/certs/privatekey.pem
+  - port:
+      number: 9443
+      name: https
+      protocol: HTTPS
+    hosts:
+    - &quot;bookinfo-namespace/*.bookinfo.com&quot;
+    tls:
+      mode: SIMPLE # enables HTTPS on this port
+      credentialName: bookinfo-secret # fetches certs from kubernetes secret
   - port:
       number: 9080
       name: http-wildcard
@@ -142,6 +151,30 @@ spec:
           number: 5555
 </code></pre>
 
+<p>It is possible to restrict the set of virtual services that can bind to
+a gateway server using the namespace/hostname syntax in the hosts field.
+For example, the following Gateway allows any virtual service in the ns1
+namespace to bind to it, while restricting only the virtual service with
+foo.bar.com host in the ns2 namespace to bind to it.</p>
+
+<pre><code class="language-yaml">apiVersion: networking.istio.io/v1alpha3
+kind: Gateway
+metadata:
+  name: my-gateway
+  namespace: some-config-namespace
+spec:
+  selector:
+    app: my-gateway-controller
+  servers:
+  - port:
+      number: 80
+      name: http
+      protocol: HTTP
+    hosts:
+    - &quot;ns1/*&quot;
+    - &quot;ns2/foo.bar.com&quot;
+</code></pre>
+
 <h2 id="Gateway">Gateway</h2>
 <section>
 <table class="message-fields">
@@ -294,8 +327,7 @@ spec:
 <td><code><a href="#Port">Port</a></code></td>
 <td>
 <p>REQUIRED: The Port on which the proxy should listen for incoming
-connections. If using Unix domain socket, use 0 as the port number,
+connections.</p>
-with a valid protocol and port name, along with the bind parameter.</p>
 
 </td>
 </tr>
@@ -416,18 +448,21 @@ client side certificate.</p>
 <td><code>string</code></td>
 <td>
 <p>The credentialName stands for a unique identifier that can be used
-to identify the serverCertificate and the privateKey. The credentialName
+to identify the serverCertificate and the privateKey. The
-appended with suffix &ldquo;-cacert&rdquo; is used to identify the CaCertificates
+credentialName appended with suffix &ldquo;-cacert&rdquo; is used to identify
-associated with this server. Gateway workloads capable of fetching
+the CaCertificates associated with this server. Gateway workloads
-credentials from a remote credential store will be configured to retrieve
+capable of fetching credentials from a remote credential store such
-the serverCertificate and the privateKey using credentialName, instead of
+as kubernetes secrets, will be configured to retrieve the
-using the file system paths specified above. If using mutual TLS,
+serverCertificate and the privateKey using credentialName, instead
+of using the file system paths specified above. If using mutual TLS,
 gateway workloads will retrieve the CaCertificates using
-credentialName-cacert. The semantics of the name are platform dependent.
+credentialName-cacert. The semantics of the name are platform
-In Kubernetes, the default Istio supplied credential server expects the
+dependent.  In Kubernetes, the default Istio supplied credential
-credentialName to match the name of the Kubernetes secret that holds the
+server expects the credentialName to match the name of the
-server certificate, the private key, and the CA certificate
+Kubernetes secret that holds the server certificate, the private
-(if using mutual TLS).</p>
+key, and the CA certificate (if using mutual TLS). Set the
+ISTIO<em>META</em>USER_SDS metadata variable in the gateway&rsquo;s proxy to
+enable the dynamic credential fetching feature.</p>
 
 </td>
 </tr>

content/docs/reference/config/networking/v1alpha3/service-entry/index.html

@@ -16,6 +16,27 @@ endpoints). These services could be external to the mesh (e.g., web
 APIs) or mesh-internal services that are not part of the platform’s
 service registry (e.g., a set of VMs talking to services in Kubernetes).</p>
 
+<p>The following example declares a few external APIs accessed by internal
+applications over HTTPS. The sidecar inspects the SNI value in the
+ClientHello message to route to the appropriate external service.</p>
+
+<pre><code class="language-yaml">apiVersion: networking.istio.io/v1alpha3
+kind: ServiceEntry
+metadata:
+  name: external-svc-https
+spec:
+  hosts:
+  - api.dropboxapi.com
+  - www.googleapis.com
+  - api.facebook.com
+  location: MESH_EXTERNAL
+  ports:
+  - number: 443
+    name: https
+    protocol: TLS
+  resolution: DNS
+</code></pre>
+
 <p>The following configuration adds a set of MongoDB instances running on
 unmanaged VMs to Istio&rsquo;s registry, so that these services can be treated
 as any other service in the mesh. The associated DestinationRule is used
@@ -58,26 +79,23 @@ spec:
 </code></pre>
 
 <p>The following example uses a combination of service entry and TLS
-routing in virtual service to demonstrate the use of SNI routing to
+routing in a virtual service to steer traffic based on the SNI value to
-forward unterminated TLS traffic from the application to external
+an internal egress firewall.</p>
-services via the sidecar. The sidecar inspects the SNI value in the
-ClientHello message to route to the appropriate external service.</p>
 
 <pre><code class="language-yaml">apiVersion: networking.istio.io/v1alpha3
 kind: ServiceEntry
 metadata:
-  name: external-svc-https
+  name: external-svc-redirect
 spec:
   hosts:
-  - api.dropboxapi.com
+  - wikipedia.org
-  - www.googleapis.com
+  - &quot;*.wikipedia.org&quot;
-  - api.facebook.com
   location: MESH_EXTERNAL
   ports:
   - number: 443
     name: https
     protocol: TLS
-  resolution: DNS
+  resolution: NONE
 </code></pre>
 
 <p>And the associated VirtualService to route based on the SNI value.</p>
@@ -88,34 +106,22 @@ metadata:
   name: tls-routing
 spec:
   hosts:
-  - api.dropboxapi.com
+  - wikipedia.org
-  - www.googleapis.com
+  - &quot;*.wikipedia.org&quot;
-  - api.facebook.com
   tls:
   - match:
-    - port: 443
+    - sniHosts:
-      sniHosts:
+      - wikipedia.org
-      - api.dropboxapi.com
+      - &quot;*.wikipedia.org&quot;
     route:
     - destination:
-        host: api.dropboxapi.com
+        host: internal-egress-firewall.ns1.svc.cluster.local
-  - match:
-    - port: 443
-      sniHosts:
-      - www.googleapis.com
-    route:
-    - destination:
-        host: www.googleapis.com
-  - match:
-    - port: 443
-      sniHosts:
-      - api.facebook.com
-    route:
-    - destination:
-        host: api.facebook.com
-
 </code></pre>
 
+<p>The virtual service with TLS match serves to override the default SNI
+match. In the absence of a virtual service, traffic will be forwarded to
+the wikipedia domains.</p>
+
 <p>The following example demonstrates the use of a dedicated egress gateway
 through which all external service traffic is forwarded.
 The &lsquo;exportTo&rsquo; field allows for control over the visibility of a service
@@ -319,11 +325,14 @@ spec:
 <td><code>string[]</code></td>
 <td>
 <p>REQUIRED. The hosts associated with the ServiceEntry. Could be a DNS
-name with wildcard prefix (external services only). DNS names in hosts
+name with wildcard prefix (external services only). For HTTP traffic
-will be ignored if the application accesses the service over non-HTTP
+the HTTP Host/Authority header will be matched against the hosts field.
-protocols such as mongo/opaque TCP/HTTPS. In such scenarios, the
+For HTTPs or TLS traffic containing Server Name Indication (SNI), the SNI value
-IP addresses specified in the Addresses field or the port will be used
+will be matched against the hosts field. For all other protocols
-to uniquely identify the destination.</p>
+the hosts will be ignored, and the port and addresses fields
+will be used if present. 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.</p>
 
 </td>
 </tr>
@@ -332,10 +341,9 @@ to uniquely identify the destination.</p>
 <td><code>string[]</code></td>
 <td>
 <p>The virtual IP addresses associated with the service. Could be CIDR
-prefix. For HTTP services, the addresses field will be ignored and
+prefix. For HTTP traffic the addresses field will be ignored and
 the destination will be identified based on the HTTP Host/Authority
-header. For non-HTTP protocols such as mongo/opaque TCP/HTTPS,
+header. If one or more IP addresses are specified,
-the hosts will be ignored. 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

content/docs/reference/config/networking/v1alpha3/sidecar/index.html

@@ -83,6 +83,103 @@ spec:
     - "prod-us1/*"
 </code></pre>
 
+<p>If the workload is deployed without IP tables based traffic capture, the
+Sidecar resource is the only way to configure the ports on the proxy
+attached to the workload. The following example declares a Sidecar
+resource in the prod-us1 namespace for all pods with labels &ldquo;app:
+productpage&rdquo; belonging to the productpage.prod-us1 service. Assuming
+that these pods are deployed without IPtable rules (i.e. the Istio init
+container) and the proxy metadata ISTIO<em>META</em>INTERCEPTION_MODE is set to
+NONE, the specification below allows such pods to receive HTTP traffic
+on port 9080 and forward it to the application listening on
+127.0.0.1:8080. It also allows the application to communicate with a
+backing MySQL database on 127.0.0.1:3306, that then gets proxied to the
+externally hosted MySQL service at mysql.foo.com:3306.</p>
+
+<pre><code class="language-yaml">apiVersion: networking.istio.io/v1alpha3
+kind: Sidecar
+metadata:
+  name: no-ip-tables
+  namespace: prod-us1
+spec:
+  workloadSelector:
+    labels:
+      app: productpage
+  ingress:
+  - port:
+      number: 9080 # binds to 0.0.0.0:9080
+      protocol: HTTP
+      name: somename
+    defaultEndpoint: 127.0.0.1:8080
+    captureMode: NONE # not needed if metadata is set for entire proxy
+  egress:
+  - port:
+      number: 3306
+      protocol: MYSQL
+      name: egressmysql
+    captureMode: NONE # not needed if metadata is set for entire proxy
+    bind: 127.0.0.1
+    hosts:
+    - &quot;*/mysql.foo.com&quot;
+</code></pre>
+
+<p>And the associated service entry for routing to mysql.foo.com:3306</p>
+
+<pre><code class="language-yaml">apiVersion: networking.istio.io/v1alpha3
+kind: ServiceEntry
+metadata:
+  name: external-svc-mysql
+  namespace: ns1
+spec:
+  hosts:
+  - mysql.foo.com
+  ports:
+  - number: 3306
+    name: mysql
+    protocol: MYSQL
+  location: MESH_EXTERNAL
+  resolution: DNS
+</code></pre>
+
+<p>It is also possible to mix and match traffic capture modes in a single
+proxy. For example, consider a setup where internal services are on the
+192.168.0.0/16 subnet. So, IP tables are setup on the VM to capture all
+outbound traffic on 192.168.0.0/16 subnet. Assume that the VM has an
+additional network interface on 172.16.0.0/16 subnet for inbound
+traffic. The following Sidecar configuration allows the VM to expose a
+listener on 172.16.1.32:80 (the VM&rsquo;s IP) for traffic arriving from the
+172.16.0.0/16 subnet. Note that in this scenario, the
+ISTIO<em>META</em>INTERCEPTION_MODE metadata on the proxy in the VM should
+contain &ldquo;REDIRECT&rdquo; or &ldquo;TPROXY&rdquo; as its value, implying that IP tables
+based traffic capture is active.</p>
+
+<pre><code class="language-yaml">apiVersion: networking.istio.io/v1alpha3
+kind: Sidecar
+metadata:
+  name: partial-ip-tables
+  namespace: prod-us1
+spec:
+  workloadSelector:
+    labels:
+      app: productpage
+  ingress:
+  - bind: 172.16.1.32
+    port:
+      number: 80 # binds to 172.16.1.32:80
+      protocol: HTTP
+      name: somename
+    defaultEndpoint: 127.0.0.1:8080
+    captureMode: NONE
+  egress:
+    # use the system detected defaults
+    # sets up configuration to handle outbound traffic to services
+    # in 192.168.0.0/16 subnet, based on information provided by the
+    # service registry
+  - captureMode: IPTABLES
+    hosts:
+    - &quot;*/*&quot;
+</code></pre>
+
 <h2 id="CaptureMode">CaptureMode</h2>
 <section>
 <p>CaptureMode describes how traffic to a listener is expected to be
@@ -298,7 +395,8 @@ namespace.</p>
 inbound traffic to the attached workload. If omitted, Istio will
 automatically configure the sidecar based on the information about the workload
 obtained from the orchestration platform (e.g., exposed ports, services,
-etc.).</p>
+etc.). If specified, inbound ports are configured if and only if the
+workload is associated with a service.</p>
 
 </td>
 </tr>

content/docs/reference/config/policy-and-telemetry/adapters/apigee/index.html

@@ -12,7 +12,7 @@ support_link: https://apigee.com/about/support/portal
 source_link: https://github.com/apigee/istio-mixer-adapter
 latest_release_link: https://github.com/apigee/istio-mixer-adapter/releases
 helm_chart_link:
-istio_versions: "1.0.0, 1.0.2, 1.0.3, 1.0.4, 1.0.5"
+istio_versions: "1.0.0, 1.0.2, 1.0.3, 1.0.4, 1.0.5, 1.0.6"
 supported_templates: authorization, analytics
 number_of_entries: 3
 ---