diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..567609b --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1 @@ +build/ diff --git a/doc/source/appendix.rst b/doc/source/appendix.rst new file mode 100644 index 0000000..e1e5816 --- /dev/null +++ b/doc/source/appendix.rst @@ -0,0 +1,7 @@ +.. _user_appendix: + +Appendix +======== + +* The `Rally plugin `_ project at GitHub. +* The official `Rally documentation `_. diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..630497d --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,21 @@ +============================================================================ +Welcome to the Mirantis OpenStack Rally Plugin Documentation! +============================================================================ + +User documentation +================== + +.. toctree:: + :maxdepth: 2 + + overview + releases + installation + user + licenses + appendix + +Indices and Tables +================== + +* :ref:`search` diff --git a/doc/source/installation.rst b/doc/source/installation.rst new file mode 100644 index 0000000..f84ecb7 --- /dev/null +++ b/doc/source/installation.rst @@ -0,0 +1,79 @@ +.. _user_installation: + +Installation Guide +================== + +Rally Fuel Plugin install using the RPM file of the Fuel Plugins Catalog +--------------------------------------------------------------------------------------- + +To install the Rally Fuel Plugin using the RPM file of the Fuel Plugins +Catalog, you need to follow these steps: + +1. Download the RPM file from the `Fuel Plugins Catalog `_. + +2. Copy the RPM file to the Fuel Master node:: + + [root@home ~]# scp fuel-plugin-rally-0.1-0.1.0-1.noarch.rpm \ + root@: + +3. Install the plugin using the `Fuel CLI `_:: + + [root@fuel ~]# fuel plugins --install fuel-plugin-rally-0.1-0.1.0-1.noarch.rpm + +4. Verify that the plugin is installed correctly:: + + [root@fuel ~]# fuel plugins --list + id | name | version | package_version + ---|----------------------|---------|---------------- + 1 | fuel-plugin-rally | 0.1.0 | 3.0.0 + +Rally Fuel Plugin install from source +---------------------------------------------------- + +Alternatively, you may want to build the RPM file of the plugin from source +if, for example, you want to test the latest features, modify some built-in +configuration or implement your own customization. +But note that running a Fuel plugin that you have built yourself is at your own risk. + +To install Rally Plugin from source, you first need to prepare an +environment to build the RPM file. +The recommended approach is to build the RPM file directly onto the Fuel Master +node so that you won't have to copy that file later on. + +**Prepare an environment for building the plugin on the Fuel Master Node** + +1. Install the standard Linux development tools:: + + [root@home ~] yum install createrepo rpm rpm-build dpkg-devel + +2. Install the Fuel Plugin Builder. To do that, you should first get pip:: + + [root@home ~] easy_install pip + +3. Then install the Fuel Plugin Builder (the `fpb` command line) with `pip`:: + + [root@home ~] pip install fuel-plugin-builder + +**Note**: You may also need to build the Fuel Plugin Builder if the package version of the +plugin is higher than package version supported by the Fuel Plugin Builder you get from `pypi`. +In this case, please refer to the section "Preparing an environment for plugin development" +of the `Fuel Plugins wiki `_ +if you need further instructions about how to build the Fuel Plugin Builder. + +4. Clone the plugin git repository:: + + [root@home ~] git clone \ + git@github.com:openstack/fuel-plugin-rally.git + +5. Check that the plugin is valid:: + + [root@home ~] fpb --check ./fuel-plugin-rally + +6. And finally, build the plugin:: + + [root@home ~] fpb --build ./fuel-plugin-rally + +7. Now that you have created the RPM file, you can install the plugin using the `fuel plugins --install` command:: + + [root@fuel ~] fuel plugins --install \ + ./fuel-plugin-rally/*.noarch.rpm diff --git a/doc/source/licenses.rst b/doc/source/licenses.rst new file mode 100644 index 0000000..6cda6e2 --- /dev/null +++ b/doc/source/licenses.rst @@ -0,0 +1,15 @@ +.. _licenses: + +Licenses +======== + +Third Party Components +---------------------- + ++------------------------+-------------------------------------------------------------+------------+ +| Name | Project Web Site | License | ++========================+=============================================================+============+ +| Rally | https://wiki.openstack.org/wiki/Rally | Apache V2 | ++------------------------+-------------------------------------------------------------+------------+ +| Augeas | http://augeas.net/index.html | LGPL V2 | ++------------------------+-------------------------------------------------------------+------------+ \ No newline at end of file diff --git a/doc/source/overview.rst b/doc/source/overview.rst new file mode 100644 index 0000000..a687fa0 --- /dev/null +++ b/doc/source/overview.rst @@ -0,0 +1,26 @@ +.. _user_overview: + +Overview +======== + +The **Rally Fuel Plugin** is used to install and configure +Rally which automates and unifies multi-node OpenStack deployment, cloud verification, benchmarking & profiling. + +.. _plugin_requirements: + +Requirements +------------ + ++------------------------+------------------------------------------------------------------------------------------+ +| **Requirement** | **Version/Comment** | ++========================+==========================================================================================+ +| Disk space | At least 10GB | ++------------------------+------------------------------------------------------------------------------------------+ +| Fuel | Mirantis OpenStack 7.0 | ++------------------------+------------------------------------------------------------------------------------------+ + + +Limitations +----------- + +A current limitation of this plugin is that it uses system-wide installation only, which requires separate node without other roles, applied for this node. \ No newline at end of file diff --git a/doc/source/releases.rst b/doc/source/releases.rst new file mode 100644 index 0000000..e7c5d1a --- /dev/null +++ b/doc/source/releases.rst @@ -0,0 +1,9 @@ +.. _releases: + +Release Notes +============= + +Version 0.1.0 +------------- + +* Initial release of the plugin. This is a beta version. diff --git a/doc/source/user.rst b/doc/source/user.rst new file mode 100644 index 0000000..bd0e95f --- /dev/null +++ b/doc/source/user.rst @@ -0,0 +1,79 @@ +.. _user_guide: + +User Guide +========== + +.. _plugin_configuration: + +Plugin configuration +-------------------- + +To configure your plugin, you need to follow these steps: + +1. `Create a new environment `_ + with the Fuel web user interface. + +#. Click on the Settings tab of the Fuel web UI. + +#. Scroll down the page and select the Rally in the left column. + +4. Select the Rally Plugin checkbox and fill-in the required fields. + + a. If official repository is used - select master or tag version. + b. If developer repository is used - type valid repository url and proper tag version + +5. Assign the *Rally* role to a new node. + +6. `Configure your environment `_ + as needed. + +#. `Verify the networks `_ on the Networks tab of the Fuel web UI. + +#. `Deploy `_ your changes. + +.. _plugin_install_verification: + +Plugin verification +------------------- + +Be aware, that depending on the number of nodes and deployment setup, +deploying a Mirantis OpenStack environment can typically take anything +from 30 minutes to several hours. + +**Rally** + +Once your deployment has completed, you should verify that Rally is +installed properly by logging into Rally node and executing :: + + rally deployment check existing + +The expected output should look like something like this:: + + keystone endpoints are valid and following services are available: + +-------------+----------------+-----------+ + | services | type | status | + +-------------+----------------+-----------+ + | __unknown__ | artifact | Available | + | __unknown__ | computev3 | Available | + | __unknown__ | volumev2 | Available | + | __unknown__ | volumev3 | Available | + | cinder | volume | Available | + | cloud | cloudformation | Available | + | glance | image | Available | + | heat | orchestration | Available | + | keystone | identity | Available | + | neutron | network | Available | + | nova | compute | Available | + | s3 | s3 | Available | + | swift | object-store | Available | + +-------------+----------------+-----------+ + +**Note:** You can retrieve the IP address where Rally is installed using +the `fuel` command line:: + + [root@fuel ~]# fuel nodes + id | status | name | cluster | ip | mac | roles | pending_roles | online | group_id + ---|--------|------------|---------|-------------|-------------------|------------|---------------|--------|--------- + 9 | ready | rally | 2 | 10.109.10.5 | 2e:2d:42:5e:a0:54 | rally | | True | 2 + 8 | ready | compute | 2 | 10.109.10.7 | 64:3f:1a:41:a6:c4 | compute | | True | 2 + 7 | ready | controller | 2 | 10.109.10.6 | 62:04:8f:5a:69:f9 | controller | | True | 2 \ No newline at end of file diff --git a/specs/rally-plugin.rst b/specs/rally-plugin.rst new file mode 100644 index 0000000..3bd8f75 --- /dev/null +++ b/specs/rally-plugin.rst @@ -0,0 +1,114 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + +http://creativecommons.org/licenses/by/3.0/legalcode + +=============================================== +Fuel plugin to install Rally +=============================================== + +# blueprint link + +Rally is a benchmarking tool that answers the question: “How does OpenStack work at scale?”. To make this possible, Rally automates and unifies multi-node OpenStack deployment, cloud verification, benchmarking & profiling. + +Problem description +=================== + +A QA engineer needs to verfy OpenStack cloud state, benchmark and profile existing infrastracture with Rally + +Proposed change +=============== + +Rally plugin provides separate Fuel role for deploying Rally node in cluster with out-of-box ready for use Rally tool. + +Alternatives +------------ + +* Rally can be installed manually, but this requires: + + - configuration with proper networks + + - system dependency resolution + + - deployment configuration with proper credentials + + +Data model impact +----------------- + +None + +REST API impact +--------------- + +None + +Upgrade impact +-------------- + +None + +Security impact +--------------- + +None + +Notifications impact +-------------------- + +None + +Other end user impact +--------------------- + +None + +Performance Impact +------------------ + +None + +Other deployer impact +--------------------- + +Rally plugin requires separate node without any other roles + +Developer impact +---------------- + +None + +Implementation +============== + +Assignee(s) +----------- + +Volodymyr Stoiko (developer) +Sergey Kulikov (developer) + + +Work Items +---------- + +* Implement the Rally plugin. + +* Implement the Puppet manifests. + +* Testing. + +* Write the documentation. + +Dependencies +============ + +* Fuel 7.0 and higher. + +* It will be installed in an empty role. + + +References +========== + +.. [#] https://wiki.openstack.org/wiki/Rally