+Steps to Start the Automatic Deploy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These steps are common for ``virtual``, ``baremetal`` or ``hybrid`` deploys,
+``x86_64``, ``aarch64`` or ``mixed`` (``x86_64`` and ``aarch64``):
+
+- Clone the OPNFV Fuel code from gerrit
+- Checkout the ``Hunter`` release tag
+- Start the deploy script
+
+.. NOTE::
+
+ The deployment uses the OPNFV Pharos project as input (``PDF`` and
+ ``IDF`` files) for hardware and network configuration of all current
+ OPNFV PODs.
+
+ When deploying a new POD, one may pass the ``-b`` flag to the deploy
+ script to override the path for the labconfig directory structure
+ containing the ``PDF`` and ``IDF`` (``<URI to configuration repo ...>`` is
+ the absolute path to a local or remote directory structure, populated
+ similar to `pharos git repo`_, i.e. ``PDF``/``IDF`` reside in a
+ subdirectory called ``labs/<lab_name>``).
+
+.. code-block:: console
+
+ jenkins@jumpserver:~$ git clone https://git.opnfv.org/fuel
+ jenkins@jumpserver:~$ cd fuel
+ jenkins@jumpserver:~/fuel$ git checkout opnfv-8.1.0
+ jenkins@jumpserver:~/fuel$ ci/deploy.sh -l <lab_name> \
+ -p <pod_name> \
+ -b <URI to configuration repo containing the PDF/IDF files> \
+ -s <scenario> \
+ -D \
+ -S <Storage directory for deploy artifacts> |& tee deploy.log
+
+.. TIP::
+
+ Besides the basic options, there are other recommended deploy arguments:
+
+ - use ``-D`` option to enable the debug info
+ - use ``-S`` option to point to a tmp dir where the disk images are saved.
+ The deploy artifacts will be re-used on subsequent (re)deployments.
+ - use ``|& tee`` to save the deploy log to a file
+
+Typical Cluster Examples
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Common cluster layouts usually fall into one of the cases described below,
+categorized by deployment type (``baremetal``, ``virtual`` or ``hybrid``) and
+high availability (``HA`` or ``noHA``).
+
+A simplified overview of the steps ``deploy.sh`` will automatically perform is:
+
+- create a Salt Master Docker container on the jumpserver, which will drive
+ the rest of the installation;
+- ``baremetal`` or ``hybrid`` only: create a ``MaaS`` container node,
+ which will be leveraged using Salt to handle OS provisioning on the
+ ``baremetal`` nodes;
+- leverage Salt to install & configure OpenStack;
+
+.. NOTE::
+
+ A Docker network ``mcpcontrol`` is always created for initial connection
+ of the infrastructure containers (``cfg01``, ``mas01``) on Jumphost.
+
+.. WARNING::
+
+ A single cluster deployment per ``jumpserver`` node is currently supported,
+ indifferent of its type (``virtual``, ``baremetal`` or ``hybrid``).
+
+Once the deployment is complete, the following should be accessible:
+
++---------------+----------------------------------+---------------------------+
+| Resource | ``HA`` scenario | ``noHA`` scenario |
++===============+==================================+===========================+
+| ``Horizon`` | ``https://<prx public VIP>`` | ``http://<ctl VIP>:8078`` |
+| (Openstack | | |
+| Dashboard) | | |
++---------------+----------------------------------+---------------------------+
+| ``SaltStack`` | ``http://<prx public VIP>:8090`` | N/A |
+| Deployment | | |
+| Documentation | | |
++---------------+----------------------------------+---------------------------+
+
+.. SEEALSO::
+
+ For more details on locating and importing the generated SSL certificate,
+ see :ref:`OPNFV Fuel User Guide <fuel-userguide>`.
+
+``virtual`` ``noHA`` POD
+------------------------
+
+In the following figure there are two generic examples of ``virtual`` deploys,
+each on a separate Jumphost node, both behind the same ``TOR`` switch:
+
+- Jumphost 1 has only virsh bridges (created by the deploy script);
+- Jumphost 2 has a mix of Linux (manually created) and ``libvirt`` managed
+ bridges (created by the deploy script);
+
+.. figure:: img/fuel_virtual_noha.png
+ :align: center
+ :width: 60%
+ :alt: OPNFV Fuel Virtual noHA POD Network Layout Examples
+
+ OPNFV Fuel Virtual noHA POD Network Layout Examples
+
+ +-------------+------------------------------------------------------------+
+ | ``cfg01`` | Salt Master Docker container |
+ +-------------+------------------------------------------------------------+
+ | ``ctl01`` | Controller VM |
+ +-------------+------------------------------------------------------------+
+ | ``gtw01`` | Gateway VM with neutron services |
+ | | (``DHCP`` agent, ``L3`` agent, ``metadata`` agent etc) |
+ +-------------+------------------------------------------------------------+
+ | ``odl01`` | VM on which ``ODL`` runs |
+ | | (for scenarios deployed with ODL) |
+ +-------------+------------------------------------------------------------+
+ | ``cmp001``, | Compute VMs |
+ | ``cmp002`` | |
+ +-------------+------------------------------------------------------------+
+
+.. TIP::
+
+ If external access to the ``public`` network is not required, there is
+ little to no motivation to create a custom ``PDF``/``IDF`` set for a
+ virtual deployment.
+
+ Instead, the existing virtual PODs definitions in `pharos git repo`_ can
+ be used as-is:
+
+ - ``ericsson-virtual1`` for ``x86_64``;
+ - ``arm-virtual2`` for ``aarch64``;
+
+.. code-block:: console
+
+ # example deploy cmd for an x86_64 virtual cluster
+ jenkins@jumpserver:~/fuel$ ci/deploy.sh -l ericsson \
+ -p virtual1 \
+ -s os-nosdn-nofeature-noha \
+ -D \
+ -S /home/jenkins/tmpdir |& tee deploy.log
+
+``baremetal`` ``noHA`` POD
+--------------------------
+
+.. WARNING::
+
+ These scenarios are not tested in OPNFV CI, so they are considered
+ experimental.
+
+.. figure:: img/fuel_baremetal_noha.png
+ :align: center
+ :width: 60%
+ :alt: OPNFV Fuel Baremetal noHA POD Network Layout Example
+
+ OPNFV Fuel Baremetal noHA POD Network Layout Example
+
+ +-------------+------------------------------------------------------------+
+ | ``cfg01`` | Salt Master Docker container |
+ +-------------+------------------------------------------------------------+
+ | ``mas01`` | MaaS Node Docker container |
+ +-------------+------------------------------------------------------------+
+ | ``ctl01`` | Baremetal controller node |
+ +-------------+------------------------------------------------------------+
+ | ``gtw01`` | Baremetal Gateway with neutron services |
+ | | (dhcp agent, L3 agent, metadata, etc) |
+ +-------------+------------------------------------------------------------+
+ | ``odl01`` | Baremetal node on which ODL runs |
+ | | (for scenarios deployed with ODL, otherwise unused |
+ +-------------+------------------------------------------------------------+
+ | ``cmp001``, | Baremetal Computes |
+ | ``cmp002`` | |
+ +-------------+------------------------------------------------------------+
+ | Tenant VM | VM running in the cloud |
+ +-------------+------------------------------------------------------------+
+
+``baremetal`` ``HA`` POD
+------------------------
+
+.. figure:: img/fuel_baremetal_ha.png
+ :align: center
+ :width: 60%
+ :alt: OPNFV Fuel Baremetal HA POD Network Layout Example
+
+ OPNFV Fuel Baremetal HA POD Network Layout Example
+
+ +---------------------------+----------------------------------------------+
+ | ``cfg01`` | Salt Master Docker container |
+ +---------------------------+----------------------------------------------+
+ | ``mas01`` | MaaS Node Docker container |
+ +---------------------------+----------------------------------------------+
+ | ``kvm01``, | Baremetals which hold the VMs with |
+ | ``kvm02``, | controller functions |
+ | ``kvm03`` | |
+ +---------------------------+----------------------------------------------+
+ | ``prx01``, | Proxy VMs for Nginx |
+ | ``prx02`` | |
+ +---------------------------+----------------------------------------------+
+ | ``msg01``, | RabbitMQ Service VMs |
+ | ``msg02``, | |
+ | ``msg03`` | |
+ +---------------------------+----------------------------------------------+
+ | ``dbs01``, | MySQL service VMs |
+ | ``dbs02``, | |
+ | ``dbs03`` | |
+ +---------------------------+----------------------------------------------+
+ | ``mdb01``, | Telemetry VMs |
+ | ``mdb02``, | |
+ | ``mdb03`` | |
+ +---------------------------+----------------------------------------------+
+ | ``odl01`` | VM on which ``OpenDaylight`` runs |
+ | | (for scenarios deployed with ``ODL``) |
+ +---------------------------+----------------------------------------------+
+ | ``cmp001``, | Baremetal Computes |
+ | ``cmp002`` | |
+ +---------------------------+----------------------------------------------+
+ | Tenant VM | VM running in the cloud |
+ +---------------------------+----------------------------------------------+
+
+.. code-block:: console
+
+ # x86_x64 baremetal deploy on pod2 from Linux Foundation lab (lf-pod2)
+ jenkins@jumpserver:~/fuel$ ci/deploy.sh -l lf \
+ -p pod2 \
+ -s os-nosdn-nofeature-ha \
+ -D \
+ -S /home/jenkins/tmpdir |& tee deploy.log
+
+.. code-block:: console
+
+ # aarch64 baremetal deploy on pod5 from Enea ARM lab (arm-pod5)
+ jenkins@jumpserver:~/fuel$ ci/deploy.sh -l arm \
+ -p pod5 \
+ -s os-nosdn-nofeature-ha \
+ -D \
+ -S /home/jenkins/tmpdir |& tee deploy.log
+
+``hybrid`` ``noHA`` POD
+-----------------------
+
+.. figure:: img/fuel_hybrid_noha.png
+ :align: center
+ :width: 60%
+ :alt: OPNFV Fuel Hybrid noHA POD Network Layout Examples
+
+ OPNFV Fuel Hybrid noHA POD Network Layout Examples
+
+ +-------------+------------------------------------------------------------+
+ | ``cfg01`` | Salt Master Docker container |
+ +-------------+------------------------------------------------------------+
+ | ``mas01`` | MaaS Node Docker container |
+ +-------------+------------------------------------------------------------+
+ | ``ctl01`` | Controller VM |
+ +-------------+------------------------------------------------------------+
+ | ``gtw01`` | Gateway VM with neutron services |
+ | | (``DHCP`` agent, ``L3`` agent, ``metadata`` agent etc) |
+ +-------------+------------------------------------------------------------+
+ | ``odl01`` | VM on which ``ODL`` runs |
+ | | (for scenarios deployed with ODL) |
+ +-------------+------------------------------------------------------------+
+ | ``cmp001``, | Baremetal Computes |
+ | ``cmp002`` | |
+ +-------------+------------------------------------------------------------+
+
+Automatic Deploy Breakdown
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When an automatic deploy is started, the following operations are performed
+sequentially by the deploy script:
+
++------------------+----------------------------------------------------------+
+| **Deploy stage** | **Details** |
++==================+==========================================================+
+| Argument | enviroment variables and command line arguments passed |
+| Parsing | to ``deploy.sh`` are interpreted |
++------------------+----------------------------------------------------------+
+| Distribution | Install and/or configure mandatory requirements on the |
+| Package | ``jumpserver`` node: |
+| Installation | |
+| | - ``Docker`` (from upstream and not distribution repos, |
+| | as the version included in ``Ubuntu`` ``Xenial`` is |
+| | outdated); |
+| | - ``docker-compose`` (from upstream, as the version |
+| | included in both ``CentOS 7`` and |
+| | ``Ubuntu Xenial 16.04`` has dependency issues on most |
+| | systems); |
+| | - ``virt-inst`` (from upstream, as the version included |
+| | in ``Ubuntu Xenial 16.04`` is outdated and lacks |
+| | certain required features); |
+| | - other miscelaneous requirements, depending on |
+| | ``jumpserver`` distribution OS; |
+| | |
+| | .. SEEALSO:: |
+| | |
+| | - ``mcp/scripts/requirements_deb.yaml`` (``Ubuntu``) |
+| | - ``mcp/scripts/requirements_rpm.yaml`` (``CentOS``) |
+| | |
+| | .. WARNING:: |
+| | |
+| | Mininum required ``Docker`` version is ``17.x``. |
+| | |
+| | .. WARNING:: |
+| | |
+| | Mininum required ``virt-inst`` version is ``1.4``. |
++------------------+----------------------------------------------------------+
+| Patch | For each ``git`` submodule in OPNFV Fuel repository, |
+| Apply | if a subdirectory with the same name exists under |
+| | ``mcp/patches``, all patches in that subdirectory are |
+| | applied using ``git-am`` to the respective ``git`` |
+| | submodule. |
+| | |
+| | This allows OPNFV Fuel to alter upstream repositories |
+| | contents before consuming them, including: |
+| | |
+| | - ``Docker`` container build process customization; |
+| | - ``salt-formulas`` customization; |
+| | - ``reclass.system`` customization; |
+| | |
+| | .. SEEALSO:: |
+| | |
+| | - ``mcp/patches/README.rst`` |
++------------------+----------------------------------------------------------+
+| SSH RSA Keypair | If not already present, a RSA keypair is generated on |
+| Generation | the ``jumpserver`` node at: |
+| | |
+| | - ``/var/lib/opnfv/mcp.rsa{,.pub}`` |
+| | |
+| | The public key will be added to the ``authorized_keys`` |
+| | list for ``ubuntu`` user, so the private key can be used |
+| | for key-based logins on: |
+| | |
+| | - ``cfg01``, ``mas01`` infrastructure nodes; |
+| | - all cluster nodes (``baremetal`` and/or ``virtual``), |
+| | including ``VCP`` VMs; |
++------------------+----------------------------------------------------------+
+| ``j2`` | Based on ``XDF`` (``PDF``, ``IDF``, ``SDF``) and |
+| Expansion | additional deployment configuration determined during |
+| | ``argument parsing`` stage described above, all jinja2 |
+| | templates are expanded, including: |
+| | |
+| | - various classes in ``reclass.cluster``; |
+| | - docker-compose ``yaml`` for Salt Master bring-up; |
+| | - ``libvirt`` network definitions (``xml``); |
++------------------+----------------------------------------------------------+
+| Jumpserver | Basic validation that common ``jumpserver`` requirements |
+| Requirements | are satisfied, e.g. ``PXE/admin`` is Linux bridge if |
+| Check | ``baremetal`` nodes are defined in the ``PDF``. |
++------------------+----------------------------------------------------------+
+| Infrastucture | .. NOTE:: |
+| Setup | |
+| | All steps apply to and only to the ``jumpserver``. |
+| | |
+| | - prepare virtual machines; |
+| | - (re)create ``libvirt`` managed networks; |
+| | - apply ``sysctl`` configuration; |
+| | - apply ``udev`` configuration; |
+| | - create & start virtual machines prepared earlier; |
+| | - create & start Salt Master (``cfg01``) Docker |
+| | container; |
++------------------+----------------------------------------------------------+
+| ``STATE`` | Based on deployment type, scenario and other parameters, |
+| Files | a ``STATE`` file list is constructed, then executed |
+| | sequentially. |
+| | |
+| | .. TIP:: |
+| | |
+| | The table below lists all current ``STATE`` files |
+| | and their intended action. |
+| | |
+| | .. SEEALSO:: |
+| | |
+| | For more information on how the list of ``STATE`` |
+| | files is constructed, see |
+| | :ref:`OPNFV Fuel User Guide <fuel-userguide>`. |
++------------------+----------------------------------------------------------+
+| Log | Contents of ``/var/log`` are recursively gathered from |
+| Collection | all the nodes, then archived together for later |
+| | inspection. |
++------------------+----------------------------------------------------------+
+
+``STATE`` Files Overview
+------------------------
+
++---------------------------+-------------------------------------------------+
+| ``STATE`` file | Targets involved and main intended action |
++===========================+=================================================+
+| ``virtual_init`` | ``cfg01``: reclass node generation |
+| | |
+| | ``jumpserver`` VMs (if present): basic OS |
+| | config |
++---------------------------+-------------------------------------------------+
+| ``maas`` | ``mas01``: OS, MaaS configuration |
+| | ``baremetal`` node commissioning and deploy |
+| | |
+| | .. NOTE:: |
+| | |
+| | Skipped if no ``baremetal`` nodes are |
+| | defined in ``PDF`` (``virtual`` deploy). |
++---------------------------+-------------------------------------------------+
+| ``baremetal_init`` | ``kvm``, ``cmp``: OS install, config |
++---------------------------+-------------------------------------------------+
+| ``dpdk`` | ``cmp``: configure OVS-DPDK |
++---------------------------+-------------------------------------------------+
+| ``networks`` | ``ctl``: create OpenStack networks |
++---------------------------+-------------------------------------------------+
+| ``neutron_gateway`` | ``gtw01``: configure Neutron gateway |
++---------------------------+-------------------------------------------------+
+| ``opendaylight`` | ``odl01``: install & configure ``ODL`` |
++---------------------------+-------------------------------------------------+
+| ``openstack_noha`` | cluster nodes: install OpenStack without ``HA`` |
++---------------------------+-------------------------------------------------+
+| ``openstack_ha`` | cluster nodes: install OpenStack with ``HA`` |
++---------------------------+-------------------------------------------------+
+| ``virtual_control_plane`` | ``kvm``: create ``VCP`` VMs |
+| | |
+| | ``VCP`` VMs: basic OS config |
+| | |
+| | .. NOTE:: |
+| | |
+| | Skipped if ``-N`` deploy argument is used. |
++---------------------------+-------------------------------------------------+
+| ``tacker`` | ``ctl``: install & configure Tacker |
++---------------------------+-------------------------------------------------+
+
+Release Notes
+=============
+
+Please refer to the :ref:`OPNFV Fuel Release Notes <fuel-releasenotes>`
+article.
+
+References
+==========
Code Review / fuel.git / blobdiff