Merge pull request #4093 from MrHohn/release-1.7-esipp-ga

Update ESIPP documentation to reflect new fields

docs/tasks/access-application-cluster/create-external-load-balancer.md

@@ -81,7 +81,9 @@ information through `kubectl`:
 ```bash
     kubectl describe services example-service
 ```
+
 which should produce output like this:
+
 ```bash
     Name:  example-service
     Selector:   app=example
@@ -97,10 +99,29 @@ which should produce output like this:
 
 The IP address is listed next to `LoadBalancer Ingress`.
 
-## Annotation to modify the LoadBalancer behavior for preservation of Source IP
-In 1.5, a Beta feature has been added that changes the behavior of the external LoadBalancer feature.
+## Preserving the client source IP
 
-This feature can be activated by adding the beta annotation below to the metadata section of the Service Configuration file.
+Due to the implementation of this feature, the source IP seen in the target
+container will *not be the original source IP* of the client. To enable
+preservation of the client IP, the following fields can be configured in the
+service spec (supported in GCE/GKE environments):
+
+* `service.spec.externalTrafficPolicy` - denotes if this Service desires to route
+external traffic to node-local or cluster-wide endpoints. There are two available
+options: "Cluster" (default) and "Local". "Cluster" obscures the client source
+IP and may cause a second hop to another node, but should have good overall
+load-spreading. "Local" preserves the client source IP and avoids a second hop
+for LoadBalancer and NodePort type services, but risks potentially imbalanced
+traffic spreading.
+* `service.spec.healthCheckNodePort` - specifies the healthcheck nodePort
+(numeric port number) for the service. If not specified, healthCheckNodePort is
+created by the service API backend with the allocated nodePort. It will use the
+user-specified nodePort value if specified by the client. It only has an
+effect when type is set to "LoadBalancer" and externalTrafficPolicy is set
+to "Local".
+
+This feature can be activated by setting `externalTrafficPolicy` to "Local" in the
+Service Configuration file.
 
 ```json
     {
@@ -108,9 +129,6 @@ This feature can be activated by adding the beta annotation below to the metadat
       "apiVersion": "v1",
       "metadata": {
         "name": "example-service",
-        "annotations": {
-            "service.beta.kubernetes.io/external-traffic": "OnlyLocal"
-        }
       },
       "spec": {
         "ports": [{
@@ -120,11 +138,33 @@ This feature can be activated by adding the beta annotation below to the metadat
         "selector": {
           "app": "example"
         },
-        "type": "LoadBalancer"
+        "type": "LoadBalancer",
+        "externalTrafficPolicy": "Local"
       }
     }
 ```
 
+### Feature availability
+
+| k8s version | Feature support |
+| :---------: |:-----------:|
+| 1.7+ | Supports the full API fields |
+| 1.5 - 1.6 | Supports Beta Annotations |
+| <1.5 | Unsupported |
+
+Below you could find the deprecated Beta annotations used to enable this feature
+prior to its stable version. Newer Kubernetes versions may stop supporting these
+after v1.7. Please update existing applications to use the fields directly.
+
+* `service.beta.kubernetes.io/external-traffic` annotation <-> `service.spec.externalTrafficPolicy` field
+* `service.beta.kubernetes.io/healthcheck-nodeport` annotation <-> `service.spec.healthCheckNodePort` field
+
+`service.beta.kubernetes.io/external-traffic` annotation has a different set of values
+compared to the `service.spec.externalTrafficPolicy` field. The values match as follows:
+
+* "OnlyLocal" for annotation <-> "Local" for field
+* "Global" for annotation <-> "Cluster" for field
+
 **Note that this feature is not currently implemented for all cloudproviders/environments.**
 
 
@@ -138,11 +178,6 @@ It is important to note that the datapath for this functionality is provided by
 
 When the service type is set to `LoadBalancer`, Kubernetes provides functionality equivalent to `type=<ClusterIP>` to pods within the cluster and extends it by programming the (external to Kubernetes) load balancer with entries for the Kubernetes VMs. The Kubernetes service controller automates the creation of the external load balancer, health checks (if needed), firewall rules (if needed) and retrieves the external IP allocated by the cloud provider and populates it in the service object.
 
-## Loss of client source IP for external traffic
-
-Due to the implementation of this feature, the source IP for sessions as seen in the target container will *not be the original source IP* of the client. This is the default behavior as of Kubernetes v1.5. However, starting in v1.5, an optional beta feature has been added
-that will preserve the client Source IP for GCE/GKE environments. This feature will be phased in for other cloud providers in subsequent releases.
-
 ## Caveats and Limitations when preserving source IPs
 
 GCE/AWS load balancers do not provide weights for their target pools. This was not an issue with the old LB