add docs for loadBalancerSourceRange field

docs/user-guide/services-firewalls.md

@@ -6,6 +6,50 @@ exposure to the internet.  When exposing a service to the external world, you ma
 one or more ports in these firewalls to serve traffic.  This document describes this process, as
 well as any provider specific details that may be necessary.
 
+### Restrict Access For LoadBlancer Service
+
+ When using a Service with `spec.type: LoadBalancer`, you can specify the IP ranges that are allowed to access the load balancer
+ by using `spec.loadBalancerSourceRanges`. This field takes a list of IP CIDR ranges, which Kubernetes will use to configure firewall exceptions.
+ This feature is currently supported on Google Compute Engine, Google Container Engine and AWS. This field will be ignored if the cloud provider does not support the feature.
+
+ Assuming 10.0.0.0/8 is the internal subnet. In the following example, a load blancer will be created that is only accessible to cluster internal ips. 
+ This will not allow clients from outside of your Kubernetes cluster to access the load blancer.
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: myapp
+spec:
+  ports:
+    - port: 8765
+      targetPort: 9376
+  selector:
+    app: example
+  type: LoadBalancer
+  loadBalancerSourceRanges:
+  - 10.0.0.0/8
+```
+
+ In the following example, a load blancer will be created that is only accessible to clients with IP addresses from 130.211.204.1 and 130.211.204.2.
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: myapp
+spec:
+  ports:
+    - port: 8765
+      targetPort: 9376
+  selector:
+    app: example
+  type: LoadBalancer
+  loadBalancerSourceRanges:
+  - 130.211.204.1/32
+  - 130.211.204.2/32
+```
+
 ### Google Compute Engine
 
 When using a Service with `spec.type: LoadBalancer`, the firewall will be
@@ -48,4 +92,4 @@ This will be fixed in an upcoming release of Kubernetes.
 
 ### Other cloud providers
 
-Coming soon.
+Coming soon.

docs/user-guide/services/load-balancer-sample.json

@@ -12,6 +12,10 @@
     "selector": {
       "app": "example"
     },
-    "type": "LoadBalancer"
+    "type": "LoadBalancer",
+    "loadBalancerSourceRanges": [
+      "10.180.0.0/16",
+      "10.245.0.0/24"
+    ]
   }
 }

docs/user-guide/services/load-balancer-sample.yaml

@@ -4,9 +4,11 @@ metadata:
   name: myapp
 spec:
   ports:
-    -
+    - port: 8765
-      port: 8765
       targetPort: 9376
   selector:
     app: example
   type: LoadBalancer
+  loadBalancerSourceRanges:
+  - 10.180.0.0/16
+  - 10.245.0.0/24

docs/user-guide/services/operations.md

@@ -51,7 +51,11 @@ YAML or as JSON, and supports the following fields:
     "selector": {
       string: string
     },
-    "type": "LoadBalancer"
+    "type": "LoadBalancer",
+    "loadBalancerSourceRanges": [
+      "10.180.0.0/16",
+      "10.245.0.0/24"
+    ]
   }
 }
 ```
@@ -71,6 +75,10 @@ Required fields are:
     * `type`: Optional. If the type is `LoadBalancer`, sets up a [network load balancer](/docs/user-guide/load-balancer/)
       for your service. This provides an externally-accessible IP address that
       sends traffic to the correct port on your cluster nodes. 
+    * `loadBalancerSourceRanges:`: Optional. Must use with `LoadBalancer` type. 
+      If specified and supported by the cloud provider, this will restrict traffic 
+      such that the load balancer will be accessible only to clients from the specified IP ranges.
+      This field will be ignored if the cloud-provider does not support the feature. 
 
 For the full `service` schema see the
 [Kubernetes api reference](/docs/api-reference/v1/definitions/#_v1_service).

docs/user-guide/services/service-sample.yaml

@@ -4,8 +4,7 @@ metadata:
   name: myapp
 spec:
   ports:
-    -
+    - port: 8765
-      port: 8765
       targetPort: 9376
   selector:
     app: example