Merge "Add docs for baremetal overcloud"

docs/static/baremetal-overcloud/copying-customized-files.rst

@@ -0,0 +1,110 @@
+Copying over customized instackenv.json, network-environment.yaml, nic-configs
+------------------------------------------------------------------------------
+
+instackenv.json
+^^^^^^^^^^^^^^^
+
+``instackenv.json`` file is generated from a template in tripleo-quickstart:
+<https://github.com/openstack/tripleo-quickstart/blob/master/roles/libvirt/setup/overcloud/tasks/main.yml#L91>.
+A customized ``instackenv.json`` can be copied to the undercloud by overwriting the
+``undercloud_instackenv_template`` variable with the path to the customized file.
+
+Below is an explanation of, and example of, the ``instackenv.json`` file:
+
+The JSON file describing your Overcloud baremetal nodes, is called
+``instackenv.json``. The file should contain a JSON object with the only field
+``nodes`` containing list of node descriptions.
+
+Each node description should contains required fields:
+
+* ``pm_type`` - driver for Ironic nodes, see `Ironic Drivers`_ for details
+
+* ``pm_addr`` - node BMC IP address (hypervisor address in case of virtual
+  environment)
+
+* ``pm_user``, ``pm_password`` - node BMC credentials
+
+Some fields are optional if you're going to use introspection later:
+
+* ``mac`` - list of MAC addresses, optional for bare metal
+
+* ``cpu`` - number of CPU's in system
+
+* ``arch`` - CPU architecture (common values are ``i386`` and ``x86_64``)
+
+* ``memory`` - memory size in MiB
+
+* ``disk`` - hard driver size in GiB
+
+It is also possible (but optional) to set Ironic node capabilities directly
+in the JSON file. This can be useful for assigning node profiles or setting
+boot options at registration time:
+
+* ``capabilities`` - Ironic node capabilities.  For example::
+
+    "capabilities": "profile:compute,boot_option:local"
+
+For example::
+
+    {
+        "nodes": [
+            {
+                "pm_type":"pxe_ipmitool",
+                "mac":[
+                    "fa:16:3e:2a:0e:36"
+                ],
+                "cpu":"2",
+                "memory":"4096",
+                "disk":"40",
+                "arch":"x86_64",
+                "pm_user":"admin",
+                "pm_password":"password",
+                "pm_addr":"10.0.0.8"
+            },
+            {
+                "pm_type":"pxe_ipmitool",
+                "mac":[
+                    "fa:16:3e:da:39:c9"
+                ],
+                "cpu":"2",
+                "memory":"4096",
+                "disk":"40",
+                "arch":"x86_64",
+                "pm_user":"admin",
+                "pm_password":"password",
+                "pm_addr":"10.0.0.15"
+            },
+            {
+                "pm_type":"pxe_ipmitool",
+                "mac":[
+                    "fa:16:3e:51:9b:68"
+                ],
+                "cpu":"2",
+                "memory":"4096",
+                "disk":"40",
+                "arch":"x86_64",
+                "pm_user":"admin",
+                "pm_password":"password",
+                "pm_addr":"10.0.0.16"
+            }
+        ]
+    }
+
+
+network-environment.yaml
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Similarly, the ``network-environment.yaml`` file is generated from a template,
+<https://github.com/openstack/tripleo-quickstart/blob/master/roles/tripleo/undercloud/tasks/post-install.yml#L32>
+A customized ``network-environment.yaml`` file can be copied to the undercloud by overwriting the
+`` network_environment_file`` variable with the path to the customized file.
+
+nic-configs
+^^^^^^^^^^^
+
+By default, the virtual environment deployment uses the standard nic-configs files are there is no
+ready section to copy custom nic-configs files.
+The ``ansible-role-tripleo-overcloud-prep-config`` repo includes a task that copies the nic-configs
+files if they are defined,
+<https://github.com/redhat-openstack/ansible-role-tripleo-overcloud-prep-config/blob/master/tasks/main.yml#L15>
+

docs/static/baremetal-overcloud/customizing-external-network-vlan.rst

@@ -0,0 +1,21 @@
+Customizing external network vlan
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If network-isolation is used in the deployment, tripleo-quickstart will, by default,
+add a NIC on the external vlan to the undercloud,
+<https://github.com/openstack/tripleo-quickstart/blob/master/roles/tripleo/undercloud/templates/undercloud-install-post.sh.j2#L88>.
+When working with a baremetal overcloud, the vlan values must be customized with the correct
+system-related values. The default vlan values can be overwritten in a settings file passed
+to triple-quickstart as in the following example:
+::
+
+    undercloud_networks:
+      external:
+        address: 10.0.7.13
+        netmask: 255.255.255.192
+        device_type: ovs
+        type: OVSIntPort
+        ovs_bridge: br-ctlplane
+        ovs_options: '"tag=102"'
+        tag: 102
+

docs/static/baremetal-overcloud/customizing-undercloud-conf.rst

@@ -0,0 +1,21 @@
+Customizing undercloud.conf
+===========================
+
+The undercloud.conf file is copied to the undercloud VM using a template where the system values
+are variables. <https://github.com/openstack/tripleo-quickstart/blob/master/roles/tripleo/undercloud/templates/undercloud.conf.j2>.
+The tripleo-quickstart defaults for these variables are suited to a virtual overcloud,
+but can be overwritten by passing custom settings to tripleo-quickstart in a settings file
+(--extra-vars @<file_path>). For example:
+::
+
+    undercloud_network_cidr: 10.0.5.0/24
+    undercloud_local_ip: 10.0.5.1/24
+    undercloud_network_gateway: 10.0.5.1
+    undercloud_undercloud_public_vip: 10.0.5.2
+    undercloud_undercloud_admin_vip: 10.0.5.3
+    undercloud_local_interface: eth1
+    undercloud_masquerade_network: 10.0.5.0/24
+    undercloud_dhcp_start: 10.0.5.5
+    undercloud_dhcp_end: 10.0.5.24
+    undercloud_inspection_iprange: 10.0.5.100,10.0.5.120
+

docs/static/baremetal-overcloud/env-setup.rst

@@ -0,0 +1,43 @@
+Install the dependencies
+------------------------
+
+You need some software available on your local system before you can run
+`quickstart.sh`. You can install the necessary dependencies by running:
+
+::
+
+    bash quickstart.sh --install-deps
+
+Setup your virtual environment
+------------------------------
+
+tripleo-quickstart includes steps to set up libvirt on the undercloud host
+machine and to create and setup the undercloud VM.
+
+Deployments on baremetal hardware require steps from third-party repos,
+in addition to the steps in tripleo-quickstart.
+Below is an example of a complete call to quickstart.sh to run a full deploy
+on baremetal overcloud nodes:
+
+::
+
+    # $HW_ENV_DIR is the directory where the baremetal environment-specific
+    # files are stored
+
+    pushd $WORKSPACE/tripleo-quickstart
+    bash quickstart.sh \
+        --ansible-debug \
+        --bootstrap \
+        --working-dir $WORKSPACE/ \
+        --tags all \
+        --no-clone \
+        --teardown all \
+        --requirements quickstart-role-requirements.txt \
+        --requirements $WORKSPACE/$HW_ENV_DIR/requirements_files/$REQUIREMENTS_FILE \
+        --config $WORKSPACE/$HW_ENV_DIR/config_files/$CONFIG_FILE \
+        --extra-vars @$WORKSPACE/$HW_ENV_DIR/env_settings.yml \
+        --playbook $PLAYBOOK \
+        --release $RELEASE \
+        $VIRTHOST
+    popd
+

docs/static/baremetal-overcloud/env-specific-pre-deploy-steps.rst

@@ -0,0 +1,15 @@
+Additional steps preparing the environment for deployment
+---------------------------------------------------------
+
+Depending on the parameters of the baremetal overcloud environment in use,
+other pre-deployment steps may be needed to ensure that the deployment succeeds.
+<https://github.com/redhat-openstack/ansible-role-tripleo-overcloud-prep-baremetal/tree/master/tasks>
+includes a number of these steps. Whether each step is run, depends on variable values
+that can be set per environment.
+
+Some examples of additional steps are:
+
+- Adding disk size hints
+- Adjusting MTU values
+- Rerunning introspection on failure
+

docs/static/baremetal-overcloud/environment-settings-structure.rst

@@ -0,0 +1,94 @@
+Settings for hardware environments
+==================================
+
+Throughout the documentation, there are example settings and custom files to
+overwrite the virt defaults in TripleO Quickstart. It is recommended to use a
+organized directory structure to store the settings and files for each hardware
+environment.
+
+Example Directory Structure
+---------------------------
+
+Each baremetal environment will need a directory structured as follows:
+
+|-- environment_name
+|    |-- instackenv.json
+|    |-- vendor_specific_setup
+|    |-- <architecture diagram/explanation document>
+|    |-- network_configs
+|    |    |--<network-islation-type-1>
+|    |    |    |-- <network-environment.yaml file>
+|    |    |    |-- env_settings.yml
+|    |    |    |-- nic_configs
+|    |    |    |    |-- ceph-storage.yaml
+|    |    |    |    |-- cinder-storage.yaml
+|    |    |    |    |-- compute.yaml
+|    |    |    |    |-- controller.yaml
+|    |    |    |    |-- swift-storage.yaml
+|    |    |    |-- config_files
+|    |    |    |    |--config.yml
+|    |    |    |    |--<other config files>
+|    |    |    |-- requirements_files
+|    |    |    |    |--requirements1.yml
+|    |    |    |    |--requirements2.yml
+|    |    |--<network-islation-type-2>
+|    |    |    |-- <network-environment.yaml file>
+|    |    |    |-- env_settings.yml
+|    |    |    |-- nic_configs
+|    |    |    |    |-- ceph-storage.yaml
+|    |    |    |    |-- cinder-storage.yaml
+|    |    |    |    |-- compute.yaml
+|    |    |    |    |-- controller.yaml
+|    |    |    |    |-- swift-storage.yaml
+|    |    |    |-- config_files
+|    |    |    |    |--config.yml
+|    |    |    |    |--<other config files>
+|    |    |    |-- requirements_files
+|    |    |    |    |--requirements1.yml
+|    |    |    |    |--requirements2.yml
+
+
+Explanation of Directory Contents
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ - instackenv.json (required)
+
+    The instackenv.json file added at this top-level directory will replace the templated instackenv.json file for virt deployments.
+
+ - vendor_specific_setup (optional)
+
+   If any script needs to run to do environment setup before deployment, such as RAID configuration, it can be included here.
+
+ - architecture diagram (optional)
+
+    Although not required, if there is a diagram or document detailing the network architecture, it is useful to include that document or diagram here as all the settings and network isolation files will be based off of it.
+
+ - network_configs (required)
+
+    This directory is used to house the directories divided by network isolation type.
+
+ - network-isolation-type (required)
+
+    Even if deploying without network isolation, the files should be included in a 'none' directory.
+    There are files examples of the following network isolation types: single_nic_vlans, bond_with_vlans, native_networking, none.
+
+ - network-environment.yaml (required, unless deploying with no network isolation)
+
+    This file should be named after the network-isolation type, for example:  bond_with_vlans.yaml. This naming convention follows the same pattern used by the default, virt workflow.
+
+ - env_settings.yaml (required)
+
+    This file stores all environment-specific settings to override default settings in TripleO quickstart and related repos, for example: the location of instackenv.json file, and setting 'overcloud_nodes' to empty so that quickstart does not create VMs for overcloud nodes. All settings required for undercloud.conf are included here.
+
+ - nic_configs (optional)
+
+    If the default nic-config files are not suitable for a particular hardware environment, specific ones can be added here and copied to the undercloud. Ensure that the network-environment.yaml file points to the correct location for the nic-configs to be used in deploy.
+
+ - config_files (required)
+
+    The deployment details are stored in the config file. Different config files can be created for scaling up nodes, HA, and other deployment combinations.
+
+ - requirements_files (required)
+
+   Multiple requirements files can be passed to quickstart.sh to include additional repos. For example, to include IPMI validation, the requirements files would need to include https://github.com/redhat-openstack/ansible-role-tripleo-validate-ipmi.
+

docs/static/baremetal-overcloud/introduction.rst

@@ -0,0 +1,21 @@
+TripleO Quickstart
+==================
+
+TripleO Quickstart is a fast and easy way to setup and configure your virtual environment for TripleO.
+Further documentation can be found at https://github.com/openstack/tripleo-quickstart
+
+A quick way to test that your virthost machine is ready to rock is:
+
+::
+
+    ssh root@$VIRTHOST uname -a
+
+Getting the script
+------------------
+
+You can download the `quickstart.sh` script with `wget`:
+
+::
+
+    wget https://raw.githubusercontent.com/openstack/tripleo-quickstart/master/quickstart.sh
+

docs/static/baremetal-overcloud/networking.rst

@@ -0,0 +1,37 @@
+Networking
+----------
+
+With a Virtual Environment, tripleo-quickstart sets up the networking as part of the workflow.
+The networking arrangement needs to be set up prior to working with tripleo-quickstart.
+
+The overcloud nodes will be deployed from the undercloud machine and therefore the
+machines need to have have their network settings modified to allow for the
+overcloud nodes to be PXE boot'ed using the undercloud machine.
+As such, the setup requires that:
+
+* All overcloud machines in the setup must support IPMI
+* A management provisioning network is setup for all of the overcloud machines.
+  One NIC from every machine needs to be in the same broadcast domain of the
+  provisioning network. In the tested environment, this required setting up a new
+  VLAN on the switch. Note that you should use the same NIC on each of the
+  overcloud machines ( for example: use the second NIC on each overcloud
+  machine). This is because during installation we will need to refer to that NIC
+  using a single name across all overcloud machines e.g. em2
+* The provisioning network NIC should not be the same NIC that you are using
+  for remote connectivity to the undercloud machine. During the undercloud
+  installation, a openvswitch bridge will be created for Neutron and the
+  provisioning NIC will be bridged to the openvswitch bridge. As such,
+  connectivity would be lost if the provisioning NIC was also used for remote
+  connectivity to the undercloud machine.
+* The overcloud machines can PXE boot off the NIC that is on the private VLAN.
+  In the tested environment, this required disabling network booting in the BIOS
+  for all NICs other than the one we wanted to boot and then ensuring that the
+  chosen NIC is at the top of the boot order (ahead of the local hard disk drive
+  and CD/DVD drives).
+* For each overcloud machine you have: the MAC address of the NIC that will PXE
+  boot on the provisioning network the IPMI information for the machine (i.e. IP
+  address of the IPMI NIC, IPMI username and password)
+
+Refer to the following diagram for more information
+
+i.. image:: _images/TripleO_Network_Diagram_.jpg

docs/static/baremetal-overcloud/requirements.rst

@@ -0,0 +1,23 @@
+Minimum System Requirements
+---------------------------
+
+By default, tripleo-quickstart requires 3 machines:
+
+* 1 Undercloud (can be a Virtual Machine)
+* 1 Overcloud Controller
+* 1 Overcloud Compute
+
+Commonly, deployments include HA (3 Overcloud Controllers) and multiple Overcloud Compute nodes.
+
+Each Overcloud machine requires at least:
+
+* 1 quad core CPU
+* 8 GB free memory
+* 60 GB disk space
+
+The undercloud VM or baremetal machine requires:
+
+* 1 quad core CPU
+* 16 GB free memory
+* 80 GB disk space
+

docs/static/baremetal-overcloud/validate-prior-to-deploy.rst

@@ -0,0 +1,9 @@
+Validating the environment prior to deployment
+----------------------------------------------
+
+In a baremetal overcloud deployment there is a custom environment and many related settings
+and steps. As such, it is worthwhile to validate the environment and custom configuration
+files prior to deployment.
+
+A collection of validation tools is available in the 'clapper' repo:
+<https://github.com/rthallisey/clapper/>.

docs/static/baremetal-overcloud/virtual-vs-baremetal-undercloud.rst

@@ -0,0 +1,17 @@
+Virtual Undercloud VS. Baremetal Undercloud
+-------------------------------------------
+
+When deploying the overcloud on baremetal nodes, there is the option of using an undercloud
+deployed on a baremetal machine or creating a virtual machine (VM) on that same baremetal machine
+and using the VM to serve as the undercloud.
+
+The advantages of using a VM undercloud are:
+
+* The VM can be rebuilt and reinstalled without reprovisioning the entire baremetal machine
+* The tripleo-quickstart default workflow is written for a Virtual Environment deployment.
+  Using a VM undercloud requires less customization of the default workflow.
+
+.. note:: When using a VM undercloud, but baremetal nodes for the overcloud
+          deployment, the ``overcloud_nodes`` variable in tripleo-quickstart
+          must overwritten and set to empty.
+