Add simple examples of DestinationRules

Author: Matt Turner

Istio/DestinationRule/README.md

@@ -0,0 +1,29 @@
+# DestinationRule
+
+After a destination Service is chosen by a `VirtualService` (the request is routed), a `DestinationRule` specifies how that Service should be talked to.
+
+> In this directory, "endpoint pool" means the set of endpoints to which traffic has been routed; a Service or a Subset of a Service
+
+It describes how to load balance between the network endpoints of the Service (as found in the Service Registry).
+It also says how connections should be made to those network endpoints (HTTP version, TLS stance) and how they should be managed (keep-alive times, maximum active connections to load-balance onto any individual endpoint at once).
+
+`DestinationRules` configure the _client_ sidecars, eg for the flow `service-a -> sidecar-a -> sidecar-b -> service-b` the `DestinationRule` for host "service-b" configures each instance of "sidecar-a".
+Thus the connection options technically configure how "sidecar-a" talks to _"sidecar-b"_ (if the destination is also in the mesh, or directly to the service or whatever proxies are in front of it if it's not).
+The only time to bear in mind that you're talking to the server's sidecar rather than the actual "app" is when considering TLS, as the server sidecar will terminate this.
+There is no way to configure the behaviour from "sidecar-b" to "service-b"; this is basically a passthrough, except the mutual TLS upgrade noted above.
+
+`DestinationRules` are implemented locally by each sidecar; there is no global coordination between sidecars.
+For example
+* circuit-breaker detection and elimination is done per client sidecar; each holds their own state for this which might differ from other sidecars'
+
+`DestinationRules` configure how one client should talk to the _pool_ of endpoints (a Service or subset of a Service).
+For example
+* load-balancer config controls how each individual client should pick one of the _n_ servers (endpoint instances) each time there's a new outbound connection
+* circuit-breaking applies across the pool (of servers); it temporarily removes instances from the pool (even if Service Discovery says they're healthy thus they're in the service registry)
+* TLS config applies to all connections from the client to any server (in the pool)
+The exception is connection-pool settings, which apply to each client-server pair individually.
+Recall though that they apply to `sidecar-a -> sidecar-b`, not `sidecar-b -> service-b`.
+
+It also somewhat confusingly details the Subsets of the Service available as routing targets in `VirtualServices`.
+You might think this would be on something like a `ServiceEntry` resource that obviously manipulates the Service Registry.
+However, `DestinationRule` settings can be per-subset (as they're different workload binaries and might need treating differently).

Istio/DestinationRule/circuit-breaker.yaml

@@ -0,0 +1,15 @@
+# Evaluates error rates for each endpoint in the pool against the settings here, ejecting them if they cross the thresholds.
+---
+apiVersion: networking.istio.io/v1beta1
+kind: DestinationRule
+metadata:
+  name: circuit-breaker
+spec:
+  host: service-a
+  trafficPolicy:
+    outlierDetection:
+      consecutive5xxErrors: 7 # Default 5
+      interval: 5m # Interval over which errors are counted and compared to the threshold. This is a periodic check, not a rolling one.
+      baseEjectionTime: 10s # Initial period for which the endpoint is ejected from the endpoint pool. Repeated ejections are longer each time. Default 30s
+      maxEjectionPercent: 50 # Max % of endpoints that can ejected from the endpoint pool. Default 10
+      minHealthPercent: 50 # Min % of endpoints in the endpoint pool that must be healthy for circuit-breaking to activate. Default 0

Istio/DestinationRule/connection-pool-settings.yaml

@@ -0,0 +1,21 @@
+# NB: these apply per server workload (Pod).
+# eg `maxConnections: 100` means each *client* Pod's sidecar will open max 100 connections to each individual *server* endpoint.
+---
+apiVersion: networking.istio.io/v1beta1
+kind: DestinationRule
+metadata:
+  name: connection-pool-settings
+spec:
+  host: service-a
+  trafficPolicy:
+    connectionPool:
+      tcp:
+        maxConnections: 100 # Default 4bn
+        connectTimeout: 50ms # Default 10s
+        tcpKeepalive: # TCP-level keepalives ie SO_KEEPALIVE
+          time: 3600s # Default 2h
+          interval: 50s # Default 75s
+      http:
+        maxRequestsPerConnection: 1 # Disables HTTP connection keep-alive/reuse. Default unlimited
+        idleTimeout: 1m # How long a keep-alive tcp connection will stay open if unused for any http requests. Default 1h
+        h2UpgradePolicy: UPGRADE # Upgrade http1.1 connections arriving at the sidecar to h2 from sidecar -> workload. Default: use mesh-wide setting

Istio/DestinationRule/load-balance.yaml

@@ -0,0 +1,9 @@
+apiVersion: networking.istio.io/v1beta1
+kind: DestinationRule
+metadata:
+  name: load-balance-simple
+spec:
+  host: service-a
+  trafficPolicy:
+    loadBalancer:
+      simple: LEAST_CONN # Default: ROUND_ROBIN, others: RANDOM

Istio/DestinationRule/sticky-sessions.yaml

@@ -0,0 +1,34 @@
+apiVersion: networking.istio.io/v1beta1
+kind: DestinationRule
+metadata:
+  name: sticky-sessions-user-cookie
+spec:
+  host: service-a
+  trafficPolicy:
+    loadBalancer:
+      consistentHash:
+        httpCookie:
+          name: user
+          ttl: 0s
+---
+apiVersion: networking.istio.io/v1beta1
+kind: DestinationRule
+metadata:
+  name: sticky-sessions-user-header
+spec:
+  host: service-a
+  trafficPolicy:
+    loadBalancer:
+      consistentHash:
+        httpHeaderName: x-remote-user
+---
+apiVersion: networking.istio.io/v1beta1
+kind: DestinationRule
+metadata:
+  name: sticky-sessions-source-ip
+spec:
+  host: service-a
+  trafficPolicy:
+    loadBalancer:
+      consistentHash:
+        useSourceIp: true

Istio/DestinationRule/subsets.yaml

@@ -0,0 +1,13 @@
+apiVersion: networking.istio.io/v1beta1
+kind: DestinationRule
+metadata:
+  name: subsets
+spec:
+  host: service-a
+  subsets:
+  - name: v1 # Arbitrary name for subset
+    labels: # Kubernetes Pod labels to match
+      version: v1
+  - name: v2
+    labels:
+      version: v2

Istio/DestinationRule/tls.yaml

@@ -0,0 +1,24 @@
+apiVersion: networking.istio.io/v1beta1
+kind: DestinationRule
+metadata:
+  name: accept-external-tls
+spec:
+  host: external-host-a
+  trafficPolicy:
+    tls:
+      mode: SIMPLE
+---
+# NB: This establishes an mTLS connection with an upstream endpoint. 
+# It's for _mesh-external_ endpoints; within the mesh Istio automatically establishes mTLS connections between pairs of sidecars.
+apiVersion: networking.istio.io/v1beta1
+kind: DestinationRule
+metadata:
+  name: mutual-external-tls
+spec:
+  host: external-host-a
+  trafficPolicy:
+    tls:
+      mode: MUTUAL
+      privateKey: /etc/certs/client_key.pem
+      clientCertificate: /etc/certs/client_certificiate.pem
+      caCertificates: /etc/certs/server_root_certificates.pem

Istio/README.md

@@ -0,0 +1,19 @@
+# Resource Types
+Colloquially
+* `ServiceEntry` - what Services exist and how are their network endpoints found?
+* `VirtualService` - to which Service should traffic for a given hostname be sent?
+* `DestinationRule` - how do I talk to that Service?
+
+### Services in Istio
+_Services_ are the *destination* of Route Rules (the `host` which a `VirtualService` matches is an arbitrary string).
+_Services_ by the Istio definition are morally "units of application behaviour".
+They are made of network _endpoints_: Pods, and external endpoints.
+Istio has a _Service Registry_ of all the Services it knows about.
+In some configurations it will refuse to send traffic to Services that aren't in the Service Registry (in others it'll assume the Service exists and take some guesses about how to find its endpoints and how to talk to them).
+
+In a Kubernetes environment, the Service Registry is populated from Kubernetes `Service` instances.
+Extra Service Registry entries (eg for internet endpoints, VMs) can be added with the `ServiceEntry` resource.
+Recall that, in some mesh configurations, such `ServiceEntries` are *necessary* for workloads in the mesh to talk to anything outside the cluster.
+`ServiceEntry` is a higher-level resource - doesn't necessarily specify all endpoints in a Service, instead it says where to discover them.
+
+There is no (easy) way to view the contents of the Service Registry; the imported Kubernetes `Services`, DNS query results, etc aren't reflected as a read-only resource like Kubernetes' `Endpoint`.