Add documentation for Service InternalTrafficPolicy

content/en/docs/concepts/services-networking/service-traffic-policy.md

@@ -0,0 +1,66 @@
+---
+reviewers:
+- maplain
+title: Service Internal Traffic Policy
+content_type: concept
+---
+
+
+<!-- overview -->
+
+{{< feature-state for_k8s_version="v1.21" state="alpha" >}}
+
+_Service Internal Traffic Policy_ enables internal traffic restrictions to only route
+internal traffic to endpoints within the node the traffic originated from. The
+"internal" traffic here refers to traffic originated from Pods in the current
+cluster. This can help to reduce costs and improve performance.
+
+<!-- body -->
+
+## Using Service Internal Traffic Policy
+
+You can enable Internal Traffic Policy for a Service by setting the
+`spec.internalTrafficPolicy` to "Local". This tells kube-proxy to only use node
+local endpoints for cluster internal traffic. Importantly, for pods on nodes with
+no endpoints for a given Service, the Service will behave as if it has zero
+endpoints (for Pods on this node) even if the service does have endpoints on other
+nodes. 
+
+The following example shows what a Service looks like when internalTrafficPolicy
+is set to "Local":
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: my-service
+spec:
+  selector:
+    app: MyApp
+  ports:
+    - protocol: TCP
+      port: 80
+      targetPort: 9376
+  internalTrafficPolicy: Local
+```
+
+## How it Works
+
+kube-proxy filters the endpoints it routes to based on the
+`spec.internalTrafficPolicy` setting. When it's "Local", only node local
+endpoints are considered. When it's "Cluster" or missing, all endpoints are
+considered.
+When the feature gate `ServiceInternalTrafficPolicy` is on,
+`spec.internalTrafficPolicy` defaults to "Cluster".
+
+## Constraints
+
+* Service Internal Traffic Policy is not used when `externalTrafficPolicy` is set
+  to "Local" on a Service. It is possible to use both features in the same cluster
+  on different Services, just not on the same Service.
+
+## {{% heading "whatsnext" %}}
+
+* Read about [enabling Topology Aware Hints](/docs/tasks/administer-cluster/enabling-topology-aware-hints)
+* Read about [Service External Traffic Policy](/docs/tasks/access-application-cluster/create-external-load-balancer/#preserving-the-client-source-ip)
+* Read [Connecting Applications with Services](/docs/concepts/services-networking/connect-applications-service/)

content/en/docs/reference/command-line-tools-reference/feature-gates.md

@@ -159,6 +159,7 @@ different Kubernetes components.
 | `SCTPSupport` | `true` | Beta | 1.19 | |
 | `ServerSideApply` | `false` | Alpha | 1.14 | 1.15 |
 | `ServerSideApply` | `true` | Beta | 1.16 | |
+| `ServiceInternalTrafficPolicy` | `false` | Alpha | 1.21 | |
 | `ServiceLBNodePortControl` | `false` | Alpha | 1.20 | |
 | `ServiceNodeExclusion` | `false` | Alpha | 1.8 | 1.18 |
 | `ServiceNodeExclusion` | `true` | Beta | 1.19 | |
@@ -727,6 +728,7 @@ Each feature gate is designed for enabling/disabling a specific feature:
   [Configure Service Accounts for Pods](/docs/tasks/configure-pod-container/configure-service-account/#service-account-issuer-discovery)
   for more details.
 - `ServiceAppProtocol`: Enables the `AppProtocol` field on Services and Endpoints.
+- `ServiceInternalTrafficPolicy`: Enables the `InternalTrafficPolicy` field on Services
 - `ServiceLBNodePortControl`: Enables the `spec.allocateLoadBalancerNodePorts`
   field on Services.
 - `ServiceLoadBalancerFinalizer`: Enable finalizer protection for Service load balancers.