Update reference docs. (#3624)

2019-03-11 11:54:59 -07:00 · 2019-03-11 11:54:59 -07:00 · 8cfa57999d
parent fbd2b162fb
commit 8cfa57999d
6 changed files with 213 additions and 60 deletions
--- a/content/docs/reference/commands/pilot-agent/index.html
+++ b/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>
--- a/content/docs/reference/config/istio.mesh.v1alpha1/index.html
+++ b/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>
--- a/content/docs/reference/config/networking/v1alpha3/gateway/index.html
+++ b/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
-port 2379 (TCP) for ingress.  The gateway will be applied to the proxy
-running on a pod with labels <code>app: my-gateway-controller</code>. While Istio
-will configure the proxy to listen on these ports, it is the
-responsibility of the user to ensure that external traffic to these
-ports are allowed into the mesh.</p>
+as a load balancer exposing port 80 and 9080 (http), 443 (https),
+9443(https) and port 2379 (TCP) for ingress.  The gateway will be
+applied to the proxy running on a pod with labels <code>app:
+my-gateway-controller</code>. While Istio will configure the proxy to listen
+on these ports, it is the responsibility of the user to ensure that
+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,
-with a valid protocol and port name, along with the bind parameter.</p>
+connections.</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
-appended with suffix &ldquo;-cacert&rdquo; is used to identify the CaCertificates
-associated with this server. Gateway workloads capable of fetching
-credentials from a remote credential store 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,
+to identify the serverCertificate and the privateKey. The
+credentialName appended with suffix &ldquo;-cacert&rdquo; 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 workloads 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).</p>
+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<em>META</em>USER_SDS metadata variable in the gateway&rsquo;s proxy to
+enable the dynamic credential fetching feature.</p>

 </td>
 </tr>
--- a/content/docs/reference/config/networking/v1alpha3/service-entry/index.html
+++ b/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&rsquo;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
-forward unterminated TLS traffic from the application to external
-services via the sidecar. The sidecar inspects the SNI value in the
-ClientHello message to route to the appropriate external service.</p>
+routing in a virtual service to steer traffic based on the SNI value to
+an internal egress firewall.</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
-  - www.googleapis.com
-  - api.facebook.com
+  - wikipedia.org
+  - &quot;*.wikipedia.org&quot;
  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
-  - www.googleapis.com
-  - api.facebook.com
+  - wikipedia.org
+  - &quot;*.wikipedia.org&quot;
  tls:
  - match:
-    - port: 443
-      sniHosts:
-      - api.dropboxapi.com
+    - sniHosts:
+      - wikipedia.org
+      - &quot;*.wikipedia.org&quot;
    route:
    - destination:
-        host: api.dropboxapi.com
-  - 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
-
+        host: internal-egress-firewall.ns1.svc.cluster.local
 </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
-will be ignored if the application accesses the service over non-HTTP
-protocols such as mongo/opaque TCP/HTTPS. In such scenarios, the
-IP addresses specified in the Addresses field or the port will be used
-to uniquely identify the destination.</p>
+name with wildcard prefix (external services only). For HTTP traffic
+the HTTP Host/Authority header will be matched against the hosts field.
+For HTTPs or TLS traffic containing Server Name Indication (SNI), the SNI value
+will be matched against the hosts field. For all other protocols
+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,
-the hosts will be ignored. If one or more IP addresses are specified,
+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
--- a/content/docs/reference/config/networking/v1alpha3/sidecar/index.html
+++ b/content/docs/reference/config/networking/v1alpha3/sidecar/index.html
@ -83,6 +83,103 @@ spec:
    - &quot;prod-us1/*&quot;
 </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>
--- a/content/docs/reference/config/policy-and-telemetry/adapters/apigee/index.html
+++ b/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
 ---