Merge pull request #435 from russellb/pr-102-followup

baremetal: Address comments on #102

Author: openshift-merge-robot

enhancements/baremetal/baremetal.md

@@ -40,7 +40,7 @@ below.
 
 Baremetal IPI deployments enable OpenShift to enroll baremetal servers to become
 Nodes that can run K8s workloads.
-The Baremetal Operator [1] along with other provisioning services (Ironic and
+The [Baremetal Operator][1] along with other provisioning services (Ironic and
 dependencies) run in their own pod called "metal3". This pod is deployed by the
 Machine API Operator when the Platform type is `BareMetal`. The OpenShift
 Installer is responsble for providing all the necessary configs required for
@@ -88,9 +88,9 @@ with the right configuration.
 With the addition of features described in this and other enhancements
 detailed in this current directory, OpenShift can be used to bring up
 a functioning cluster starting with a set of baremetal servers. As
-mentioned earlier, these enhancements rely on the Baremetal Operator (BMO)
-[1] running within the "metal3" pod to manage baremetal hosts. The BMO in
-turn relies on the Ironic service [3] to manage and provision baremetal
+mentioned earlier, these enhancements rely on the [Baremetal Operator (BMO)][1]
+running within the "metal3" pod to manage baremetal hosts. The BMO in
+turn relies on the [Ironic service][3] to manage and provision baremetal
 servers.
 
 1. Will enable the user to deploy a control plane with 3 master nodes.
@@ -100,34 +100,41 @@ nodes.
 
 ### Implementation Details/Notes/Constraints
 
-Baremetal IPI is integrated with OpenShift through the metal3.io [8] project.
+Baremetal IPI is integrated with OpenShift through the [metal3.io][8] project.
 Metal3.io is a set of Kubernetes controllers that wrap the OpenStack Ironic
 project to provide Kubernetes native APIs for managing deployment and
 monitoring of physical hosts.
 
 The installer support for Baremetal IPI deployments is described in more detail
-in [7]. The installer runs on a special "provisioning host" that needs to be
-connected to both a "provisioning network" and an "external network". The
-provisioning network is a dedicated network used just for the purposes of
-configuring baremetal servers to be part of the cluster. The traffic on the
-provisioning network needs to be isolated from the traffic on the external
-network (hence 2 seperate networks.). The external network is used to carry
-cluster traffic which which includes cluster control plane traffic, application
-and data traffic.
+in [this document][7]. The installer runs on a special "provisioning host" that
+needs to be connected to both a "provisioning network" and an "external
+network". The provisioning network is a dedicated network used just for the
+purposes of configuring baremetal servers to be part of the cluster. The
+traffic on the provisioning network needs to be isolated from the traffic on
+the external network (hence 2 seperate networks.). The external network is used
+to carry cluster traffic which which includes cluster control plane traffic,
+application and data traffic.  More detail on the networking requirements for
+the cluster can be found in [this document][10].
 
 Control Plane Deployment
 
+Details about DNS and load balancer automation for this platform are documented
+[here][11].
+
 1. A minimin Baremetal IPI deployment consists of 4 hosts, one to be used
 first as a provisioning host and later potentially re-purposed as a worker.
 The other 3 make up the control plane. These 4 hosts need to be connected
-to both the provisioning and external networks.
+to both the provisioning and external networks.  The provisioning host is a
+RHEL 8 host capable of running libvirt VMs.
 
 2. Installation can be kicked off by downloading and running
 "openshift-baremetal-install". This image differs from the "openshift-install"
 binary only because libvirt is needs to be always linked for the baremetal
 install. Removing a bootstrap node would remove the dependency on libvirt
 and then baremetal IPI installs can be part of the normal Openshift installer.
-This is in the roadmap for this work and being investigated.
+This is in the roadmap for this work and being investigated.  Note that it is
+still built from the same installer code base and is only a separate binary
+build.
 
 3. The installer starts a bootstrap VM on the provisioning host. With other
 platform types supported by OpenShift, a cloud already exists and the installer
@@ -140,16 +147,20 @@ the network interface on the provisioning host that is connected to the
 provisioning network needs to be provided to the installer.
 
 5. The bootstrap VM must be configured with a special well-known IP within the
-provisioning network that needs to provided as input to the installer.
+provisioning network that needs to provided as input to the installer.  This
+happens automatically and does not need any intervention by the cluster
+operator.
 
 6. The installer user Ironic in the bootstrap VM to provision each host that
 makes up the control plane. The installer uses terraform to invoke Ironic API
 that configures each host to boot over the provisioning network using DHCP
 and PXE.
 
-7. The bootstrap VM runs a DHCP server and responds with network infomation and
-PXE instructions when Ironic powers on a host. The host boots the Ironic Agent
-image which is hosted on the httpd instance also running on the bootstrap VM.
+7. The bootstrap VM runs a DHCP server on the isolated provisioning network and
+responds with network infomation and PXE instructions when Ironic powers on
+a host. The host boots the Ironic Agent image which is hosted on the httpd
+instance also running on the bootstrap VM.  Note that this DHCP server moves
+into the cluster as part of the `metal3` pod once the cluster comes up.
 
 8. After the Ironic Agent on the host boots and runs from its ramdisk image, it
 looks for the Ironic Service either using an URL passed in as a kernel command line
@@ -195,7 +206,7 @@ address in the provisioning network are assigned to each of these hosts.
 
 2. The user adds hosts to the available inventory for their cluster by creating
 BareMetalHost CRs. For more information about the 3 CRs that already exist for a host
-transitioning from a baremetal host to a Node, please refer to [9].
+transitioning from a baremetal host to a Node, please refer to [this doc][9].
 
 3. The cluster-api-provider-baremetal (CAPBM) controller finds an unassigned/free
 BareMetalHost and uses it to fulfill a Machine resource. It then sets the configuration
@@ -229,23 +240,23 @@ Will be specified in follow-up enhancement requests mentioned above.
 ### Test Plan
 
 True e2e and integration testing can happen only after implementation for
-enhancement [2] lands. Until then, e2e testing is being performed with the
+[this enhancement][2] lands. Until then, e2e testing is being performed with the
 help of some developer scripts.
 
 Unit tests have been added to MAO and the Installer to test additions
 made for the Baremetal IPI case.
 
 ### Graduation Criteria
 
-Metal3 integration is in tech preview in 4.2 and is targetted for GA in 4.4.
+Metal3 integration is in tech preview in 4.2 and is targeted for GA in 4.6.
 
 Metal3 integration is currently missing an important piece to information on
 the baremetal servers and ther provisioning environment. Without this, true
 end to end testing cannot be performed in order to graduate to GA.
 
 ### Upgrade / Downgrade Strategy
 
-Metal3 integration is in tech preview n 4.2 and missing key pieces that allows
+Metal3 integration is in tech preview in 4.2 and missing key pieces that allows
 a user to specify the baremetal server details and its provisioning setup. It
 is really not usable in this state without the help of external scripts that
 provied the above information in the form of a Config Map.
@@ -262,22 +273,25 @@ respective requests.
 
 ## Implementation History
 
-Implementation to deploy a Metal3 cluster from the MAO was added via [4].
+Implementation to deploy a Metal3 cluster from the MAO was added via [this
+commit][4].
 
 ## Infrastructure Needed
 
 The Baremetal IPI solution depends on the Baremetal Operator and the baremetal
-Machine actuator both of which can be found at [5].
-OpenShift integration can be found here : [6].
+Machine actuator both of which can be found [here][5].
+OpenShift integration can be found [here][6].
 Implementation is complete on the metal3-io and relevant bits have been
-added to the OpenShift repo. 
-
-[1] - https://github.com/metal3-io/baremetal-operator
-[2] - https://github.com/openshift/enhancements/blob/master/enhancements/baremetal/baremetal-provisioning-config.md
-[3] - https://github.com/openstack/ironic
-[4] - https://github.com/openshift/machine-api-operator/commit/43dd52d5d2dfea1559504a01970df31925501e35
-[5] - https://github.com/metal3-io
-[6] - https://github.com/openshift-metal3 
-[7] - https://github.com/openshift/installer/blob/master/docs/user/metal/install_ipi.md
-[8] - https://metal3.io/
-[9] - https://github.com/metal3-io/metal3-docs/blob/master/design/nodes-machines-and-hosts.md
+added to the OpenShift repo.
+
+[1]: https://github.com/metal3-io/baremetal-operator
+[2]: https://github.com/openshift/enhancements/blob/master/enhancements/baremetal/baremetal-provisioning-config.md
+[3]: https://github.com/openstack/ironic
+[4]: https://github.com/openshift/machine-api-operator/commit/43dd52d5d2dfea1559504a01970df31925501e35
+[5]: https://github.com/metal3-io
+[6]: https://github.com/openshift-metal3 
+[7]: https://github.com/openshift/installer/blob/master/docs/user/metal/install_ipi.md
+[8]: https://metal3.io/
+[9]: https://github.com/metal3-io/metal3-docs/blob/master/design/nodes-machines-and-hosts.md
+[10]: https://github.com/openshift/installer/blob/master/docs/user/metal/install_ipi.md
+[11]: https://github.com/openshift/installer/blob/master/docs/design/baremetal/networking-infrastructure.md