diff --git a/docs/quickstart.rst b/docs/build-oss-image.rst similarity index 76% rename from docs/quickstart.rst rename to docs/build-oss-image.rst index bc68dc4..0cc0817 100644 --- a/docs/quickstart.rst +++ b/docs/build-oss-image.rst @@ -1,7 +1,7 @@ -.. _oss-quickstart-guide: +.. _build-oss-image: -OSS Tooling Quick Start Guide -============================= +Build a Mirantis OSS Tooling ISO image +====================================== Mirantis Operational Support System Tooling, or OSS Tooling, is a software platform that enables Mirantis Managed Services engineers to access remote @@ -14,14 +14,13 @@ appliance. This document includes the following sections: -* :ref:`qs-prerequisites` -* :ref:`qs-required-packages` -* :ref:`qs-prepare-env` -* :ref:`qs-generate-gpg-key` -* :ref:`qs-build-bootstrap-image` -* :ref:`qs-automated-deployment` +* :ref:`prerequisites` +* :ref:`required-packages` +* :ref:`prepare-env` +* :ref:`generate-gpg-key` +* :ref:`build-bootstrap-image` -.. _qs-prerequisites: +.. _prerequisites: Prerequisites ~~~~~~~~~~~~~ @@ -65,10 +64,10 @@ image. .. seealso:: - * :ref:`qs-required-packages` + * :ref:`required-packages` * `CentOS Minimal ISO mirrors `_ -.. _qs-required-packages: +.. _required-packages: ISO image packages ------------------ @@ -78,7 +77,7 @@ installed on the base operating system of the ISO image. The latest packages are used automatically. This set of packages is different from the packages required for the -building environment described in :ref:`qs-prepare-env`. +building environment described in :ref:`prepare-env`. The OSS Tooling ISO image includes the following packages: @@ -145,7 +144,7 @@ The OSS Tooling ISO image includes the following packages: * - ``setools-libs`` - A set of tools for SELinux policy analysis. -.. _qs-prepare-env: +.. _prepare-env: Prepare the building environment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -177,9 +176,9 @@ your building environment by installing the required packages. unzip packer_0.11.0_linux_amd64.zip packer -d ~/ #. If you use Ubuntu as a building environment, proceed to - :ref:`qs-generate-gpg-key`. + :ref:`generate-gpg-key`. -.. _qs-generate-gpg-key: +.. _generate-gpg-key: Generate a new GPG key ---------------------- @@ -218,19 +217,19 @@ GnuPG. This GPG key will be used to sign the repository inside the ISO image. gpg -K -.. _qs-build-bootstrap-image: +.. _build-bootstrap-image: -Build an OSS Tolling ISO image -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Build the ISO image +~~~~~~~~~~~~~~~~~~~ After preparing your environment as described in -:ref:`qs-prepare-env`, you can build +:ref:`prepare-env`, you can build an OSS Tooling ISO image. **To build an OSS Tooling ISO image:** #. Download the recommended base OS image. Supported versions are - listed in :ref:`qs-prerequisites`. + listed in :ref:`prerequisites`. #. Copy the downloaded base OS image to a directory in your build environment. #. Clone the image builder source code from the GitHub repository: @@ -283,56 +282,3 @@ an OSS Tooling ISO image. If you used the parameters from the example above, the created ISO image will be placed in ``~/build/ms-centos-7.iso`` - -.. _qs-automated-deployment: - -Automated deployment of OSS Infrastructure -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The deployment of OSS Tools requires at least four hardware or virtual nodes -which are connected in the same network. The first node is needed to bootstrap -images and then run deployment of OSS Tools on the other nodes. These nodes -have to be installed from the pre-built OSS Tooling ISO. - -.. note:: - During the installation from ISO the `mirantis` user will be created with - the default password `mirantis`. - -After installation of nodes `automation` have to be copied on the deployment -node: - - :: - - git clone https://github.com/seecloud/automation - -Then, change the current directory to `automation` and perform the bootstrap -process which downloads all necessary images for further installation: - - :: - - ansible-playbook -i inventory/bootstrap.cfg bootstrap-runner.yml - -.. note:: - The Internet connection is only needed to bootstrap images, the automated - deployment is an offline process. - -Roles have to be properly assigned on nodes before to run the deployment, -the pre-installed nodes should be listed in the following command: - - :: - - utils/inventory-generator --nodes \ - node1[ansible_ssh_host=10.20.0.1] \ - node2[ansible_ssh_host=10.20.0.2] \ - node3[ansible_ssh_host=10.20.0.3] \ - -The command above generates an inventory file which is located at -`inventory/inventory.cfg`. The inventory file is used to perform the automation -deployment: - - :: - - ansible-playbook -i inventory/inventory.cfg automation-runner.yml - -After all above steps three nodes run the fully functional OSS Infrastructure -which is ready to run OSS Tools Services. diff --git a/docs/deploy-oss-tooling.rst b/docs/deploy-oss-tooling.rst new file mode 100644 index 0000000..57fa6a2 --- /dev/null +++ b/docs/deploy-oss-tooling.rst @@ -0,0 +1,171 @@ +.. _deploy-oss-tooling: + +Deploy an OSS Tooling framework +=============================== + +After you obtain a Mirantis OSS Tooling ISO image, you can deploy the +Mirantis OSS Tooling framework. + +The Mirantis OSS Tooling framework runs on core nodes. +Although for testing purposes, one core node is sufficient, for production +environment, deploy at least 3 virtual or physical core nodes. + +You will also need a machine from which you configure core nodes after +installing the base operating system. This machine sometimes +called deployment node. A deployment node must run Ubuntu 14.04 or later +or CentOS 7. If you do not have such machine at hand, you may use the +Mirantis OSS Tooling ISO image to deploy one. After installing and +configuring the Mirantis OSS Tooling framework, the deployment node +does not participate in the framework lifecycle. Therefore, you can use +your laptop or any other machine as deployment node. + +This section includes the following topics: + +* :ref:`hard-soft-reqs` +* :ref:`prepare-deployment-node` +* :ref:`deploy-base-os-core-nodes` +* :ref:`assign-node-roles` +* :ref:`configure-core-nodes` + +.. _hard-soft-reqs: + +Hardware and software requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Your environment must meet the following requirements: + +* **Deployment node** + + * Operating system: Ubuntu 16.04 or CentOS 7 (You can install CentOS 7 + from the same pre-build ISO or use your own system) + * RAM: 2+ GB + * Network: 1 GbE network interface with network connectivity to data nodes + * Disk: 20+ GB of free space + +* **Core node** + + * Operating system: empty, will be installed from the ISO. + * RAM: 4+ GB + * Network: 1 GbE network interface + * Disk: 20+ GB of free space + +.. _prepare-deployment-node: + +Prepare a deployment node +~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can prepare a deployment node in advance and use the configuration to set +up core nodes later. For example, if you need to deploy the Mirantis OSS +Tooling framework in a facility without an Internet connection, you can +create a required configuration in your office on your laptop and later +bootstrap the configuration in the facility. In this case, your laptop +becomes a deployment node. Therefore it must meet the requirements listed +in :ref`hard-soft-reqs`. + +The task described in this section requires an Internet connection. + +**To prepare a deployment node:** + +#. Log in to the deployment node. +#. Clone the ``automation`` repository: + + :: + + git clone https://github.com/seecloud/automation + +#. Change the directory to the newly created ``automation`` directory. +#. Download all the required images for deployment by running the + ``bootstrap-runner.yml`` Ansible Playbook: + + :: + + ansible-playbook -i inventory/bootstrap.cfg bootstrap-runner.yml + +#. Proceed to :ref:`deploy-base-os-core-nodes`. + +.. _deploy-base-os-core-nodes: + +Provision the base operating system on core nodes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Data nodes will run all required tools and services for remote management +of OpenStack environments. Your data nodes must meet requirements listed +in :ref:`hard-soft-reqs`. Use the Mirantis OSS Tooling ISO that +you have built as described in :ref:`build-oss-image` or the one you +have obtained from the automatic build system. + +You must deploy at least three nodes to ensure high-availability and +fault tolerance of your system. + +**To the base operating system on Data nodes:** + +#. Make the ISO available to the servers which you plan to use as Data + nodes by creating a USB drive with the ISO image or by uploading the + ISO image to a server and make it available through the IPMI. + +#. Boot the required physical or virtual machines. + + The operating system installs automatically with the pre-configured + settings. + + If you use virtual machines, you can deploy one machine and then create + two clones of that machine. + + note: + Username: mirantis + Password: mirantis + +#. Proceed to :ref:`assign-node-roles` + +.. _assign-node-roles: + +Assign node roles +~~~~~~~~~~~~~~~~~ + +Before you run a deployment, you must assign roles to core nodes. +A role determines what processes a core node runs. + +If you use DHCP in this network during the provisioning, +nodes will try to obtain IP addresses automatically. +If you do not use DHCP, you must log in to the nodes +and assign available static IP addresses. + +**To assign node roles:**: + +#. Log in to the deployment node. +#. Assign node roles: + + :: + + utils/inventory-generator --nodes \ + node1[ansible_ssh_host=] \ + node2[ansible_ssh_host=] \ + node3[ansible_ssh_host=] + + The command generates the ``inventory.cfg`` file. + +#. Proceed to :ref:`configure-core-nodes`. + +.. _configure-core-nodes: + +Configure core nodes +~~~~~~~~~~~~~~~~~~~~ + +After you provision core nodes and assign roles, you must +configure a specific set of packages that you have previously +downloaded on your deployment node as described in +:ref:`prepare-deployment-node`. The ``inventory/inventory.cfg`` +file must be present on the deployment node. + +The task described in this section does not require an Internet +connection. + +**Configure core nodes:** + +#. Log in to the deployment node. +#. Deploy the configuration on all core nodes using the + ``ansible-playbook`` command: + + :: + + ansible-playbook -i inventory/inventory.cfg automation-runner.yml diff --git a/source/index.rst b/source/index.rst index 67a853a..931235b 100644 --- a/source/index.rst +++ b/source/index.rst @@ -1,22 +1,23 @@ DevOps Portal for OpenStack =========================== -Welcome to DevOps Portal's documentation. This documentation covers DevOps Portal and tools for managing cloud infrastructure. +Welcome to DevOps Portal's documentation. This documentation describes +the steps required to build a Mirantis OSS Tooling framework ISO image, +as well as how to deploy the image on physical or virtual nodes that +will run services required for managing cloud infrastructures at +customers site. Documentation also provides an architectural overview +of the Mirantis OSS Tooling framework required that is recommended for +better understanding of the project internals. -Contents: +Contents +======== + +------------------------------- .. toctree:: :maxdepth: 2 - docs/quickstart docs/architecture + docs/build-oss-image + docs/deploy-oss-tooling license - - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`search` -