diff --git a/doc/Makefile b/doc/Makefile index edfccd7..6e99431 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -15,9 +15,9 @@ endif # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source # the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source .PHONY: help help: @@ -144,6 +144,9 @@ latexpdf: @echo "Running LaTeX files through pdflatex..." $(MAKE) -C $(BUILDDIR)/latex all-pdf @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + cp $(BUILDDIR)/latex/*.pdf . + mv test-plan.pdf TestPlanforSwiftStackFuelPlugin.pdf + mv test-report.pdf TestReportforSwiftStackFuelPlugin.pdf .PHONY: latexpdfja latexpdfja: diff --git a/doc/SwiftStackPluginforFuel.pdf b/doc/SwiftStackPluginforFuel.pdf new file mode 100644 index 0000000..92122da Binary files /dev/null and b/doc/SwiftStackPluginforFuel.pdf differ diff --git a/doc/TestPlanforSwiftStackFuelPlugin.pdf b/doc/TestPlanforSwiftStackFuelPlugin.pdf new file mode 100644 index 0000000..fca976b Binary files /dev/null and b/doc/TestPlanforSwiftStackFuelPlugin.pdf differ diff --git a/doc/TestReportforSwiftStackFuelPlugin.pdf b/doc/TestReportforSwiftStackFuelPlugin.pdf new file mode 100644 index 0000000..906b642 Binary files /dev/null and b/doc/TestReportforSwiftStackFuelPlugin.pdf differ diff --git a/doc/source/appendix.rst b/doc/source/appendix.rst new file mode 100644 index 0000000..47ecc62 --- /dev/null +++ b/doc/source/appendix.rst @@ -0,0 +1,10 @@ +Appendix +======== + +* SwiftStack Quick Start Guide: https://swiftstack.com/docs/install/index.html +* SwiftStack Admin Guide - Middleware: https://swiftstack.com/docs/admin/middleware.html +* SwiftStack Admin Guide - Keystone Auth Middleware: https://swiftstack.com/docs/admin/middleware/keystone_auth.html +* SwiftStack Admin Guide - Keystone Auth Token Middleware: https://swiftstack.com/docs/admin/middleware/keystone_auth_token.html +* SwiftStack Admin Guide - Swift S3 Emulation Layer Middleware: https://swiftstack.com/docs/admin/middleware/s3_middleware.html +* SwiftStack docs: https://swiftstack.com/docs/ + diff --git a/doc/conf.py b/doc/source/conf.py similarity index 95% rename from doc/conf.py rename to doc/source/conf.py index a32a705..5bb8543 100644 --- a/doc/conf.py +++ b/doc/source/conf.py @@ -13,7 +13,6 @@ # serve to show the default. import sys -import os import datetime # If extensions (or modules to document with autodoc) are in another directory, @@ -44,11 +43,14 @@ source_suffix = '.rst' # The master toctree document. master_doc = 'index' +plugin_guide = 'plugin-guide' +test_plan = 'test-plan' +test_report = 'test-report' # General information about the project. project = u'SwiftStack Plugin for Fuel 8.0' -copyright = u'2015–%s, SwiftStack' % datetime.date.today().year -author = u'Charles Hsu' +copyright = u'2015–%s, SwiftStack Inc.' % datetime.date.today().year +author = u'SwiftStack Inc.' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -232,7 +234,13 @@ latex_elements = { # author, documentclass [howto, manual, or own class]). latex_documents = [ (master_doc, 'SwiftStackPluginforFuel.tex', u'SwiftStack Plugin for Fuel Documentation', - u'SwiftStack Inc.', 'manual'), + author, 'manual'), + (plugin_guide, 'plugin-guide.tex', u'Guide for SwiftStack Fuel Plugin', + author, 'howto'), + (test_plan, 'test-plan.tex', u'Test Plan for SwiftStack Fuel Plugin', + author, 'howto'), + (test_report, 'test-report.tex', u'Test Report for SwiftStack Fuel Plugin', + author, 'howto'), ] # The name of an image file (relative to this directory) to place at the top of diff --git a/doc/images/1_add_nodes.png b/doc/source/images/1_add_nodes.png similarity index 100% rename from doc/images/1_add_nodes.png rename to doc/source/images/1_add_nodes.png diff --git a/doc/images/2_enable_plugin.png b/doc/source/images/2_enable_plugin.png similarity index 100% rename from doc/images/2_enable_plugin.png rename to doc/source/images/2_enable_plugin.png diff --git a/doc/images/3-1_proxy_outward-facing.png b/doc/source/images/3-1_proxy_outward-facing.png similarity index 100% rename from doc/images/3-1_proxy_outward-facing.png rename to doc/source/images/3-1_proxy_outward-facing.png diff --git a/doc/images/3-2_swift_api_ip.png b/doc/source/images/3-2_swift_api_ip.png similarity index 100% rename from doc/images/3-2_swift_api_ip.png rename to doc/source/images/3-2_swift_api_ip.png diff --git a/doc/images/3_config_network.png b/doc/source/images/3_config_network.png similarity index 100% rename from doc/images/3_config_network.png rename to doc/source/images/3_config_network.png diff --git a/doc/images/3_config_network_mgmt.png b/doc/source/images/3_config_network_mgmt.png similarity index 100% rename from doc/images/3_config_network_mgmt.png rename to doc/source/images/3_config_network_mgmt.png diff --git a/doc/images/3_config_network_storage.png b/doc/source/images/3_config_network_storage.png similarity index 100% rename from doc/images/3_config_network_storage.png rename to doc/source/images/3_config_network_storage.png diff --git a/doc/images/3_config_network_swift_cluster.png b/doc/source/images/3_config_network_swift_cluster.png similarity index 100% rename from doc/images/3_config_network_swift_cluster.png rename to doc/source/images/3_config_network_swift_cluster.png diff --git a/doc/images/4_config_interfaces.png b/doc/source/images/4_config_interfaces.png similarity index 100% rename from doc/images/4_config_interfaces.png rename to doc/source/images/4_config_interfaces.png diff --git a/doc/images/5_config_key1.png b/doc/source/images/5_config_key1.png similarity index 100% rename from doc/images/5_config_key1.png rename to doc/source/images/5_config_key1.png diff --git a/doc/images/6_config_key2.png b/doc/source/images/6_config_key2.png similarity index 100% rename from doc/images/6_config_key2.png rename to doc/source/images/6_config_key2.png diff --git a/doc/images/7_deploy_verify1.png b/doc/source/images/7_deploy_verify1.png similarity index 100% rename from doc/images/7_deploy_verify1.png rename to doc/source/images/7_deploy_verify1.png diff --git a/doc/source/images/enable_s3token.png b/doc/source/images/enable_s3token.png new file mode 100644 index 0000000..bb2e1f8 Binary files /dev/null and b/doc/source/images/enable_s3token.png differ diff --git a/doc/source/images/enable_swift3.png b/doc/source/images/enable_swift3.png new file mode 100644 index 0000000..42d35ce Binary files /dev/null and b/doc/source/images/enable_swift3.png differ diff --git a/doc/source/images/horizon_access.png b/doc/source/images/horizon_access.png new file mode 100644 index 0000000..9f57be1 Binary files /dev/null and b/doc/source/images/horizon_access.png differ diff --git a/doc/source/images/show_ec2.png b/doc/source/images/show_ec2.png new file mode 100644 index 0000000..bc55fb8 Binary files /dev/null and b/doc/source/images/show_ec2.png differ diff --git a/doc/images/use_on_prem.png b/doc/source/images/use_on_prem.png similarity index 100% rename from doc/images/use_on_prem.png rename to doc/source/images/use_on_prem.png diff --git a/doc/images/use_platform.png b/doc/source/images/use_platform.png similarity index 100% rename from doc/images/use_platform.png rename to doc/source/images/use_platform.png diff --git a/doc/index.rst b/doc/source/index.rst similarity index 93% rename from doc/index.rst rename to doc/source/index.rst index 3d3b23c..76edd31 100644 --- a/doc/index.rst +++ b/doc/source/index.rst @@ -9,3 +9,5 @@ Guide to the Swiftstack plugin for Fuel ver. 0.3.0.3.0-1 install user troubleshoot + appendix + diff --git a/doc/install.rst b/doc/source/install.rst similarity index 100% rename from doc/install.rst rename to doc/source/install.rst diff --git a/doc/overview.rst b/doc/source/overview.rst similarity index 100% rename from doc/overview.rst rename to doc/source/overview.rst diff --git a/doc/plugin-guide.rst b/doc/source/plugin-guide.rst similarity index 97% rename from doc/plugin-guide.rst rename to doc/source/plugin-guide.rst index 8a127a3..70f7b75 100644 --- a/doc/plugin-guide.rst +++ b/doc/source/plugin-guide.rst @@ -98,10 +98,5 @@ Known issues It is highly recommended to use certificates signed by a known, trusted Certificate -Appendix -======== - -#. SwiftStack docs can be found at https://swiftstack.com/docs/ - - +.. include:: appendix.rst diff --git a/doc/source/test-plan.rst b/doc/source/test-plan.rst new file mode 100644 index 0000000..9c4c5a2 --- /dev/null +++ b/doc/source/test-plan.rst @@ -0,0 +1,590 @@ +Test Plan for SwiftStack Fuel Plugin +==================================== + +Revision history +================ + +.. tabularcolumns:: |p{1.5cm}|p{2.5cm}|p{6cm}|p{5.6cm}| + +.. list-table:: + :header-rows: 1 + + * - Version + - Revision Date + - Editor + - Comment + * - 1.0 + - 27.08.2015 + - Charles Hsu(chsu@swiftstack.com) + - Created + * - 2.0 + - 06.07.2016 + - Charles Hsu(chsu@swiftstack.com) + - Revised for Fuel 8.0 + * - 2.1 + - 06.15.2016 + - Charles Hsu(chsu@swiftstack.com) + - Update contents and rewrite in RST + +SwiftStack Fuel Plugin +====================== + +Allow Mirantis OpenStack environment able to use an existing Swift cluster +managed by SwiftStack Controller. SwiftStack plugin will disable the swift +cluster deployed in the nodes are role **Controller** or **Primary-controller**. +And then reconfigures API endpoints, keystone and glance settings to point +an existing SwiftStack Swift cluster. + +Here are two basic Fuel OpenStack environments as follows: + +Use SwiftStack On-Premises Controller +------------------------------------- + +Please setup an On-Premises SwiftStack controller first, and then setup a single node Swift +cluster with SwiftStack controller, here is our `quick start guide`_. + + * 1 SwiftStack On-Premises controller + * 1 Swift cluster (single node) + +Also prepare a Fuel environment using Slave nodes according to the `Fuel Install Guide`_. + + .. note:: + In this diagram, the Swift cluster is also connected to Fuel Storage network for SwiftStack + cluster-facing and data replication network, if you have performance concern, please consider + to separate Swift cluster-facing and data replication network out of Fuel networks. + That prevents network starvation on Fuel Storage network when Swift service daemons are + moving data or clients upload large data into the Swift cluster. + + Also, SwiftStack Nodes need to communicate with the On-Premises controller over Fuel + Management network, so please make sure the On-Premises controller also connected to Fuel Management + network. You can run a CLI command ``ssdiag`` on SwiftStack nodes to check the connectivity + between SwiftStack Nodes and Controller. + + .. image:: images/use_on_prem.png + + + +Use SwiftStack Public Controller (Platform) +------------------------------------------- + +Please setup a single node Swift cluster with our public controller, here is our `quick start guide`_. + + * 1 Swift cluster (single node) + +Also prepare a Fuel environment using Slave nodes according to the `Fuel Install Guide`_. + + + .. note:: + In this diagram, the Swift cluster is also connected to Fuel Storage network for SwiftStack + cluster-facing and data replication network, if you have performance concern, please consider + to separate Swift cluster-facing and data replication network out of Fuel networks. + That prevents network starvation on Fuel Storage network when Swift service daemons are + moving data or clients upload large data into the Swift cluster. + + Also, SwiftStack Nodes need to communicate with SwiftStack Public controller over Fuel + Public network, so please make sure SwiftStack Nodes able to reach Internet. + + .. image:: images/use_platform.png + + +.. _quick start guide: https://swiftstack.com/docs/install/index.html +.. _Fuel Install Guide: http://docs.openstack.org/developer/fuel-docs/userdocs/fuel-install-guide.html + + +Developer’s specification +========================= + +See developers specification in this repository: https://github.com/openstack/fuel-plugin-swiftstack + +Limitations +=========== + +The plugin only supports a running SwiftStack Swift cluster and it able to reach +from the OpenStack environment. Make sure you have the correct network +configuration for the Swift cluster and Mirantis OpenStack environment before +you enable this plugin. + +Test strategy +============= + +Types of tests included +----------------------- + + * Check Swift API endpoints + * Basic Swift APIs operations + * System Tests + +Types of tests not included +--------------------------- + + * Swift cluster operations + +Acceptance criteria +------------------- + +These tests should be pass: + + * Check Swift API endpoints + * Basic Swift APIs operation + * System Tests + +Test environment and infrastructure +----------------------------------- + +Before install the plugin to your fuel environment, make sure you have a running +SwiftStack Swift cluster managed by SwiftStack Platform controller or On-Premises +controller. You’ll need to configure few middlewares from the controller and push +configuration to the SwiftStack cluster. + + * A running SwiftStack Swift cluster + +Product compatibility matrix +---------------------------- + +.. tabularcolumns:: |p{8cm}|p{7.6cm}| + +.. list-table:: + :header-rows: 1 + + * - Issue + - Version + * - Mirantis OpenStack + - 8.0 + +Check Swift API endpoints +========================= + + * Swift API endpoint should be like + http[s]://:[80|443]/v1/KEY_%(tenant_id)s + + * Disable TLS with Swift endpoint + + * http://:80/v1/KEY_%(tenant_id)s + + * Enable TLS with Swift endpoint + + * https://:443/v1/KEY_%(tenant_id)s + + + .. code-block:: bash + ### Login to Controller node + ~$ source ~/openrc + ~$ cat ~/openrc | grep OS_AUTH_URL + export OS_AUTH_URL='http://192.168.0.2:5000/' + + ## + ## Correct OS_AUTH_URL, append ‘v2.0’ in the end of line + ## + ~$ export OS_AUTH_URL='http://192.168.0.2:5000/v2.0' + + ~$ keystone endpoint-list |grep KEY + | b858f41ee3704f32a05060932492943b | RegionOne | + http://172.16.0.100:80/v1/KEY_%(tenant_id)s | + http://172.16.0.100:80/v1/KEY_%(tenant_id)s | + http://172.16.0.100:80/v1/KEY_%(tenant_id)s | + 19966ec76f0d455d94caa87d9569a347 | + + +Basic Swift APIs operation +========================== + +#. Verify Swift account with Keystone authentication. + + .. code-block:: bash + + # Login to one of nodes of Swift cluster. + + # Test admin account + root@node-23:~$ cat rc.admin + export ST_AUTH=http://192.168.0.2:5000/v2.0 + export ST_USER=admin:admin + export ST_KEY=admin + export ST_AUTH_VERSION=2 + + ~$ source rc.admin + + ~$ swift stat + Account: KEY_8408a5a799364d06b81542a8017e7975 + Containers: 0 + Objects: 0 + Bytes: 0 + X-Put-Timestamp: 1465289155.00899 + X-Timestamp: 1465289155.00899 + X-Trans-Id: tx1d35d328e5294c88baf5e-00575689c2 + Content-Type: text/plain; charset=utf-8 + + +#. Upload/download object and check md5sum + + .. code-block:: bash + + ~$ swift upload test rc.admin + rc.admin + + ~$ swift stat test rc.admin + Account: KEY_8408a5a799364d06b81542a8017e7975 + Container: test + Object: rc.admin + Content Type: application/octet-stream + Content Length: 117 + Last Modified: Tue, 07 Jun 2016 08:46:16 GMT + ETag: 4a97d36410af1b380fe5b014a6cd8db5 + Meta Mtime: 1465288847.821181 + Accept-Ranges: bytes + X-Timestamp: 1465289175.47789 + X-Trans-Id: tx13823ad38c084e529c20d-00575689de + + ~$ swift download test rc.admin -o rc.admin.download + rc.admin [auth 1.171s, headers 1.452s, total 1.460s, 0.000 MB/s] + + ~$ md5sum rc.admin* + 4a97d36410af1b380fe5b014a6cd8db5 rc.admin + 4a97d36410af1b380fe5b014a6cd8db5 rc.admin.download + +System testing +============== + +Install plugin and deploy environment +------------------------------------- + +.. tabularcolumns:: |p{3cm}|p{13cm}| + +.. list-table:: + :header-rows: 0 + + * - Test Case ID + - install_plugin_deploy_env + * - Steps + - + #. Copy the plugin to the Fuel Master node + #. Install the plugin. + #. Ensure that plugin is installed successfully with running + ``fuel plugins --list`` command in the Fuel CLI. + #. Create an environment with enabled plugin in the Fuel Web UI. + #. Add 3 nodes with Controller role and 1 node with Compute and Cinder role. + #. Finalize environment configuration (e.g. networking, nodes interfaces). + #. Run network verification check. + #. Deploy the cluster. + #. Run OSTF. + * - Expected Result + - + #. Plugin is installed successfully at the Fuel Master node and the + corresponding output appears in the CLI. + #. Cluster is created and network verification check is passed. + #. OSTF tests (Health Checks) are passed. + #. Environment is deployed successfully. + + +Install plugin and deploy environment with Swift API hostname +------------------------------------------------------------- + +.. tabularcolumns:: |p{3cm}|p{13cm}| + +.. list-table:: + :header-rows: 0 + + * - Test Case ID + - install_plugin_deploy_env_with_swift_hostname + * - Steps + - + #. Copy the plugin to the Fuel Master node + #. Install the plugin. + #. Ensure that plugin is installed successfully with running + ``fuel plugins --list`` command in the Fuel CLI. + #. Create an environment with enabled plugin in the Fuel Web UI. + #. Add 3 nodes with Controller role and 1 node with Compute and Cinder role. + #. Finalize environment configuration (e.g. networking, nodes interfaces). + #. Run network verification check. + #. Enabled Swift API hostname in the plugin section + #. Deploy the cluster. + #. Run OSTF. + * - Expected Result + - + #. Plugin is installed successfully at the Fuel Master node and the + corresponding output appears in the CLI. + #. Cluster is created and network verification check is passed. + #. OSTF tests (Health Checks) are passed. + #. Environment is deployed successfully. + + +Modifying env with enabled plugin (removing/adding controller nodes) +-------------------------------------------------------------------- + +.. tabularcolumns:: |p{3cm}|p{13cm}| + +.. list-table:: + :header-rows: 0 + + * - Test Case ID + - modify_env_with_plugin_remove_add_controller + * - Steps + - + #. Copy the plugin to the Fuel Master node + #. Install the plugin. + #. Ensure that plugin is installed successfully with running + ``fuel plugins --list`` command in the Fuel CLI. + #. Create an environment with enabled plugin in the Fuel Web UI. + #. Add 3 nodes with Controller role and 1 node with Compute and Cinder role. + #. Finalize environment configuration (e.g. networking, nodes interfaces). + #. Enable the plugin and configure it following the instructions + from the Plugin Guide. + #. Run network verification check. + #. Deploy the cluster. + #. Run OSTF. + #. Remove 1 node with Controller role + #. Re-deploy the cluster. + #. Run OSTF. + #. Add 1 new node with Controller role. + #. Re-deploy the cluster. + #. Run OSTF. + * - Expected Result + - + #. Plugin is installed successfully at the Fuel Master node and the + corresponding output appears in the CLI. + #. Cluster is created and network verification check is passed. + #. Plugin is enabled and configured in the Fuel Web UI. + #. OSTF tests (Health Checks) are passed. + #. Environment is deployed successfully. + #. When adding/removing Controller node (where plugin-related services are run): + + #. all plugins resources are migrated to another Controller node + #. the environment is redeployed successfully when adding/removing Controller node. + + + +Modifying env with enabled plugin (removing/adding compute node) +---------------------------------------------------------------- + +.. tabularcolumns:: |p{3cm}|p{13cm}| + +.. list-table:: + :header-rows: 0 + + * - Test Case ID + - modify_env_with_plugin_remove_add_compute + * - Steps + - + #. Copy the plugin to the Fuel Master node + #. Install the plugin. + #. Ensure that plugin is installed successfully with running + ``fuel plugins --list`` command in the Fuel CLI. + #. Create an environment with enabled plugin in the Fuel Web UI. + #. Add 3 nodes with Controller role and 1 node with Compute and Cinder role. + #. Finalize environment configuration + #. Enable the plugin and configure it following the instructions from the Plugin Guide. + #. Run network verification check. + #. Deploy the cluster. + #. Run OSTF. + #. Add 1 new node with Compute role. + #. Re-deploy the cluster. + #. Run OSTF. + #. Remove 1 node with Compute role + #. Re-deploy the cluster. + #. Run OSTF. + * - Expected Result + - + #. Plugin is installed successfully at the Fuel Master node and the + corresponding output appears in the CLI. + #. Cluster is created and network verification check is passed. + #. Plugin is enabled and configured in the Fuel Web UI. + #. OSTF tests (Health Checks) are passed. + #. Environment is deployed successfully. + #. When adding/removing Compute node (where plugin-related services are run): + + #. all plugins resources are migrated to another Compute node + #. the environment is re-deployed successfully when adding/removing Compute node + + + +Fuel create mirror and update (setup) of core repos +--------------------------------------------------- + +.. tabularcolumns:: |p{3cm}|p{13cm}| + +.. list-table:: + :header-rows: 0 + + * - Test Case ID + - Fuel_create_mirror_update_core_repos + * - Steps + - + #. Copy the plugin to the Fuel Master node + #. Install the plugin. + #. Ensure that plugin is installed successfully with running + ``fuel plugins --list`` command in the Fuel CLI. + #. Create an environment with enabled plugin in the Fuel Web UI. + #. Add 3 nodes with Controller role and 1 node with Compute and Cinder role. + #. Finalize environment configuration (e.g. networking, nodes interfaces). + #. Enable the plugin and configure it following the instructions from the Plugin Guide. + #. Run network verification check. + #. Deploy the cluster. + #. Run OSTF. + #. Go in cli through controller / compute / storage /etc nodes and get + pid of services which were launched by plugin and store them. + #. Launch the following command on the Fuel Master node: + + fuel-createmirror -M + + #. Launch the following command on the Fuel Master node: + + #. For MOS < 8.0: + + fuel --env node --node-id + --tasks upload_core_repos + + #. For MOS 8.0: + + fuel --env node --node-id + --tasks setup_repositories + #. Go to controller/plugin/storage node and check if plugin's services + are alive and aren't changed their pid. + #. Check with fuel nodes command that all nodes are remain in ready status. + #. Rerun OSTF. + + * - Expected Result + - + #. Plugin is installed successfully at the Fuel Master node and + the corresponding output appears in the CLI. + #. Cluster is created and network verification check is passed. + #. Plugin is enabled and configured in the Fuel Web UI. + #. OSTF tests (Health Checks) are passed. + #. Environment is deployed successfully. + #. Plugin's services shouldn't be restarted after corresponding + task was executed. If they are restarted as some exception, + this information should be added to plugin's User Guide. + #. Cluster (nodes) should remain in ready state. + #. OSTF test should be passed on rerun. + +Uninstall of plugin in the deployed environment +----------------------------------------------- + +.. tabularcolumns:: |p{3cm}|p{13cm}| + +.. list-table:: + :header-rows: 0 + + * - Test Case ID + - uninstall_plugin_with_deployed_env + * - Steps + - + #. Copy the plugin to the Fuel Master node + #. Install the plugin. + #. Ensure that plugin is installed successfully with running + ``fuel plugins --list`` command in the Fuel CLI. + #. Add 3 nodes with Controller role and 1 node with Compute and Cinder role. + #. Finalize environment configuration (e.g. networking, nodes interfaces). + #. Enable the plugin and configure it following the instructions from the Plugin Guide. + #. Run network verification check. + #. Deploy the cluster. + #. Run OSTF. + #. Uninstall the plugin with running + ``fuel plugins --remove == (e.g. 1.0.1)``` + + Ensure that the following output appears in CLI: + "400 Client Error: Bad Request (Can't delete plugin which is enabled for some environment.)" + + * - Expected Result + - + #. Plugin is installed successfully at the Fuel Master node and + the corresponding output appears in the CLI. + #. Cluster is created and network verification check is passed. + #. Plugin is enabled and configured in the Fuel Web UI. + #. OSTF tests (Health Checks) are passed. + #. Environment is deployed successfully. + #. Alert is displayed when trying the uninstall the plugin. + + +Uninstall of plugin in the non-deployed environment +--------------------------------------------------- + +.. tabularcolumns:: |p{3cm}|p{13cm}| + +.. list-table:: + :header-rows: 0 + + * - Test Case ID + - uninstall_plugin + * - Steps + - + #. Copy the plugin to the Fuel Master node + #. Install the plugin. + #. Ensure that plugin is installed successfully with running + ``fuel plugins --list`` command in the Fuel CLI. + #. Add 3 nodes with Controller role and 1 node with Compute and Cinder role. + #. Finalize environment configuration (e.g. networking, nodes interfaces). + #. Enable the plugin and configure it following the instructions from the Plugin Guide. + #. Run network verification check. + #. Delete listed environment + #. Uninstall the plugin with running + ``fuel plugins --remove == (e.g. 1.0.1)`` for more details. + #. Install the plugin. + * - Expected Result + - + #. Plugin is installed successfully at the Fuel Master node and + the corresponding output appears in the CLI. + #. Cluster is created and network verification check is passed. + #. Plugin is enabled and configured in the Fuel Web UI. + #. When uninstalling the plugin, no plugin-related elements are + left in the environment (e.g. UI elements disappear, Nailgun + database is restored to the default state, no output for + command ``fuel plugins --list``). + + +Apply maintenance updates to deployed environment +------------------------------------------------------------- +Mirantis OpenStack features the ability to receive patches via the common +flow called `Maintenance Updates`_. Please reach out to Partner Enablement team +about the latest Maintenance Updates portion to test against with you plugin. + +.. tabularcolumns:: |p{3cm}|p{13cm}| + +.. list-table:: + :header-rows: 0 + + * - Test Case ID + - apply_mu + * - Steps + - + #. Copy the plugin to the Fuel Master node + #. Install the plugin. + #. Ensure that plugin is installed successfully with running + ``fuel plugins --list`` command in the Fuel CLI. + #. Add 3 nodes with Controller role and 1 node with Compute and cinder role. + #. Finalize environment configuration (e.g. networking, nodes interfaces). + #. Enable the plugin and configure it following the instructions from the Plugin Guide. + #. Run network verification check. + #. Deploy the cluster. + #. Run OSTF. + #. Once environment is deployed, apply maintenance updates following the instructions. + #. Check is plugin services continue running. + #. Make sure all nodes are in ready state and no regression is observed. + #. Run OSTF checks. + + * - Expected Result + - + #. Plugin is installed successfully at the Fuel Master node and + the corresponding output appears in the CLI. + #. Cluster is created and network verification check is passed. + #. Plugin is enabled and configured in the Fuel Web UI. + #. OSTF tests (Health Checks) are passed. + #. Environment is deployed successfully. + #. Maintenance Updates do not affect running services related to the plugin + (e.g. the services aren't restarted). + #. Cluster remains in the fully operational state after applying Maintenance Updates. + +.. _Maintenance Updates: https://docs.mirantis.com/openstack/fuel/fuel-8.0/maintenance-updates.html#mu8-0-how-to-update + + +Appendix +======== + +.. tabularcolumns:: |p{1cm}|p{14cm}| + +.. list-table:: + :header-rows: 1 + + * - # + - Resource title + * - + - + diff --git a/doc/source/test-report.rst b/doc/source/test-report.rst new file mode 100644 index 0000000..2f5fb25 --- /dev/null +++ b/doc/source/test-report.rst @@ -0,0 +1,224 @@ +Test Report for SwiftStack Fuel Plugin +====================================== + +Revision history +================ + +.. tabularcolumns:: |p{1.5cm}|p{2.5cm}|p{6cm}|p{5.6cm}| + +.. list-table:: + :header-rows: 1 + + * - Version + - Revision Date + - Editor + - Comment + * - 1.0 + - 27.08.2015 + - Charles Hsu(chsu@swiftstack.com) + - Created + * - 2.0 + - 06.07.2016 + - Charles Hsu(chsu@swiftstack.com) + - Revised for Fuel 8.0 + * - 2.1 + - 06.15.2016 + - Charles Hsu(chsu@swiftstack.com) + - Update contents and rewrite in RST + * - + - + - + - + +Document purpose +================ + +This document provides test run results for Integration testing of SwiftStack +Fuel Plugin 0.3.0 on Mirantis OpenStack 8.0. + +Test environment +================ + +The following is the hardware configuration for target nodes used for +verification. For other configuration settings, please see the test plan. + + * Mirantis OpenStack: 8.0 + * Plugin release version: 0.3.0 + * Lab environment: + * 4 nodes (3 controllers and 1 compute nodes) or more + * 1 SwiftStack Swift cluster + +Plugin's RPM +------------ + +.. tabularcolumns:: |p{8cm}|p{7.6cm}| + +.. list-table:: + :header-rows: 1 + + + * - Name + - md5 checksum + * - swiftstack-0.3-0.3.0-1.noarch.rpm + - 7116620d039d9b93731aa38ababe48fa + + +Test coverage and metrics +------------------------- + + * Test Coverage – 100% + * Tests Passed – 100% + * Tests Failed – 0% + +Test results summary +==================== + +SwiftStack plugin is an integration plugin, so we run + +* System testing + + * Manuel Test (8) + + +Type of testing +=============== + +Coverage of features +-------------------- + +.. tabularcolumns:: |p{12cm}|p{3.6cm}| + +.. list-table:: + :header-rows: 1 + + * - Parameter + - Value + * - Total quantity of executed test cases + - 8 + * - Total quantity of not executed test cases + - 0 + * - Quantity of automated test cases + - 0 + * - Quantity of not automated test cases + - 8 + +Detailed test run results +------------------------- + +.. tabularcolumns:: |p{1cm}|p{7cm}|p{1.3cm}|p{1.3cm}|p{1.3cm}|p{3cm}| + +.. list-table:: + :header-rows: 1 + + * - # + - Test case ID + - Passed + - Failed + - Skipped + - Comment + * - 1 + - install_plugin_deploy_env + - yes + - + - + - + * - 2 + - install_plugin_deploy_env_with_swift_hostname + - yes + - + - + - + * - 3 + - modify_env_with_plugin_remove_add_controller + - yes + - + - + - + * - 4 + - modify_env_with_plugin_remove_add_compute + - yes + - + - + - + * - 5 + - Fuel_create_mirror_update_core_repos + - yes + - + - + - + * - 6 + - uninstall_plugin_with_deployed_env + - yes + - + - + - + * - 7 + - uninstall_plugin + - yes + - + - + - + * - 8 + - apply_mu + - yes + - + - + - + * - + - + - + - + - + - + * - Total + - + - 8 + - + - + - + * - Total, % + - + - 100% + - + - + - + +Known issues +============ + +.. list-table:: + :header-rows: 1 + + * - # + - Description + - Severity + - Status + * - + - + - + - + + +Logs +==== + +.. list-table:: + :header-rows: 1 + + * - # + - Title + * - + - + +Appendix +======== + +.. list-table:: + :header-rows: 1 + + * - # + - Title of resource + * - + - + + diff --git a/doc/troubleshoot.rst b/doc/source/troubleshoot.rst similarity index 63% rename from doc/troubleshoot.rst rename to doc/source/troubleshoot.rst index a8b0325..43452be 100644 --- a/doc/troubleshoot.rst +++ b/doc/source/troubleshoot.rst @@ -93,3 +93,56 @@ and :ref:`config Swift middlewares ` first. Once that're please :ref:`verify it with Swift CLI`. +403 Forbidden issue from clients through S3 APIs +------------------------------------------------ + +When you saw clients get 403 response from S3 APIs, please check **Swift3 Keystone Integration Middleware** +first and make sure auth_url is point to keystone amdinurl. + + .. code-block:: bash + + ~$ ./s3get.sh test http://172.16.0.100:80 \ + > e8f3617f41d34d02a7ba129f8581a3b6 \ + > 85f2ae90a9614a8b832747af3c6e6c9b \ + > test rc.admin + Wed, 15 Jun 2016 14:15:14 UTC + /test/rc.admin + * Hostname was NOT found in DNS cache + * Trying 172.16.0.100... + * Connected to 172.16.0.100 (172.16.0.100) port 80 (#0) + > GET /test/rc.admin HTTP/1.1 + > User-Agent: curl/7.35.0 + > Host: 172.16.0.100 + > Accept: */* + > Date: Wed, 15 Jun 2016 14:15:14 UTC + > Authorization: AWS e8f3617f41d34d02a7ba129f8581a3b6:RG6hF77QUN/fmMMLSFP5SauMD7Q= + > + < HTTP/1.1 403 Forbidden + HTTP/1.1 403 Forbidden + < x-amz-id-2: tx6359093a27f642db8a398-00576162f3 + x-amz-id-2: tx6359093a27f642db8a398-00576162f3 + < x-amz-request-id: tx6359093a27f642db8a398-00576162f3 + x-amz-request-id: tx6359093a27f642db8a398-00576162f3 + < Content-Type: application/xml + Content-Type: application/xml + < X-Trans-Id: tx6359093a27f642db8a398-00576162f3 + X-Trans-Id: tx6359093a27f642db8a398-00576162f3 + < Date: Wed, 15 Jun 2016 14:15:15 GMT + Date: Wed, 15 Jun 2016 14:15:15 GMT + < Transfer-Encoding: chunked + Transfer-Encoding: chunked + +And if that is still can't solve the problem or you see other error codes +(500 Internal server error, etc.) from S3 APIs, please try to check the +swift logs (/var/log/swift/all.log) to see is any exception on that. And you +will have a ``X-Trams-Id`` for each request, so please use that to grep Swift +logs likes, + + .. code-block:: bash + + # Please login to SwiftStack Nodes + $ grep tx6359093a27f642db8a398-00576162f3 /var/log/swift/all.log + +And send the output to `SwiftStack Support`_. + +.. _SwiftStack Support: https://swiftstack.zendesk.com/ diff --git a/doc/user.rst b/doc/source/user.rst similarity index 74% rename from doc/user.rst rename to doc/source/user.rst index 596131f..c4f3a4d 100644 --- a/doc/user.rst +++ b/doc/source/user.rst @@ -292,6 +292,7 @@ Deploying Mirantis OpenStack with a SwiftStack Swift cluster echo "----------------------------------------------------------------------------" echo " identity_url : http://$SwiftIP:5000/" echo " auth_url : http://$SwiftIP:5000/" + echo " auth_url (for s3) : http://$SwiftIP:35357/" echo " admin_user : swift" echo " admin_password : $SwiftPW" @@ -313,6 +314,7 @@ Deploying Mirantis OpenStack with a SwiftStack Swift cluster ---------------------------------------------------------------------------- identity_url : http://192.168.0.2:5000/ auth_url : http://192.168.0.2:5000/ + auth_url (for s3) : http://192.168.0.2:35357/ admin_user : swift admin_password : v4LiGbh6xPU0vtqXQSMeDjxc @@ -343,9 +345,39 @@ Deploying Mirantis OpenStack with a SwiftStack Swift cluster .. image:: images/6_config_key2.png +#. If you want to your Swift cluster supports S3 APIs, please also enabled + `Swift S3 Emulation Layer Middleware`_ and **Swift3 Keystone Integration Middleware** + + #. Enable Swift S3 Emulation Layer Middleware, select ``Enabled`` checkbox and submit it + + .. image:: images/enable_swift3.png + + + #. Enable Swift3 Keystone Integration Middleware, select ``Enabled`` checkbox + and fill **http://192.168.0.2:35357/** to ``auth_url`` and then submit it + + .. code-block:: bash + + auth_url (for s3): http://192.168.0.2:35357/ + + .. image:: images/enable_s3token.png + + +.. _Swift S3 Emulation Layer Middleware: https://swiftstack.com/docs/admin/middleware/s3_middleware.html + #. Push configure settings to SwiftStack Swift cluster. +#. Netwerk verification check + Please check Fuel network configuration and SwiftStack settings before you deploy + the OpenStack environment: + + #. SwiftStack Nodes should able to reach Keystone endpoint (internalURL) + on Management network. + #. Clients should able to reach SwiftStack Nodes over Public network. + #. All IPs of SwiftStack Nodes (includes Load Balancer) should be skip in Fuel networks. + #. If you use VLAN, please check VLAN settings on each node + #. Get back to the Fuel Web UI and deploy your OpenStack environment. #. Once Mirantis OpenStack environment is done, you will see the SwiftStack plugin is also deployed. @@ -353,34 +385,39 @@ Deploying Mirantis OpenStack with a SwiftStack Swift cluster .. image:: images/7_deploy_verify1.png Verification -++++++++++++ +------------ Please run the verification steps below to ensure your SwiftStack plugin is configured properly: -#. Check API endpoints with Keystone CLI: +Check API endpoints with Keystone CLI: +++++++++++++++++++++++++++++++++++++++ .. code-block:: bash - root@node-23:~# source ~/openrc + ### Login to Controller node + ~$ source ~/openrc + ~$ cat ~/openrc | grep OS_AUTH_URL + export OS_AUTH_URL='http://192.168.0.2:5000/' ## - ## Make sure the keystone VIP is correct + ## Correct OS_AUTH_URL, append ‘v2.0’ in the end of line ## - root@node-23:~# export OS_AUTH_URL='http://192.168.0.2:5000/v2.0' + ~$ export OS_AUTH_URL='http://192.168.0.2:5000/v2.0' - root@node-23:~# keystone endpoint-list |grep KEY - | b858f41ee3704f32a05060932492943b | RegionOne - | http://172.16.0.100:80/v1/KEY_%(tenant_id)s - | http://172.16.0.100:80/v1/KEY_%(tenant_id)s - | http://172.16.0.100:80/v1/KEY_%(tenant_id)s - | 19966ec76f0d455d94caa87d9569a347 | + ~$ keystone endpoint-list |grep KEY + | b858f41ee3704f32a05060932492943b | RegionOne | + http://172.16.0.100:80/v1/KEY_%(tenant_id)s | + http://172.16.0.100:80/v1/KEY_%(tenant_id)s | + http://172.16.0.100:80/v1/KEY_%(tenant_id)s | + 19966ec76f0d455d94caa87d9569a347 | .. _verity_cluster_swift_cli: -#. Verify Swift cluster, Keystone and Glance integration through Swift cli +Verify Swift cluster, Keystone and Glance integration through Swift cli ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - * Check admin account + Check admin account .. code-block:: bash @@ -410,7 +447,7 @@ Please run the verification steps below to ensure your SwiftStack plugin is conf X-Trans-Id: txf07064e2471544b29f84d-0057579086 Content-Type: text/plain; charset=utf-8 - * Check glance account when **Use Swift as Glance backend** is enabled + Check glance account when **Use Swift as Glance backend** is enabled .. code-block:: bash @@ -454,9 +491,124 @@ Please run the verification steps below to ensure your SwiftStack plugin is conf Content-Type: text/plain; charset=utf-8 -Appendix --------- - * SwiftStack docs can be found at https://swiftstack.com/docs/ +Verify S3 APIs, Swift cluster and Keystone +++++++++++++++++++++++++++++++++++++++++++ + + Find EC2 access key and secret key from Horizon + + .. image:: images/horizon_access.png + + When you click ``View Credentials``, it shows a diaglog for EC2 keys + in below, + + .. image:: images/show_ec2.png + + Or you can use keystone CLI to get EC2 keys. + + .. code-block:: bash + + ~$ keystone ec2-credentials-list + +--------+----------------------------------+----------------------------------+ + | tenant | access | secret | + +--------+----------------------------------+----------------------------------+ + | admin | e8f3617f41d34d02a7ba129f8581a3b6 | 85f2ae90a9614a8b832747af3c6e6c9b | + +--------+----------------------------------+----------------------------------+ + + + Upload single file to a container + + .. code-block:: bash + + ~$ swift upload test rc.admin + ~$ swift stat test rc.admin + Account: KEY_5f88ea5c603f4c3bb091aac02001b318 + Container: test + Object: rc.admin + Content Type: application/octet-stream + Content Length: 115 + Last Modified: Wed, 15 Jun 2016 12:48:44 GMT + ETag: ed6eb254c7a7ba2cba19728f3fff5645 + Meta Mtime: 1465994722.799261 + Accept-Ranges: bytes + X-Timestamp: 1465994923.49250 + X-Trans-Id: tx3dd9b89f2ebc4579857b7-005761743f + + + Please create a script file called s3get.sh and add contents in below, + + .. code-block:: bash + + #!/bin/bash + + url=$1 + s3key=$2 + s3secret=$3 + bucket=$4 + file=$5 + + # Path style + resource="/${bucket}/${file}" + fullpath="${url}/${bucket}/${file}" + + dateValue=`date -u +%a,\ %d\ %h\ %Y\ %T\ %Z` + + echo ${dateValue} + echo ${resource} + + stringToSign="GET\n\n\n${dateValue}\n${resource}" + signature=`echo -en ${stringToSign}|openssl sha1 -hmac ${s3secret} -binary|base64` + curl -I -v -X GET \ + -H "Date: ${dateValue}" \ + -H "Authorization: AWS ${s3key}:${signature}" \ + ${fullpath} + + Try to retrieve the object (container: test, object: rc.admin) through S3 APIs. + + .. code-block:: bash + + ~$ ./s3get.sh http://172.16.0.100:80 \ + > e8f3617f41d34d02a7ba129f8581a3b6 \ + > 85f2ae90a9614a8b832747af3c6e6c9b \ + > test rc.admin + Wed, 15 Jun 2016 15:25:51 UTC + /test/rc.admin + * Hostname was NOT found in DNS cache + * Trying 172.16.0.100... + * Connected to 172.16.0.100 (172.16.0.100) port 80 (#0) + > GET /test/rc.admin HTTP/1.1 + > User-Agent: curl/7.35.0 + > Host: 172.16.0.100 + > Accept: */* + > Date: Wed, 15 Jun 2016 15:25:51 UTC + > Authorization: AWS e8f3617f41d34d02a7ba129f8581a3b6:tHnRZjiCzPzeJhs8SAQ8msBWH3Y= + > + < HTTP/1.1 200 OK + HTTP/1.1 200 OK + < Content-Length: 115 + Content-Length: 115 + < x-amz-id-2: tx43598dcd71274707a7adc-0057617380 + x-amz-id-2: tx43598dcd71274707a7adc-0057617380 + < x-amz-meta-mtime: 1465994722.799261 + x-amz-meta-mtime: 1465994722.799261 + < Last-Modified: Wed, 15 Jun 2016 12:48:44 GMT + Last-Modified: Wed, 15 Jun 2016 12:48:44 GMT + < ETag: "ed6eb254c7a7ba2cba19728f3fff5645" + ETag: "ed6eb254c7a7ba2cba19728f3fff5645" + < x-amz-request-id: tx43598dcd71274707a7adc-0057617380 + x-amz-request-id: tx43598dcd71274707a7adc-0057617380 + < Content-Type: application/octet-stream + Content-Type: application/octet-stream + < X-Trans-Id: tx43598dcd71274707a7adc-0057617380 + X-Trans-Id: tx43598dcd71274707a7adc-0057617380 + < Date: Wed, 15 Jun 2016 15:25:52 GMT + Date: Wed, 15 Jun 2016 15:25:52 GMT + + < + * Excess found in a non pipelined read: excess = 115 url = /test/rc.admin + (zero-length body) + * Connection #0 to host 172.16.0.100 left intact + +