WTD (#3757)

Edits from genwhitt in Portland at WTD conference. Apply template, copyedit, apply style guide.

docs/tasks/administer-cluster/declare-network-policy.md

@@ -9,22 +9,26 @@ redirect_from:
 - "/docs/tasks/configure-pod-container/declare-network-policy/"
 - "/docs/tasks/configure-pod-container/declare-network-policy.html"
 ---
+{% capture overview %}
+This document helps you get started using using the Kubernetes [NetworkPolicy API](/docs/user-guide/networkpolicies) to declare network policies that govern how pods communicate with each other. 
+{% endcapture %}
 
-Kubernetes can be used to declare network policies which govern how Pods can communicate with each other.  This document helps you get started using the Kubernetes [NetworkPolicy API](/docs/user-guide/networkpolicies), and provides a demonstration thereof. 
+{% capture prerequisites %}
-
+You'll need to have a Kubernetes cluster in place, with network policy support. There are a number of network providers that support NetworkPolicy, including:
-In this article, we assume a Kubernetes cluster has been created with network policy support. There are a number of network providers that support NetworkPolicy including:
 
 * [Calico](/docs/tasks/configure-pod-container/calico-network-policy/)
 * [Romana](/docs/tasks/configure-pod-container/romana-network-policy/)
 * [Weave Net](/docs/tasks/configure-pod-container/weave-network-policy/)
 
-Add-ons are sorted alphabetically - the ordering does not imply any preferential status.
+**Note**: The above list is sorted alphabetically by product name, not by recommendation or preference. This example is valid for a Kubernetes cluster using any of these providers.
+{% endcapture %}
 
-The following example walkthrough will work on a Kubernetes cluster using any of the listed providers.
 
-## Using NetworkPolicy 
+{% capture steps %}
 
-To explain how Kubernetes network policy works let's start off by creating an `nginx` Deployment and expose it via a Service. 
+## Create an `nginx` deployment and expose it via a service
+
+To see how Kubernetes network policy works, start off by creating an `nginx` deployment and exposing it via a service. 
 
 ```console
 $ kubectl run nginx --image=nginx --replicas=2
@@ -33,7 +37,7 @@ $ kubectl expose deployment nginx --port=80
 service "nginx" exposed
 ```
 
-This will run two nginx Pods in the default Namespace, and expose them through a Service called `nginx`. 
+This runs two `nginx` pods in the default namespace, and exposes them through a service called `nginx`. 
 
 ```console
 $ kubectl get svc,pod
@@ -46,9 +50,11 @@ po/nginx-701339712-e0qfq    1/1           Running       0          35s
 po/nginx-701339712-o00ef    1/1           Running       0          35s
 ```
 
-We should be able to access our new nginx Service from other Pods.  Let's try to access it from another Pod 
+## Test the service by accessing it from another pod
-in the default namespace.  We haven't enabled isolation on the namespace, so this should just work. Start a
+
-busybox container, and use `wget` to hit the nginx Service:
+You should be able to access the new `nginx` service from other pods. To test, access the service from another pod in the default namespace. Make sure you haven't enabled isolation on the namespace.
+
+Start a busybox container, and use `wget` on the `nginx` service:
 
 ```console
 $ kubectl run busybox --rm -ti --image=busybox /bin/sh
@@ -61,14 +67,17 @@ Connecting to nginx (10.100.0.16:80)
 / #
 ```
 
-Let's say we want to limit access to our nginx Service so that only pods with the label `access: true` can query it.  First, we'll
+## Limit access to the `nginx` service
-enable ingress isolation on the `default` Namespace.  This will prevent _any_ pods from accessing the nginx Service.
+
+Let's say you want to limit access to the `nginx` service so that only pods with the label `access: true` can query it. The first step is to enable ingress isolation on the `default` namespace. This prevents **_any_** pods from accessing the `nginx` service.
 
 ```console
 $ kubectl patch ns default -p '{"spec": {"networkPolicy": {"ingress": {"isolation": "DefaultDeny"}}}}'
 ```
 
-With ingress isolation in place, we should no longer be able to access the nginx Service like we were able to before:
+## Test the access limitation
+
+Test to see that with ingress isolation in place, you no longer have access to the `nginx` service:
 
 ```console
 $ kubectl run busybox --rm -ti --image=busybox /bin/sh
@@ -82,7 +91,9 @@ wget: download timed out
 / #
 ```
 
-Let's now create a `NetworkPolicy` which allows connections from pods with the label `access: true`.
+## Create a policy that allows connections from authorized pods
+
+Next, create a `NetworkPolicy` that allows connections from pods with the label `access: true`.
 
 ```yaml
 kind: NetworkPolicy
@@ -100,12 +111,15 @@ spec:
           access: "true"
 ```
 
+## Assign the policy to the service
+
 Use kubectl to create a NetworkPolicy from the above nginx-policy.yaml file:
 ```console
 $ kubectl create -f nginx-policy.yaml
 networkpolicy "access-nginx" created
 ```
 
+## Test access to the service when access label is not defined
 If we attempt to access the nginx Service from a pod without the correct labels, the request will still time out:
 
 ```console
@@ -120,7 +134,9 @@ wget: download timed out
 / #
 ```
 
-However, if we create a Pod with the correct labels, the request will be allowed:
+## Define access label and test again
+
+Create a pod with the correct labels, and you'll see that the request is allowed:
 
 ```console
 $ kubectl run busybox --rm -ti --labels="access=true" --image=busybox /bin/sh
@@ -132,3 +148,12 @@ Hit enter for command prompt
 Connecting to nginx (10.100.0.16:80)
 / #
 ```
+{% endcapture %}
+
+
+{% capture whatsnext %}
+Learn more about [kubectl proxy](/docs/user-guide/kubectl/v1.6/#proxy).
+{% endcapture %}
+
+{% include templates/task.md %}
+