diff --git a/.gitignore b/.gitignore index 00efc26..969d0c6 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ .build/ calico-fuel-plugin-*.rpm +/doc/build diff --git a/doc/.gitkeep b/doc/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..36879ad --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,177 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/fuel-plugin-openbook.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/fuel-plugin-openbook.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/fuel-plugin-openbook" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/fuel-plugin-openbook" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/doc/source/TestPlanforCalicoFuelPlugin.rst b/doc/source/TestPlanforCalicoFuelPlugin.rst new file mode 100644 index 0000000..cf1c273 --- /dev/null +++ b/doc/source/TestPlanforCalicoFuelPlugin.rst @@ -0,0 +1,495 @@ +==================================================== +Test Plan for the Calico Fuel Plugin ver 2.0-2.0.2-1 +==================================================== + +Calico Plugin +============= + +Calico presents a new approach to virtual networking, based on the same +scalable IP networking principles as the Internet. It targets data centers +where most of the workloads (VMs, containers or bare metal servers) only +require IP connectivity, and provides that using standard IP routing. Isolation +between workloads - whether according to tenant ownership, or any finer grained +policy - is achieved by iptables programming at the servers hosting the source +and destination workloads. + +Developer's specification +========================= + +Is available on `GitHub`_. + +.. _GitHub: https://github.com/stackforge/fuel-plugin-calico/blob/master/specs/calico-fuel-plugin.rst + +Test strategy +============= + +At present, all plugin-specific tests are manual, and are concerned with +establishing basic Calico function. The Calico project has a large number of +manual and automated tests which cover its function, security and performance - +this test plan does not replicate those tests. + +Acceptance criteria +------------------- + +All tests should pass. + +Test environment, infrastructure and tools +------------------------------------------ + +All tests run in a single environment. This is a Mirantis OpenStack cluster +with a Fuel master node, one controller node, and two or more compute nodes. +The cluster should be deployed with the Calico plugin enabled, as follows: + +#. Create a new OpenStack environment, selecting: + + - Kilo on Ubuntu Trusty + + - "Neutron with VLAN segmentation" as the networking setup. + +#. Under the Settings tab, make sure the following options are checked: + + - "Assign public network to all nodes" + + - "Use Calico Virtual Networking" + +#. Under the Network tab, configure the 'Public' settings (leaving all of the + other sections with their default values): + + - IP Range: 172.18.203.60 - 172.18.203.69 + + - CIDR: 172.18.203.0/24 + + - Use VLAN tagging: No + + - Gateway: 172.18.203.1 + + - Floating IP range: 172.18.203.70 - 172.18.203.79 + +#. Add one controller and two compute nodes. + +#. Deploy changes. + +Once the cluster has deployed, go to Project->Network->Networks in the +OpenStack web UI and create a network and subnet from which instance IP +addresses will be allocated. Use the following settings: + +- Name: demo +- IP subnet: 10.65.0.0/24 +- Gateway: 10.65.0.1 +- DHCP-enabled: Yes + +Also in the OpenStack web UI, under Project->Compute->Access&Security, create +two new security groups named 'sg1' and 'sg2', both with description +'test'. For each security group, select 'Manage Rules' and add two new rules +using the following settings: + +- First Rule: + + - Rule: ALL ICMP + - Direction: Ingress + - Remote: Security Group + - Security Group: + - Ether Type: IPv4 + +- Second Rule: + + - Rule: SSH + - Remote: CIDR + - CIDR: 0.0.0.0/0 + +Product compatibility matrix +---------------------------- + +The plugin is compatible with MOS 7.0. This test plan is executed against MOS +7.0 GA plus mu-3. + +Type of testing +=============== + +As above, this test plan is concerned with establishing that Calico networking +has been successfully deployed. Security, performance, and detailed functional +testing are covered by the main Project Calico test plan. + +Build Plugin +------------ + ++------------------+------------------------------------------------------------------+ +| Test Case ID | build_plugin | ++------------------+------------------------------------------------------------------+ +| Description | Verify that the plugin builds successfully. | ++------------------+------------------------------------------------------------------+ +| Steps | 1. git clone https://github.com/openstack/fuel-plugin-calico.git | +| | 2. pushd fuel-plugin-calico; git checkout 7.0; popd | +| | 3. fpb --build fuel-plugin-calico | ++------------------+------------------------------------------------------------------+ +| Expected Result | Outputs the message 'Plugin is built' and the | +| | calico-fuel-plugin-2.0-2.0.2-1.noarch.rpm package is created in | +| | the fuel-plugin-calico directory. | ++------------------+------------------------------------------------------------------+ + +Install Plugin +-------------- + ++------------------+------------------------------------------------------------------+ +| Test Case ID | install_plugin | ++------------------+------------------------------------------------------------------+ +| Description | Verify that the plugin installs successfully. | ++------------------+------------------------------------------------------------------+ +| Steps | 1. Copy the plugin package into /tmp on the Fuel Master Node. | +| | 2. SSH onto the Fuel Master Node. | +| | 3. fuel plugins --install \ | +| | /tmp/calico-fuel-plugin-2.0-2.0.2-1.noarch.rpm | +| | 4. fuel plugins --list | ++------------------+------------------------------------------------------------------+ +| Expected Result | Output from step 4 should be:: | +| | | +| | id | name | version | package_version | +| | ---|--------------------|---------|---------------- | +| | 1 | calico-fuel-plugin | 2.0.2 | 3.0.0 | ++------------------+------------------------------------------------------------------+ + +Verify Calico option in Fuel web UI +----------------------------------- + ++------------------+------------------------------------------------------------------+ +| Test Case ID | verify_calico_in_fuel_web_ui | ++------------------+------------------------------------------------------------------+ +| Description | Verify that the Calico plugin appears in the Fuel UI. | ++------------------+------------------------------------------------------------------+ +| Steps | 1. Create a new OpenStack environment in the Fuel web UI. | +| | 2. Navigate to the Settings tab. | ++------------------+------------------------------------------------------------------+ +| Expected Result | There should be a tick box labelled 'Use Calico Virtual | +| | Networking'. | ++------------------+------------------------------------------------------------------+ + +Deploy OpenStack with Calico +---------------------------- + ++------------------+------------------------------------------------------------------+ +| Test Case ID | deploy_openstack_with_calico | ++------------------+------------------------------------------------------------------+ +| Description | Verify that an OpenStack environment can be successfully | +| | deployed with the Calico plugin enabled. | ++------------------+------------------------------------------------------------------+ +| Steps | 1. Create a new OpenStack environment in the Fuel web UI and | +| | configure/deploy as per the instructions in the 'Test | +| | environment, infrastructure and tools' section of this test | +| | plan. | ++------------------+------------------------------------------------------------------+ +| Expected Result | 'Success' message is displayed in the Fuel web UI. Followed by: | +| | 'Deployment of environment 'test' is done. Access the OpenStack | +| | dashboard (Horizon) at ...' | ++------------------+------------------------------------------------------------------+ + +Verify BGP Sessions +------------------- + ++------------------+------------------------------------------------------------------+ +| Test Case ID | verify_bgp_sessions | ++------------------+------------------------------------------------------------------+ +| Description | Verify that there is a BGP route reflector running on the | +| | controller node, and that it has established peer connections to | +| | the compute nodes. | ++------------------+------------------------------------------------------------------+ +| Steps | 1. SSH onto the controller node from the Fuel master node. | +| | 2. Enter the command 'birdc', followed by 'show protocols all'. | +| | 3. Check the output details show two established BGP sessions - | +| | one to each compute node. | ++------------------+------------------------------------------------------------------+ +| Expected Result | There is a running route reflector on the controller node, with | +| | established BGP peer connections to the two compute nodes. | ++------------------+------------------------------------------------------------------+ + +Create VMs +---------- + ++------------------+------------------------------------------------------------------+ +| Test Case ID | create_vms | ++------------------+------------------------------------------------------------------+ +| Description | Verify that Calico does not interfere with the creation of new | +| | VMs. | ++------------------+------------------------------------------------------------------+ +| Steps | 1. In the OpenStack web UI, go to Project->Instances. | +| | 2. Launch a batch of 6 VMs with the following details. | +| | | +| | - Flavor: m1.tiny | +| | | +| | - Boot from image: TestVM | +| | | +| | - Under the Networking tab, drag 'demo' into the 'Selected | +| | Networks' box. | +| | | +| | - Under the Access & Security tab, select either 'sg1' or | +| | 'sg2' as the security group, such that roughly half of the | +| | VMs are in each security group. | +| | | +| | 3. Under Admin->Instances, verify that: | +| | | +| | - the requested 6 VMs (aka instances) have been launched | +| | | +| | - they are distributed roughly evenly across the two compute | +| | hosts | +| | | +| | - they have each been assigned an IP address from the range | +| | that you configured above (e.g. 10.65.0/24) | +| | | +| | - they reach Active status within about a minute. | ++------------------+------------------------------------------------------------------+ +| Expected Result | The VMs are correctly distributed, and activate in a reasonable | +| | time. | ++------------------+------------------------------------------------------------------+ + +Test connectivity +----------------- + ++------------------+------------------------------------------------------------------+ +| Test Case ID | test_connectivity | ++------------------+------------------------------------------------------------------+ +| Description | Verify that Calico has configured the network routing to allow | +| | communication between the VMs. | ++------------------+------------------------------------------------------------------+ +| Steps | 1. Log on to one of the VMs, for example using SSH from that | +| | VM's compute host. | +| | 2. Use 'ping' to verify connectivity to the IP address of each | +| | of the other VMs in the same security group. | ++------------------+------------------------------------------------------------------+ +| Expected Result | Ping responses are received from all the VMs in the same | +| | security group. | ++------------------+------------------------------------------------------------------+ + +Test security +------------- + ++------------------+------------------------------------------------------------------+ +| Test Case ID | test_security | ++------------------+------------------------------------------------------------------+ +| Description | Verify that Calico correctly enforces the configured security | +| | rules. | ++------------------+------------------------------------------------------------------+ +| Steps | 1. Log on to one of the VMs, for example using SSH from that | +| | VM's compute host. | +| | 2. Use 'ping' to verify lack of connectivity to the IP address | +| | of each of the VMs in the other security group. | ++------------------+------------------------------------------------------------------+ +| Expected Result | Ping responses are not received from any of the VMs in the other | +| | security group. | ++------------------+------------------------------------------------------------------+ + +Test Initial Route Reflector Configuration +------------------------------------------ + ++------------------+------------------------------------------------------------------+ +| Test Case ID | test_initial_rr_config | ++------------------+------------------------------------------------------------------+ +| Description | Verify that BIRD's BGP peer configuration is correct. | ++------------------+------------------------------------------------------------------+ +| Steps | 1. Deploy an environment with 1 controller, 1 compute node and | +| | one storage node. | +| | 2. Verify that the BIRD instance on the controller is configured | +| | with only one peer (the compute node). | ++------------------+------------------------------------------------------------------+ +| Expected Result | BGP peer configuration is created only for compute nodes. | ++------------------+------------------------------------------------------------------+ + +Test Route Reflector Configuration Changes +------------------------------------------ + ++------------------+------------------------------------------------------------------+ +| Test Case ID | test_rr_config_changes | ++------------------+------------------------------------------------------------------+ +| Description | Verify that BIRD's BGP peer configuration is updated correctly | +| | after a change to the deployment. | ++------------------+------------------------------------------------------------------+ +| Steps | 1. Deploy an environment with 1 controller and 1 compute node. | +| | 2. Verify that the BIRD instance on the controller is configured | +| | with only one peer (the compute node). | +| | 3. Add a compute node and re-deploy. | +| | 4. Verify that the BIRD instance on the controller is now | +| | configured with two peers (both compute nodes). | +| | 5. Delete both compute nodes and re-deploy. | +| | 6. Add a storage node and re-deploy. | +| | 7. Verify that the BIRD instance on the controller is now | +| | configured with no peers. | ++------------------+------------------------------------------------------------------+ +| Expected Result | New BGP peer configuration is added to the BIRD instance on the | +| | controller when a compute node is added to the deployment. | ++------------------+------------------------------------------------------------------+ + +External connectivity +--------------------- + ++------------------+------------------------------------------------------------------+ +| Test Case ID | test_external_connectivity | ++------------------+------------------------------------------------------------------+ +| Description | Verify that a VM can connect to an address outside the cluster. | ++------------------+------------------------------------------------------------------+ +| Steps | 1. Create a VM, as in the 'Create VMs' test above. | +| | 2. SSH to that VM's compute host. | +| | 3. Execute the following to allow the compute host to do NAT | +| | for traffic from local VMs to the outside world:: | +| | | +| | iptables -t nat -A POSTROUTING -s 10.65.0/24 \ | +| | ! -d 10.65.0/24 -o br-ex -j MASQUERADE | +| | | +| | (If you configured an IP subnet other than 10.65.0/24 for | +| | your VMs, use that subnet here instead of '10.65.0/24'.) | +| | | +| | 4. Log on to the VM, using SSH from the compute host. | +| | 5. Run 'ping 8.8.8.8'. | ++------------------+------------------------------------------------------------------+ +| Expected Result | The VM gets ping responses from 8.8.8.8. | +| | | +| | Note that in a full Calico deployment, NAT like this would be | +| | configured on the border gateways between the data center and | +| | the outside world, instead of on each compute host. Hence the | +| | Calico agent does not automatically configure iptables rules | +| | like the one used here on each compute host. For the purposes | +| | of testing in a small Fuel cluster, however, programming the NAT | +| | directly on the compute host demonstrates the principle of how | +| | Calico external connectivity works. | ++------------------+------------------------------------------------------------------+ + +Mandatory Tests +=============== + +Install plugin and deploy environment +------------------------------------- + +Covered above. + +Modifying env with enabled plugin (removing/adding controller nodes) +-------------------------------------------------------------------- + ++------------------+------------------------------------------------------------------+ +| Test Case ID | modify_env_with_plugin_remove_add_controller | ++------------------+------------------------------------------------------------------+ +| Steps | 1. Install the Calico plugin on the Fuel master node. | +| | 2. Using the Fuel UI, create an environment with the Calico | +| | plugin enabled, editing the network and settings | +| | configuration as above. | +| | 3. Add 1 controller and 2 compute nodes. | +| | 4. Deploy the cluster. | +| | 5. Run the 'Create VMs', 'Test connectivity' and 'Test security' | +| | tests above - all should pass. | +| | 6. Add a second controller, and re-deploy the cluster. | +| | 7. Create another VM in each security group (sg1 and sg2). | +| | 8. Run the 'Test connectivity' and 'Test security' tests again - | +| | all should pass. | +| | 9. Delete the original controller, and re-deploy the cluster. | +| | 10. Add a new controller, and re-deploy the cluster. | +| | 11. Create another VM in each security group (sg1 and sg2). | +| | 12. Run the 'Test connectivity' and 'Test security' tests again | +| | - all should pass. | ++------------------+------------------------------------------------------------------+ +| Expected Result | The Calico plugin is installed successfully, the cluster is | +| | created, and all plugin services are enabled and working as | +| | expected after modifying the environment. | ++------------------+------------------------------------------------------------------+ + +Modifying env with enabled plugin (removing/adding compute nodes) +----------------------------------------------------------------- + ++------------------+------------------------------------------------------------------+ +| Test Case ID | modify_env_with_plugin_remove_add_compute | ++------------------+------------------------------------------------------------------+ +| Steps | 1. Install the Calico plugin on the Fuel master node. | +| | 2. Using the Fuel UI, create an environment with the Calico | +| | plugin enabled, editing the network and settings | +| | configuration as above. | +| | 3. Add 1 controller and 2 compute nodes. | +| | 4. Deploy the cluster. | +| | 5. Run the 'Create VMs', 'Test connectivity' and 'Test security' | +| | tests above - all should pass. | +| | 6. Terminate the created VM instances. | +| | 7. Remove 1 compute node. | +| | 8. Re-deploy the cluster. | +| | 9. Run the 'Create VMs', 'Test connectivity' and 'Test security' | +| | tests above - all should pass. (Note all VMs will be | +| | created on the same compute node, as there is now only one.) | +| | 10. Terminate the created VM instances. | +| | 11. Add 1 compute node. | +| | 12. Re-deploy the cluster. | +| | 13. Run the 'Create VMs', 'Test connectivity' and 'Test | +| | security' tests above - all should pass. | ++------------------+------------------------------------------------------------------+ +| Expected Result | The Calico plugin is installed successfully, the cluster is | +| | created, and all plugin services are enabled and working as | +| | expected after modifying the environment. | ++------------------+------------------------------------------------------------------+ + + +Uninstall of plugin with deployed environment +--------------------------------------------- + ++------------------+------------------------------------------------------------------+ +| Test Case ID | uninstall_plugin_with_deployed_env | ++------------------+------------------------------------------------------------------+ +| Steps | 1. Install the Calico plugin. | +| | 2. As above, deploy an environment with the Calico plugin | +| | enabled. | +| | 3. Run the 'Create VMs', 'Test connectivity' and 'Test security' | +| | tests above - all should pass. | +| | 4. Try to remove the Calico plugin: | +| | fuel plugins --remove calico-fuel-plugin==2.0.0 | +| | This should fail with the | +| | error message: "400 Client Error: Bad Request (Can't delete | +| | plugin which is enabled for some environment.)". Verify that | +| | the Calico plugin is still installed. | +| | 5. Remove the environment. | +| | 6. Remove the Calico plugin. | +| | 7. Check the Calico plugin was successfully removed. | ++------------------+------------------------------------------------------------------+ +| Expected Result | Plugin is installed successfully. An error message is present | +| | when we attempt to remove a plugin which is attached to an | +| | enabled environment, and the plugin is not removed. When the | +| | environment is removed, the plugin can be removed successfully. | ++------------------+------------------------------------------------------------------+ + +Uninstall of plugin +------------------- + ++------------------+------------------------------------------------------------------+ +| Test Case ID | uninstall_plugin | ++------------------+------------------------------------------------------------------+ +| Steps | 1. Install the Calico plugin. | +| | 2. Check that it was installed successfully. | +| | 3. Remove the Calico plugin. | +| | 4. Check that it was successfully removed. | ++------------------+------------------------------------------------------------------+ +| Expected Result | Plugin was installed and then removed successfully. | ++------------------+------------------------------------------------------------------+ + +Appendix +======== + +Project Calico - `http://www.projectcalico.org/`_ + +Calico Documentation - `http://docs.projectcalico.org/en/latest/index.html`_ + +Calico GitHub - `https://github.com/projectcalico/calico`_ + +.. _http://www.projectcalico.org/: http://www.projectcalico.org/ +.. _http://docs.projectcalico.org/en/latest/index.html: http://docs.projectcalico.org/en/latest/index.html +.. _https://github.com/projectcalico/calico: https://github.com/projectcalico/calico + +Revision history +================ + ++---------+---------------+-------------------------------------------------+------------------------------------------------------+ +| Version | Revision date | Editor | Comment | ++---------+---------------+-------------------------------------------------+------------------------------------------------------+ +| 0.1 | 23.01.2015 | Irina Povolotskaya (ipovolotskaya@mirantis.com) | Created the template structure. | ++---------+---------------+-------------------------------------------------+------------------------------------------------------+ +| 0.2 | 29.04.2015 | Joe Marshall (joemarshall@projectcalico.org) | First draft. | ++---------+---------------+-------------------------------------------------+------------------------------------------------------+ +| 0.3 | 08.05.2015 | Emma Gordon (emma@projectcalico.org) | Additional test cases. | ++---------+---------------+-------------------------------------------------+------------------------------------------------------+ +| 0.4 | 02.07.2015 | Emma Gordon (emma@projectcalico.org) | Added new mandatory test cases for all Fuel plugins. | ++---------+---------------+-------------------------------------------------+------------------------------------------------------+ +| 0.5 | 03.08.2015 | Emma Gordon (emma@projectcalico.org) | Added new test cases. | ++---------+---------------+-------------------------------------------------+------------------------------------------------------+ +| 0.6 | 19.02.2016 | Neil Jerram (neil@projectcalico.org) | First RST version, for plugin version 2.0. | ++---------+---------------+-------------------------------------------------+------------------------------------------------------+ +| 0.7 | 14.03.2016 | Dave Langridge (dave@projectcalico.org) | Fixed typos, and clarified some tests. | ++---------+---------------+-------------------------------------------------+------------------------------------------------------+ diff --git a/doc/source/TestReportforCalicoFuelPlugin.rst b/doc/source/TestReportforCalicoFuelPlugin.rst new file mode 100644 index 0000000..47ce4d3 --- /dev/null +++ b/doc/source/TestReportforCalicoFuelPlugin.rst @@ -0,0 +1,116 @@ +====================================================== +Test Report for the Calico Fuel Plugin ver 2.0-2.0.2-1 +====================================================== + +Revision history +================ + ++---------+---------------+-------------------------------------------------+------------------------------------------------------+ +| Version | Revision date | Editor | Comment | ++---------+---------------+-------------------------------------------------+------------------------------------------------------+ +| 1.0 | 23.01.2015 | Irina Povolotskaya (ipovolotskaya@mirantis.com) | Created the template structure. | ++---------+---------------+-------------------------------------------------+------------------------------------------------------+ +| 2.0 | 15.06.2015 | Emma Gordon (emma@projectcalico.org) | Wrote the test report. | ++---------+---------------+-------------------------------------------------+------------------------------------------------------+ +| 3.0 | 02.05.2015 | Emma Gordon (emma@projectcalico.org) | Updated report with results of new mandatory tests | +| | | | for all Fuel plugins. | ++---------+---------------+-------------------------------------------------+------------------------------------------------------+ +| 4.0 | 03.08.2015 | Emma Gordon (emma@projectcalico.org) | Updated with new test cases. | ++---------+---------------+-------------------------------------------------+------------------------------------------------------+ +| 5.0 | 19.02.2016 | Neil Jerram (neil@projectcalico.org) | First RST version, for plugin version 2.0. | ++---------+---------------+-------------------------------------------------+------------------------------------------------------+ +| 6.0 | 14.03.2016 | Dave Langridge (dave@projectcalico.org) | Added results for plugin version 2.0.2. | ++---------+---------------+-------------------------------------------------+------------------------------------------------------+ + +Document purpose +================ + +This document provides test run results for the Calico Fuel Plugin version 2.0 +on Mirantis OpenStack 7.0; specifically with MOS 7.0 GA plus mu-3. + +Test environment +================ + +As described in the test plan. + +Test coverage and metrics +========================= + +Test Coverage - 100% + +Tests Passed - 100% + +Tests Failed - 0% + +Test results summary +==================== + +System Testing +-------------- + ++-------------------------------------------+-------+ +| Parameter | Value | ++-------------------------------------------+-------+ +| Total quantity of executed test cases | 15 | ++-------------------------------------------+-------+ +| Total quantity of not executed test cases | 0 | ++-------------------------------------------+-------+ +| Quantity of automated test cases | 0 | ++-------------------------------------------+-------+ +| Quantity of not automated test cases | 15 | ++-------------------------------------------+-------+ + +Detailed test run results +------------------------- + ++----------+--------------------------+--------+--------+---------+-------------------------------+ +| # | Test case ID | Passed | Failed | Skipped | Comment | ++----------+--------------------------+--------+--------+---------+-------------------------------+ +| 1 | Build Plugin | pass | | | | ++----------+--------------------------+--------+--------+---------+-------------------------------+ +| 2 | Install Plugin | pass | | | | ++----------+--------------------------+--------+--------+---------+-------------------------------+ +| 3 | Verify Calico option in | pass | | | | +| | Fuel web UI | | | | | ++----------+--------------------------+--------+--------+---------+-------------------------------+ +| 4 | Deploy OpenStack with | pass | | | | +| | Calico | | | | | ++----------+--------------------------+--------+--------+---------+-------------------------------+ +| 5 | Verify BGP Sessions | pass | | | | ++----------+--------------------------+--------+--------+---------+-------------------------------+ +| 6 | Create VMs | pass | | | | ++----------+--------------------------+--------+--------+---------+-------------------------------+ +| 7 | Test connectivity | pass | | | | ++----------+--------------------------+--------+--------+---------+-------------------------------+ +| 8 | Test security | pass | | | | ++----------+--------------------------+--------+--------+---------+-------------------------------+ +| 9 | Test initial route | pass | | | | +| | reflector configuration | | | | | ++----------+--------------------------+--------+--------+---------+-------------------------------+ +| 10 | Test route reflector | pass | | | | +| | configuration changes | | | | | ++----------+--------------------------+--------+--------+---------+-------------------------------+ +| 11 | External connectivity | pass | | | | ++----------+--------------------------+--------+--------+---------+-------------------------------+ +| 12 | Modifying env with | pass | | | | +| | enabled plugin (remove | | | | | +| | /add controller nodes) | | | | | ++----------+--------------------------+--------+--------+---------+-------------------------------+ +| 13 | Modifying env with | pass | | | | +| | enabled plugin (remove | | | | | +| | /add compute nodes) | | | | | ++----------+--------------------------+--------+--------+---------+-------------------------------+ +| 14 | Uninstall of plugin with | pass | | | | +| | deployed environment | | | | | ++----------+--------------------------+--------+--------+---------+-------------------------------+ +| 15 | Uninstall of plugin | pass | | | | ++----------+--------------------------+--------+--------+---------+-------------------------------+ +| Total | | 15 | 0 | 0 | | ++----------+--------------------------+--------+--------+---------+-------------------------------+ +| Total, % | | 100 | 0 | 0 | | ++----------+--------------------------+--------+--------+---------+-------------------------------+ + +Known issues +============ + +No issues were found during the testing. diff --git a/doc/source/_static/screenshot-all-instances.png b/doc/source/_static/screenshot-all-instances.png new file mode 100644 index 0000000..d861ede Binary files /dev/null and b/doc/source/_static/screenshot-all-instances.png differ diff --git a/doc/source/_static/screenshot-assign-public-network.png b/doc/source/_static/screenshot-assign-public-network.png new file mode 100644 index 0000000..7a82d94 Binary files /dev/null and b/doc/source/_static/screenshot-assign-public-network.png differ diff --git a/doc/source/_static/screenshot-create-network.png b/doc/source/_static/screenshot-create-network.png new file mode 100644 index 0000000..0e8b26d Binary files /dev/null and b/doc/source/_static/screenshot-create-network.png differ diff --git a/doc/source/_static/screenshot-create-security-group.png b/doc/source/_static/screenshot-create-security-group.png new file mode 100644 index 0000000..b71556e Binary files /dev/null and b/doc/source/_static/screenshot-create-security-group.png differ diff --git a/doc/source/_static/screenshot-example-network-config.png b/doc/source/_static/screenshot-example-network-config.png new file mode 100644 index 0000000..f65cf1f Binary files /dev/null and b/doc/source/_static/screenshot-example-network-config.png differ diff --git a/doc/source/_static/screenshot-instance-console.png b/doc/source/_static/screenshot-instance-console.png new file mode 100644 index 0000000..f04f0a7 Binary files /dev/null and b/doc/source/_static/screenshot-instance-console.png differ diff --git a/doc/source/_static/screenshot-launch-instance.png b/doc/source/_static/screenshot-launch-instance.png new file mode 100644 index 0000000..e146d8f Binary files /dev/null and b/doc/source/_static/screenshot-launch-instance.png differ diff --git a/doc/source/_static/screenshot-manage-rules.png b/doc/source/_static/screenshot-manage-rules.png new file mode 100644 index 0000000..7fbb205 Binary files /dev/null and b/doc/source/_static/screenshot-manage-rules.png differ diff --git a/doc/source/_static/screenshot-openstack-dashboard-link.png b/doc/source/_static/screenshot-openstack-dashboard-link.png new file mode 100644 index 0000000..172ddd4 Binary files /dev/null and b/doc/source/_static/screenshot-openstack-dashboard-link.png differ diff --git a/doc/source/_static/screenshot-use-calico-networking.png b/doc/source/_static/screenshot-use-calico-networking.png new file mode 100644 index 0000000..f9c23be Binary files /dev/null and b/doc/source/_static/screenshot-use-calico-networking.png differ diff --git a/doc/source/calico-fuel-plugin-2.0.rst b/doc/source/calico-fuel-plugin-2.0.rst new file mode 100644 index 0000000..028cd19 --- /dev/null +++ b/doc/source/calico-fuel-plugin-2.0.rst @@ -0,0 +1,328 @@ +Guide to the Calico Plugin for Fuel ver 2.0 +=========================================== + +Calico Plugin +------------- + +Calico provides seamless, scalable, secure Layer 3 Virtual Networking for your +Mirantis OpenStack Deployment. + +By replacing OpenStack's native networking model, Calico provides efficient, +easy to troubleshoot networking, without the complexity and inefficiency of +overlay networking models. Calico does not require any additional nodes or +Calico specific management - it just works, and gets out of your way! + +More details can be found at http://docs.projectcalico.org/en/latest/. + +This version of the Calico plugin supports HA - specifically OpenStack +deployments with multiple controller nodes, where OpenStack API requests are +load-balanced across those nodes. + +Requirements +~~~~~~~~~~~~ + +This Calico plugin is compatible with Mirantis OpenStack 7.0. + +The minimal sensible deployment for a Fuel/Calico cluster is one controller +node and two compute hosts. For OpenStack API request load-balancing and HA +you can add further controllers, and obviously more compute nodes for further +compute capacity. (As an illustration of possible scaling, Project Calico's +own testing - although not using the Fuel deployment technology - has included +up to 500 compute nodes and 10 controller nodes.) + +Limitations +~~~~~~~~~~~ + +This plugin only supports an Ubuntu OpenStack setup (as does Mirantis OpenStack +7.0). + +Installation Guide +------------------ + +To install the Calico plugin, follow these steps: + +1. Prepare a clean Fuel Master node, as described by the Mirantis + `documentation`_. + +.. _documentation: https://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html#install-fuel-master-node + +2. Download the Calico plugin from the `Fuel Plugin Catalog`_. + +.. _Fuel Plugin Catalog: https://software.mirantis.com/download-mirantis-openstack-fuel-plug-ins/ + +3. Copy the plugin onto the Fuel Master node:: + + scp calico-fuel-plugin-2.0-2.0.2-1.noarch.rpm root@:/tmp + +4. Log into the Fuel Master Node:: + + ssh root@ + +5. Install the plugin:: + + cd /tmp + fuel plugins --install calico-fuel-plugin-2.0-2.0.2-1.noarch.rpm + +6. Check the plugin was installed correctly by running:: + + fuel plugins --list + + The expected output is:: + + [root@fuel-master tmp]# fuel plugins --list + id | name | version | package_version + ---|--------------------|---------|---------------- + 1 | calico-fuel-plugin | 2.0.2 | 3.0.0 + +User Guide +---------- + +Deploying Mirantis OpenStack with Calico Networking +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use the Fuel web UI to deploy an OpenStack cluster, observing the following +guidelines: + +#. `Create a new OpenStack environment`_, selecting "Neutron with VLAN + segmentation" as the `networking setup`_ + + Other options can be left as their defaults. + + .. _Create a new OpenStack environment: https://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html#launch-wizard-to-create-new-environment + .. _networking setup: https://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html#network-service + +#. Under the `Settings tab`_, make sure the following options are checked and then + save your changes: + + - "Assign public network to all nodes" + + Calico uses IP routing between compute hosts to transport data between + VMs, and between VMs and the outside world. Therefore every compute host + must have a routable IP address. + + .. image:: _static/screenshot-assign-public-network.png + :alt: Screenshot: "Assign public network to all nodes" + + - "Use Calico Virtual Networking" + + .. image:: _static/screenshot-use-calico-networking.png + :alt: Screenshot: "Use Calico Virtual Networking" + + .. _Settings tab: https://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html#settings-tab + +#. Under the `Networks tab`_, configure the 'Public' settings (these will need to + be set to sensible values for your network setup): + + - IP Range + - CIDR + - Use VLAN tagging: No + - Gateway + - Floating IP range + + All of the other network settings should be left with their default + values. Ensure you save your changes once you are finished. + + Example network configuration: + + .. image:: _static/screenshot-example-network-config.png + :alt: Screenshot: Example network configuration + + .. _Networks tab: https://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html#network-settings + +#. Click the 'Verify Networks' button at the bottom of the screen, to check the + network configuration. + +#. Under the Nodes tab, `add some nodes`_ (for meaningful testing, you will + need at least two compute nodes and one controller). + + .. _add some nodes: https://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html#add-nodes-to-the-environment + +#. `Deploy changes`_. + + .. _Deploy changes: https://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html#deploy-changes + +#. Verify that Calico networking is operating correctly in the new deployment, + by following the 'Demonstration Setup' section below. + +Using your Calico networked Mirantis OpenStack deployment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You are now ready to use the OpenStack dashboard to configure your +deployment. Your particular requirements will determine how you use your +OpenStack deployment, but you may wish to refer to the Calico documentation for +some common `next steps`_. + +.. _next steps: http://docs.projectcalico.org/en/latest/next-steps.html + +Demonstration Setup +~~~~~~~~~~~~~~~~~~~ + +The following is a demonstration OpenStack setup that, if wished, can be +followed to verify the Calico elements of your OpenStack deployment are +operating as intended. + +In this example, we will launch a number of VMs (load balanced across the +compute hosts), split into two security groups - with VMs in the same security +group able to contact each other, but not VMs in the other security group +(regardless of which compute host the VMs are on). + +Steps: + +#. Follow the link from the Fuel web UI to the OpenStack dashboard: + + .. image:: _static/screenshot-openstack-dashboard-link.png + :alt: Screenshot: OpenStack dashboard link + +#. Under Project->Network->Networks in the OpenStack dashboard, create a + network and subnet from which instance IP addresses will be allocated. + + .. image:: _static/screenshot-create-network.png + :alt: Screenshot: Create a network + + Use the following settings: + + - Network: + - Name: demo + - Admin State: UP + + - Subnet: + - Create Subnet: Yes + - Name: demo_subnet + - Network Address: 10.65.0.0/24 + - IP Version: IPv4 + - Gateway IP: 10.65.0.1 + + - Subnet Detail: + - Enable DHCP: Yes + +#. Under Project->Compute->Access&Security in the OpenStack dashboard, create + two new security groups, named 'sg1' and 'sg2', and both with description + 'test'. + + .. image:: _static/screenshot-create-security-group.png + :alt: Screenshot: Create security group + +#. For each security group, select 'Manage Rules' and add two new rules. + + .. image:: _static/screenshot-manage-rules.png + :alt: Screenshot: Manage rules + + Use the following settings: + + - First Rule: + - Rule: ALL ICMP + - Direction: Ingress + - Remote: Security Group + - Security Group: + - Ether Type: IPv4 + + - Second Rule: + - Rule: SSH + - Remote: CIDR + - CIDR: 0.0.0.0/0 + +#. Under Project->Compute->Instances in the OpenStack dashboard, launch several + instances. + + .. image:: _static/screenshot-launch-instance.png + :alt: Screenshot: Launch instance + + Use the following settings: + + - Flavor: m1.tiny + + - Instance Boot Source: Boot from Image + + - Image Name: TestVM + + - Under the Access & Security tab, select one of sg1/sg2 (split your + instances roughly 50:50 between the two security groups). + + - Under the Networking tab, drag 'demo' into the 'Selected Networks' box. + +#. Under Admin->Instances in the OpenStack dashboard, verify that: + + - the requested instances have been launched + + - they are distributed roughly evenly across the compute hosts + + - they have each been assigned an IP address from the range that you + configured above (e.g. 10.65.0.0/24) + + - they reach Active status within about a minute. + + .. image:: _static/screenshot-all-instances.png + :alt: Screenshot: All instances + +#. Open a console on one of the instances. You should find that you can ping + the other instances in the same security group, but not the instances in the + other security group. + + .. image:: _static/screenshot-instance-console.png + :alt: Screenshot: Instance console + +Frequently Asked Questions +-------------------------- + +How do I setup instances with internet access? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For outbound access, you need to ensure that your VMs can send traffic to your +border gateway router (typically this will be the case, because usually your +compute hosts will be able to do so). The border gateway can then perform +SNAT. + +For inbound connections, you need assign a publically routable IP address to +your VM - that is, attach it to a network with a public IP address. You will +also need to make sure that your border router (and any intermediate routers +between the border router and the compute host) can route to that address +too. The simplest way to do that is to peer the border router with the route +reflector on the control host. + +The Calico documentation has an overview of `addressing and connectivity`_. + +.. _addressing and connectivity: http://docs.projectcalico.org/en/latest/addressing.html + +On the controller, BIRD lists routes to my instances listed as unreachable - is that a problem? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +No, this is expected. On the control node, BIRD is acting as a route reflector, +so won't write routes into the Linux forwarding table. Hence these routes are +unreachable from the control node. That's ok though - they are reachable from +the compute hosts, and therefore from the instances themselves. + +Why do instances in different networks have connectivity? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +With Calico networking, any two networks will have connectivity, unless you +have specifically disabled it using security groups. This is different to +standard OpenStack networking - you can find more information in the `Calico +Neutron API documentation`_. + +.. _Calico Neutron API documentation: http://docs.projectcalico.org/en/latest/calico-neutron-api.html + +Appendix +-------- + +General Calico docs can be found at http://docs.projectcalico.org/en/latest/. + +The official Calico website is at http://www.projectcalico.org/. + +The Calico code base lives at https://github.com/projectcalico/calico. + +Revision history +---------------- + ++---------+---------------+-----------------------------------------+----------------------------------------------+ +| Version | Revision date | Editor | Comment | ++---------+---------------+-----------------------------------------+----------------------------------------------+ +| 0.1 | 04.30.2015 | Brook Roberts (brook@projectcalico.org) | Created the document. | ++---------+---------------+-----------------------------------------+----------------------------------------------+ +| 0.2 | 05.07.2015 | Emma Gordon (emma@projectcalico.org) | Review markups from Mirantis feedback. | ++---------+---------------+-----------------------------------------+----------------------------------------------+ +| 0.3 | 03.08.2015 | Emma Gordon (emma@projectcalico.org) | Updated link to calico repository on GitHub. | ++---------+---------------+-----------------------------------------+----------------------------------------------+ +| 0.4 | 02.10.2016 | Neil Jerram (neil@projectcalico.org) | First RST version, for plugin version 2.0. | ++---------+---------------+-----------------------------------------+----------------------------------------------+ +| 0.5 | 04.21.2016 | Neil Jerram (neil@projectcalico.org) | Review markups from Mirantis feedback. | ++---------+---------------+-----------------------------------------+----------------------------------------------+ diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..acf9f44 --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,337 @@ +# -*- coding: utf-8 -*- +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ +# 'sphinx.ext.todo', +# 'sphinx.ext.coverage', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'The Calico plugin for Fuel' +copyright = u'2016, Metaswitch Networks' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '2.0' +# The full version, including alpha/beta/rc tags. +release = '2.0-2.0.2-1' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'classic' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'fuel-plugin-calico' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ('index', 'fuel-plugin-calico.tex', u'The Calico Plugin for Fuel Documentation', + u'Metaswitch Networks', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + +# make latex stop printing blank pages between sections +# http://stackoverflow.com/questions/5422997/sphinx-docs-remove-blank-pages-from-generated-pdfs +latex_elements = { 'classoptions': ',openany,oneside', 'babel' : '\\usepackage[english]{babel}' } + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'fuel-plugin-calico', u'Calico Plugin for Fuel, version 2.0', + [u'Metaswitch Networks'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'fuel-plugin-calico', u'The Calico Plugin for Fuel Documentation', + u'Metaswitch Networks', 'fuel-plugin-calico', 'The Calico Plugin for Fuel Documentation', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + +# Insert footnotes where they are defined instead of +# at the end. +pdf_inline_footnotes = True + + + +# -- Options for Epub output ---------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = u'The Calico Plugin for Fuel' +epub_author = u'Metaswitch Networks' +epub_publisher = u'Metaswitch Networks' +epub_copyright = u'2015, Metaswitch Networks' + +# The basename for the epub file. It defaults to the project name. +#epub_basename = u'fuel-plugin-calico' + +# The HTML theme for the epub output. Since the default themes are not optimized +# for small screen space, using the same theme for HTML and epub output is +# usually not wise. This defaults to 'epub', a theme designed to save visual +# space. +#epub_theme = 'epub' + +# The language of the text. It defaults to the language option +# or en if the language is not set. +#epub_language = '' + +# The scheme of the identifier. Typical schemes are ISBN or URL. +#epub_scheme = '' + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +#epub_identifier = '' + +# A unique identification for the text. +#epub_uid = '' + +# A tuple containing the cover image and cover page html template filenames. +#epub_cover = () + +# A sequence of (type, uri, title) tuples for the guide element of content.opf. +#epub_guide = () + +# HTML files that should be inserted before the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_pre_files = [] + +# HTML files shat should be inserted after the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_post_files = [] + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + +# The depth of the table of contents in toc.ncx. +#epub_tocdepth = 3 + +# Allow duplicate toc entries. +#epub_tocdup = True + +# Choose between 'default' and 'includehidden'. +#epub_tocscope = 'default' + +# Fix unsupported image types using the PIL. +#epub_fix_images = False + +# Scale large images. +#epub_max_image_width = 0 + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#epub_show_urls = 'inline' + +# If false, no index is generated. +#epub_use_index = True diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..b307d3a --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,9 @@ + +=================================== +Calico Plugin for Fuel, version 2.0 +=================================== + +.. toctree:: + :maxdepth: 2 + + calico-fuel-plugin-2.0