Merge "Add documentation about the disk_label capability"

doc/source/deploy/install-guide.rst

@@ -1369,6 +1369,74 @@ The boot modes can be configured in Bare Metal service in the following way:
   is configured for bare metal nodes, then nova scheduler will consider all
   nodes and user may get either ``bios`` or ``uefi`` machine.
 
+.. _choosing_the_disk_label:
+
+Choosing the disk label
+-----------------------
+
+.. note::
+   The term ``disk label`` is historically used in Ironic and was taken
+   from `parted <https://www.gnu.org/software/parted>`_. Apparently
+   everyone seems to have a different word for ``disk label`` - these
+   are all the same thing: disk type, partition table, partition map
+   and so on...
+
+Ironic allows operators to choose which disk label they want their
+bare metal node to be deployed with when Ironic is responsible for
+partitioning the disk; therefore choosing the disk label does not apply
+when the image being deployed is a ``whole disk image``.
+
+.. note::
+   At present the agent_* drivers do not support deploying partition
+   images, therefore forcing the disk label for those drivers is not
+   possible.
+
+There are some edge cases where someone may want to choose a specific
+disk label for the images being deployed, including but not limited to:
+
+* For machines in ``bios`` boot mode with disks larger than 2 terabytes
+  it's recommended to use a ``gpt`` disk label. That's because
+  a capacity beyond 2 terabytes is not addressable by using the
+  MBR partitioning type. But, although GPT claims to be backward
+  compatible with legacy BIOS systems `that's not always the case
+  <http://www.rodsbooks.com/gdisk/bios.html>`_.
+
+* Operators may want to force the partitioning to be always MBR (even
+  if the machine is deployed with boot mode ``uefi``) to avoid breakage
+  of applications and tools running on those instances.
+
+The disk label can be configured in two ways; when Ironic is used with
+the Compute service or in standalone mode. The following bullet points
+and sections will describe both methods:
+
+* When no disk label is provided Ironic will configure it according
+  to the `boot mode <boot_mode_support_>`_; ``bios`` boot mode will use
+  ``msdos`` and ``uefi`` boot mode will use ``gpt``.
+
+* Only one disk label - either ``msdos`` or ``gpt`` - can be configured
+  for the node.
+
+When used with Compute service
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When Ironic is used with the Compute service the disk label should be
+set to node's ``properties/capabilities`` field and also to the flavor
+which will request such capability, for example::
+
+    ironic node-update <node-uuid> add properties/capabilities='disk_label:gpt'
+
+As for the flavor::
+
+    nova flavor-key baremetal set capabilities:disk_label="gpt"
+
+When used in standalone mode
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When used without the Compute service, the disk label should be set
+directly to the node's ``instance_info`` field, as below::
+
+    ironic node-update <node-uuid> add instance_info/capabilities='{"disk_label": "gpt"}'
+
 
 Local boot with partition images
 ================================