diff --git a/.gitignore b/.gitignore index 54f0201049..7bc5d94581 100644 --- a/.gitignore +++ b/.gitignore @@ -7,7 +7,9 @@ cover/ covhtml/ dist/ doc/build -doc/source/devref/flow_diagrams/ +doc/source/configuration/_static/octavia.policy.yaml.sample +doc/source/contributor/devref/flow_diagrams/ +doc/source/contributor/modules .idea/* *.DS_Store *.pyc diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index 67a835a52e..f0530ed92a 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -13,7 +13,7 @@ Current API version Supported API version - `Octavia API v1 `_ + :doc:`v1/octaviaapi` Deprecated API version @@ -23,6 +23,7 @@ Deprecated API version :hidden: v2/index + v1/octaviaapi The API status reflects the state of the endpoint on the service. diff --git a/doc/source/api/octaviaapi.rst b/api-ref/source/v1/octaviaapi.rst similarity index 100% rename from doc/source/api/octaviaapi.rst rename to api-ref/source/v1/octaviaapi.rst diff --git a/doc-requirements.txt b/doc-requirements.txt index 9a362eeba4..516079c39a 100644 --- a/doc-requirements.txt +++ b/doc-requirements.txt @@ -2,7 +2,6 @@ actdiag blockdiag docutils>=0.11 nwdiag -oslosphinx seqdiag sphinx>=1.6.2 sphinxcontrib-actdiag diff --git a/doc/source/_static/.placeholder b/doc/source/_static/.placeholder new file mode 100644 index 0000000000..e69de29bb2 diff --git a/doc/source/main/Anchor.rst b/doc/source/admin/Anchor.rst similarity index 100% rename from doc/source/main/Anchor.rst rename to doc/source/admin/Anchor.rst diff --git a/doc/source/devref/apache-httpd.rst b/doc/source/admin/apache-httpd.rst similarity index 100% rename from doc/source/devref/apache-httpd.rst rename to doc/source/admin/apache-httpd.rst diff --git a/doc/source/guides/operator-maintenance.rst b/doc/source/admin/guides/operator-maintenance.rst similarity index 96% rename from doc/source/guides/operator-maintenance.rst rename to doc/source/admin/guides/operator-maintenance.rst index c7338b5d21..87e18ad489 100644 --- a/doc/source/guides/operator-maintenance.rst +++ b/doc/source/admin/guides/operator-maintenance.rst @@ -17,9 +17,9 @@ Operator Maintenance Guide ====================================== This document is intended for operators. For a developer guide see the -:doc:`dev-quick-start` in this documentation repository. For an end-user -guide, please see the :doc:`basic-cookbook` in this documentation -repository. +:doc:`../../contributor/guides/dev-quick-start` in this documentation +repository. For an end-user guide, please see the +:doc:`../../user/guides/basic-cookbook` in this documentation repository. Monitoring ========== @@ -40,7 +40,8 @@ monitoring of the other services showed problems as well, so depending on your overall monitoring strategy this might be optional. If additional monitoring is necessary, review the corresponding calls on -the amphora agent REST interface (see :doc:`../api/haproxy-amphora-api`) +the amphora agent REST interface (see +:doc:`../../contributor/api/haproxy-amphora-api`) Monitoring Pool Members ----------------------- @@ -286,7 +287,7 @@ Rotating Amphora Certificates ----------------------------- For the server part Octavia will either act as a certificate authority itself, -or use :doc:`../main/Anchor` to issue amphora certificates to be used +or use :doc:`../Anchor` to issue amphora certificates to be used by each amphora. Octavia will also monitor those certificates and refresh them before they expire. @@ -310,7 +311,7 @@ There are three ways to initiate a rotation manually: issued amphora certificates by switching off validation of the old amphora certificate. This requires a client certificate which can be validated by the client CA file on the amphora. Refer to - :doc:`../api/haproxy-amphora-api` for more details. + :doc:`../../contributor/api/haproxy-amphora-api` for more details. * If the client certificate on the control plane changed in a way that it can't be validated by the client certificate authority certificate on the amphora, @@ -336,7 +337,7 @@ find them. to the new certs in the configuration file and restart all Octavia services (except octavia-api). -# Review :ref:`_rotate-amphora-certs` above to determine if and how the +# Review :ref:`rotate-amphora-certs` above to determine if and how the amphora certificates needs to be rotated. Rotating Client Certificates diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst new file mode 100644 index 0000000000..fb39ffcddf --- /dev/null +++ b/doc/source/admin/index.rst @@ -0,0 +1,41 @@ +====================== +Octavia Administration +====================== + + +Getting Started +--------------- + +.. toctree:: + :maxdepth: 1 + + ../reference/introduction.rst + ../reference/glossary.rst + +APIs +---- + +.. toctree:: + :maxdepth: 1 + + Octavia API Reference + ../contributor/api/haproxy-amphora-api.rst + + +Operator Reference +------------------ + +.. toctree:: + :maxdepth: 1 + + ../contributor/guides/dev-quick-start.rst + guides/operator-maintenance.rst + ../configuration/configref.rst + ../configuration/policy.rst + Anchor.rst + apache-httpd.rst + +Indices and Search +------------------ + +* :ref:`search` diff --git a/doc/source/conf.py b/doc/source/conf.py index f3f64b5cf5..1b67795d30 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -18,12 +18,13 @@ from tools import create_flow_docs # Generate our flow diagrams create_flow_docs.generate( - 'tools/flow-list.txt', 'doc/source/devref/flow_diagrams') + 'tools/flow-list.txt', 'doc/source/contributor/devref/flow_diagrams') # 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('.')) +sys.path.insert(0, os.path.abspath('../../octavia')) # -- General configuration ----------------------------------------------------- @@ -40,7 +41,7 @@ extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.seqdiag', 'sphinxcontrib.nwdiag', 'sphinx.ext.graphviz', - 'oslosphinx', + 'openstackdocstheme', 'oslo_config.sphinxext', 'oslo_policy.sphinxpolicygen' ] @@ -75,7 +76,9 @@ copyright = u'2014, OpenStack Octavia Team' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['_build', 'specs/skeleton.rst', 'specs/template.rst'] +exclude_patterns = ['_build', + 'contributor/specs/skeleton.rst', + 'contributor/specs/template.rst'] # The reST default role (used for this markup: `text`) to use for all documents. #default_role = None @@ -104,7 +107,7 @@ man_pages = [] # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'nature' +html_theme = 'openstackdocs' # 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 @@ -134,9 +137,7 @@ html_static_path = ['_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. -git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local", - "-n1"] -html_last_updated_fmt = subprocess.check_output(git_cmd).decode('utf-8') +html_last_updated_fmt = '%Y-%m-%d %H:%M' # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. @@ -150,10 +151,10 @@ html_last_updated_fmt = subprocess.check_output(git_cmd).decode('utf-8') #html_additional_pages = {} # If false, no module index is generated. -html_domain_indices = False +html_domain_indices = True # If false, no index is generated. -html_use_index = False +html_use_index = True # If true, the index is split into individual pages for each letter. #html_split_index = False @@ -284,4 +285,12 @@ epub_copyright = u'2014, OpenStack Octavia Team' # RBAC sample policy file generation policy_generator_config_file = '../../etc/policy/octavia-policy-generator.conf' -sample_policy_basename = '_static/octavia' +sample_policy_basename = 'configuration/_static/octavia' + +# openstackdocstheme options +html_theme_options = { + "display_toc": False +} +repository_name = 'openstack/octavia' +bug_project = 'octavia' +bug_tag = 'docs' diff --git a/doc/source/main/configref.rst b/doc/source/configuration/configref.rst similarity index 100% rename from doc/source/main/configref.rst rename to doc/source/configuration/configref.rst diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst new file mode 100644 index 0000000000..037a354eba --- /dev/null +++ b/doc/source/configuration/index.rst @@ -0,0 +1,9 @@ +===================== +Octavia Configuration +===================== + +.. toctree:: + :maxdepth: 1 + + configref + policy diff --git a/doc/source/main/policy.rst b/doc/source/configuration/policy.rst similarity index 97% rename from doc/source/main/policy.rst rename to doc/source/configuration/policy.rst index ec5d3294ef..bdbd85f60e 100644 --- a/doc/source/main/policy.rst +++ b/doc/source/configuration/policy.rst @@ -76,4 +76,4 @@ in effective policy:: Default Octavia Policies ------------------------ -.. literalinclude:: ../_static/octavia.policy.yaml.sample +.. literalinclude:: _static/octavia.policy.yaml.sample diff --git a/doc/source/main/CONSTITUTION.rst b/doc/source/contributor/CONSTITUTION.rst similarity index 100% rename from doc/source/main/CONSTITUTION.rst rename to doc/source/contributor/CONSTITUTION.rst diff --git a/doc/source/main/HACKING.rst b/doc/source/contributor/HACKING.rst similarity index 100% rename from doc/source/main/HACKING.rst rename to doc/source/contributor/HACKING.rst diff --git a/doc/source/api/haproxy-amphora-api.rst b/doc/source/contributor/api/haproxy-amphora-api.rst similarity index 100% rename from doc/source/api/haproxy-amphora-api.rst rename to doc/source/contributor/api/haproxy-amphora-api.rst diff --git a/doc/source/design/version0.5/component-design.rst b/doc/source/contributor/design/version0.5/component-design.rst similarity index 100% rename from doc/source/design/version0.5/component-design.rst rename to doc/source/contributor/design/version0.5/component-design.rst diff --git a/doc/source/design/version0.5/v0.5-component-design.dot b/doc/source/contributor/design/version0.5/v0.5-component-design.dot similarity index 95% rename from doc/source/design/version0.5/v0.5-component-design.dot rename to doc/source/contributor/design/version0.5/v0.5-component-design.dot index c3971e1aa0..d5b08430c9 100644 --- a/doc/source/design/version0.5/v0.5-component-design.dot +++ b/doc/source/contributor/design/version0.5/v0.5-component-design.dot @@ -63,7 +63,12 @@ digraph G { - + + + + + + Driver diff --git a/doc/source/devref/flows.rst b/doc/source/contributor/devref/flows.rst similarity index 100% rename from doc/source/devref/flows.rst rename to doc/source/contributor/devref/flows.rst diff --git a/doc/source/main/gmr.rst b/doc/source/contributor/devref/gmr.rst similarity index 100% rename from doc/source/main/gmr.rst rename to doc/source/contributor/devref/gmr.rst diff --git a/doc/source/guides/dev-quick-start.rst b/doc/source/contributor/guides/dev-quick-start.rst similarity index 99% rename from doc/source/guides/dev-quick-start.rst rename to doc/source/contributor/guides/dev-quick-start.rst index 9f59261812..fed63fb636 100644 --- a/doc/source/guides/dev-quick-start.rst +++ b/doc/source/contributor/guides/dev-quick-start.rst @@ -301,7 +301,7 @@ Configuring Octavia ___________________ Going into all of the specifics of how Octavia can be configured is actually beyond the scope of this document. For full documentation of this, please see -the configuration reference: :doc:`../main/configref` +the configuration reference: :doc:`../../configuration/configref` A configuration template can be found in ``etc/octavia.conf`` in this repository. diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst new file mode 100644 index 0000000000..74817baf17 --- /dev/null +++ b/doc/source/contributor/index.rst @@ -0,0 +1,88 @@ +=================== +Octavia Contributor +=================== + +Contributor Guidelines +---------------------- +.. toctree:: + :glob: + :maxdepth: 1 + + CONSTITUTION.rst + HACKING.rst + +Contributor Reference +--------------------- +.. toctree:: + :glob: + :maxdepth: 1 + + guides/* + devref/* + + +Internal APIs +------------- +.. toctree:: + :glob: + :maxdepth: 1 + + api/* + +Design Documentation +-------------------- + +Version 0.5 (liberty) +````````````````````` +.. toctree:: + :glob: + :maxdepth: 1 + + design/version0.5/* + +Project Specifications +---------------------- + +Version 0.5 (liberty) +````````````````````` +.. toctree:: + :glob: + :maxdepth: 1 + + specs/version0.5/* + +Version 0.8 (mitaka) +```````````````````` +.. toctree:: + :glob: + :maxdepth: 1 + + specs/version0.8/* + +Version 0.9 (newton) +```````````````````` +.. toctree:: + :glob: + :maxdepth: 1 + + specs/version0.9/* + +Version 1.0 (pike) +`````````````````` +.. toctree:: + :glob: + :maxdepth: 1 + + specs/version1.0/* + +Indices and Search +------------------ + +.. toctree:: + :hidden: + + modules/autoindex + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/doc/source/contributor/specs b/doc/source/contributor/specs new file mode 120000 index 0000000000..0a70be60cd --- /dev/null +++ b/doc/source/contributor/specs @@ -0,0 +1 @@ +../../../specs \ No newline at end of file diff --git a/doc/source/index.rst b/doc/source/index.rst index b7a2fc0098..5277dd02ad 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,119 +1,28 @@ -.. octavia-specs documentation master file +.. octavia documentation master file ===================== Octavia Documentation ===================== -Getting started ---------------- +Welcome to the OpenStack Octavia project documentation. Octavia brings +network load balancing to OpenStack. + +See :doc:`reference/introduction` for an overview of Octavia. + +To align with the overall OpenStack documentation, the Octavia documentation +is grouped into the following topic areas. .. toctree:: :maxdepth: 1 - main/introduction.rst - main/glossary.rst - -For users ---------- - -.. toctree:: - :maxdepth: 1 - - guides/basic-cookbook.rst - guides/l7.rst - guides/l7-cookbook.rst - -For developers --------------- - -.. toctree:: - :maxdepth: 1 - - guides/dev-quick-start.rst - main/CONSTITUTION.rst - main/HACKING.rst - devref/flows.rst - main/gmr.rst - -For operators -------------- - -.. toctree:: - :maxdepth: 1 - - guides/dev-quick-start.rst - guides/operator-maintenance.rst - main/configref.rst - main/policy.rst - main/Anchor.rst - devref/apache-httpd.rst - -==== -APIs -==== - -.. toctree:: - :glob: - :maxdepth: 1 - + admin/index.rst Octavia API Reference - api/haproxy-amphora-api.rst + configuration/index.rst + contributor/index.rst + install/index.rst + reference/index.rst + user/index.rst -==================== -Design Documentation -==================== -Version 0.5 (liberty) ---------------------- -.. toctree:: - :glob: - :maxdepth: 1 - - design/version0.5/* - -====================== -Project Specifications -====================== - -Version 0.5 (liberty) ---------------------- - -.. toctree:: - :glob: - :maxdepth: 1 - - specs/version0.5/* - -Version 0.8 (mitaka) --------------------- - -.. toctree:: - :glob: - :maxdepth: 1 - - specs/version0.8/* - -Version 0.9 (newton) --------------------- - -.. toctree:: - :glob: - :maxdepth: 1 - - specs/version0.9/* - -Version 1.0 ------------ - -.. toctree:: - :glob: - :maxdepth: 1 - - specs/version1/* - -================== -Indices and tables -================== - -* :ref:`search` +:ref:`search` diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst new file mode 100644 index 0000000000..cce0c4a629 --- /dev/null +++ b/doc/source/install/index.rst @@ -0,0 +1,8 @@ +==================== +Octavia Installation +==================== + +.. toctree:: + :maxdepth: 1 + + Installation overview guide <../contributor/guides/dev-quick-start> diff --git a/doc/source/main/glossary.rst b/doc/source/reference/glossary.rst similarity index 100% rename from doc/source/main/glossary.rst rename to doc/source/reference/glossary.rst diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst new file mode 100644 index 0000000000..978922f564 --- /dev/null +++ b/doc/source/reference/index.rst @@ -0,0 +1,16 @@ +================= +Octavia Reference +================= + +.. toctree:: + :glob: + :maxdepth: 1 + + * + +Indices and Search +------------------ + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/doc/source/main/introduction.rst b/doc/source/reference/introduction.rst similarity index 98% rename from doc/source/main/introduction.rst rename to doc/source/reference/introduction.rst index 47ea18a4b4..c5d1f1b00d 100644 --- a/doc/source/main/introduction.rst +++ b/doc/source/reference/introduction.rst @@ -148,5 +148,5 @@ Octavia version 0.9 consists of the following major components: service is deployed by the tenant. For a more complete description of Octavia's components, please see the -:doc:`../design/version0.5/component-design` document within this documentation -repository. +:doc:`../contributor/design/version0.5/component-design` document within this +documentation repository. diff --git a/doc/source/main/octavia-component-overview.svg b/doc/source/reference/octavia-component-overview.svg similarity index 100% rename from doc/source/main/octavia-component-overview.svg rename to doc/source/reference/octavia-component-overview.svg diff --git a/doc/source/specs b/doc/source/specs deleted file mode 120000 index 87a4030175..0000000000 --- a/doc/source/specs +++ /dev/null @@ -1 +0,0 @@ -../../specs \ No newline at end of file diff --git a/doc/source/guides/basic-cookbook.rst b/doc/source/user/guides/basic-cookbook.rst similarity index 99% rename from doc/source/guides/basic-cookbook.rst rename to doc/source/user/guides/basic-cookbook.rst index 50f8d7d2f3..21d3acdd1e 100644 --- a/doc/source/guides/basic-cookbook.rst +++ b/doc/source/user/guides/basic-cookbook.rst @@ -32,9 +32,9 @@ TLS certificates from a trusted provider, and so on. A description of the starting conditions is given in each example below. Please also note that this guide assumes you are familiar with the specific -load balancer terminology defined in the :doc:`../main/glossary`. For a +load balancer terminology defined in the :doc:`../../reference/glossary`. For a description of load balancing itself and the Octavia project, please see: -:doc:`../main/introduction`. +:doc:`../../reference/introduction`. Examples @@ -537,7 +537,7 @@ them out of the pool. Since effective health monitors depend as much on back-end application server configuration as proper load balancer configuration, some additional discussion of best practices is warranted here. -See also: :doc:`../api/octaviaapi` +See also: `Octavia API Reference `_ Heath monitor options diff --git a/doc/source/guides/l7-cookbook.rst b/doc/source/user/guides/l7-cookbook.rst similarity index 98% rename from doc/source/guides/l7-cookbook.rst rename to doc/source/user/guides/l7-cookbook.rst index b7045eeee7..fa99214344 100644 --- a/doc/source/guides/l7-cookbook.rst +++ b/doc/source/user/guides/l7-cookbook.rst @@ -36,8 +36,8 @@ Examples .. _redirect-http-to-https: -Redirect http://www.example.com/ to https://www.example.com/ ------------------------------------------------------------- +Redirect *http://www.example.com/* to *https://www.example.com/* +---------------------------------------------------------------- **Scenario description**: * Load balancer *lb1* has been set up with ``TERMINATED_HTTPS`` listener @@ -121,8 +121,8 @@ Send requests starting with /js or /images to *static_pool* neutron lbaas-l7rule-create --type PATH --compare-type REGEX --value '^/(js|images)' policy1 -Send requests for http://www2.example.com/ to *pool2* ------------------------------------------------------ +Send requests for *http://www2.example.com/* to *pool2* +------------------------------------------------------- **Scenario description**: * Listener *listener1* on load balancer *lb1* is set up to send all requests to diff --git a/doc/source/guides/l7.rst b/doc/source/user/guides/l7.rst similarity index 96% rename from doc/source/guides/l7.rst rename to doc/source/user/guides/l7.rst index d4e73cf63d..1053e53de5 100644 --- a/doc/source/guides/l7.rst +++ b/doc/source/user/guides/l7.rst @@ -70,7 +70,7 @@ It consists of a rule type, a comparison type, a value, and an optional key that gets used depending on the rule type. An L7 rule must always be associated with an L7 policy. -See also: :doc:`../api/octaviaapi` +See also: `Octavia API Reference `_ Rule types __________ @@ -115,7 +115,7 @@ may also have an association to a back-end pool. Policies describe actions that should be taken by the load balancing software if all of the rules in the policy return true. -See also: :doc:`../api/octaviaapi` +See also: `Octavia API Reference `_ Policy Logic ____________ @@ -180,6 +180,6 @@ For a cookbook of common L7 usage examples, please see the :doc:`l7-cookbook` Useful links ============ -* :doc:`../api/octaviaapi` +* `Octavia API Reference `_ * https://github.com/openstack/neutron-specs/blob/master/specs/mitaka/lbaas-l7-rules.rst * http://cbonte.github.io/haproxy-dconv/1.6/configuration.html#7 diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst new file mode 100644 index 0000000000..c6b1d11613 --- /dev/null +++ b/doc/source/user/index.rst @@ -0,0 +1,15 @@ +============ +Octavia User +============ + +.. toctree:: + :glob: + :maxdepth: 1 + + guides/* + +Indices and Search +------------------ + +* :ref:`genindex` +* :ref:`search` diff --git a/octavia/amphorae/backends/agent/api_server/util.py b/octavia/amphorae/backends/agent/api_server/util.py index 48cc15e9b6..422dadd68d 100644 --- a/octavia/amphorae/backends/agent/api_server/util.py +++ b/octavia/amphorae/backends/agent/api_server/util.py @@ -111,7 +111,7 @@ def get_listeners(): """Get Listeners :returns: An array with the ids of all listeners, e.g. ['123', '456', ...] - or [] if no listeners exist + or [] if no listeners exist """ if os.path.exists(CONF.haproxy_amphora.base_path): diff --git a/octavia/amphorae/backends/utils/haproxy_query.py b/octavia/amphorae/backends/utils/haproxy_query.py index 0d181769a1..2a51b5cd1d 100644 --- a/octavia/amphorae/backends/utils/haproxy_query.py +++ b/octavia/amphorae/backends/utils/haproxy_query.py @@ -40,7 +40,7 @@ class HAProxyQuery(object): """Send the given query to the haproxy statistics socket. :returns: the output of a successful query as a string with trailing - newlines removed, or raise an Exception if the query fails. + newlines removed, or raise an Exception if the query fails. """ sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) @@ -76,20 +76,17 @@ class HAProxyQuery(object): def show_stat(self, proxy_iid=-1, object_type=-1, server_id=-1): """Get and parse output from 'show status' command. - :param proxy_iid: - Proxy ID (column 27 in CSV output). -1 for all. + :param proxy_iid: Proxy ID (column 27 in CSV output). -1 for all. + :param object_type: Select the type of dumpable object. Values can + be ORed. + -1 - everything + 1 - frontends + 2 - backends + 4 - servers + :param server_id: Server ID (column 28 in CSV output?), or -1 + for everything. + :returns: stats (split into an array by newline) - :param object_type: - Select the type of dumpable object. Values can be ORed. - -1 - everything - 1 - frontends - 2 - backends - 4 - servers - - :param server_id: - Server ID (column 28 in CSV output?), or -1 for everything. - - :returns: stats (split into an array by \n) """ results = self._query( @@ -105,12 +102,10 @@ class HAProxyQuery(object): """Get status for each server and the pool as a whole. :returns: pool data structure - {: { - 'uuid': , - 'status': 'UP'|'DOWN', - 'members': [ - : 'UP'|'DOWN' - ] + {: { + 'uuid': , + 'status': 'UP'|'DOWN', + 'members': [: 'UP'|'DOWN'] }} """ results = self.show_stat(object_type=6) # servers + pool diff --git a/octavia/amphorae/drivers/driver_base.py b/octavia/amphorae/drivers/driver_base.py index 6b4753c6f8..e7229ac2d6 100644 --- a/octavia/amphorae/drivers/driver_base.py +++ b/octavia/amphorae/drivers/driver_base.py @@ -26,7 +26,7 @@ class AmphoraLoadBalancerDriver(object): """Update the amphora with a new configuration. :param listener: listener object, - need to use its protocol_port property + need to use its protocol_port property :type listener: object :param vip: vip object, need to use its ip_address property :type vip: object @@ -42,7 +42,7 @@ class AmphoraLoadBalancerDriver(object): """Stop the listener on the vip. :param listener: listener object, - need to use its protocol_port property + need to use its protocol_port property :type listener: object :param vip: vip object, need to use its ip_address property :type vip: object @@ -58,9 +58,9 @@ class AmphoraLoadBalancerDriver(object): """Start the listener on the vip. :param listener: listener object, - need to use its protocol_port property + need to use its protocol_port property :type listener: object - :param vip : vip object, need to use its ip_address property + :param vip: vip object, need to use its ip_address property :type vip: object :returns: return a value list (listener, vip, status flag--enable) @@ -74,7 +74,7 @@ class AmphoraLoadBalancerDriver(object): """Delete the listener on the vip. :param listener: listener object, - need to use its protocol_port property + need to use its protocol_port property :type listener: object :param vip: vip object, need to use its ip_address property :type vip: object @@ -109,7 +109,7 @@ class AmphoraLoadBalancerDriver(object): :param amphora: amphora object, need to use its id property :type amphora: object :returns: return a value list (amphora.id, status flag--'ge - t_diagnostics') + t_diagnostics') At this moment, we just build the basic structure for testing, will add more function along with the development, eventually, we want it diff --git a/octavia/amphorae/drivers/health/heartbeat_udp.py b/octavia/amphorae/drivers/health/heartbeat_udp.py index 9ce9f5b9a8..d395024b13 100644 --- a/octavia/amphorae/drivers/health/heartbeat_udp.py +++ b/octavia/amphorae/drivers/health/heartbeat_udp.py @@ -81,85 +81,86 @@ class UDPStatusGetter(object): can be seen below. Note that listener_1 has no pools and listener_4 has no members. - {"listeners": { - "listener_uuid_1": { - "pools": {}, - "status": "OPEN", - "stats": { - "conns": 0, - "rx": 0, - "tx": 0 - } - }, - "listener_uuid_2": { - "pools": { - "pool_uuid_1": { - "members": [ - { - "member_uuid_1": "DOWN" + Example:: + + { + "listeners": { + "listener_uuid_1": { + "pools": {}, + "status": "OPEN", + "stats": { + "conns": 0, + "rx": 0, + "tx": 0 + } + }, + "listener_uuid_2": { + "pools": { + "pool_uuid_1": { + "members": [{ + "member_uuid_1": "DOWN" }, { - "member_uuid_2": "DOWN" + "member_uuid_2": "DOWN" }, { - "member_uuid_3": "DOWN" + "member_uuid_3": "DOWN" }, { - "member_uuid_4": "DOWN" + "member_uuid_4": "DOWN" } - ] - } - }, - "status": "OPEN", - "stats": { - "conns": 0, - "rx": 0, - "tx": 0 - } - }, - "listener_uuid_3": { - "pools": { - "pool_uuid_2": { - "members": [ - { - "member_uuid_5": "DOWN" + ] + } + }, + "status": "OPEN", + "stats": { + "conns": 0, + "rx": 0, + "tx": 0 + } + }, + "listener_uuid_3": { + "pools": { + "pool_uuid_2": { + "members": [{ + "member_uuid_5": "DOWN" }, { - "member_uuid_6": "DOWN" + "member_uuid_6": "DOWN" }, { - "member_uuid_7": "DOWN" + "member_uuid_7": "DOWN" }, { - "member_uuid_8": "DOWN" + "member_uuid_8": "DOWN" } - ] + ] + } + }, + "status": "OPEN", + "stats": { + "conns": 0, + "rx": 0, + "tx": 0 + } + }, + "listener_uuid_4": { + "pools": { + "pool_uuid_3": { + "members": [] + } + }, + "status": "OPEN", + "stats": { + "conns": 0, + "rx": 0, + "tx": 0 + } } - }, - "status": "OPEN", - "stats": { - "conns": 0, - "rx": 0, - "tx": 0 + }, + "id": "amphora_uuid", + "seq": 1033 } - }, - "listener_uuid_4": { - "pools": { - "pool_uuid_3": { - "members": [] - } - }, - "status": "OPEN", - "stats": { - "conns": 0, - "rx": 0, - "tx": 0 - } - } - }, - "id": "amphora_uuid", - "seq": 1033 -} """ (data, srcaddr) = self.sock.recvfrom(UDP_MAX_SIZE) diff --git a/octavia/common/decorators.py b/octavia/common/decorators.py index 2d5df509af..22903dfd94 100644 --- a/octavia/common/decorators.py +++ b/octavia/common/decorators.py @@ -20,8 +20,9 @@ def rename_kwargs(**renamed_kwargs): """Renames a class's variables and maintains backwards compatibility. :param renamed_kwargs: mapping of old kwargs to new kwargs. For example, - to say a class has renamed variable foo to bar the decorator would - be used like: rename_kwargs(foo='bar') + to say a class has renamed variable foo to bar the + decorator would be used like: + rename_kwargs(foo='bar') """ diff --git a/octavia/common/tls_utils/cert_parser.py b/octavia/common/tls_utils/cert_parser.py index 3bb667c3c9..dc42643ec7 100644 --- a/octavia/common/tls_utils/cert_parser.py +++ b/octavia/common/tls_utils/cert_parser.py @@ -101,8 +101,8 @@ def get_intermediates_pems(intermediates=None): :param intermediates: PEM or PKCS7 encoded intermediate certificates :returns: A list of strings where each string represents an - X509 pem block surrounded by BEGIN CERTIFICATE, - END CERTIFICATE block tags + X509 pem block surrounded by BEGIN CERTIFICATE, + END CERTIFICATE block tags """ if X509_BEG in intermediates: for x509Pem in _split_x509s(intermediates): @@ -242,10 +242,10 @@ def get_host_names(certificate): :param certificate: A PEM encoded certificate :returns: A dictionary containing the following keys: - ['cn', 'dns_names'] - where 'cn' is the CN from the SubjectName of the certificate, and - 'dns_names' is a list of dNSNames (possibly empty) from - the SubjectAltNames of the certificate. + ['cn', 'dns_names'] + where 'cn' is the CN from the SubjectName of the + certificate, and 'dns_names' is a list of dNSNames + (possibly empty) from the SubjectAltNames of the certificate. """ try: cert = x509.load_pem_x509_certificate(certificate, diff --git a/octavia/compute/compute_base.py b/octavia/compute/compute_base.py index 8b3eb60c6e..4e69b2c976 100644 --- a/octavia/compute/compute_base.py +++ b/octavia/compute/compute_base.py @@ -34,16 +34,18 @@ class ComputeBase(object): :param key_name: Optionally specify a keypair :param sec_groups: Optionally specify list of security groups :param network_ids: A list of network IDs to attach to the amphora - :param config_drive_files: An optional dict of files to overwrite on - the server upon boot. Keys are file names (i.e. /etc/passwd) - and values are the file contents (either as a string or as - a file-like object). A maximum of five entries is allowed, - and each file must be 10k or less. + :param config_drive_files: An optional dict of files to overwrite on + the server upon boot. Keys are file names + (i.e. /etc/passwd) and values are the + file contents (either as a string or as + a file-like object). A maximum of five + entries is allowed, and each file must be + 10k or less. :param user_data: Optional user data to pass to be exposed by the - metadata server this can be a file type object as well or - a string + metadata server this can be a file type object as + well or a string :param server_group_id: Optional server group id(uuid) which is used - for anti_affinity feature + for anti_affinity feature :raises ComputeBuildException: if compute failed to build amphora :returns: UUID of amphora diff --git a/octavia/compute/drivers/nova_driver.py b/octavia/compute/drivers/nova_driver.py index 114dde7ba9..e0d0f56292 100644 --- a/octavia/compute/drivers/nova_driver.py +++ b/octavia/compute/drivers/nova_driver.py @@ -104,18 +104,21 @@ class VirtualMachineManager(compute_base.ComputeBase): :param network_ids: Network IDs to include on virtual machine :param port_ids: Port IDs to include on virtual machine :param config_drive_files: An optional dict of files to overwrite on - the server upon boot. Keys are file names (i.e. /etc/passwd) - and values are the file contents (either as a string or as - a file-like object). A maximum of five entries is allowed, - and each file must be 10k or less. + the server upon boot. Keys are file names + (i.e. /etc/passwd) and values are the file + contents (either as a string or as a + file-like object). A maximum of five + entries is allowed, and each file must be + 10k or less. :param user_data: Optional user data to pass to be exposed by the - metadata server this can be a file type object as well or - a string + metadata server this can be a file type object as + well or a string :param server_group_id: Optional server group id(uuid) which is used - for anti_affinity feature + for anti_affinity feature :raises ComputeBuildException: if nova failed to build virtual machine :returns: UUID of amphora + ''' try: diff --git a/octavia/controller/healthmanager/update_db.py b/octavia/controller/healthmanager/update_db.py index 8598dcfb06..4d2b1e7987 100644 --- a/octavia/controller/healthmanager/update_db.py +++ b/octavia/controller/healthmanager/update_db.py @@ -67,19 +67,20 @@ class UpdateHealthDb(object): :type map: string :returns: null - The input health data structure is shown as below: + The input health data structure is shown as below:: - health = { - "id": self.FAKE_UUID_1, - "listeners": { - "listener-id-1": {"status": constants.OPEN, "pools": { - "pool-id-1": {"status": constants.UP, - "members": {"member-id-1": constants.ONLINE} - } - } + health = { + "id": self.FAKE_UUID_1, + "listeners": { + "listener-id-1": {"status": constants.OPEN, "pools": { + "pool-id-1": {"status": constants.UP, + "members": { + "member-id-1": constants.ONLINE} + } + } + } } } - } """ session = db_api.get_session() @@ -228,27 +229,29 @@ class UpdateStatsDb(stats.StatsMixin): :type map: string :returns: null - health = { - "id": self.FAKE_UUID_1, - "listeners": { - "listener-id-1": { - "status": constants.OPEN, - "stats": { - "ereq":0, - "conns": 0, - "totconns": 0, - "rx": 0, - "tx": 0, - }, - "pools": { - "pool-id-1": { - "status": constants.UP, - "members": {"member-id-1": constants.ONLINE} + Example:: + + health = { + "id": self.FAKE_UUID_1, + "listeners": { + "listener-id-1": { + "status": constants.OPEN, + "stats": { + "ereq":0, + "conns": 0, + "totconns": 0, + "rx": 0, + "tx": 0, + }, + "pools": { + "pool-id-1": { + "status": constants.UP, + "members": {"member-id-1": constants.ONLINE} + } } } } } - } """ session = db_api.get_session() diff --git a/octavia/controller/worker/flows/listener_flows.py b/octavia/controller/worker/flows/listener_flows.py index 6760b89eba..c3183ea054 100644 --- a/octavia/controller/worker/flows/listener_flows.py +++ b/octavia/controller/worker/flows/listener_flows.py @@ -88,6 +88,7 @@ class ListenerFlows(object): """Create a flow to delete a listener and l7policies internally (will skip deletion on the amp and marking LB active) + :returns: The flow for deleting a listener """ delete_listener_flow = linear_flow.Flow(constants.DELETE_LISTENER_FLOW) diff --git a/octavia/controller/worker/tasks/network_tasks.py b/octavia/controller/worker/tasks/network_tasks.py index 0d0b0be4a8..4e6f7d4f30 100644 --- a/octavia/controller/worker/tasks/network_tasks.py +++ b/octavia/controller/worker/tasks/network_tasks.py @@ -90,8 +90,9 @@ class CalculateDelta(BaseNetworkTask): """Compute which NICs need to be plugged for the amphora to become operational. + :param loadbalancer: the loadbalancer to calculate deltas for all - amphorae + amphorae :returns: dict of octavia.network.data_models.Delta keyed off amphora id """ diff --git a/octavia/db/repositories.py b/octavia/db/repositories.py index d70471b289..ea6a44894f 100644 --- a/octavia/db/repositories.py +++ b/octavia/db/repositories.py @@ -671,8 +671,9 @@ class LoadBalancerRepository(BaseRepository): :param session: A Sql Alchemy database session. :param lb_id: id of an load balancer object :param exp_age: A standard datetime delta which is used to see for how - long can a load balancer live without updates before it is considered - expired (default: CONF.house_keeping.load_balancer_expiry_age) + long can a load balancer live without updates before + it is considered expired (default: + CONF.house_keeping.load_balancer_expiry_age) :returns: boolean """ if not exp_age: @@ -1032,8 +1033,9 @@ class AmphoraHealthRepository(BaseRepository): :param session: A Sql Alchemy database session. :param amphora_id: id of an amphora object :param exp_age: A standard datetime delta which is used to see for how - long can an amphora live without updates before it is considered - expired (default: CONF.house_keeping.amphora_expiry_age) + long can an amphora live without updates before it is + considered expired (default: + CONF.house_keeping.amphora_expiry_age) :returns: boolean """ if not exp_age: diff --git a/octavia/hacking/checks.py b/octavia/hacking/checks.py index 1e85189a93..2a2c04d5c6 100644 --- a/octavia/hacking/checks.py +++ b/octavia/hacking/checks.py @@ -169,8 +169,8 @@ def no_translate_logs(logical_line, filename): :param logical_line: The logical line to check. :param filename: The file name where the logical line exists. :returns: None if the logical line passes the check, otherwise a tuple - is yielded that contains the offending index in logical line and a - message describe the check validation failure. + is yielded that contains the offending index in logical line + and a message describe the check validation failure. """ if _translation_checks_not_enforced(filename): return @@ -187,8 +187,8 @@ def check_raised_localized_exceptions(logical_line, filename): :param logical_line: The logical line to check. :param filename: The file name where the logical line exists. :returns: None if the logical line passes the check, otherwise a tuple - is yielded that contains the offending index in logical line and a - message describe the check validation failure. + is yielded that contains the offending index in logical line + and a message describe the check validation failure. """ if _translation_checks_not_enforced(filename): return @@ -208,8 +208,8 @@ def check_no_basestring(logical_line): :param logical_line: The logical line to check. :returns: None if the logical line passes the check, otherwise a tuple - is yielded that contains the offending index in logical line and a - message describe the check validation failure. + is yielded that contains the offending index in logical line + and a message describe the check validation failure. """ if re.search(r"\bbasestring\b", logical_line): msg = ("O343: basestring is not Python3-compatible, use " @@ -222,8 +222,8 @@ def check_python3_no_iteritems(logical_line): :param logical_line: The logical line to check. :returns: None if the logical line passes the check, otherwise a tuple - is yielded that contains the offending index in logical line and a - message describe the check validation failure. + is yielded that contains the offending index in logical line + and a message describe the check validation failure. """ if re.search(r".*\.iteritems\(\)", logical_line): msg = ("O344: Use dict.items() instead of dict.iteritems() to be " @@ -239,8 +239,8 @@ def check_no_eventlet_imports(logical_line): :param logical_line: The logical line to check. :returns: None if the logical line passes the check, otherwise a tuple - is yielded that contains the offending index in logical line and a - message describe the check validation failure. + is yielded that contains the offending index in logical line + and a message describe the check validation failure. """ if re.match(r'(import|from)\s+[(]?eventlet', logical_line): msg = 'O345 Usage of Python eventlet module not allowed' @@ -253,8 +253,8 @@ def check_line_continuation_no_backslash(logical_line, tokens): :param logical_line: The logical line to check. Not actually used. :param tokens: List of tokens to check. :returns: None if the tokens don't contain any issues, otherwise a tuple - is yielded that contains the offending index in the logical line and a - message describe the check validation failure. + is yielded that contains the offending index in the logical + line and a message describe the check validation failure. """ backslash = None for token_type, text, start, end, orig_line in tokens: diff --git a/octavia/network/base.py b/octavia/network/base.py index d5f6aaf83c..fa6f15f89f 100644 --- a/octavia/network/base.py +++ b/octavia/network/base.py @@ -293,12 +293,11 @@ class AbstractNetworkDriver(object): means the driver is responsible for providing data that is appropriate for the amphora network configurations. - Example return: - {: } + Example return: {: } :param load_balancer: The load_balancer configuration :return: dict of octavia.network.data_models.AmphoraNetworkConfig - keyed off of the amphora id the config is associated with. + keyed off of the amphora id the config is associated with. :raises: NotFound, NetworkNotFound, SubnetNotFound, PortNotFound """ pass diff --git a/octavia/opts.py b/octavia/opts.py index 46392de7d1..84db8555d7 100644 --- a/octavia/opts.py +++ b/octavia/opts.py @@ -25,6 +25,7 @@ def list_opts(): return [ ('DEFAULT', itertools.chain(octavia.common.config.core_opts)), + ('api_settings', octavia.common.config.api_opts), ('amphora_agent', octavia.common.config.amphora_agent_opts), ('networking', octavia.common.config.networking_opts), ('oslo_messaging', octavia.common.config.oslo_messaging_opts), @@ -35,9 +36,11 @@ def list_opts(): ('certificates', octavia.common.config.certificate_opts), ('house_keeping', octavia.common.config.house_keeping_opts), ('keepalived_vrrp', octavia.common.config.keepalived_vrrp_opts), + ('anchor', octavia.common.config.anchor_opts), ('nova', octavia.common.config.nova_opts), ('neutron', octavia.common.config.neutron_opts), ('glance', octavia.common.config.glance_opts), + ('quotas', octavia.common.config.quota_opts), add_auth_opts(), ] diff --git a/releasenotes/source/conf.py b/releasenotes/source/conf.py index d3f2537f82..57c97e3bbb 100644 --- a/releasenotes/source/conf.py +++ b/releasenotes/source/conf.py @@ -39,7 +39,7 @@ from octavia import version # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'oslosphinx', + 'openstackdocstheme', 'reno.sphinxext', ] @@ -152,6 +152,7 @@ html_static_path = ['_static'] # 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' +html_last_updated_fmt = '%Y-%m-%d %H:%M' # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. diff --git a/setup.cfg b/setup.cfg index a4f1b8d7a2..b9d0e54a7a 100644 --- a/setup.cfg +++ b/setup.cfg @@ -41,9 +41,19 @@ data_files = all_files = 1 build-dir = doc/build source-dir = doc/source +warning-is-error = 1 [pbr] -warnerrors = True +autodoc_tree_index_modules = False +autodoc_tree_excludes = + setup.py + octavia/tests/ + octavia/db/migration/ +autodoc_index_modules = True +autodoc_exclude_modules = + octavia.tests.* + octavia.db.migration.* +api_doc_dir = contributor/modules [wheel] universal = 1 diff --git a/specs/version0.9/active-active-distributor.rst b/specs/version0.9/active-active-distributor.rst index ff4739f598..adb3222c9f 100644 --- a/specs/version0.9/active-active-distributor.rst +++ b/specs/version0.9/active-active-distributor.rst @@ -828,10 +828,10 @@ Documentation Impact References ========== -.. [1] https://blueprints.launchpad.net/octavia/+spec/base-image -.. [2] https://blueprints.launchpad.net/octavia/+spec/controller-worker -.. [3] https://blueprints.launchpad.net/octavia/+spec/amphora-driver-interface -.. [4] https://blueprints.launchpad.net/octavia/+spec/controller -.. [5] https://blueprints.launchpad.net/octavia/+spec/operator-api -.. [6] :doc:`../../api/haproxy-amphora-api` -.. [7] https://blueprints.launchpad.net/octavia/+spec/active-active-topology +https://blueprints.launchpad.net/octavia/+spec/base-image +https://blueprints.launchpad.net/octavia/+spec/controller-worker +https://blueprints.launchpad.net/octavia/+spec/amphora-driver-interface +https://blueprints.launchpad.net/octavia/+spec/controller +https://blueprints.launchpad.net/octavia/+spec/operator-api +:doc:`../../api/haproxy-amphora-api` +https://blueprints.launchpad.net/octavia/+spec/active-active-topology diff --git a/specs/version0.9/active-active-topology.rst b/specs/version0.9/active-active-topology.rst index fd318ef5e6..4deca38c4c 100644 --- a/specs/version0.9/active-active-topology.rst +++ b/specs/version0.9/active-active-topology.rst @@ -626,10 +626,10 @@ Octavia with ACTIVE-ACTIVE topology. References ========== -.. [1] https://blueprints.launchpad.net/octavia/+spec/base-image -.. [2] https://blueprints.launchpad.net/octavia/+spec/controller-worker -.. [3] https://blueprints.launchpad.net/octavia/+spec/amphora-driver-interface -.. [4] https://blueprints.launchpad.net/octavia/+spec/controller -.. [5] https://blueprints.launchpad.net/octavia/+spec/operator-api -.. [6] :doc:`../../api/haproxy-amphora-api` -.. [7] https://blueprints.launchpad.net/octavia/+spec/active-active-topology +https://blueprints.launchpad.net/octavia/+spec/base-image +https://blueprints.launchpad.net/octavia/+spec/controller-worker +https://blueprints.launchpad.net/octavia/+spec/amphora-driver-interface +https://blueprints.launchpad.net/octavia/+spec/controller +https://blueprints.launchpad.net/octavia/+spec/operator-api +:doc:`../../api/haproxy-amphora-api` +https://blueprints.launchpad.net/octavia/+spec/active-active-topology diff --git a/specs/version1/health_ip_port.rst b/specs/version1.0/health_ip_port.rst similarity index 100% rename from specs/version1/health_ip_port.rst rename to specs/version1.0/health_ip_port.rst diff --git a/specs/version1/n-lbaas-api-parity.rst b/specs/version1.0/n-lbaas-api-parity.rst similarity index 100% rename from specs/version1/n-lbaas-api-parity.rst rename to specs/version1.0/n-lbaas-api-parity.rst diff --git a/specs/version1/vip-qos-policy-application.rst b/specs/version1.0/vip-qos-policy-application.rst similarity index 100% rename from specs/version1/vip-qos-policy-application.rst rename to specs/version1.0/vip-qos-policy-application.rst diff --git a/tools/create_flow_docs.py b/tools/create_flow_docs.py index 4d4d91683d..5819188f8c 100755 --- a/tools/create_flow_docs.py +++ b/tools/create_flow_docs.py @@ -98,7 +98,7 @@ def generate(flow_list, output_directory): current_doc_file.write('.. image:: ' + doc_tuple[0] + '-' + doc_tuple[1] + '.svg\n') current_doc_file.write(' :width: 660px\n') - current_doc_file.write(' :target: ../../_images/' + + current_doc_file.write(' :target: ../../../_images/' + doc_tuple[0] + '-' + doc_tuple[1] + '.svg\n') @@ -129,7 +129,7 @@ def generate(flow_list, output_directory): current_doc_file.write('.. image:: ' + doc_tuple[0] + '-' + doc_tuple[1] + '.svg\n') current_doc_file.write(' :width: 660px\n') - current_doc_file.write(' :target: ../../_images/' + + current_doc_file.write(' :target: ../../../_images/' + doc_tuple[0] + '-' + doc_tuple[1] + '.svg\n')