Merge pull request #8620 from bfallonf/day2_feedback

Edits to day 2 guide as suggested

Author: Brice Fallon-Freeman

day_two_guide/topics/default_storage_class.adoc

@@ -24,4 +24,4 @@ two kinds of persistent storage are available: standard (HDD) and SSD. Notice
 the standard storage class is configured as the default. If there is no storage
 class defined, or none is set as a default, see the
 xref:../install_config/persistent_storage/dynamically_provisioning_pvs.adoc[Dynamic
-Provisioning and Creating Storage Classes] section.
+Provisioning and Creating Storage Classes] section for instructions on how to set up a storage class as suggested.

day_two_guide/topics/deprecating_master.adoc

@@ -92,21 +92,7 @@ a node host] section.
 
 . Remove the master host from the `[masters]` and `[nodes]` groups in the
 `/etc/ansible/hosts` Ansible inventory file to avoid issues if running any
-Ansible tasks using that inventory file:
-+
-----
-...[OUTPUT OMITTED]...
-# host group for masters
-[masters]
-*master-0.example.com*
-master-1.example.com
-master-2.example.com
-
-# host group for nodes, includes region info
-[nodes]
-*master-0.example.com openshift_node_labels="{'role': 'master'}" openshift_hostname=master-0.example.com openshift_schedulable=false*
-...[OUTPUT OMITTED]...
-----
+Ansible tasks using that inventory file.
 +
 [WARNING]
 ====

day_two_guide/topics/entropy.adoc

@@ -28,15 +28,17 @@ Red Hat recommends monitoring this value and issuing an alert if the value is
 under `800`.
 ====
 
-The most reliable way to determine the available entropy is with the
-`rngtest` command from the `rng-tools`: 
+Alternatively, you can use the `rngtest` command to check not only the available
+entropy, but if your system can _feed_ enough entropy as well:
 
 ----
 $ cat /dev/random | rngtest -c 100
 ----
 
-If the above takes too long to complete, then there is not enough entropy
-available.
+The `rngtest` command is available from the `rng-tools`
+
+If the above takes around 30 seconds to complete, then there is not enough
+entropy available.
 
 Depending on your environment, entropy can be increased in multiple ways. For
 more information, see the following blog post:

day_two_guide/topics/etcd_backup.adoc

@@ -183,30 +183,25 @@ inadvertently being joined onto an existing cluster.
 . Perform the backup:
 +
 ----
-# mkdir -p */backup/etcd-$(date +%Y%m%d)*
-# systemctl stop etcd.service
+# mkdir -p /backup/etcd-$(date +%Y%m%d)
 # etcdctl2 backup \
     --data-dir /var/lib/etcd \
-    --backup-dir */backup/etcd-$(date +%Y%m%d)*
-# cp /var/lib/etcd/member/snap/db */backup/etcd-$(date +%Y%m%d)*
-# systemctl start etcd.service
+    --backup-dir /backup/etcd-$(date +%Y%m%d)
+# cp /var/lib/etcd/member/snap/db /backup/etcd-$(date +%Y%m%d)
 ----
 +
-While stopping the etcd service is not strictly necessary, doing so ensures that
-the etcd data is fully synchronized.
-+
 The `etcdctl2 backup` command creates etcd v2 data backup where copying the `db`
 file while the etcd service is not running is equivalent to running `etcdctl3
 snapshot` for etcd v3 data backup:
 +
 ----
-# mkdir -p */backup/etcd-$(date +%Y%m%d)*
+# mkdir -p /backup/etcd-$(date +%Y%m%d)
 # etcdctl3 snapshot save */backup/etcd-$(date +%Y%m%d)*/db
 Snapshot saved at /backup/etcd-<date>/db
 # systemctl stop etcd.service
 # etcdctl2 backup \
     --data-dir /var/lib/etcd \
-    --backup-dir */backup/etcd-$(date +%Y%m%d)*
+    --backup-dir /backup/etcd-$(date +%Y%m%d)
 # systemctl start etcd.service
 ----
 +
@@ -346,7 +341,7 @@ $ ss -l4n | grep 2380
 . Update the member information with that IP:
 +
 ----
-# etcdctl2 member update *5ee217d17301* https://*192.168.55.8*:2380
+# etcdctl2 member update 5ee217d17301 https://192.168.55.8:2380
 Updated member with ID 5ee217d17301 in cluster
 ----
 
@@ -467,11 +462,11 @@ restore procedure is going to be performed:
 match the following command:
 +
 ----
-# etcdctl3 snapshot restore */backup/etcd-xxxxxx/backup.db* \
+# etcdctl3 snapshot restore /backup/etcd-xxxxxx/backup.db \
   --data-dir /var/lib/etcd \
-  --name *master-0.example.com* \
-  --initial-cluster *"master-0.example.com=https://192.168.55.8:2380"* \ --initial-cluster-token *"etcd-cluster-1"* \
-  --initial-advertise-peer-urls *https://192.168.55.8:2380*
+  --name master-0.example.com \
+  --initial-cluster "master-0.example.com=https://192.168.55.8:2380" \ --initial-cluster-token "etcd-cluster-1" \
+  --initial-advertise-peer-urls https://192.168.55.8:2380
 
 2017-10-03 08:55:32.440779 I | mvcc: restore compact to 1041269
 2017-10-03 08:55:32.468244 I | etcdserver/membership: added member 40bef1f6c79b3163 [https://192.168.55.8:2380] to cluster 26841ebcf610583c
@@ -586,9 +581,6 @@ https://master-2.example.com:2379, 59229711e4bc65c8, 3.2.5, 28 MB, false, 9, 287
 Scaling the etcd cluster can be performed vertically by adding more resources to
 the etcd hosts, or horizontally by adding more etcd hosts.
 
-If etcd is collocated on master instances, horizontally scaling etcd prevents
-the API and controller services competing with etcd for resources.
-
 [NOTE]
 ====
 Due to the voting system etcd uses, the cluster must always contain an odd
@@ -717,7 +709,7 @@ etcd0.example.com
 host:
 +
 ----
-FLANNEL_ETCD_ENDPOINTS=https://master-0.example.com:2379,https://master-1.example.com:2379,https://master-2.example.com:2379,*https://etcd0.example.com:2379*
+FLANNEL_ETCD_ENDPOINTS=https://master-0.example.com:2379,https://master-1.example.com:2379,https://master-2.example.com:2379,https://etcd0.example.com:2379
 ----
 
 . Restart the `flanneld` service:
@@ -743,7 +735,7 @@ proper values. To make this process easier, create some environment variables:
 +
 ----
 export NEW_ETCD_HOSTNAME="*etcd0.example.com*"
-export NEW_ETCD_IP="*192.168.55.21*"
+export NEW_ETCD_IP="192.168.55.21"
 
 export CN=$NEW_ETCD_HOSTNAME
 export SAN="IP:${NEW_ETCD_IP}"
@@ -907,7 +899,7 @@ for the instance to allow incoming traffic to those ports as well.
 . Untar the certificates and configuration files
 +
 ----
-# tar xzvf /tmp/*etcd0.example.com*.tgz -C /etc/etcd/
+# tar xzvf /tmp/etcd0.example.com.tgz -C /etc/etcd/
 ----
 
 . Restore etcd configuration and data owner:
@@ -977,7 +969,7 @@ etcdClientInfo:
     - https://master-0.example.com:2379
     - https://master-1.example.com:2379
     - https://master-2.example.com:2379
-    *- https://etcd0.example.com:2379*
+    - https://etcd0.example.com:2379
 ----
 
 . Restart the master API service on every master:
@@ -1002,7 +994,7 @@ The number of etcd nodes must be odd, so at least two hosts must be added.
 include the new etcd host:
 +
 ----
-FLANNEL_ETCD_ENDPOINTS=https://master-0.example.com:2379,https://master-1.example.com:2379,https://master-2.example.com:2379,*https://etcd0.example.com:2379*
+FLANNEL_ETCD_ENDPOINTS=https://master-0.example.com:2379,https://master-1.example.com:2379,https://master-2.example.com:2379,https://etcd0.example.com:2379
 ----
 
 . Restart the `flanneld` service:
@@ -1039,7 +1031,7 @@ etcdClientInfo:
   urls:
     - https://master-0.example.com:2379
     - https://master-1.example.com:2379
-    *- https://master-2.example.com:2379* <1>
+    - https://master-2.example.com:2379 <1>
 ----
 <1> The host to be removed.
 
@@ -1145,12 +1137,14 @@ FLANNEL_ETCD_ENDPOINTS=https://master-0.example.com:2379,https://master-1.exampl
 
 ==== Replacing an etcd host
 
-To replace an etcd host, first remove the etcd node from the cluster following
-the steps from
+Before you remove the etcd host, scale up the etcd cluster with the new host
+using the scale up Ansible playbook or the manual procedure in
+xref:../day_two_guide/host_level_tasks.adoc#scaling-etcd[Scaling etcd]. This
+ensures that you keep quorum if you lose an etcd host during the replacing
+procedure. Then, you can remove the etcd node from the cluster following the
+steps from
 xref:../day_two_guide/host_level_tasks.adoc#removing-an-etcd-host[Removing an
-etcd host], then scale up the etcd cluster with the new host using the scale up
-Ansible playbook or the manual procedure in
-xref:../day_two_guide/host_level_tasks.adoc#scaling-etcd[Scaling etcd].
+etcd host].
 
 [WARNING]
 ====

day_two_guide/topics/increasing_docker_storage.adoc

@@ -10,6 +10,7 @@ Increasing the amount of storage available ensures continued deployment without
 any outages. To do so, a free partition must be made available that contains an
 appropriate amount of free capacity.
 
+[[evacuating-a-node]]
 ==== Evacuating the node
 
 [discrete]
@@ -52,23 +53,32 @@ NAME      READY     STATUS    RESTARTS   AGE
 For more information on evacuating and draining pods or nodes, see
 xref:../day_two_guide/host_level_tasks.adoc#day-two-guide-node-maintenance[Node maintenance].
 
-==== Increasing storage with a new disk
+==== Increasing storage
+
+You can increase Docker storage in two ways: attaching a new disk, or extending
+the existing disk.
+
+*Increasing storage with a new disk*
 
 [discrete]
 == Prerequisites
 
-The following procedure assumes that a new disk has been added and is available
-to the existing instance that required additional storage.
-
+* The following examples assume the original disk is labeled `/dev/xvdb` and the
+new disk is labeled `/dev/xvdd`.
+* The following procedure assumes that a new disk has been added and is available
+to the existing instance that required additional storage:
++
+----
+# vi /etc/sysconfig/docker-storage-setup
+DEVS="/dev/xvdb /dev/xvdd"
+----
++
 [NOTE]
 ====
 The process may differ depending on the underlying {product-title}
 infrastructure.
 ====
 
-The examples below assume the original disk is labeled `/dev/xvdb` and the
-new disk is labeled `/dev/xvdd`.
-
 [discrete]
 == Procedure
 
@@ -88,7 +98,11 @@ INFO: Device /dev/xvdb is already partitioned and is part of volume group docker
 INFO: Device node /dev/xvdd1 exists.
   Physical volume "/dev/xvdd1" successfully created.
   Volume group "docker_vol" successfully extended
+----
 
+. Start the Docker services:
++
+----
 # systemctl start docker
 # vgs
   VG         #PV #LV #SN Attr   VSize  VFree
@@ -127,6 +141,75 @@ ose-app-node01.example.com   Ready                      24m       v1.6.1+5115d70
 ose-app-node02.example.com   Ready                      24m       v1.6.1+5115d708d7
 ----
 
+*Increasing storage with a new disk*
+
+. Evacuate the node xref:evacuating-a-node[following the previous steps].
+
+. Stop the `docker` and `atomic-openshift-node` services:
++
+----
+# systemctl stop docker atomic-openshift-node
+----
+
+. Resize the existing disk as desired. This can can depend on your environment:
++
+* If you are using LVM (Logical Volume Manager):
++
+** link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/logical_volume_manager_administration/lv#LV_remove[Remove the logical volume]:
++
+----
+# lvremove /dev/docker_vg/docker/lv
+----
++
+** link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/logical_volume_manager_administration/vg_admin#VG_remove[Remove the Docker volume group]:
++
+----
+# vgremove docker_vg
+----
++
+** link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/logical_volume_manager_administration/physvol_admin#PV_remove[Remove the physical volume]:
++
+----
+# pvremove /dev/<my_previous_disk_device>
+----
++
+* If you are using a cloud provider, you can detach the disk,
+destroy the disk, then create a new bigger disk, and attach it to the instance.
++
+* For a non-cloud environment, the disk and file system can be resized. See the
+following solution for more information:
++
+** https://access.redhat.com/solutions/199573
+
+. Verify that the *_/etc/sysconfig/container-storage-setup_* file is correctly
+configured for the new disk by checking the device name, size, etc.
+
+. Run `docker-storage-setup` to reconfigure the new disk:
++
+----
+# docker-storage-setup
+INFO: Volume group backing root filesystem could not be determined
+INFO: Device /dev/xvdb is already partitioned and is part of volume group docker_vol
+INFO: Device node /dev/xvdd1 exists.
+  Physical volume "/dev/xvdd1" successfully created.
+  Volume group "docker_vol" successfully extended
+----
+
+. Start the Docker services:
++
+----
+# systemctl start docker
+# vgs
+  VG         #PV #LV #SN Attr   VSize  VFree
+  docker_vol   2   1   0 wz--n- 64.99g <55.00g
+----
+
+. Start the `atomic-openshift-node` service:
++
+----
+# systemctl start atomic-openshift-node
+----
+
 === Changing the storage backend
 
 With the advancements of services and file systems, changes in a storage backend
@@ -140,7 +223,7 @@ an example of changing a device mapper backend to an `overlay2` storage backend.
 any pod from the node and disable scheduling of other pods on that node:
 +
 ----
-$ NODE=*ose-app-node01.example.com*
+$ NODE=ose-app-node01.example.com
 $ oc adm manage-node ${NODE} --schedulable=false
 NAME                          STATUS                     AGE       VERSION
 ose-app-node01.example.com   Ready,SchedulingDisabled   20m       v1.6.1+5115d708d7
@@ -237,7 +320,7 @@ CONTAINER_ROOT_LV_SIZE=100%FREE
 # systemctl start docker atomic-openshift-node
 ----
 
-. With the storage modified to use `overlay2`, the enable the node to be
+. With the storage modified to use `overlay2`, enable the node to be
 schedulable in order to accept new incoming pods.
 +
 From a master instance, or as a cluster administrator:

day_two_guide/topics/managing_docker_certs.adoc

@@ -9,7 +9,7 @@ Module included in the following assemblies:
 An {product-title} internal registry is created as a pod. However, containers
 may be pulled from external registries if desired. By default, registries listen
 on TCP port 5000. Registries provide the option of securing exposed images via
-TLS or running a registry with no encrypting traffic.
+TLS or running a registry without encrypting traffic.
 
 [WARNING]
 ====