Updates from reviewing networking sections

bergerhoffer · bergerhoffer · commit af9c80458f0a · 2019-03-20T11:40:07.000-04:00
diff --git a/modules/nw-annotating-a-route-with-a-cookie-name.adoc b/modules/nw-annotating-a-route-with-a-cookie-name.adoc
@@ -24,10 +24,10 @@ $ oc annotate route <route_name> router.openshift.io/<cookie_name>="-<cookie_ann
 ----
 +
 For example, to annotate the cookie name of `my_cookie` to the `my_route` with
-the annotation of `my_cookie_anno`:
+the annotation of `my_cookie_annotation`:
 +
 ----
-$ oc annotate route my_route router.openshift.io/my_cookie="-my_cookie_anno"
+$ oc annotate route my_route router.openshift.io/my_cookie="-my_cookie_annotation"
 ----
 
 . Save the cookie, and access the route:
diff --git a/modules/nw-enabling-hsts.adoc b/modules/nw-enabling-hsts.adoc
@@ -52,5 +52,5 @@ services to include this site in their HSTS preload lists. For example, sites
 such as Google can construct a list of sites that have `preload` set. Browsers
 can then use these lists to determine which sites they can communicate with
 over HTTPS,
-before they have interacted with the site. Without `preload` set, browsers need
-to have interacted with the site over HTTPS to get the header.
+before they have interacted with the site. Without `preload` set, browsers must
+have interacted with the site over HTTPS to get the header.
diff --git a/modules/nw-ne-openshift-dns.adoc b/modules/nw-ne-openshift-dns.adoc
@@ -11,7 +11,7 @@ service IPs, and more so the front-end Pods can communicate with the back-end
 services. If the service is deleted and recreated, a new IP address can be
 assigned to the service, and requires the front-end Pods to be recreated to pick
 up the updated values for the service IP environment variable. Additionally, the
-back-end service has to be created before any of the front-end Pods to ensure that
+back-end service must be created before any of the front-end Pods to ensure that
 the service IP is generated properly, and that it can be provided to the
 front-end Pods as an environment variable.
 
diff --git a/modules/nw-throughput-troubleshoot.adoc b/modules/nw-throughput-troubleshoot.adoc
@@ -25,14 +25,10 @@ traffic from other Pods, storage devices, or the data plane.
 $ tcpdump -s 0 -i any -w /tmp/dump.pcap host <podip 1> && host <podip 2> <1>
 ----
 +
-<1> `podip` is the IP address for the Pod. Run the following command to get
-the IP address of the Pods:
+<1> `podip` is the IP address for the Pod. Run the `oc get pod <pod_name> -o wide` command to get
+the IP address of a Pod.
 +
-----
-$ oc get pod <podname> -o wide
-----
-+
-tcpdump generates a file at [filename]`/tmp/dump.pcap` containing all traffic between
+tcpdump generates a file at `/tmp/dump.pcap` containing all traffic between
 these two Pods. Ideally, run the analyzer shortly
 before the issue is reproduced and stop the analyzer shortly after the issue
 is finished reproducing to minimize the size of the file.
diff --git a/modules/nw-using-cookies-keep-route-statefulness.adoc b/modules/nw-using-cookies-keep-route-statefulness.adoc
@@ -10,12 +10,12 @@
 
 {product-title} provides sticky sessions, which enables stateful application
 traffic by ensuring all traffic hits the same endpoint. However, if the endpoint
-pod terminates, whether through restart, scaling, or a change in configuration,
+Pod terminates, whether through restart, scaling, or a change in configuration,
 this statefulness can disappear.
 
 {product-title} can use cookies to configure session persistence. The router
 selects an endpoint to handle any user requests, and creates a cookie for the
 session. The cookie is passed back in the response to the request and the user
 sends the cookie back with the next request in the session. The cookie tells the
 router which endpoint is handling the session, ensuring that client requests use
-the cookie so that they are routed to the same pod.
+the cookie so that they are routed to the same Pod.
diff --git a/modules/nw_multinetwork-creating-first-attachments.adoc b/modules/nw_multinetwork-creating-first-attachments.adoc
@@ -3,35 +3,34 @@
 // * networking/managing_multinetworking.adoc
 
 [id="multinetwork-creating-first-attachments-{context}"]
-= Creating additional network interfaces for the first time
+= Creating additional network interfaces
 
-Additional interfaces for pods are defined in CNI configurations that are stored as Custom Resources (CRs).
+Additional interfaces for Pods are defined in CNI configurations that are stored as Custom Resources (CRs).
 These CRs can be created, listed, edited, and deleted using the `oc` tool.
 
-The procedure below configures a `macvlan` interface on a pod. This configuration might not apply to all production environments, but you use the same procedure for other CNI plug-ins.
+The procedure below configures a `macvlan` interface on a Pod. This configuration might not apply to all production environments, but you use the same procedure for other CNI plug-ins.
 
 == Creating a CNI configuration for an additional interface as a CR
 
 [NOTE]
 ====
-If you want to attach an additional interface to a pod, the CR that defines the interface must be in the same project (namespace) as the pod.
+If you want to attach an additional interface to a Pod, the CR that defines the interface must be in the same project (namespace) as the Pod.
 ====
 
-. Create a project to store CNI configurations as CRs and the pods that will use the CRs.
+. Create a project to store CNI configurations as CRs and the Pods that will use the CRs.
 +
 ----
 $ oc new-project multinetwork-example
-$ oc project multinetwork-example
 ----
 
-. Create the CR that will define an additional network interface. Create a YAML file:
+. Create the CR that will define an additional network interface. Create a YAML file called `macvlan-conf.yaml` with the following contents:
 +
 [source,yaml]
 ----
 apiVersion: "k8s.cni.cncf.io/v1"
-kind: NetworkAttachmentDefinition <2>
+kind: NetworkAttachmentDefinition <1>
 metadata:
-  name: macvlan-conf <1>
+  name: macvlan-conf <2>
 spec:
   config: '{ <3>
       "cniVersion": "0.3.0",
@@ -51,29 +50,29 @@ spec:
     }'
 ----
 +
-<1> `name` maps to the annotation, which is used in the next step.
-<2> `kind: NetworkAttachmentDefinition`. This is the name for the CR where this configuration will be stored. It is a custom extension of Kubernetes that defines how networks are attached to pods.
+<1> `kind: NetworkAttachmentDefinition`. This is the name for the CR where this configuration will be stored. It is a custom extension of Kubernetes that defines how networks are attached to Pods.
+<2> `name` maps to the annotation, which is used in the next step.
 <3> `config`: The CNI configuration is packaged in the `config` field.
-
++
 The configuration above is specific to a plug-in, which enables `macvlan`. Note the `type` line in the CNI configuration portion.
-Aside from the IPAM (IP address management) parameters for networking, in this example the `master` field must reference a network interface that resides on the node(s) hosting the pod(s).
+Aside from the IPAM (IP address management) parameters for networking, in this example the `master` field must reference a network interface that resides on the node(s) hosting the Pod(s).
 
 . Run the following command to create the CR:
 +
 ----
-oc create -f macvlan-conf.yaml
+$ oc create -f macvlan-conf.yaml
 ----
 
 [NOTE]
 ====
 This example is based on a `macvlan` CNI plug-in. Note that in AWS environments, macvlan traffic might be filtered and, therefore, might not reach the desired destination.
 ====
 
-== Managing the CRs for Additional Interfaces
+== Managing the CRs for additional interfaces
 
-You can manage the CRs for additional interfaces using the `oc` tool.
+You can manage the CRs for additional interfaces using the `oc` CLI.
 
-To list the CRs for additional interfaces, execute:
+Use the following command to list the CRs for additional interfaces:
 
 ----
 $ oc get network-attachment-definitions.k8s.cni.cncf.io
@@ -85,9 +84,9 @@ Use the following command to delete CRs for additional interfaces:
 $ oc delete network-attachment-definitions.k8s.cni.cncf.io macvlan-conf
 ----
 
-== Create an annotated pod that uses the CR
+== Creating an annotated Pod that uses the CR
 
-To create a pod which uses the additional interface, use an `annotation` that refers to the CR, create a YAML file for a pod:
+To create a Pod that uses the additional interface, use an annotation that refers to the CR. Create a YAML file called `samplepod.yaml` for a Pod with the following contents:
 
 [source,yaml]
 ----
@@ -106,13 +105,13 @@ spec:
 
 <1> The `annotations` field contains `k8s.v1.cni.cncf.io/networks: macvlan-conf`, which correlates to the `name` field in the CR defined earlier.
 
-Run the following command to create the `samplepod` pod:
+Run the following command to create the `samplepod` Pod:
 
 ----
-oc create -f samplepod.yaml
+$ oc create -f samplepod.yaml
 ----
 
-To verify that an additional network interface has been created and attached to the pod, use the following command to list the IPv4 address information:
+To verify that an additional network interface has been created and attached to the Pod, use the following command to list the IPv4 address information:
 
 ----
 $ oc exec -it samplepod -- ip -4 addr
@@ -121,7 +120,6 @@ $ oc exec -it samplepod -- ip -4 addr
 Three interfaces are listed in the output:
 
 ----
-$ oc exec -it samplepod -- ip -4 addr
 1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN qlen 1000 <1>
     inet 127.0.0.1/8 scope host lo
        valid_lft forever preferred_lft forever
@@ -133,34 +131,34 @@ $ oc exec -it samplepod -- ip -4 addr
        valid_lft forever preferred_lft forever
 ----
 
-<1> `lo`: a loopback interface.
-<2> `eth0`: the interface that connects to the cluster-wide default network.
-<3> `net1`: the new interface that you just created.
+<1> `lo`: A loopback interface.
+<2> `eth0`: The interface that connects to the cluster-wide default network.
+<3> `net1`: The new interface that you just created.
 
-=== Attaching multiple interfaces to a pod
+=== Attaching multiple interfaces to a Pod
 
-To attach more than one additional interface to a pod, specify multiple names, in comma-delimited format, in the `annotation` field in the pod definition.
+To attach more than one additional interface to a Pod, specify multiple names, in comma-delimited format, in the `annotations` field in the Pod definition.
 
-The following `annotation` field in a pod definition specifies different CRs for the additional interfaces:
+The following `annotations` field in a Pod definition specifies different CRs for the additional interfaces:
 
 [source,yaml]
 ----
   annotations:
     k8s.v1.cni.cncf.io/networks: macvlan-conf, tertiary-conf, quaternary-conf
 ----
 
-The following `annotation` field in a pod definition specifies the same CR for the additional interfaces:
+The following `annotations` field in a Pod definition specifies the same CR for the additional interfaces:
 
 [source,yaml]
 ----
   annotations:
-    k8s.v1.cni.cncf.io/networks: macvlan-conf, macvlan-conf.
+    k8s.v1.cni.cncf.io/networks: macvlan-conf, macvlan-conf
 ----
 
-== View the interface configuration in a running pod
+== Viewing the interface configuration in a running Pod
 
-Once the pod is running, you can can review the configurations of the additional interfaces created.
-To view the sample pod from the earlier example, execute the following command.
+After the Pod is running, you can review the configurations of the additional interfaces created.
+To view the sample Pod from the earlier example, execute the following command.
 
 ----
 $ oc describe pod samplepod
@@ -192,16 +190,16 @@ Annotations:
 ----
 
 <1> `name` refers to the custom resource name, `macvlan-conf`.
-<2> `interface` refers to the name of the interface in the pod.
-<3> `ips` is a list of IP addresses as assigned to the pod.
+<2> `interface` refers to the name of the interface in the Pod.
+<3> `ips` is a list of IP addresses as assigned to the Pod.
 <4> `mac` is the MAC address of the interface.
 <5> `dns` refers DNS for the interface.
 
-The first annotation, `k8s.v1.cni.cncf.io/networks: macvlan-conf`, refers to the CR created in the example. This annotation was specified in the pod definition.
+The first annotation, `k8s.v1.cni.cncf.io/networks: macvlan-conf`, refers to the CR created in the example. This annotation was specified in the Pod definition.
 
 The second annotation is `k8s.v1.cni.cncf.io/networks-status`.
 There are two interfaces listed under `k8s.v1.cni.cncf.io/networks-status`.
 
 * The first interface describes the interface for the default network, `openshift-sdn`. This interface is created as `eth0`. It is used for communications within the cluster.
 
-* The second interface is the additional interface that you created, `net1`. The output above lists some key values that were configured when the interface was created, for example, the IP addresses that were assigned to the pod.
+* The second interface is the additional interface that you created, `net1`. The output above lists some key values that were configured when the interface was created, for example, the IP addresses that were assigned to the Pod.
diff --git a/modules/nw_multinetwork-host-device.adoc b/modules/nw_multinetwork-host-device.adoc
@@ -5,7 +5,7 @@
 [id="multinetwork-host-device-{context}"]
 = Configuring additional interfaces using host devices
 
-The host-device plug-in connects an existing network device on a node directly to a pod.
+The host-device plug-in connects an existing network device on a node directly to a Pod.
 
 The code below creates a dummy device using a dummy module to back a virtual device, and assigns the dummy device `name` to `exampledevice0`.
 
@@ -15,18 +15,16 @@ $ lsmod | grep dummy
 | ip link set name exampledevice0 dev dummy0
 ----
 
-
-
 .Procedure
 
-. To connect the dummy network device to a pod, label the host, so that you can assign a pod to the node where the device exists.
+. To connect the dummy network device to a Pod, label the host, so that you can assign a Pod to the node where the device exists.
 +
 ----
-$ oc label nodes {your-worker-node-name} exampledevice=true
+$ oc label nodes <your-worker-node-name> exampledevice=true
 $ oc get nodes --show-labels
 ----
 
-. Create a YAML file for a custom resource to refer to this configuration:
+. Create a YAML file called `hostdevice-example.yaml` for a custom resource to refer to this configuration:
 +
 [source,yaml]
 ----
@@ -45,11 +43,10 @@ spec:
 . Run the following command to create the `hostdevice-example` CR:
 +
 ----
-oc create -f hostdevice-example.yaml
+$ oc create -f hostdevice-example.yaml
 ----
 
-
-. Create a YAML file for a pod which refers to this name in the annotation. Include `nodeSelector` to assign the pod to the machine where you created the alias.
+. Create a YAML file for a Pod which refers to this name in the annotation. Include `nodeSelector` to assign the Pod to the machine where you created the alias.
 +
 [source,yaml]
 ----
@@ -68,10 +65,10 @@ spec:
     exampledevice: "true"
 ----
 
-. Run the following command to create the `hostdevicesamplepod` pod:
+. Run the following command to create the `hostdevicesamplepod` Pod:
 +
 ----
-oc create -f hostdevicesamplepod.yaml
+$ oc create -f hostdevicesamplepod.yaml
 ----
 
 . View the additional interface that you created:
diff --git a/modules/nw_multinetwork-sriov.adoc b/modules/nw_multinetwork-sriov.adoc
diff --git a/networking/managing_multinetworking.adoc b/networking/managing_multinetworking.adoc
diff --git a/networking/understanding-networking.adoc b/networking/understanding-networking.adoc

Original file line number	Diff line number	Diff line change
`@@ -24,10 +24,10 @@ $ oc annotate route <route_name> router.openshift.io/<cookie_name>="-<cookie_ann`
`24`	`24`	`----`
`25`	`25`	`+`
`26`	`26`	For example, to annotate the cookie name of `my_cookie` to the `my_route` with
`27`		-the annotation of `my_cookie_anno`:
	`27`	+the annotation of `my_cookie_annotation`:
`28`	`28`	`+`
`29`	`29`	`----`
`30`		`-$ oc annotate route my_route router.openshift.io/my_cookie="-my_cookie_anno"`
	`30`	`+$ oc annotate route my_route router.openshift.io/my_cookie="-my_cookie_annotation"`
`31`	`31`	`----`
`32`	`32`
`33`	`33`	`. Save the cookie, and access the route:`