Merge pull request #46716 from thockin/proxy-comments

Kube-proxy cleanups

Merge pull request #46716 from thockin/proxy-comments
be987b01 · Tim Hockin · GitHub · b641aedc · fc34a9d6 · be987b01
Commit be987b01 authored Jun 03, 2017 by Tim Hockin Committed by GitHub Jun 03, 2017
26 changed files
--- a/api/openapi-spec/swagger.json
+++ b/api/openapi-spec/swagger.json
@@ -49749,7 +49749,7 @@
      "type": "string"
     },
     "externalTrafficPolicy": {
-      "description": "externalTrafficPolicy denotes if this Service desires to route external traffic to local endpoints only. This preserves Source IP and avoids a second hop for LoadBalancer and Nodeport type services.",
+      "description": "externalTrafficPolicy denotes if this Service desires to route external traffic to node-local or cluster-wide endpoints. \"Local\" preserves the client source IP and avoids a second hop for LoadBalancer and Nodeport type services, but risks potentially imbalanced traffic spreading. \"Cluster\" obscures the client source IP and may cause a second hop to another node, but should have good overall load-spreading.",
      "type": "string"
     },
     "healthCheckNodePort": {
--- a/api/swagger-spec/v1.json
+++ b/api/swagger-spec/v1.json
@@ -21715,7 +21715,7 @@
     },
     "externalTrafficPolicy": {
      "type": "string",
-      "description": "externalTrafficPolicy denotes if this Service desires to route external traffic to local endpoints only. This preserves Source IP and avoids a second hop for LoadBalancer and Nodeport type services."
+      "description": "externalTrafficPolicy denotes if this Service desires to route external traffic to node-local or cluster-wide endpoints. \"Local\" preserves the client source IP and avoids a second hop for LoadBalancer and Nodeport type services, but risks potentially imbalanced traffic spreading. \"Cluster\" obscures the client source IP and may cause a second hop to another node, but should have good overall load-spreading."
     },
     "healthCheckNodePort": {
      "type": "integer",

--- a/cmd/kube-proxy/app/server.go
+++ b/cmd/kube-proxy/app/server.go
@@ -140,7 +140,7 @@ func AddFlags(options *Options, fs *pflag.FlagSet) {
 	fs.DurationVar(&options.config.IPTables.SyncPeriod.Duration, "iptables-sync-period", options.config.IPTables.SyncPeriod.Duration, "The maximum interval of how often iptables rules are refreshed (e.g. '5s', '1m', '2h22m').  Must be greater than 0.")
 	fs.DurationVar(&options.config.IPTables.MinSyncPeriod.Duration, "iptables-min-sync-period", options.config.IPTables.MinSyncPeriod.Duration, "The minimum interval of how often the iptables rules can be refreshed as endpoints and services change (e.g. '5s', '1m', '2h22m').")
 	fs.DurationVar(&options.config.ConfigSyncPeriod.Duration, "config-sync-period", options.config.ConfigSyncPeriod.Duration, "How often configuration from the apiserver is refreshed.  Must be greater than 0.")
-	fs.BoolVar(&options.config.IPTables.MasqueradeAll, "masquerade-all", options.config.IPTables.MasqueradeAll, "If using the pure iptables proxy, SNAT everything")
+	fs.BoolVar(&options.config.IPTables.MasqueradeAll, "masquerade-all", options.config.IPTables.MasqueradeAll, "If using the pure iptables proxy, SNAT everything (this not commonly needed)")
 	fs.StringVar(&options.config.ClusterCIDR, "cluster-cidr", options.config.ClusterCIDR, "The CIDR range of pods in the cluster. It is used to bridge traffic coming from outside of the cluster. If not provided, no off-cluster bridging will be performed.")
 	fs.StringVar(&options.config.ClientConnection.ContentType, "kube-api-content-type", options.config.ClientConnection.ContentType, "Content type of requests sent to apiserver.")
 	fs.Float32Var(&options.config.ClientConnection.QPS, "kube-api-qps", options.config.ClientConnection.QPS, "QPS to use while talking with kubernetes apiserver")

--- a/docs/api-reference/v1/definitions.html
+++ b/docs/api-reference/v1/definitions.html
@@ -9861,7 +9861,7 @@ Examples:<br>
 </tr>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">externalTrafficPolicy</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">externalTrafficPolicy denotes if this Service desires to route external traffic to local endpoints only. This preserves Source IP and avoids a second hop for LoadBalancer and Nodeport type services.</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">externalTrafficPolicy denotes if this Service desires to route external traffic to node-local or cluster-wide endpoints. "Local" preserves the client source IP and avoids a second hop for LoadBalancer and Nodeport type services, but risks potentially imbalanced traffic spreading. "Cluster" obscures the client source IP and may cause a second hop to another node, but should have good overall load-spreading.</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td>
 <td class="tableblock halign-left valign-top"></td>
@@ -10105,7 +10105,7 @@ Examples:<br>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2017-05-31 19:35:23 UTC
+Last updated 2017-06-01 23:03:33 UTC
 </div>
 </div>
 </body>

--- a/federation/apis/openapi-spec/swagger.json
+++ b/federation/apis/openapi-spec/swagger.json
@@ -12589,7 +12589,7 @@
      "type": "string"
     },
     "externalTrafficPolicy": {
-      "description": "externalTrafficPolicy denotes if this Service desires to route external traffic to local endpoints only. This preserves Source IP and avoids a second hop for LoadBalancer and Nodeport type services.",
+      "description": "externalTrafficPolicy denotes if this Service desires to route external traffic to node-local or cluster-wide endpoints. \"Local\" preserves the client source IP and avoids a second hop for LoadBalancer and Nodeport type services, but risks potentially imbalanced traffic spreading. \"Cluster\" obscures the client source IP and may cause a second hop to another node, but should have good overall load-spreading.",
      "type": "string"
     },
     "healthCheckNodePort": {

--- a/federation/apis/swagger-spec/v1.json
+++ b/federation/apis/swagger-spec/v1.json
@@ -5118,7 +5118,7 @@
     },
     "externalTrafficPolicy": {
      "type": "string",
-      "description": "externalTrafficPolicy denotes if this Service desires to route external traffic to local endpoints only. This preserves Source IP and avoids a second hop for LoadBalancer and Nodeport type services."
+      "description": "externalTrafficPolicy denotes if this Service desires to route external traffic to node-local or cluster-wide endpoints. \"Local\" preserves the client source IP and avoids a second hop for LoadBalancer and Nodeport type services, but risks potentially imbalanced traffic spreading. \"Cluster\" obscures the client source IP and may cause a second hop to another node, but should have good overall load-spreading."
     },
     "healthCheckNodePort": {
      "type": "integer",

--- a/federation/docs/api-reference/v1/definitions.html
+++ b/federation/docs/api-reference/v1/definitions.html
@@ -2207,7 +2207,7 @@ When an object is created, the system will populate this list with the current s
 </tr>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">externalTrafficPolicy</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">externalTrafficPolicy denotes if this Service desires to route external traffic to local endpoints only. This preserves Source IP and avoids a second hop for LoadBalancer and Nodeport type services.</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">externalTrafficPolicy denotes if this Service desires to route external traffic to node-local or cluster-wide endpoints. "Local" preserves the client source IP and avoids a second hop for LoadBalancer and Nodeport type services, but risks potentially imbalanced traffic spreading. "Cluster" obscures the client source IP and may cause a second hop to another node, but should have good overall load-spreading.</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td>
 <td class="tableblock halign-left valign-top"></td>
@@ -2331,7 +2331,7 @@ Examples:<br>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2017-05-17 22:26:25 UTC
+Last updated 2017-06-01 05:34:38 UTC
 </div>
 </div>
 </body>

--- a/pkg/api/service/util_test.go
+++ b/pkg/api/service/util_test.go
@@ -157,7 +157,7 @@ func TestRequestsOnlyLocalTraffic(t *testing.T) {
 	checkRequestsOnlyLocalTraffic(false, &api.Service{
 		Spec: api.ServiceSpec{
 			Type: api.ServiceTypeNodePort,
-			ExternalTrafficPolicy: api.ServiceExternalTrafficPolicyTypeGlobal,
+			ExternalTrafficPolicy: api.ServiceExternalTrafficPolicyTypeCluster,
 		},
 	})
 	checkRequestsOnlyLocalTraffic(true, &api.Service{
@@ -169,7 +169,7 @@ func TestRequestsOnlyLocalTraffic(t *testing.T) {
 	checkRequestsOnlyLocalTraffic(false, &api.Service{
 		Spec: api.ServiceSpec{
 			Type: api.ServiceTypeLoadBalancer,
-			ExternalTrafficPolicy: api.ServiceExternalTrafficPolicyTypeGlobal,
+			ExternalTrafficPolicy: api.ServiceExternalTrafficPolicyTypeCluster,
 		},
 	})
 	checkRequestsOnlyLocalTraffic(true, &api.Service{
@@ -197,7 +197,7 @@ func TestNeedsHealthCheck(t *testing.T) {
 	checkNeedsHealthCheck(false, &api.Service{
 		Spec: api.ServiceSpec{
 			Type: api.ServiceTypeNodePort,
-			ExternalTrafficPolicy: api.ServiceExternalTrafficPolicyTypeGlobal,
+			ExternalTrafficPolicy: api.ServiceExternalTrafficPolicyTypeCluster,
 		},
 	})
 	checkNeedsHealthCheck(false, &api.Service{
@@ -209,7 +209,7 @@ func TestNeedsHealthCheck(t *testing.T) {
 	checkNeedsHealthCheck(false, &api.Service{
 		Spec: api.ServiceSpec{
 			Type: api.ServiceTypeLoadBalancer,
-			ExternalTrafficPolicy: api.ServiceExternalTrafficPolicyTypeGlobal,
+			ExternalTrafficPolicy: api.ServiceExternalTrafficPolicyTypeCluster,
 		},
 	})
 	checkNeedsHealthCheck(true, &api.Service{
@@ -268,13 +268,13 @@ func TestGetServiceHealthCheckNodePort(t *testing.T) {
 	checkGetServiceHealthCheckNodePort(0, &api.Service{
 		Spec: api.ServiceSpec{
 			Type: api.ServiceTypeNodePort,
-			ExternalTrafficPolicy: api.ServiceExternalTrafficPolicyTypeGlobal,
+			ExternalTrafficPolicy: api.ServiceExternalTrafficPolicyTypeCluster,
 		},
 	})
 	checkGetServiceHealthCheckNodePort(0, &api.Service{
 		Spec: api.ServiceSpec{
 			Type: api.ServiceTypeLoadBalancer,
-			ExternalTrafficPolicy: api.ServiceExternalTrafficPolicyTypeGlobal,
+			ExternalTrafficPolicy: api.ServiceExternalTrafficPolicyTypeCluster,
 		},
 	})
 	checkGetServiceHealthCheckNodePort(34567, &api.Service{
@@ -306,7 +306,7 @@ func TestClearExternalTrafficPolicy(t *testing.T) {
 			&api.Service{
 				Spec: api.ServiceSpec{
 					Type: api.ServiceTypeClusterIP,
-					ExternalTrafficPolicy: api.ServiceExternalTrafficPolicyTypeGlobal,
+					ExternalTrafficPolicy: api.ServiceExternalTrafficPolicyTypeCluster,
 				},
 			},
 		},
@@ -346,7 +346,7 @@ func TestSetServiceHealthCheckNodePort(t *testing.T) {
 			&api.Service{
 				Spec: api.ServiceSpec{
 					Type: api.ServiceTypeClusterIP,
-					ExternalTrafficPolicy: api.ServiceExternalTrafficPolicyTypeGlobal,
+					ExternalTrafficPolicy: api.ServiceExternalTrafficPolicyTypeCluster,
 				},
 			},
 			30012,
@@ -356,7 +356,7 @@ func TestSetServiceHealthCheckNodePort(t *testing.T) {
 			&api.Service{
 				Spec: api.ServiceSpec{
 					Type: api.ServiceTypeClusterIP,
-					ExternalTrafficPolicy: api.ServiceExternalTrafficPolicyTypeGlobal,
+					ExternalTrafficPolicy: api.ServiceExternalTrafficPolicyTypeCluster,
 				},
 			},
 			0,

--- a/pkg/api/testing/fuzzer.go
+++ b/pkg/api/testing/fuzzer.go
@@ -322,7 +322,7 @@ func coreFuncs(t apitesting.TestingCommon) []interface{} {
 			*p = types[c.Rand.Intn(len(types))]
 		},
 		func(p *api.ServiceExternalTrafficPolicyType, c fuzz.Continue) {
-			types := []api.ServiceExternalTrafficPolicyType{api.ServiceExternalTrafficPolicyTypeGlobal, api.ServiceExternalTrafficPolicyTypeLocal}
+			types := []api.ServiceExternalTrafficPolicyType{api.ServiceExternalTrafficPolicyTypeCluster, api.ServiceExternalTrafficPolicyTypeLocal}
 			*p = types[c.Rand.Intn(len(types))]
 		},
 		func(ct *api.Container, c fuzz.Continue) {

--- a/pkg/api/types.go
+++ b/pkg/api/types.go
@@ -2504,10 +2504,10 @@ const (
 type ServiceExternalTrafficPolicyType string
 const (
-	// ServiceExternalTrafficPolicyTypeLocal specifies local endpoints behavior.
+	// ServiceExternalTrafficPolicyTypeLocal specifies node-local endpoints behavior.
 	ServiceExternalTrafficPolicyTypeLocal ServiceExternalTrafficPolicyType = "Local"
-	// ServiceExternalTrafficPolicyTypeGlobal specifies global (legacy) behavior.
+	// ServiceExternalTrafficPolicyTypeCluster specifies cluster-wide (legacy) behavior.
-	ServiceExternalTrafficPolicyTypeGlobal ServiceExternalTrafficPolicyType = "Global"
+	ServiceExternalTrafficPolicyTypeCluster ServiceExternalTrafficPolicyType = "Cluster"
 )
 // ServiceStatus represents the current status of a service
@@ -2610,9 +2610,12 @@ type ServiceSpec struct {
 	// +optional
 	LoadBalancerSourceRanges []string
-	// externalTrafficPolicy denotes if this Service desires to route external traffic to
+	// externalTrafficPolicy denotes if this Service desires to route external
-	// local endpoints only. This preserves Source IP and avoids a second hop for
+	// traffic to node-local or cluster-wide endpoints. "Local" preserves the
-	// LoadBalancer and Nodeport type services.
+	// client source IP and avoids a second hop for LoadBalancer and Nodeport
+	// type services, but risks potentially imbalanced traffic spreading.
+	// "Cluster" obscures the client source IP and may cause a second hop to
+	// another node, but should have good overall load-spreading.
 	// +optional
 	ExternalTrafficPolicy ServiceExternalTrafficPolicyType

--- a/pkg/api/v1/defaults.go
+++ b/pkg/api/v1/defaults.go
@@ -120,7 +120,7 @@ func SetDefaults_Service(obj *Service) {
 	} else if (obj.Spec.Type == ServiceTypeNodePort ||
 		obj.Spec.Type == ServiceTypeLoadBalancer) &&
 		obj.Spec.ExternalTrafficPolicy == "" {
-		obj.Spec.ExternalTrafficPolicy = ServiceExternalTrafficPolicyTypeGlobal
+		obj.Spec.ExternalTrafficPolicy = ServiceExternalTrafficPolicyTypeCluster
 	}
 }
 func SetDefaults_Pod(obj *Pod) {

--- a/pkg/api/v1/defaults_test.go
+++ b/pkg/api/v1/defaults_test.go
@@ -885,15 +885,15 @@ func TestSetDefaulServiceExternalTraffic(t *testing.T) {
 	in = &v1.Service{Spec: v1.ServiceSpec{Type: v1.ServiceTypeNodePort}}
 	obj = roundTrip(t, runtime.Object(in))
 	out = obj.(*v1.Service)
-	if out.Spec.ExternalTrafficPolicy != v1.ServiceExternalTrafficPolicyTypeGlobal {
+	if out.Spec.ExternalTrafficPolicy != v1.ServiceExternalTrafficPolicyTypeCluster {
-		t.Errorf("Expected ExternalTrafficPolicy to be %v, got %v", v1.ServiceExternalTrafficPolicyTypeGlobal, out.Spec.ExternalTrafficPolicy)
+		t.Errorf("Expected ExternalTrafficPolicy to be %v, got %v", v1.ServiceExternalTrafficPolicyTypeCluster, out.Spec.ExternalTrafficPolicy)
 	}
 	in = &v1.Service{Spec: v1.ServiceSpec{Type: v1.ServiceTypeLoadBalancer}}
 	obj = roundTrip(t, runtime.Object(in))
 	out = obj.(*v1.Service)
-	if out.Spec.ExternalTrafficPolicy != v1.ServiceExternalTrafficPolicyTypeGlobal {
+	if out.Spec.ExternalTrafficPolicy != v1.ServiceExternalTrafficPolicyTypeCluster {
-		t.Errorf("Expected ExternalTrafficPolicy to be %v, got %v", v1.ServiceExternalTrafficPolicyTypeGlobal, out.Spec.ExternalTrafficPolicy)
+		t.Errorf("Expected ExternalTrafficPolicy to be %v, got %v", v1.ServiceExternalTrafficPolicyTypeCluster, out.Spec.ExternalTrafficPolicy)
 	}
 	in = &v1.Service{

--- a/pkg/api/v1/generated.proto
+++ b/pkg/api/v1/generated.proto
@@ -3734,9 +3734,12 @@ message ServiceSpec {
  // +optional
  optional string externalName = 10;
-  // externalTrafficPolicy denotes if this Service desires to route external traffic to
+  // externalTrafficPolicy denotes if this Service desires to route external
-  // local endpoints only. This preserves Source IP and avoids a second hop for
+  // traffic to node-local or cluster-wide endpoints. "Local" preserves the
-  // LoadBalancer and Nodeport type services.
+  // client source IP and avoids a second hop for LoadBalancer and Nodeport
+  // type services, but risks potentially imbalanced traffic spreading.
+  // "Cluster" obscures the client source IP and may cause a second hop to
+  // another node, but should have good overall load-spreading.
  // +optional
  optional string externalTrafficPolicy = 11;

--- a/pkg/api/v1/service/util_test.go
+++ b/pkg/api/v1/service/util_test.go
@@ -157,7 +157,7 @@ func TestRequestsOnlyLocalTraffic(t *testing.T) {
 	checkRequestsOnlyLocalTraffic(false, &v1.Service{
 		Spec: v1.ServiceSpec{
 			Type: v1.ServiceTypeNodePort,
-			ExternalTrafficPolicy: v1.ServiceExternalTrafficPolicyTypeGlobal,
+			ExternalTrafficPolicy: v1.ServiceExternalTrafficPolicyTypeCluster,
 		},
 	})
 	checkRequestsOnlyLocalTraffic(true, &v1.Service{
@@ -169,7 +169,7 @@ func TestRequestsOnlyLocalTraffic(t *testing.T) {
 	checkRequestsOnlyLocalTraffic(false, &v1.Service{
 		Spec: v1.ServiceSpec{
 			Type: v1.ServiceTypeLoadBalancer,
-			ExternalTrafficPolicy: v1.ServiceExternalTrafficPolicyTypeGlobal,
+			ExternalTrafficPolicy: v1.ServiceExternalTrafficPolicyTypeCluster,
 		},
 	})
 	checkRequestsOnlyLocalTraffic(true, &v1.Service{
@@ -197,7 +197,7 @@ func TestNeedsHealthCheck(t *testing.T) {
 	checkNeedsHealthCheck(false, &v1.Service{
 		Spec: v1.ServiceSpec{
 			Type: v1.ServiceTypeNodePort,
-			ExternalTrafficPolicy: v1.ServiceExternalTrafficPolicyTypeGlobal,
+			ExternalTrafficPolicy: v1.ServiceExternalTrafficPolicyTypeCluster,
 		},
 	})
 	checkNeedsHealthCheck(false, &v1.Service{
@@ -209,7 +209,7 @@ func TestNeedsHealthCheck(t *testing.T) {
 	checkNeedsHealthCheck(false, &v1.Service{
 		Spec: v1.ServiceSpec{
 			Type: v1.ServiceTypeLoadBalancer,
-			ExternalTrafficPolicy: v1.ServiceExternalTrafficPolicyTypeGlobal,
+			ExternalTrafficPolicy: v1.ServiceExternalTrafficPolicyTypeCluster,
 		},
 	})
 	checkNeedsHealthCheck(true, &v1.Service{
@@ -268,13 +268,13 @@ func TestGetServiceHealthCheckNodePort(t *testing.T) {
 	checkGetServiceHealthCheckNodePort(0, &v1.Service{
 		Spec: v1.ServiceSpec{
 			Type: v1.ServiceTypeNodePort,
-			ExternalTrafficPolicy: v1.ServiceExternalTrafficPolicyTypeGlobal,
+			ExternalTrafficPolicy: v1.ServiceExternalTrafficPolicyTypeCluster,
 		},
 	})
 	checkGetServiceHealthCheckNodePort(0, &v1.Service{
 		Spec: v1.ServiceSpec{
 			Type: v1.ServiceTypeLoadBalancer,
-			ExternalTrafficPolicy: v1.ServiceExternalTrafficPolicyTypeGlobal,
+			ExternalTrafficPolicy: v1.ServiceExternalTrafficPolicyTypeCluster,
 		},
 	})
 	checkGetServiceHealthCheckNodePort(34567, &v1.Service{
@@ -306,7 +306,7 @@ func TestClearExternalTrafficPolicy(t *testing.T) {
 			&v1.Service{
 				Spec: v1.ServiceSpec{
 					Type: v1.ServiceTypeClusterIP,
-					ExternalTrafficPolicy: v1.ServiceExternalTrafficPolicyTypeGlobal,
+					ExternalTrafficPolicy: v1.ServiceExternalTrafficPolicyTypeCluster,
 				},
 			},
 		},
@@ -346,7 +346,7 @@ func TestSetServiceHealthCheckNodePort(t *testing.T) {
 			&v1.Service{
 				Spec: v1.ServiceSpec{
 					Type: v1.ServiceTypeClusterIP,
-					ExternalTrafficPolicy: v1.ServiceExternalTrafficPolicyTypeGlobal,
+					ExternalTrafficPolicy: v1.ServiceExternalTrafficPolicyTypeCluster,
 				},
 			},
 			30012,
@@ -356,7 +356,7 @@ func TestSetServiceHealthCheckNodePort(t *testing.T) {
 			&v1.Service{
 				Spec: v1.ServiceSpec{
 					Type: v1.ServiceTypeClusterIP,
-					ExternalTrafficPolicy: v1.ServiceExternalTrafficPolicyTypeGlobal,
+					ExternalTrafficPolicy: v1.ServiceExternalTrafficPolicyTypeCluster,
 				},
 			},
 			0,

--- a/pkg/api/v1/types.go
+++ b/pkg/api/v1/types.go
@@ -2842,10 +2842,10 @@ const (
 type ServiceExternalTrafficPolicyType string
 const (
-	// ServiceExternalTrafficPolicyTypeLocal specifies local endpoints behavior.
+	// ServiceExternalTrafficPolicyTypeLocal specifies node-local endpoints behavior.
 	ServiceExternalTrafficPolicyTypeLocal ServiceExternalTrafficPolicyType = "Local"
-	// ServiceExternalTrafficPolicyTypeGlobal specifies global (legacy) behavior.
+	// ServiceExternalTrafficPolicyTypeCluster specifies node-global (legacy) behavior.
-	ServiceExternalTrafficPolicyTypeGlobal ServiceExternalTrafficPolicyType = "Global"
+	ServiceExternalTrafficPolicyTypeCluster ServiceExternalTrafficPolicyType = "Cluster"
 )
 // ServiceStatus represents the current status of a service.
@@ -2961,9 +2961,12 @@ type ServiceSpec struct {
 	// +optional
 	ExternalName string `json:"externalName,omitempty" protobuf:"bytes,10,opt,name=externalName"`
-	// externalTrafficPolicy denotes if this Service desires to route external traffic to
+	// externalTrafficPolicy denotes if this Service desires to route external
-	// local endpoints only. This preserves Source IP and avoids a second hop for
+	// traffic to node-local or cluster-wide endpoints. "Local" preserves the
-	// LoadBalancer and Nodeport type services.
+	// client source IP and avoids a second hop for LoadBalancer and Nodeport
+	// type services, but risks potentially imbalanced traffic spreading.
+	// "Cluster" obscures the client source IP and may cause a second hop to
+	// another node, but should have good overall load-spreading.
 	// +optional
 	ExternalTrafficPolicy ServiceExternalTrafficPolicyType `json:"externalTrafficPolicy,omitempty" protobuf:"bytes,11,opt,name=externalTrafficPolicy"`

--- a/pkg/api/v1/types_swagger_doc_generated.go
+++ b/pkg/api/v1/types_swagger_doc_generated.go
@@ -1858,7 +1858,7 @@ var map_ServiceSpec = map[string]string{
 	"loadBalancerIP":           "Only applies to Service Type: LoadBalancer LoadBalancer will get created with the IP specified in this field. This feature depends on whether the underlying cloud-provider supports specifying the loadBalancerIP when a load balancer is created. This field will be ignored if the cloud-provider does not support the feature.",
 	"loadBalancerSourceRanges": "If specified and supported by the platform, this will restrict traffic through the cloud-provider load-balancer will be restricted to the specified client IPs. This field will be ignored if the cloud-provider does not support the feature.\" More info: https://kubernetes.io/docs/tasks/access-application-cluster/configure-cloud-provider-firewall/",
 	"externalName":             "externalName is the external reference that kubedns or equivalent will return as a CNAME record for this service. No proxying will be involved. Must be a valid DNS name and requires Type to be ExternalName.",
-	"externalTrafficPolicy":    "externalTrafficPolicy denotes if this Service desires to route external traffic to local endpoints only. This preserves Source IP and avoids a second hop for LoadBalancer and Nodeport type services.",
+	"externalTrafficPolicy":    "externalTrafficPolicy denotes if this Service desires to route external traffic to node-local or cluster-wide endpoints. \"Local\" preserves the client source IP and avoids a second hop for LoadBalancer and Nodeport type services, but risks potentially imbalanced traffic spreading. \"Cluster\" obscures the client source IP and may cause a second hop to another node, but should have good overall load-spreading.",
 	"healthCheckNodePort":      "healthCheckNodePort specifies the healthcheck nodePort for the service. If not specified, HealthCheckNodePort is created by the service api backend with the allocated nodePort. Will use user-specified nodePort value if specified by the client. Only effects when Type is set to LoadBalancer and ExternalTrafficPolicy is set to Local.",
 }

--- a/pkg/api/validation/validation.go
+++ b/pkg/api/validation/validation.go
@@ -2901,10 +2901,10 @@ func validateServiceExternalTrafficFieldsValue(service *api.Service) field.Error
 	// Check first class fields.
 	if service.Spec.ExternalTrafficPolicy != "" &&
-		service.Spec.ExternalTrafficPolicy != api.ServiceExternalTrafficPolicyTypeGlobal &&
+		service.Spec.ExternalTrafficPolicy != api.ServiceExternalTrafficPolicyTypeCluster &&
 		service.Spec.ExternalTrafficPolicy != api.ServiceExternalTrafficPolicyTypeLocal {
 		allErrs = append(allErrs, field.Invalid(field.NewPath("spec").Child("externalTrafficPolicy"), service.Spec.ExternalTrafficPolicy,
-			fmt.Sprintf("ExternalTrafficPolicy must be empty, %v or %v", api.ServiceExternalTrafficPolicyTypeGlobal, api.ServiceExternalTrafficPolicyTypeLocal)))
+			fmt.Sprintf("ExternalTrafficPolicy must be empty, %v or %v", api.ServiceExternalTrafficPolicyTypeCluster, api.ServiceExternalTrafficPolicyTypeLocal)))
 	}
 	if service.Spec.HealthCheckNodePort < 0 {
 		allErrs = append(allErrs, field.Invalid(field.NewPath("spec").Child("healthCheckNodePort"), service.Spec.HealthCheckNodePort,

--- a/pkg/api/validation/validation_test.go
+++ b/pkg/api/validation/validation_test.go
@@ -6380,7 +6380,7 @@ func TestValidateServiceExternalTrafficFieldsCombination(t *testing.T) {
 			name: "cannot set healthCheckNodePort field on loadBalancer service with externalTrafficPolicy!=Local",
 			tweakSvc: func(s *api.Service) {
 				s.Spec.Type = api.ServiceTypeLoadBalancer
-				s.Spec.ExternalTrafficPolicy = api.ServiceExternalTrafficPolicyTypeGlobal
+				s.Spec.ExternalTrafficPolicy = api.ServiceExternalTrafficPolicyTypeCluster
 				s.Spec.HealthCheckNodePort = 34567
 			},
 			numErrs: 1,

--- a/pkg/proxy/iptables/proxier.go
+++ b/pkg/proxy/iptables/proxier.go
@@ -1175,8 +1175,12 @@ func (proxier *Proxier) syncProxyRules() {
 		)
 		if proxier.masqueradeAll {
 			writeLine(proxier.natRules, append(args, "-j", string(KubeMarkMasqChain))...)
-		}
+		} else if len(proxier.clusterCIDR) > 0 {
-		if len(proxier.clusterCIDR) > 0 {
+			// This masquerades off-cluster traffic to a service VIP.  The idea
+			// is that you can establish a static route for your Service range,
+			// routing to any node, and that node will bridge into the Service
+			// for you.  Since that might bounce off-node, we masquerade here.
+			// If/when we support "Local" policy for VIPs, we should update this.
 			writeLine(proxier.natRules, append(args, "! -s", proxier.clusterCIDR, "-j", string(KubeMarkMasqChain))...)
 		}
 		writeLine(proxier.natRules, append(args, "-j", string(svcChain))...)
@@ -1480,7 +1484,7 @@ func (proxier *Proxier) syncProxyRules() {
 				localEndpointChains = append(localEndpointChains, endpointChains[i])
 			}
 		}
-		// First rule in the chain redirects all pod -> external vip traffic to the
+		// First rule in the chain redirects all pod -> external VIP traffic to the
 		// Service's ClusterIP instead. This happens whether or not we have local
 		// endpoints; only if clusterCIDR is specified
 		if len(proxier.clusterCIDR) > 0 {

--- a/pkg/registry/core/service/rest_test.go
+++ b/pkg/registry/core/service/rest_test.go
@@ -1189,7 +1189,7 @@ func TestServiceRegistryExternalTrafficGlobal(t *testing.T) {
 				Protocol:   api.ProtocolTCP,
 				TargetPort: intstr.FromInt(6502),
 			}},
-			ExternalTrafficPolicy: api.ServiceExternalTrafficPolicyTypeGlobal,
+			ExternalTrafficPolicy: api.ServiceExternalTrafficPolicyTypeCluster,
 		},
 	}
 	created_svc, err := storage.Create(ctx, svc, false)

--- a/staging/src/k8s.io/client-go/pkg/api/types.go
+++ b/staging/src/k8s.io/client-go/pkg/api/types.go
@@ -2504,10 +2504,10 @@ const (
 type ServiceExternalTrafficPolicyType string
 const (
-	// ServiceExternalTrafficPolicyTypeLocal specifies local endpoints behavior.
+	// ServiceExternalTrafficPolicyTypeLocal specifies node-local endpoints behavior.
 	ServiceExternalTrafficPolicyTypeLocal ServiceExternalTrafficPolicyType = "Local"
-	// ServiceExternalTrafficPolicyTypeGlobal specifies global (legacy) behavior.
+	// ServiceExternalTrafficPolicyTypeCluster specifies cluster-wide (legacy) behavior.
-	ServiceExternalTrafficPolicyTypeGlobal ServiceExternalTrafficPolicyType = "Global"
+	ServiceExternalTrafficPolicyTypeCluster ServiceExternalTrafficPolicyType = "Cluster"
 )
 // ServiceStatus represents the current status of a service
@@ -2610,9 +2610,12 @@ type ServiceSpec struct {
 	// +optional
 	LoadBalancerSourceRanges []string
-	// externalTrafficPolicy denotes if this Service desires to route external traffic to
+	// externalTrafficPolicy denotes if this Service desires to route external
-	// local endpoints only. This preserves Source IP and avoids a second hop for
+	// traffic to node-local or cluster-wide endpoints. "Local" preserves the
-	// LoadBalancer and Nodeport type services.
+	// client source IP and avoids a second hop for LoadBalancer and Nodeport
+	// type services, but risks potentially imbalanced traffic spreading.
+	// "Cluster" obscures the client source IP and may cause a second hop to
+	// another node, but should have good overall load-spreading.
 	// +optional
 	ExternalTrafficPolicy ServiceExternalTrafficPolicyType

--- a/staging/src/k8s.io/client-go/pkg/api/v1/defaults.go
+++ b/staging/src/k8s.io/client-go/pkg/api/v1/defaults.go
@@ -120,7 +120,7 @@ func SetDefaults_Service(obj *Service) {
 	} else if (obj.Spec.Type == ServiceTypeNodePort ||
 		obj.Spec.Type == ServiceTypeLoadBalancer) &&
 		obj.Spec.ExternalTrafficPolicy == "" {
-		obj.Spec.ExternalTrafficPolicy = ServiceExternalTrafficPolicyTypeGlobal
+		obj.Spec.ExternalTrafficPolicy = ServiceExternalTrafficPolicyTypeCluster
 	}
 }
 func SetDefaults_Pod(obj *Pod) {

--- a/staging/src/k8s.io/client-go/pkg/api/v1/generated.proto
+++ b/staging/src/k8s.io/client-go/pkg/api/v1/generated.proto
@@ -3734,9 +3734,12 @@ message ServiceSpec {
  // +optional
  optional string externalName = 10;
-  // externalTrafficPolicy denotes if this Service desires to route external traffic to
+  // externalTrafficPolicy denotes if this Service desires to route external
-  // local endpoints only. This preserves Source IP and avoids a second hop for
+  // traffic to node-local or cluster-wide endpoints. "Local" preserves the
-  // LoadBalancer and Nodeport type services.
+  // client source IP and avoids a second hop for LoadBalancer and Nodeport
+  // type services, but risks potentially imbalanced traffic spreading.
+  // "Cluster" obscures the client source IP and may cause a second hop to
+  // another node, but should have good overall load-spreading.
  // +optional
  optional string externalTrafficPolicy = 11;

--- a/staging/src/k8s.io/client-go/pkg/api/v1/types.go
+++ b/staging/src/k8s.io/client-go/pkg/api/v1/types.go
@@ -2842,10 +2842,10 @@ const (
 type ServiceExternalTrafficPolicyType string
 const (
-	// ServiceExternalTrafficPolicyTypeLocal specifies local endpoints behavior.
+	// ServiceExternalTrafficPolicyTypeLocal specifies node-local endpoints behavior.
 	ServiceExternalTrafficPolicyTypeLocal ServiceExternalTrafficPolicyType = "Local"
-	// ServiceExternalTrafficPolicyTypeGlobal specifies global (legacy) behavior.
+	// ServiceExternalTrafficPolicyTypeCluster specifies node-global (legacy) behavior.
-	ServiceExternalTrafficPolicyTypeGlobal ServiceExternalTrafficPolicyType = "Global"
+	ServiceExternalTrafficPolicyTypeCluster ServiceExternalTrafficPolicyType = "Cluster"
 )
 // ServiceStatus represents the current status of a service.
@@ -2961,9 +2961,12 @@ type ServiceSpec struct {
 	// +optional
 	ExternalName string `json:"externalName,omitempty" protobuf:"bytes,10,opt,name=externalName"`
-	// externalTrafficPolicy denotes if this Service desires to route external traffic to
+	// externalTrafficPolicy denotes if this Service desires to route external
-	// local endpoints only. This preserves Source IP and avoids a second hop for
+	// traffic to node-local or cluster-wide endpoints. "Local" preserves the
-	// LoadBalancer and Nodeport type services.
+	// client source IP and avoids a second hop for LoadBalancer and Nodeport
+	// type services, but risks potentially imbalanced traffic spreading.
+	// "Cluster" obscures the client source IP and may cause a second hop to
+	// another node, but should have good overall load-spreading.
 	// +optional
 	ExternalTrafficPolicy ServiceExternalTrafficPolicyType `json:"externalTrafficPolicy,omitempty" protobuf:"bytes,11,opt,name=externalTrafficPolicy"`

--- a/staging/src/k8s.io/client-go/pkg/api/v1/types_swagger_doc_generated.go
+++ b/staging/src/k8s.io/client-go/pkg/api/v1/types_swagger_doc_generated.go
@@ -1858,7 +1858,7 @@ var map_ServiceSpec = map[string]string{
 	"loadBalancerIP":           "Only applies to Service Type: LoadBalancer LoadBalancer will get created with the IP specified in this field. This feature depends on whether the underlying cloud-provider supports specifying the loadBalancerIP when a load balancer is created. This field will be ignored if the cloud-provider does not support the feature.",
 	"loadBalancerSourceRanges": "If specified and supported by the platform, this will restrict traffic through the cloud-provider load-balancer will be restricted to the specified client IPs. This field will be ignored if the cloud-provider does not support the feature.\" More info: https://kubernetes.io/docs/tasks/access-application-cluster/configure-cloud-provider-firewall/",
 	"externalName":             "externalName is the external reference that kubedns or equivalent will return as a CNAME record for this service. No proxying will be involved. Must be a valid DNS name and requires Type to be ExternalName.",
-	"externalTrafficPolicy":    "externalTrafficPolicy denotes if this Service desires to route external traffic to local endpoints only. This preserves Source IP and avoids a second hop for LoadBalancer and Nodeport type services.",
+	"externalTrafficPolicy":    "externalTrafficPolicy denotes if this Service desires to route external traffic to node-local or cluster-wide endpoints. \"Local\" preserves the client source IP and avoids a second hop for LoadBalancer and Nodeport type services, but risks potentially imbalanced traffic spreading. \"Cluster\" obscures the client source IP and may cause a second hop to another node, but should have good overall load-spreading.",
 	"healthCheckNodePort":      "healthCheckNodePort specifies the healthcheck nodePort for the service. If not specified, HealthCheckNodePort is created by the service api backend with the allocated nodePort. Will use user-specified nodePort value if specified by the client. Only effects when Type is set to LoadBalancer and ExternalTrafficPolicy is set to Local.",
 }

--- a/test/e2e/service.go
+++ b/test/e2e/service.go
@@ -1456,7 +1456,7 @@ var _ = framework.KubeDescribe("ESIPP [Slow]", func() {
 		By("turning ESIPP off")
 		svc = jig.UpdateServiceOrFail(svc.Namespace, svc.Name, func(svc *v1.Service) {
-			svc.Spec.ExternalTrafficPolicy = v1.ServiceExternalTrafficPolicyTypeGlobal
+			svc.Spec.ExternalTrafficPolicy = v1.ServiceExternalTrafficPolicyTypeCluster
 		})
 		if service.GetServiceHealthCheckNodePort(svc) > 0 {
 			framework.Failf("Service HealthCheck NodePort still present")