Retire Packaging Deb project repos
This commit is part of a series to retire the Packaging Deb project. Step 2 is to remove all content from the project repos, replacing it with a README notification where to find ongoing work, and how to recover the repo if needed at some future point (as in https://docs.openstack.org/infra/manual/drivers.html#retiring-a-project). Change-Id: I548868a77d769b1466ab02aa43a9f290bf592643
This commit is contained in:
Tony Breeds
parent
609045ebb2
commit
ab766108a5
@ -1,8 +0,0 @@
|
||||
[run]
|
||||
branch = True
|
||||
omit = zaqar/tests/*
|
||||
|
||||
[report]
|
||||
exclude_lines =
|
||||
if _ZAQAR_SETUP__:
|
||||
raise NotImplementedError
|
||||
29
.gitignore
vendored
29
.gitignore
vendored
@ -1,29 +0,0 @@
|
||||
*.bak
|
||||
*.DS_Store
|
||||
target/
|
||||
*.pyc
|
||||
*.dat
|
||||
TAGS
|
||||
*.egg-info
|
||||
*.egg
|
||||
build
|
||||
.coverage
|
||||
.tox
|
||||
cover
|
||||
venv
|
||||
.venv
|
||||
output.xml
|
||||
*.sublime-workspace
|
||||
*.sqlite
|
||||
*.html
|
||||
.*.swp
|
||||
.DS_Store
|
||||
.testrepository
|
||||
versioninfo
|
||||
var/*
|
||||
ChangeLog
|
||||
AUTHORS
|
||||
etc/zaqar.conf.sample
|
||||
.idea
|
||||
# Files created by releasenotes build
|
||||
releasenotes/build
|
||||
@ -1,4 +0,0 @@
|
||||
[gerrit]
|
||||
host=review.openstack.org
|
||||
port=29418
|
||||
project=openstack/zaqar.git
|
||||
@ -1,7 +0,0 @@
|
||||
[DEFAULT]
|
||||
test_command=OS_STDOUT_CAPTURE=${OS_STDOUT_CAPTURE:-1} \
|
||||
OS_STDERR_CAPTURE=${OS_STDERR_CAPTURE:-1} \
|
||||
OS_TEST_TIMEOUT=${OS_TEST_TIMEOUT:-60} \
|
||||
${PYTHON:-python} $JIT_FLAG -m subunit.run discover -t ${OS_TOP_LEVEL:-./} ${OS_TEST_PATH:-./zaqar/tests/unit} $LISTOPT $IDOPTION
|
||||
test_id_option=--load-list $IDFILE
|
||||
test_list_option=--list
|
||||
14
AUTHORS.rst
14
AUTHORS.rst
@ -1,14 +0,0 @@
|
||||
Maintainer
|
||||
----------
|
||||
OpenStack Foundation
|
||||
IRC: #openstack on irc.freenode.net
|
||||
|
||||
Original Authors
|
||||
----------------
|
||||
Bryan Davidson (bryan.davidson@rackspace.com)
|
||||
Kurt Griffiths (mail@kgriffs.com)
|
||||
Jamie Painter (jamie.painter@rackspace.com)
|
||||
Flavio Premoli (flaper87@flaper87.org)
|
||||
Zhihao Yuan (lichray@gmail.com)
|
||||
|
||||
See also AUTHORS for a complete list of contributors.
|
||||
@ -1,19 +0,0 @@
|
||||
If you would like to contribute to the development of OpenStack,
|
||||
you must follow the steps in this page:
|
||||
|
||||
https://docs.openstack.org/infra/manual/developers.html
|
||||
|
||||
Once those steps have been completed, changes to OpenStack
|
||||
should be submitted for review via the Gerrit tool, following
|
||||
the workflow documented at:
|
||||
|
||||
https://docs.openstack.org/infra/manual/developers.html#development-workflow
|
||||
|
||||
Pull requests submitted through GitHub will be ignored.
|
||||
|
||||
Bugs should be filed on Launchpad, not GitHub:
|
||||
|
||||
https://bugs.launchpad.net/zaqar
|
||||
|
||||
|
||||
|
||||
136
HACKING.rst
136
HACKING.rst
@ -1,136 +0,0 @@
|
||||
========================
|
||||
Zaqar style commandments
|
||||
========================
|
||||
|
||||
- Step 1: Read the OpenStack Style Commandments
|
||||
https://docs.openstack.org/developer/hacking/
|
||||
- Step 2: Read on for Zaqar specific commandments
|
||||
|
||||
General
|
||||
-------
|
||||
- Optimize for readability; whitespace is your friend.
|
||||
- Use blank lines to group related logic.
|
||||
- All classes must inherit from ``object`` (explicitly).
|
||||
- Use single-quotes for strings unless the string contains a
|
||||
single-quote.
|
||||
- Use the double-quote character for blockquotes (``"""``, not ``'''``)
|
||||
- USE_ALL_CAPS_FOR_GLOBAL_CONSTANTS
|
||||
|
||||
Comments
|
||||
--------
|
||||
- In general use comments as "memory pegs" for those coming after you up
|
||||
the trail.
|
||||
- Guide the reader though long functions with a comments introducing
|
||||
different sections of the code.
|
||||
- Choose clean, descriptive names for functions and variables to make
|
||||
them self-documenting.
|
||||
- Add ``# NOTE(termie): blah blah...`` comments to clarify your intent, or
|
||||
to explain a tricky algorithm, when it isn't obvious from just reading
|
||||
the code.
|
||||
|
||||
|
||||
Identifiers
|
||||
-----------
|
||||
- Don't use single characters in identifiers except in trivial loop variables and mathematical algorithms.
|
||||
- Avoid abbreviations, especially if they are ambiguous or their meaning would not be immediately clear to the casual reader or newcomer.
|
||||
|
||||
Wrapping
|
||||
--------
|
||||
Wrap long lines by using Python's implied line continuation inside
|
||||
parentheses, brackets and braces. Make sure to indent the continued
|
||||
line appropriately. The preferred place to break around a binary
|
||||
operator is after the operator, not before it.
|
||||
|
||||
Example::
|
||||
|
||||
class Rectangle(Blob):
|
||||
|
||||
def __init__(self, width, height,
|
||||
color='black', emphasis=None, highlight=0):
|
||||
|
||||
# More indentation included to distinguish this from the rest.
|
||||
if (width == 0 and height == 0 and
|
||||
color == 'red' and emphasis == 'strong' or
|
||||
highlight > 100):
|
||||
raise ValueError('sorry, you lose')
|
||||
|
||||
if width == 0 and height == 0 and (color == 'red' or
|
||||
emphasis is None):
|
||||
raise ValueError("I don't think so -- values are {0}, {1}".format(
|
||||
width, height))
|
||||
|
||||
msg = ('this is a very long string that goes on and on and on and'
|
||||
'on and on and on...')
|
||||
|
||||
super(Rectangle, self).__init__(width, height,
|
||||
color, emphasis, highlight)
|
||||
|
||||
|
||||
Imports
|
||||
-------
|
||||
- Classes and functions may be hoisted into a package namespace, via __init__ files, with some discretion.
|
||||
|
||||
More Import Examples
|
||||
--------------------
|
||||
|
||||
**INCORRECT** ::
|
||||
|
||||
import zaqar.transport.wsgi as wsgi
|
||||
|
||||
**CORRECT** ::
|
||||
|
||||
from zaqar.transport import wsgi
|
||||
|
||||
Docstrings
|
||||
----------
|
||||
|
||||
Docstrings are required for all functions and methods.
|
||||
|
||||
Docstrings should ONLY use triple-double-quotes (``"""``)
|
||||
|
||||
Single-line docstrings should NEVER have extraneous whitespace
|
||||
between enclosing triple-double-quotes.
|
||||
|
||||
**INCORRECT** ::
|
||||
|
||||
""" There is some whitespace between the enclosing quotes :( """
|
||||
|
||||
**CORRECT** ::
|
||||
|
||||
"""There is no whitespace between the enclosing quotes :)"""
|
||||
|
||||
Docstrings should document default values for named arguments
|
||||
if they're not None
|
||||
|
||||
Docstrings that span more than one line should look like this:
|
||||
|
||||
Example::
|
||||
|
||||
"""Single-line summary, right after the opening triple-double-quote.
|
||||
|
||||
If you are going to describe parameters and return values, use Sphinx; the
|
||||
appropriate syntax is as follows.
|
||||
|
||||
:param foo: the foo parameter
|
||||
:param bar: (Default True) the bar parameter
|
||||
:param foo_long_bar: the foo parameter description is very
|
||||
long so we have to split it in multiple lines in order to
|
||||
keep things ordered
|
||||
:returns: return_type -- description of the return value
|
||||
:returns: description of the return value
|
||||
:raises ValueError: if the message_body exceeds 160 characters
|
||||
:raises TypeError: if the message_body is not a basestring
|
||||
"""
|
||||
|
||||
**DO NOT** leave an extra newline before the closing triple-double-quote.
|
||||
|
||||
Creating Unit Tests
|
||||
-------------------
|
||||
NOTE: 100% coverage is required
|
||||
|
||||
Logging
|
||||
-------
|
||||
Use __name__ as the name of your logger and name your module-level logger
|
||||
objects 'LOG'::
|
||||
|
||||
LOG = logging.getLogger(__name__)
|
||||
176
LICENSE
176
LICENSE
@ -1,176 +0,0 @@
|
||||
|
||||
Apache License
|
||||
Version 2.0, January 2004
|
||||
http://www.apache.org/licenses/
|
||||
|
||||
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||
|
||||
1. Definitions.
|
||||
|
||||
"License" shall mean the terms and conditions for use, reproduction,
|
||||
and distribution as defined by Sections 1 through 9 of this document.
|
||||
|
||||
"Licensor" shall mean the copyright owner or entity authorized by
|
||||
the copyright owner that is granting the License.
|
||||
|
||||
"Legal Entity" shall mean the union of the acting entity and all
|
||||
other entities that control, are controlled by, or are under common
|
||||
control with that entity. For the purposes of this definition,
|
||||
"control" means (i) the power, direct or indirect, to cause the
|
||||
direction or management of such entity, whether by contract or
|
||||
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||
|
||||
"You" (or "Your") shall mean an individual or Legal Entity
|
||||
exercising permissions granted by this License.
|
||||
|
||||
"Source" form shall mean the preferred form for making modifications,
|
||||
including but not limited to software source code, documentation
|
||||
source, and configuration files.
|
||||
|
||||
"Object" form shall mean any form resulting from mechanical
|
||||
transformation or translation of a Source form, including but
|
||||
not limited to compiled object code, generated documentation,
|
||||
and conversions to other media types.
|
||||
|
||||
"Work" shall mean the work of authorship, whether in Source or
|
||||
Object form, made available under the License, as indicated by a
|
||||
copyright notice that is included in or attached to the work
|
||||
(an example is provided in the Appendix below).
|
||||
|
||||
"Derivative Works" shall mean any work, whether in Source or Object
|
||||
form, that is based on (or derived from) the Work and for which the
|
||||
editorial revisions, annotations, elaborations, or other modifications
|
||||
represent, as a whole, an original work of authorship. For the purposes
|
||||
of this License, Derivative Works shall not include works that remain
|
||||
separable from, or merely link (or bind by name) to the interfaces of,
|
||||
the Work and Derivative Works thereof.
|
||||
|
||||
"Contribution" shall mean any work of authorship, including
|
||||
the original version of the Work and any modifications or additions
|
||||
to that Work or Derivative Works thereof, that is intentionally
|
||||
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||
or by an individual or Legal Entity authorized to submit on behalf of
|
||||
the copyright owner. For the purposes of this definition, "submitted"
|
||||
means any form of electronic, verbal, or written communication sent
|
||||
to the Licensor or its representatives, including but not limited to
|
||||
communication on electronic mailing lists, source code control systems,
|
||||
and issue tracking systems that are managed by, or on behalf of, the
|
||||
Licensor for the purpose of discussing and improving the Work, but
|
||||
excluding communication that is conspicuously marked or otherwise
|
||||
designated in writing by the copyright owner as "Not a Contribution."
|
||||
|
||||
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||
on behalf of whom a Contribution has been received by Licensor and
|
||||
subsequently incorporated within the Work.
|
||||
|
||||
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
copyright license to reproduce, prepare Derivative Works of,
|
||||
publicly display, publicly perform, sublicense, and distribute the
|
||||
Work and such Derivative Works in Source or Object form.
|
||||
|
||||
3. Grant of Patent License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
(except as stated in this section) patent license to make, have made,
|
||||
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||
where such license applies only to those patent claims licensable
|
||||
by such Contributor that are necessarily infringed by their
|
||||
Contribution(s) alone or by combination of their Contribution(s)
|
||||
with the Work to which such Contribution(s) was submitted. If You
|
||||
institute patent litigation against any entity (including a
|
||||
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||
or a Contribution incorporated within the Work constitutes direct
|
||||
or contributory patent infringement, then any patent licenses
|
||||
granted to You under this License for that Work shall terminate
|
||||
as of the date such litigation is filed.
|
||||
|
||||
4. Redistribution. You may reproduce and distribute copies of the
|
||||
Work or Derivative Works thereof in any medium, with or without
|
||||
modifications, and in Source or Object form, provided that You
|
||||
meet the following conditions:
|
||||
|
||||
(a) You must give any other recipients of the Work or
|
||||
Derivative Works a copy of this License; and
|
||||
|
||||
(b) You must cause any modified files to carry prominent notices
|
||||
stating that You changed the files; and
|
||||
|
||||
(c) You must retain, in the Source form of any Derivative Works
|
||||
that You distribute, all copyright, patent, trademark, and
|
||||
attribution notices from the Source form of the Work,
|
||||
excluding those notices that do not pertain to any part of
|
||||
the Derivative Works; and
|
||||
|
||||
(d) If the Work includes a "NOTICE" text file as part of its
|
||||
distribution, then any Derivative Works that You distribute must
|
||||
include a readable copy of the attribution notices contained
|
||||
within such NOTICE file, excluding those notices that do not
|
||||
pertain to any part of the Derivative Works, in at least one
|
||||
of the following places: within a NOTICE text file distributed
|
||||
as part of the Derivative Works; within the Source form or
|
||||
documentation, if provided along with the Derivative Works; or,
|
||||
within a display generated by the Derivative Works, if and
|
||||
wherever such third-party notices normally appear. The contents
|
||||
of the NOTICE file are for informational purposes only and
|
||||
do not modify the License. You may add Your own attribution
|
||||
notices within Derivative Works that You distribute, alongside
|
||||
or as an addendum to the NOTICE text from the Work, provided
|
||||
that such additional attribution notices cannot be construed
|
||||
as modifying the License.
|
||||
|
||||
You may add Your own copyright statement to Your modifications and
|
||||
may provide additional or different license terms and conditions
|
||||
for use, reproduction, or distribution of Your modifications, or
|
||||
for any such Derivative Works as a whole, provided Your use,
|
||||
reproduction, and distribution of the Work otherwise complies with
|
||||
the conditions stated in this License.
|
||||
|
||||
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||
any Contribution intentionally submitted for inclusion in the Work
|
||||
by You to the Licensor shall be under the terms and conditions of
|
||||
this License, without any additional terms or conditions.
|
||||
Notwithstanding the above, nothing herein shall supersede or modify
|
||||
the terms of any separate license agreement you may have executed
|
||||
with Licensor regarding such Contributions.
|
||||
|
||||
6. Trademarks. This License does not grant permission to use the trade
|
||||
names, trademarks, service marks, or product names of the Licensor,
|
||||
except as required for reasonable and customary use in describing the
|
||||
origin of the Work and reproducing the content of the NOTICE file.
|
||||
|
||||
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||
agreed to in writing, Licensor provides the Work (and each
|
||||
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
implied, including, without limitation, any warranties or conditions
|
||||
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||
appropriateness of using or redistributing the Work and assume any
|
||||
risks associated with Your exercise of permissions under this License.
|
||||
|
||||
8. Limitation of Liability. In no event and under no legal theory,
|
||||
whether in tort (including negligence), contract, or otherwise,
|
||||
unless required by applicable law (such as deliberate and grossly
|
||||
negligent acts) or agreed to in writing, shall any Contributor be
|
||||
liable to You for damages, including any direct, indirect, special,
|
||||
incidental, or consequential damages of any character arising as a
|
||||
result of this License or out of the use or inability to use the
|
||||
Work (including but not limited to damages for loss of goodwill,
|
||||
work stoppage, computer failure or malfunction, or any and all
|
||||
other commercial damages or losses), even if such Contributor
|
||||
has been advised of the possibility of such damages.
|
||||
|
||||
9. Accepting Warranty or Additional Liability. While redistributing
|
||||
the Work or Derivative Works thereof, You may choose to offer,
|
||||
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||
or other liability obligations and/or rights consistent with this
|
||||
License. However, in accepting such obligations, You may act only
|
||||
on Your own behalf and on Your sole responsibility, not on behalf
|
||||
of any other Contributor, and only if You agree to indemnify,
|
||||
defend, and hold each Contributor harmless for any liability
|
||||
incurred by, or claims asserted against, such Contributor by reason
|
||||
of your accepting any such warranty or additional liability.
|
||||
|
||||
14
README
Normal file
14
README
Normal file
@ -0,0 +1,14 @@
|
||||
This project is no longer maintained.
|
||||
|
||||
The contents of this repository are still available in the Git
|
||||
source code management system. To see the contents of this
|
||||
repository before it reached its end of life, please check out the
|
||||
previous commit with "git checkout HEAD^1".
|
||||
|
||||
For ongoing work on maintaining OpenStack packages in the Debian
|
||||
distribution, please see the Debian OpenStack packaging team at
|
||||
https://wiki.debian.org/OpenStack/.
|
||||
|
||||
For any further questions, please email
|
||||
openstack-dev@lists.openstack.org or join #openstack-dev on
|
||||
Freenode.
|
||||
73
README.rst
73
README.rst
@ -1,73 +0,0 @@
|
||||
========================
|
||||
Team and repository tags
|
||||
========================
|
||||
|
||||
.. image:: https://governance.openstack.org/badges/zaqar.svg
|
||||
:target: https://governance.openstack.org/reference/tags/index.html
|
||||
|
||||
.. Change things from this point on
|
||||
|
||||
=====
|
||||
Zaqar
|
||||
=====
|
||||
|
||||
Zaqar is a multi-tenant cloud messaging and notification service for web
|
||||
and mobile developers.
|
||||
It combines the ideas pioneered by Amazon's SQS product with additional
|
||||
semantics to support event broadcasting.
|
||||
|
||||
The service features a fully RESTful API, which developers can use to send
|
||||
messages between various components of their SaaS and mobile applications, by
|
||||
using a variety of communication patterns. Underlying this API is an efficient
|
||||
messaging engine designed with scalability and security in mind.
|
||||
|
||||
Other OpenStack components can integrate with Zaqar to surface events to end
|
||||
users and to communicate with guest agents that run in the "over-cloud" layer.
|
||||
Cloud operators can leverage Zaqar to provide equivalents of SQS and SNS to
|
||||
their customers.
|
||||
|
||||
General information is available in wiki:
|
||||
|
||||
https://wiki.openstack.org/wiki/Zaqar
|
||||
|
||||
The API v2.0 (stable) specification and documentation are available at:
|
||||
|
||||
https://wiki.openstack.org/wiki/Zaqar/specs/api/v2.0
|
||||
|
||||
Zaqar's Documentation, the source of which is in ``doc/source/``, is
|
||||
available at:
|
||||
|
||||
https://docs.openstack.org/zaqar/latest
|
||||
|
||||
Contributors are encouraged to join IRC (``#openstack-zaqar`` channel on
|
||||
``irc.freenode.net``):
|
||||
|
||||
https://wiki.openstack.org/wiki/IRC
|
||||
|
||||
Information on how to run unit and functional tests is available at:
|
||||
|
||||
https://docs.openstack.org/zaqar/admin/running_tests.html
|
||||
|
||||
Information on how to run benchmarking tool is available at:
|
||||
|
||||
https://docs.openstack.org/zaqar/admin/running_benchmark.html
|
||||
|
||||
Using Zaqar
|
||||
-----------
|
||||
|
||||
If you are new to Zaqar and just want to try it, you can set up Zaqar in
|
||||
the development environment.
|
||||
|
||||
Using Zaqar in production environment:
|
||||
|
||||
Coming soon!
|
||||
|
||||
Using Zaqar in development environment:
|
||||
|
||||
The instruction is available at:
|
||||
|
||||
https://docs.openstack.org/zaqar/contributor/development.environment.html
|
||||
|
||||
This will allow you to run local Zaqar server with MongoDB as database.
|
||||
|
||||
This way is the easiest, quickest and most suitable for beginners.
|
||||
@ -1,218 +0,0 @@
|
||||
===============
|
||||
Claims (claims)
|
||||
===============
|
||||
Claim is a mechanism to mark messages so that other workers will not process
|
||||
the same message.
|
||||
|
||||
Claim messages
|
||||
==============
|
||||
|
||||
.. rest_method:: POST /v2/queues/{queue_name}/claims
|
||||
|
||||
Claims a set of messages from the specified queue.
|
||||
|
||||
This operation claims a set of messages (up to the value of the ``limit``
|
||||
parameter) from oldest to newest and skips any messages that are already
|
||||
claimed. If no unclaimed messages are available, the API returns a
|
||||
``204 No Content`` message.
|
||||
|
||||
When a client (worker) finishes processing a message, it should delete the
|
||||
message before the claim expires to ensure that the message is processed only
|
||||
once. As part of the delete operation, workers should specify the claim ID
|
||||
(which is best done by simply using the provided href). If workers perform
|
||||
these actions, then if a claim simply expires, the server can return an error
|
||||
and notify the worker of the race condition. This action gives the worker a
|
||||
chance to roll back its own processing of the given message because another
|
||||
worker can claim the message and process it.
|
||||
|
||||
The age given for a claim is relative to the server's clock. The claim's age
|
||||
is useful for determining how quickly messages are getting processed and
|
||||
whether a given message's claim is about to expire.
|
||||
|
||||
When a claim expires, it is released. If the original worker failed to process
|
||||
the message, another client worker can then claim the message.
|
||||
|
||||
Note that claim creation is best-effort, meaning the worker may claim and
|
||||
return less than the requested number of messages.
|
||||
|
||||
The ``ttl`` attribute specifies how long the server waits before releasing
|
||||
the claim. The ttl value must be between 60 and 43200 seconds (12 hours).
|
||||
You must include a value for this attribute in your request.
|
||||
|
||||
The ``grace`` attribute specifies the message grace period in seconds. The
|
||||
value of ``grace`` value must be between 60 and 43200 seconds (12 hours).
|
||||
You must include a value for this attribute in your request. To deal with
|
||||
workers that have stopped responding (for up to 1209600 seconds or 14 days,
|
||||
including claim lifetime), the server extends the lifetime of claimed messages
|
||||
to be at least as long as the lifetime of the claim itself, plus the specified
|
||||
grace period. If a claimed message would normally live longer than the claim's
|
||||
live period, its expiration is not adjusted.
|
||||
|
||||
|
||||
|
||||
Normal response codes: 201, 204
|
||||
|
||||
Error response codes:
|
||||
|
||||
- Unauthorized(401)
|
||||
- Forbidden(403)
|
||||
- itemNotFound(404)
|
||||
- ServiceUnavailable(503)
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queue_name: queue_name
|
||||
- limit: claim_limit
|
||||
- ttl: claim_ttl
|
||||
- grace: claim_grace
|
||||
|
||||
**Example Claim Messages: JSON request**
|
||||
|
||||
|
||||
.. literalinclude:: samples/claim_messages_request.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
**Example Claim Messages: JSON response**
|
||||
|
||||
|
||||
.. literalinclude:: samples/claim_messages_response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
|
||||
Query Claim
|
||||
===========
|
||||
|
||||
.. rest_method:: GET /v2/queues/{queue_name}/claims/{claim_id}
|
||||
|
||||
Queries the specified claim for the specified queue.
|
||||
|
||||
This operation queries the specified claim for the specified queue. Claims
|
||||
with malformed IDs or claims that are not found by ID are ignored.
|
||||
|
||||
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error response codes:
|
||||
|
||||
- Unauthorized(401)
|
||||
- Forbidden(403)
|
||||
- itemNotFound(404)
|
||||
- ServiceUnavailable(503)
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queue_name: queue_name
|
||||
- claim_id: claim_id
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
**Example Query Claim: JSON response**
|
||||
|
||||
|
||||
.. literalinclude:: samples/claim_query_response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
|
||||
Update(Renew) Claim
|
||||
===================
|
||||
|
||||
.. rest_method:: PATCH /v2/queues/{queue_name}/claims/{claim_id}
|
||||
|
||||
Updates the specified claim for the specified queue.
|
||||
|
||||
This operation updates the specified claim for the specified queue. Claims
|
||||
with malformed IDs or claims that are not found by ID are ignored.
|
||||
|
||||
Clients should periodically renew claims during long-running batches of work
|
||||
to avoid losing a claim while processing a message. The client can renew a
|
||||
claim by issuing a ``PATCH`` command to a specific claim resource and
|
||||
including a new TTL for the claim (which can be different from the original
|
||||
TTL). The server resets the age of the claim and applies the new TTL.
|
||||
|
||||
|
||||
|
||||
Normal response codes: 204
|
||||
|
||||
Error response codes:
|
||||
|
||||
- Unauthorized(401)
|
||||
- Forbidden(403)
|
||||
- itemNotFound(404)
|
||||
- ServiceUnavailable(503)
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queue_name: queue_name
|
||||
- claim_id: claim_id
|
||||
- ttl: claim_ttl
|
||||
- grace: claim_grace
|
||||
|
||||
**Example Update Claim: JSON request**
|
||||
|
||||
|
||||
.. literalinclude:: samples/claim_update_request.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
This operation does not return a response body.
|
||||
|
||||
|
||||
Delete(Release) Claim
|
||||
=====================
|
||||
|
||||
.. rest_method:: DELETE /v2/queues/{queue_name}/claims/{claim_id}
|
||||
|
||||
Releases the specified claim for the specified queue.
|
||||
|
||||
This operation immediately releases a claim, making any remaining, undeleted)
|
||||
messages that are associated with the claim available to other workers. Claims
|
||||
with malformed IDs or claims that are not found by ID are ignored.
|
||||
|
||||
This operation is useful when a worker is performing a graceful shutdown,
|
||||
fails to process one or more messages, or is taking longer than expected to
|
||||
process messages, and wants to make the remainder of the messages available
|
||||
to other workers.
|
||||
|
||||
|
||||
|
||||
Normal response codes: 204
|
||||
|
||||
Error response codes:
|
||||
|
||||
- Unauthorized(401)
|
||||
- Forbidden(403)
|
||||
- itemNotFound(404)
|
||||
- ServiceUnavailable(503)
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queue_name: queue_name
|
||||
- claim_id: claim_id
|
||||
|
||||
|
||||
This operation does not accept a request body and does not return a response
|
||||
body.
|
||||
@ -1,229 +0,0 @@
|
||||
# Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
# not use this file except in compliance with the License. You may obtain
|
||||
# a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
# License for the specific language governing permissions and limitations
|
||||
# under the License.
|
||||
#
|
||||
# nova documentation build configuration file, created by
|
||||
# sphinx-quickstart on Sat May 1 15:17:47 2010.
|
||||
#
|
||||
# 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 os
|
||||
import subprocess
|
||||
import sys
|
||||
|
||||
import openstackdocstheme
|
||||
|
||||
html_theme = 'openstackdocs'
|
||||
html_theme_path = [openstackdocstheme.get_html_theme_path()]
|
||||
html_theme_options = {
|
||||
"sidebar_mode": "toc",
|
||||
}
|
||||
|
||||
extensions = [
|
||||
'os_api_ref',
|
||||
]
|
||||
|
||||
# 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('../'))
|
||||
sys.path.insert(0, os.path.abspath('./'))
|
||||
|
||||
# -- General configuration ----------------------------------------------------
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
|
||||
|
||||
# The suffix of source filenames.
|
||||
source_suffix = '.rst'
|
||||
|
||||
# The encoding of source files.
|
||||
#
|
||||
# source_encoding = 'utf-8'
|
||||
|
||||
# The master toctree document.
|
||||
master_doc = 'index'
|
||||
|
||||
# General information about the project.
|
||||
project = u'Messaging Service API Reference'
|
||||
copyright = u'2010-present, OpenStack Foundation'
|
||||
|
||||
# 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.
|
||||
#
|
||||
from zaqar.version import version_info
|
||||
# The full version, including alpha/beta/rc tags.
|
||||
release = version_info.release_string()
|
||||
# The short X.Y version.
|
||||
version = version_info.version_string()
|
||||
|
||||
# Config logABug feature
|
||||
giturl = u'http://git.openstack.org/cgit/openstack/zaqar/tree/api-ref/source'
|
||||
# source tree
|
||||
# html_context allows us to pass arbitrary values into the html template
|
||||
html_context = {'bug_tag': 'api-ref',
|
||||
'giturl': giturl,
|
||||
'bug_project': 'zaqar'}
|
||||
|
||||
# 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'
|
||||
|
||||
# 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 = False
|
||||
|
||||
# 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'
|
||||
|
||||
# -- Options for man page output ----------------------------------------------
|
||||
|
||||
# Grouping the document tree for man pages.
|
||||
# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual'
|
||||
|
||||
|
||||
# -- Options for HTML output --------------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. Major themes that come with
|
||||
# Sphinx are currently 'default' and 'sphinxdoc'.
|
||||
# html_theme_path = ["."]
|
||||
# html_theme = '_theme'
|
||||
|
||||
# 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
|
||||
# "<project> v<release> 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']
|
||||
|
||||
# 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'
|
||||
git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local",
|
||||
"-n1"]
|
||||
html_last_updated_fmt = subprocess.check_output(git_cmd).decode('utf-8')
|
||||
|
||||
# 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_use_modindex = 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, an OpenSearch description file will be output, and all pages will
|
||||
# contain a <link> tag referring to it. The value of this option must be the
|
||||
# base URL from which the finished HTML is served.
|
||||
# html_use_opensearch = ''
|
||||
|
||||
# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
|
||||
# html_file_suffix = ''
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = 'zaqardoc'
|
||||
|
||||
|
||||
# -- Options for LaTeX output -------------------------------------------------
|
||||
|
||||
# The paper size ('letter' or 'a4').
|
||||
# latex_paper_size = 'letter'
|
||||
|
||||
# The font size ('10pt', '11pt' or '12pt').
|
||||
# latex_font_size = '10pt'
|
||||
|
||||
# Grouping the document tree into LaTeX files. List of tuples
|
||||
# (source start file, target name, title, author, documentclass
|
||||
# [howto/manual]).
|
||||
latex_documents = [
|
||||
('index', 'Zaqar.tex', u'OpenStack Messaging Service API Documentation',
|
||||
u'OpenStack Foundation', '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
|
||||
|
||||
# Additional stuff for the LaTeX preamble.
|
||||
# latex_preamble = ''
|
||||
|
||||
# Documents to append as an appendix to all manuals.
|
||||
# latex_appendices = []
|
||||
|
||||
# If false, no module index is generated.
|
||||
# latex_use_modindex = True
|
||||
@ -1,207 +0,0 @@
|
||||
=================
|
||||
Flavors (flavors)
|
||||
=================
|
||||
|
||||
Queue flavors allow users to have different types of queues based on the
|
||||
storage capabilities. By using flavors, it's possible to allow consumers of the
|
||||
service to choose between durable storage, fast storage, etc. Flavors must be
|
||||
created by service administrators and they rely on the existence of pools.
|
||||
|
||||
List flavors
|
||||
============
|
||||
|
||||
.. rest_method:: GET /v2/flavors
|
||||
|
||||
Lists flavors.
|
||||
|
||||
This operation lists flavors for the project. The flavors are sorted
|
||||
alphabetically by name.
|
||||
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error response codes:
|
||||
|
||||
- Unauthorized (401)
|
||||
- Forbidden (403)
|
||||
|
||||
Query Parameters
|
||||
-----------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- limit: limit
|
||||
- marker: marker
|
||||
- detailed: detailed
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- flavors: flavors
|
||||
- links: flavor_links
|
||||
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/flavor-list-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Create flavor
|
||||
=============
|
||||
|
||||
.. rest_method:: PUT /v2/flavors/{flavor_name}
|
||||
|
||||
Creates a flavor.
|
||||
|
||||
This operation creates a new flavor.
|
||||
|
||||
``flavor_name`` is the name that you give to the flavor. The name must not
|
||||
exceed 64 bytes in length, and it is limited to US-ASCII letters, digits,
|
||||
underscores, and hyphens.
|
||||
|
||||
|
||||
Normal response codes: 201
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- Forbidden (403)
|
||||
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- flavor_name: flavor_name_path
|
||||
- pool_group: flavor_pool_group
|
||||
|
||||
Request Example
|
||||
---------------
|
||||
|
||||
.. literalinclude:: samples/flavor-create-request.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
This operation does not return a response body.
|
||||
|
||||
|
||||
Update flavor
|
||||
=============
|
||||
|
||||
.. rest_method:: PATCH /v2/flavors/{flavor_name}
|
||||
|
||||
Updates a flavor.
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- Forbidden (403)
|
||||
- Not Found (404)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- flavor_name: flavor_name_path
|
||||
- pool_group: flavor_pool_group
|
||||
|
||||
|
||||
Request Example
|
||||
---------------
|
||||
|
||||
.. literalinclude:: samples/flavor-update-request.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/flavor-update-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Show flavor details
|
||||
===================
|
||||
|
||||
.. rest_method:: GET /v2/flavors/{flavor_name}
|
||||
|
||||
Shows details for a flavor.
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- Forbidden (403)
|
||||
- Not Found (404)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- flavor_name: flavor_name_path
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- name: flavor_name
|
||||
- capabilities: capabilities
|
||||
- pool_group: flavor_pool_group
|
||||
- href: flavor_href
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/flavor-show-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Delete flavor
|
||||
=============
|
||||
|
||||
.. rest_method:: DELETE /v2/flavors/{flavor_name}
|
||||
|
||||
Deletes the specified flavor.
|
||||
|
||||
This operation immediately deletes a flavor.
|
||||
|
||||
``flavor_name`` is the name that you give to the flavor. The name must not
|
||||
exceed 64 bytes in length, and it is limited to US-ASCII letters, digits,
|
||||
underscores, and hyphens.
|
||||
|
||||
|
||||
Normal response codes: 204
|
||||
|
||||
Error response codes:
|
||||
|
||||
- Unauthorized (401)
|
||||
- Forbidden (403)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- flavor_name: flavor_name_path
|
||||
|
||||
This operation does not accept a request body and does not return a response
|
||||
body.
|
||||
@ -1,69 +0,0 @@
|
||||
===============
|
||||
Health (health)
|
||||
===============
|
||||
With health API, user or operator can get a general idea about the status of
|
||||
Zaqar server. Those information can be used for basic validation, performance
|
||||
checking, etc.
|
||||
|
||||
Ping
|
||||
====
|
||||
|
||||
.. rest_method:: GET /v2/ping
|
||||
|
||||
Simple health check for end user.
|
||||
|
||||
A request to ping Zaqar server when server is working returns 204, otherwise
|
||||
returns 503. This can be a handy API for end user to check if the messaging
|
||||
service is in working status.
|
||||
|
||||
Normal response codes: 204
|
||||
|
||||
Error response codes:
|
||||
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
|
||||
This operation does not accept a request body and does not return a response
|
||||
body.
|
||||
|
||||
|
||||
Health
|
||||
======
|
||||
|
||||
.. rest_method:: GET /v2/health
|
||||
|
||||
Detailed health check for cloud operator/admin.
|
||||
|
||||
This is an ``admin only`` API. A request to get detailed health information
|
||||
of Zaqar server.
|
||||
|
||||
The response body will depend on the storage setting of Zaqar server. By
|
||||
default, there is no pool created. Then the response body will only
|
||||
contain the ``catalog_reachable``. Otherwise, the response body will have
|
||||
``catalog_reachable`` and the health status for each pool.
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error response codes:
|
||||
|
||||
- Unauthorized (401)
|
||||
- Forbidden (403)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- catalog_reachable: catalog_reachable
|
||||
- storage_reachable: storage_reachable
|
||||
- operation_status: operation_status
|
||||
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/health-response.json
|
||||
:language: javascript
|
||||
|
||||
@ -1,27 +0,0 @@
|
||||
..
|
||||
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
not use this file except in compliance with the License. You may obtain
|
||||
a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
License for the specific language governing permissions and limitations
|
||||
under the License.
|
||||
|
||||
:tocdepth: 2
|
||||
|
||||
==================================
|
||||
Messaging Service API v2 (CURRENT)
|
||||
==================================
|
||||
|
||||
.. include:: versions.inc
|
||||
.. include:: queues.inc
|
||||
.. include:: messages.inc
|
||||
.. include:: claims.inc
|
||||
.. include:: subscription.inc
|
||||
.. include:: health.inc
|
||||
.. include:: pools.inc
|
||||
.. include:: flavors.inc
|
||||
@ -1,334 +0,0 @@
|
||||
===================
|
||||
Messages (messages)
|
||||
===================
|
||||
Message is sent through a queue and exists until it is deleted by a recipient
|
||||
or automatically by the system based on a TTL (time-to-live) value.
|
||||
|
||||
All message-related operations require Client-Id to be included in the headers.
|
||||
This is to ensure that messages are not echoed back to the client that posted
|
||||
them unless the client explicitly requests this.
|
||||
|
||||
Post Message
|
||||
============
|
||||
|
||||
.. rest_method:: POST /v2/queues/{queue_name}/messages
|
||||
|
||||
Posts the message or messages for the specified queue.
|
||||
|
||||
This operation posts the specified message or messages.
|
||||
|
||||
You can submit up to 10 messages in a single request, but you must always
|
||||
encapsulate the messages in a collection container (an array in JSON, even
|
||||
for a single message - without the JSON array, you receive the "Invalid request
|
||||
body" message). The resulting value of the Location header or response body
|
||||
might be used to retrieve the created messages for further processing.
|
||||
|
||||
The client specifies only the body and TTL for the message. The server inserts
|
||||
metadata, such as ID and age.
|
||||
|
||||
The response body contains a list of resource paths that correspond to each
|
||||
message submitted in the request, in the order of the messages. If a
|
||||
server-side error occurs during the processing of the submitted messages, a
|
||||
partial list is returned, the partial attribute is set to true, and the client
|
||||
tries to post the remaining messages again. If the server cannot enqueue any
|
||||
messages, the server returns a ``503 Service Unavailable`` error message.
|
||||
|
||||
The ``body`` attribute specifies an arbitrary document that constitutes the
|
||||
body of the message being sent.
|
||||
|
||||
.The following rules apply for the maximum size:
|
||||
|
||||
The maximum size of posted messages is the maximum size of the entire request
|
||||
document (rather than the sum of the individual message body field values as
|
||||
it was in earlier releases). On error, the client will now be notified of how
|
||||
much it exceeded the limit.
|
||||
|
||||
The size is limited to 256 KB, including whitespace.
|
||||
|
||||
The document must be valid JSON. (The Message Queuing service validates it.)
|
||||
|
||||
The ``ttl`` attribute specifies how long the server waits before marking the
|
||||
message as expired and removing it from the queue. The value of ``ttl`` must
|
||||
be between 60 and 1209600 seconds (14 days). Note that the server might not
|
||||
actually delete the message until its age has reached up to (ttl + 60) seconds,
|
||||
to allow for flexibility in storage implementations.
|
||||
|
||||
|
||||
Normal response codes: 201
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- Not Found (404)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queue_name: queue_name
|
||||
|
||||
Request Example
|
||||
---------------
|
||||
|
||||
.. literalinclude:: samples/messages-post-request.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- resources: messages_resources
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/messages-post-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
List Messages
|
||||
=============
|
||||
|
||||
.. rest_method:: GET /v2/queues/{queue_name}/messages
|
||||
|
||||
List the messages in the specified queue.
|
||||
|
||||
A request to list messages when the queue is not found or when messages are
|
||||
not found returns 204, instead of 200, because there was no information to
|
||||
send back. Messages with malformed IDs or messages that are not found by ID
|
||||
are ignored.
|
||||
|
||||
This operation gets the message or messages in the specified queue.
|
||||
|
||||
Message IDs and markers are opaque strings. Clients should make no assumptions
|
||||
about their format or length. Furthermore, clients should assume that there is
|
||||
no relationship between markers and message IDs (that is, one cannot be derived
|
||||
from the other). This allows for a wide variety of storage driver
|
||||
implementations.
|
||||
|
||||
Results are ordered by age, oldest message first.
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- Not Found (404)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queue_name: queue_name
|
||||
- marker: marker
|
||||
- limit: limit
|
||||
- echo: echo
|
||||
- include_claimed: include_claimed
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- messages: messages
|
||||
- links: links
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/messages-list-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Get A Set Of Messages By Id
|
||||
===========================
|
||||
|
||||
.. rest_method:: GET /v2/queues/{queue_name}/messages?ids={ids}
|
||||
|
||||
Gets a specified set of messages from the specified queue.
|
||||
|
||||
This operation provides a more efficient way to query multiple messages
|
||||
compared to using a series of individual ``GET`` s. Note that the list of IDs
|
||||
cannot exceed 20. If a malformed ID or a nonexistent message ID is provided,
|
||||
it is ignored, and the remaining messages are returned.
|
||||
|
||||
Unlike the Get Messages operation, a client's own messages are always returned
|
||||
in this operation. If you use the ids parameter, the echo parameter is not used
|
||||
and is ignored if it is specified.
|
||||
|
||||
The message attributes are defined as follows: ``href`` is an opaque relative
|
||||
URI that the client can use to uniquely identify a message resource and
|
||||
interact with it. ``ttl`` is the TTL that was set on the message when it was
|
||||
posted. The message expires after (ttl - age) seconds. ``age`` is the number
|
||||
of seconds relative to the server's clock. ``body`` is the arbitrary document
|
||||
that was submitted with the original request to post the message.
|
||||
|
||||
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- Not Found (404)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queue_name: queue_name
|
||||
- ids: ids
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- messages: messages
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/messages-get-byids-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Delete A Set Of Messages By Id
|
||||
==============================
|
||||
|
||||
.. rest_method:: DELETE /v2/queues/{queue_name}/messages?ids={ids}
|
||||
|
||||
Provides a bulk delete for messages.
|
||||
|
||||
This operation immediately deletes the specified messages. If any of the
|
||||
message IDs are malformed or non-existent, they are ignored. The remaining
|
||||
valid messages IDs are deleted.
|
||||
|
||||
|
||||
|
||||
Normal response codes: 204
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- Not Found (404)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queue_name: queue_name
|
||||
- ids: ids
|
||||
- pop: pop
|
||||
|
||||
|
||||
This operation does not accept a request body and does not return a response
|
||||
body.
|
||||
|
||||
|
||||
Get A Specific Message
|
||||
======================
|
||||
|
||||
.. rest_method:: GET /v2/queues/{queue_name}/messages/{message_id}
|
||||
|
||||
Gets the specified message from the specified queue.
|
||||
|
||||
This operation gets the specified message from the specified queue.
|
||||
|
||||
If either the message ID is malformed or nonexistent, no message is returned.
|
||||
|
||||
Message fields are defined as follows: ``href`` is an opaque relative URI that
|
||||
the client can use to uniquely identify a message resource and interact with
|
||||
it. ``ttl`` is the TTL that was set on the message when it was posted. The
|
||||
message expires after (ttl - age) seconds. ``age`` is the number of seconds
|
||||
relative to the server's clock. ``body`` is the arbitrary document that was
|
||||
submitted with the original request to post the message.
|
||||
|
||||
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- Not Found (404)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queue_name: queue_name
|
||||
- message_id: message_id
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/messages-get-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Delete A Specific Message
|
||||
=========================
|
||||
|
||||
.. rest_method:: DELETE /v2/queues/{queue_name}/messages/{message_id}
|
||||
|
||||
Deletes the specified message from the specified queue.
|
||||
|
||||
This operation immediately deletes the specified message.
|
||||
|
||||
The ``claim_id`` parameter specifies that the message is deleted only if it
|
||||
has the specified claim ID and that claim has not expired. This specification
|
||||
is useful for ensuring only one worker processes any given message. When a
|
||||
worker's claim expires before it can delete a message that it has processed,
|
||||
the worker must roll back any actions it took based on that message because
|
||||
another worker can now claim and process the same message.
|
||||
|
||||
If you do not specify ``claim_id``, but the message is claimed, the operation
|
||||
fails. You can only delete claimed messages by providing an appropriate
|
||||
``claim_id``.
|
||||
|
||||
|
||||
|
||||
Normal response codes: 204
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- Not Found (404)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queue_name: queue_name
|
||||
- message_id: message_id
|
||||
|
||||
This operation does not accept a request body and does not return a response
|
||||
body.
|
||||
|
||||
@ -1,498 +0,0 @@
|
||||
#### variables in header #####################################################
|
||||
|
||||
client_id:
|
||||
type: UUID
|
||||
in: header
|
||||
description: |
|
||||
A UUID for each client instance. The UUID must be submitted in its
|
||||
canonical form (for example, 3381af92-2b9e-11e3-b191-71861300734c). The
|
||||
client generates the Client-ID once. Client-ID persists between restarts
|
||||
of the client so the client should reuse that same Client-ID. Note: All
|
||||
message-related operations require the use of ``Client-ID`` in the headers
|
||||
to ensure that messages are not echoed back to the client that posted
|
||||
them, unless the client explicitly requests this.
|
||||
|
||||
#### variables in path #######################################################
|
||||
|
||||
claim_id:
|
||||
type: string
|
||||
in: path
|
||||
required: True
|
||||
description: |
|
||||
The id of the claim.
|
||||
|
||||
flavor_name_path:
|
||||
type: string
|
||||
in: path
|
||||
required: True
|
||||
description:
|
||||
The name of the flavor.
|
||||
|
||||
message_id:
|
||||
type: string
|
||||
in: path
|
||||
required: True
|
||||
description: |
|
||||
The ID of the message.
|
||||
|
||||
pool_name_path:
|
||||
type: string
|
||||
in: path
|
||||
required: True
|
||||
description:
|
||||
The name of the pool.
|
||||
|
||||
queue_name:
|
||||
type: string
|
||||
in: path
|
||||
required: True
|
||||
description: |
|
||||
The name of the queue.
|
||||
|
||||
subscription_id_path:
|
||||
type: string
|
||||
in: path
|
||||
required: True
|
||||
description: |
|
||||
The id of the subscription.
|
||||
|
||||
#### variables in query ######################################################
|
||||
|
||||
claim_limit:
|
||||
type: integer
|
||||
in: query
|
||||
required: false
|
||||
description: |
|
||||
The ``limit`` specifies up to 20 messages (configurable) to claim. If not
|
||||
specified, limit defaults to 10. Note that claim creation is best-effort,
|
||||
meaning the server may claim and return less than the requested number of
|
||||
messages.
|
||||
|
||||
detailed:
|
||||
type: boolean
|
||||
in: query
|
||||
required: false
|
||||
description: |
|
||||
The 'detailed' specifies if showing the detailed information when querying
|
||||
queues, flavors and pools.
|
||||
|
||||
echo:
|
||||
type: boolean
|
||||
in: query
|
||||
required: false
|
||||
description:
|
||||
Indicate if the messages can be echoed back to the client that posted
|
||||
them.
|
||||
|
||||
ids:
|
||||
type: list
|
||||
in: query
|
||||
required: false
|
||||
description: |
|
||||
A list of the messages ids. ``pop`` & ``ids`` parameters are mutually
|
||||
exclusive. Using them together in a request will result in HTTP 400.
|
||||
|
||||
NOTE: Actually, it's not a real list, it's string combined with many
|
||||
message ids separated with comma, for example:
|
||||
/messages?ids=578f0055508f153f256f717e,578f0055508f153f256f717f
|
||||
|
||||
include_claimed:
|
||||
type: boolean
|
||||
in: query
|
||||
required: false
|
||||
description:
|
||||
Indicate if the messages list should include the claimed messages.
|
||||
|
||||
limit:
|
||||
type: integer
|
||||
in: query
|
||||
required: false
|
||||
description: |
|
||||
Requests a page size of items. Returns a number of items up to a limit
|
||||
value. Use the ``limit`` parameter to make an initial limited request and
|
||||
use the ID of the last-seen item from the response as the ``marker``
|
||||
parameter value in a subsequent limited request.
|
||||
|
||||
marker:
|
||||
type: string
|
||||
in: query
|
||||
required: false
|
||||
description: |
|
||||
The ID of the last-seen item. Use the ``limit`` parameter to make an
|
||||
initial limited request and use the ID of the last-seen item from the
|
||||
response as the ``marker`` parameter value in a subsequent limited request.
|
||||
|
||||
pop:
|
||||
type: integer
|
||||
in: query
|
||||
required: false
|
||||
description: |
|
||||
The ``pop`` specifies how many messages will be popped up from the queue.
|
||||
``pop`` & ``ids`` parameters are mutually exclusive. Using them together
|
||||
in a request will result in HTTP 400.
|
||||
|
||||
#### variables in request ####################################################
|
||||
|
||||
_dead_letter_queue:
|
||||
type: string
|
||||
in: body
|
||||
required: False
|
||||
description: |
|
||||
The target the message will be moved to when the message can't processed
|
||||
successfully after meet the max claim count. It's not supported to add
|
||||
queue C as the dead letter queue for queue B where queue B has been set
|
||||
as a dead letter queue for queue A. There is no default value for this
|
||||
attribute. If it's not set explicitly, then that means there is no dead
|
||||
letter queue for current queue. It is one of the ``reserved attributes``
|
||||
of Zaqar queues.
|
||||
|
||||
_dead_letter_queue_messages_ttl:
|
||||
type: integer
|
||||
in: body
|
||||
required: False
|
||||
description: |
|
||||
The new TTL setting for messages when moved to dead letter queue. If it's
|
||||
not set, current TTL will be kept. It is one of the ``reserved attributes``
|
||||
of Zaqar queues.
|
||||
|
||||
_default_message_ttl:
|
||||
type: integer
|
||||
in: body
|
||||
required: True
|
||||
description: |
|
||||
The default TTL of messages defined for a queue, which will effect for
|
||||
any messages posted to the queue. So when there is no TTL defined for a
|
||||
message, the queue's _default_message_ttl will be used. By default, the
|
||||
value is the same value defined as ''max_message_ttl'' in zaqar.conf. It is
|
||||
one of the ``reserved attributes`` of Zaqar queues. The value will be
|
||||
reverted to the default value after deleting it explicitly.
|
||||
|
||||
_flavor:
|
||||
type: string
|
||||
in: body
|
||||
required: False
|
||||
description: |
|
||||
The flavor name which can tell Zaqar which storage pool will be used to
|
||||
create the queue. It is one of the ``reserved attributes`` of Zaqar
|
||||
queues.
|
||||
|
||||
_max_claim_count:
|
||||
type: integer
|
||||
in: body
|
||||
required: False
|
||||
description: |
|
||||
The max number the message can be claimed. Generally,
|
||||
it means the message cannot be processed successfully. There is no default
|
||||
value for this attribute. If it's not set, then that means this feature
|
||||
won't be enabled for current queue. It is one of the
|
||||
``reserved attributes`` of Zaqar queues.
|
||||
|
||||
_max_messages_post_size:
|
||||
type: integer
|
||||
in: body
|
||||
required: True
|
||||
description: |
|
||||
The max post size of messages defined for a queue, which will effect for
|
||||
any messages posted to the queue. So user can define a queue's level
|
||||
cap for post size which can't bigger than the max_messages_post_size
|
||||
defined in zaqar.conf. It is one of the ``reserved attributes`` of Zaqar
|
||||
queues. The value will be reverted to the default value after deleting it
|
||||
explicitly.
|
||||
|
||||
capabilities:
|
||||
type: list
|
||||
in: body
|
||||
description: |
|
||||
Capabilities describe what this flavor is capable of base on the storage
|
||||
capabilities. They are used to inform the final user such capabilities.
|
||||
|
||||
catalog_reachable:
|
||||
type: boolean
|
||||
in: body
|
||||
required: True
|
||||
description: |
|
||||
A boolean value to indicate if the management(catalog) datatabse is
|
||||
reachable or not.
|
||||
|
||||
claim_grace:
|
||||
type: integer
|
||||
in: body
|
||||
required: false
|
||||
description: |
|
||||
The ``grace`` attribute specifies the message grace period in seconds. The
|
||||
value of ``grace`` value must be between 60 and 43200 seconds (12 hours).
|
||||
You must include a value for this attribute in your request. To deal with
|
||||
workers that have stopped responding (for up to 1209600 seconds or 14 days,
|
||||
including claim lifetime), the server extends the lifetime of claimed
|
||||
messages to be at least as long as the lifetime of the claim itself, plus
|
||||
the specified grace period. If a claimed message would normally live longer
|
||||
than the claim's live period, its expiration is not adjusted.
|
||||
|
||||
claim_ttl:
|
||||
type: integer
|
||||
in: body
|
||||
required: false
|
||||
description: |
|
||||
The ``ttl`` attribute specifies how long the server waits before releasing
|
||||
the claim. The ttl value must be between 60 and 43200 seconds (12 hours).
|
||||
You must include a value for this attribute in your request.
|
||||
|
||||
flavor_href:
|
||||
type: string
|
||||
in: body
|
||||
description: |
|
||||
The url of the flavor.
|
||||
|
||||
flavor_links:
|
||||
type: array
|
||||
in: body
|
||||
required: true
|
||||
description: |
|
||||
Links related to the flavors. This is a list of dictionaries, each including
|
||||
keys ``href`` and ``rel``.
|
||||
|
||||
flavor_name:
|
||||
type: string
|
||||
in: body
|
||||
required: true
|
||||
description: |
|
||||
The name of the flavor.
|
||||
|
||||
flavor_pool_group:
|
||||
type: string
|
||||
in: body
|
||||
required: true
|
||||
description: |
|
||||
The ``pool_group`` attribute specifies the name of the pool group
|
||||
this flavor sits on top of.
|
||||
|
||||
flavors:
|
||||
type: list
|
||||
in: body
|
||||
description: |
|
||||
A list of the flaovrs.
|
||||
|
||||
links:
|
||||
type: array
|
||||
in: body
|
||||
required: true
|
||||
description: |
|
||||
Links related to the queues. This is a list of dictionaries, each including
|
||||
keys ``href`` and ``rel``.
|
||||
|
||||
messages:
|
||||
type: list
|
||||
in: body
|
||||
required: True
|
||||
description: |
|
||||
A list of the messages.
|
||||
|
||||
messages_resources:
|
||||
type: list
|
||||
in: body
|
||||
description: |
|
||||
A list of the URL to messages.
|
||||
|
||||
operation_status:
|
||||
type: dict
|
||||
in: body
|
||||
required: False
|
||||
description: |
|
||||
A dict which will contain the status for many different actions/operations.
|
||||
For example, post_messages, delete_messages, delete queue, etc. And each
|
||||
status is a dict which contains three items: ``seconds``, ``ref`` and
|
||||
``succeeded``. Seconds means how long the operation took and succeeded will
|
||||
indicate if the actions was successful or not. Ref may contain the
|
||||
information if the succeeded is False, otherwise it's null.
|
||||
|
||||
pool_group:
|
||||
type: string
|
||||
in: body
|
||||
required: false
|
||||
description: |
|
||||
The ``group`` attribute specifies a tag to given to more than one pool
|
||||
so that it keeps user remind the purpose/capabilities of all pools that
|
||||
falls under that group.
|
||||
|
||||
pool_href:
|
||||
type: string
|
||||
in: body
|
||||
description: |
|
||||
The url of the pool.
|
||||
|
||||
pool_links:
|
||||
type: array
|
||||
in: body
|
||||
required: true
|
||||
description: |
|
||||
Links related to the pools. This is a list of dictionaries, each including
|
||||
keys ``href`` and ``rel``.
|
||||
|
||||
pool_name:
|
||||
type: string
|
||||
in: body
|
||||
description: |
|
||||
The name of the pool.
|
||||
|
||||
pool_options:
|
||||
type: dict
|
||||
in: body
|
||||
required: false
|
||||
description: |
|
||||
The ``options`` attribute gives storage-specific options used by storage
|
||||
driver implementations. The value must be a dict and valid key-value come
|
||||
from the registered options for a given storage backend.
|
||||
|
||||
pool_uri:
|
||||
type: string
|
||||
in: body
|
||||
required: true
|
||||
description: |
|
||||
The ``uri`` attribute specifies a connection string compatible with a
|
||||
storage client (e.g., pymongo) attempting to connect to that pool.
|
||||
|
||||
pool_weight:
|
||||
type: integer
|
||||
in: body
|
||||
required: true
|
||||
description: |
|
||||
The ``weight`` attribute specifies the likelihood that this pool will be
|
||||
selected for the next queue allocation. The value must be an integer
|
||||
greater than -1.
|
||||
|
||||
pools:
|
||||
type: list
|
||||
in: body
|
||||
description: |
|
||||
A list of the pools.
|
||||
|
||||
pre_signed_queue_expires:
|
||||
type: string
|
||||
in: body
|
||||
required: True
|
||||
description: |
|
||||
The time to indicate when the pre-signed will be expired.
|
||||
|
||||
pre_signed_queue_methods:
|
||||
type: list
|
||||
in: body
|
||||
required: True
|
||||
description: |
|
||||
A list of HTTP methods. The HTTP method(s) this URL was created for. By
|
||||
selecting the HTTP method, it’s possible to give either read or read/write
|
||||
access to a specific resource.
|
||||
|
||||
pre_signed_queue_paths:
|
||||
type: list
|
||||
in: body
|
||||
required: True
|
||||
description: |
|
||||
A list of paths the pre-signed queue can support. It could be a set of
|
||||
``messages``, ``subscriptions``, ``claims``.
|
||||
|
||||
pre_signed_queue_signature:
|
||||
type: list
|
||||
in: body
|
||||
required: True
|
||||
description: |
|
||||
The signature is generated after create the pre-signed URL. It can be
|
||||
consumed by adding below to HTTP headers:
|
||||
|
||||
URL-Signature: 6a63d63242ebd18c3518871dda6fdcb6273db2672c599bf985469241e9a1c799
|
||||
URL-Expires: 2015-05-31T19:00:17Z
|
||||
|
||||
project_id:
|
||||
type: string
|
||||
in: body
|
||||
required: True
|
||||
description: |
|
||||
The ID of current project/tenant.
|
||||
|
||||
queue_metadata:
|
||||
type: dict
|
||||
in: body
|
||||
description: |
|
||||
Metadata of queue.
|
||||
|
||||
queues:
|
||||
type: list
|
||||
in: body
|
||||
description: |
|
||||
A list of the queues.
|
||||
|
||||
resource_types:
|
||||
type: list
|
||||
in: body
|
||||
required: false
|
||||
description: |
|
||||
The ``resource_types`` attribute allows user to purge particular resource
|
||||
of the queue.
|
||||
|
||||
storage_reachable:
|
||||
type: boolean
|
||||
in: body
|
||||
required: False
|
||||
description: |
|
||||
A boolean value to indicate if the messages(pool) datatabse is
|
||||
reachable or not.
|
||||
|
||||
subscriber:
|
||||
type: string
|
||||
in: body
|
||||
required: True
|
||||
description: |
|
||||
The ``subscriber`` attribute specifies the destination where the message
|
||||
notify to. It has been designed to match the Internet RFC on Relative
|
||||
Uniform Resource Locators. Zaqar now support two kinds of subscribers:
|
||||
http/https and email. The http/https subscriber should start with
|
||||
``http/https``. The email subscriber should start with ``mailto``.
|
||||
|
||||
subscription_age:
|
||||
type: integer
|
||||
in: body
|
||||
description: |
|
||||
How long the subscription has be existed.
|
||||
|
||||
subscription_id:
|
||||
type: string
|
||||
in: body
|
||||
description: |
|
||||
The id of the subscription.
|
||||
|
||||
subscription_options:
|
||||
type: dict
|
||||
in: body
|
||||
required: false
|
||||
description: |
|
||||
The ``options`` attribute specifies the extra metadata for the subscription
|
||||
. The value must be a dict and could contain any key-value. If the
|
||||
subscriber is "mailto". The ``options`` can contain ``from`` and
|
||||
``subject`` to indicate the email's author and title.
|
||||
|
||||
subscription_source:
|
||||
type: string
|
||||
in: body
|
||||
description: |
|
||||
The queue name which the subscription is registered on.
|
||||
|
||||
subscription_ttl:
|
||||
type: integer
|
||||
in: body
|
||||
required: false
|
||||
description: |
|
||||
The ``ttl`` attribute specifies how long the subscription be alive. The ttl
|
||||
value must be great than 60 seconds. The default value is 3600 seconds.
|
||||
|
||||
|
||||
subscriptions:
|
||||
type: list
|
||||
in: body
|
||||
description: |
|
||||
A list of the subscriptions.
|
||||
|
||||
versions:
|
||||
type: list
|
||||
in: body
|
||||
required: True
|
||||
description: |
|
||||
A list of supported major API versions.
|
||||
@ -1,212 +0,0 @@
|
||||
===============
|
||||
Pools (pools)
|
||||
===============
|
||||
If pooling is enabled, queuing service uses multiple queues databases in order
|
||||
to scale horizontally. A pool (queues database) can be added any time without
|
||||
stopping the service. Each pool has a weight that is assigned during the
|
||||
creation time but can be changed later. Pooling is done by queue which
|
||||
indicates that all messages for a particular queue can be found in the same
|
||||
pool (queues database).
|
||||
|
||||
List pools
|
||||
==========
|
||||
|
||||
.. rest_method:: GET /v2/pools
|
||||
|
||||
Lists pools.
|
||||
|
||||
This operation lists pools for the project. The pools are sorted
|
||||
alphabetically by name.
|
||||
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error response codes:
|
||||
|
||||
- Not Found (404)
|
||||
- Unauthorized (401)
|
||||
|
||||
Query Parameters
|
||||
-----------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- limit: limit
|
||||
- marker: marker
|
||||
- detailed: detailed
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- pools: pools
|
||||
- links: pool_links
|
||||
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/pool-list-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Create pool
|
||||
============
|
||||
|
||||
.. rest_method:: PUT /v2/pools/{pool_name}
|
||||
|
||||
Creates a pool.
|
||||
|
||||
This operation creates a new pool.
|
||||
|
||||
``pool_name`` is the name that you give to the pool. The name must not
|
||||
exceed 64 bytes in length, and it is limited to US-ASCII letters, digits,
|
||||
underscores, and hyphens.
|
||||
|
||||
|
||||
Normal response codes: 201
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- Conflict (409)
|
||||
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- pool_name: pool_name_path
|
||||
- weight: pool_weight
|
||||
- uri: pool_uri
|
||||
- group: pool_group
|
||||
- options: pool_options
|
||||
|
||||
Request Example
|
||||
---------------
|
||||
|
||||
.. literalinclude:: samples/pool-create-request.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
This operation does not return a response body.
|
||||
|
||||
|
||||
Update pool
|
||||
============
|
||||
|
||||
.. rest_method:: PATCH /v2/pools/{pool_name}
|
||||
|
||||
Updates a pool.
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- Not Found (404)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- pool_name: pool_name_path
|
||||
- weight: pool_weight
|
||||
- uri: pool_uri
|
||||
- group: pool_group
|
||||
- options: pool_options
|
||||
|
||||
|
||||
Request Example
|
||||
---------------
|
||||
|
||||
.. literalinclude:: samples/pool-update-request.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/pool-update-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Show pool details
|
||||
==================
|
||||
|
||||
.. rest_method:: GET /v2/pools/{pool_name}
|
||||
|
||||
Shows details for a pool.
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- pool_name: pool_name_path
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- name: pool_name
|
||||
- weight: pool_weight
|
||||
- uri: pool_uri
|
||||
- group: pool_group
|
||||
- href: pool_href
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/pool-show-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Delete pool
|
||||
===============
|
||||
|
||||
.. rest_method:: DELETE /v2/pools/{pool_name}
|
||||
|
||||
Deletes the specified pool.
|
||||
|
||||
This operation immediately deletes a pool.
|
||||
|
||||
``pool_name`` is the name that you give to the pool. The name must not
|
||||
exceed 64 bytes in length, and it is limited to US-ASCII letters, digits,
|
||||
underscores, and hyphens.
|
||||
|
||||
|
||||
Normal response codes: 204
|
||||
|
||||
Error response codes:
|
||||
|
||||
- Unauthorized (401)
|
||||
- Forbidden (403)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- pool_name: pool_name_path
|
||||
|
||||
This operation does not accept a request body and does not return a response
|
||||
body.
|
||||
@ -1,366 +0,0 @@
|
||||
===============
|
||||
Queues (queues)
|
||||
===============
|
||||
Queue is a logical entity that groups messages. Ideally a queue is created per
|
||||
work type. For example, if you want to compress files, you would create a queue
|
||||
dedicated for this job. Any application that reads from this queue would only
|
||||
compress files.
|
||||
|
||||
Nowadays, queue in Zaqar is most like a topic, it's created lazily. User can
|
||||
post messages to a queue before creating the queue. Zaqar will create the
|
||||
queue/topic automatically.
|
||||
|
||||
List queues
|
||||
===========
|
||||
|
||||
.. rest_method:: GET /v2/queues
|
||||
|
||||
Lists queues.
|
||||
|
||||
A request to list queues when you have no queues in your account returns 204,
|
||||
instead of 200, because there was no information to send back.
|
||||
|
||||
This operation lists queues for the project. The queues are sorted
|
||||
alphabetically by name.
|
||||
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- limit: limit
|
||||
- marker: marker
|
||||
- detailed: detailed
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queues: queues
|
||||
- links: links
|
||||
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/queues-list-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Create queue
|
||||
============
|
||||
|
||||
.. rest_method:: PUT /v2/queues/{queue_name}
|
||||
|
||||
Creates a queue.
|
||||
|
||||
This operation creates a new queue.
|
||||
|
||||
The body of the request is empty.
|
||||
|
||||
``queue_name`` is the name that you give to the queue. The name must not
|
||||
exceed 64 bytes in length, and it is limited to US-ASCII letters, digits,
|
||||
underscores, and hyphens.
|
||||
|
||||
When create queue, user can specify metadata for the queue. Currently, Zaqar
|
||||
supports below metadata: _flavor, _max_claim_count, _dead_letter_queue and
|
||||
_dead_letter_queue_messages_ttl.
|
||||
|
||||
|
||||
Normal response codes: 201, 204
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queue_name: queue_name
|
||||
- _dead_letter_queue: _dead_letter_queue
|
||||
- _dead_letter_queue_messages_ttl: _dead_letter_queue_messages_ttl
|
||||
- _default_message_ttl: _default_message_ttl
|
||||
- _flavor: _flavor
|
||||
- _max_claim_count: _max_claim_count
|
||||
- _max_messages_post_size: _max_messages_post_size
|
||||
|
||||
Request Example
|
||||
---------------
|
||||
|
||||
.. literalinclude:: samples/queue-create-request.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
This operation does not return a response body.
|
||||
|
||||
|
||||
Update queue
|
||||
============
|
||||
|
||||
.. rest_method:: PATCH /v2/queues/{queue_name}
|
||||
|
||||
Updates a queue.
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- Not Found (404)
|
||||
- Conflict (409)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queue_name: queue_name
|
||||
|
||||
When setting the request body of updating queue, the body must be a list which
|
||||
contains a series of json object which follows
|
||||
https://tools.ietf.org/html/draft-ietf-appsawg-json-patch-10.
|
||||
|
||||
.. note::
|
||||
|
||||
- The "Content-Type" header should be
|
||||
"application/openstack-messaging-v2.0-json-patch"
|
||||
|
||||
- The ''path'' must start with /metadata, for example, if the key is
|
||||
''ttl'', then the path should be /metadata/ttl
|
||||
|
||||
|
||||
Request Example
|
||||
---------------
|
||||
|
||||
.. literalinclude:: samples/queue-update-request.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/queue-update-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Show queue details
|
||||
==================
|
||||
|
||||
.. rest_method:: GET /v2/queues/{queue_name}
|
||||
|
||||
Shows details for a queue.
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queue_name: queue_name
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- _max_messages_post_size: _max_messages_post_size
|
||||
- _default_message_ttl: _default_message_ttl
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/queue-show-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Delete queue
|
||||
===============
|
||||
|
||||
.. rest_method:: DELETE /v2/queues/{queue_name}
|
||||
|
||||
Deletes the specified queue.
|
||||
|
||||
This operation immediately deletes a queue and all of its existing messages.
|
||||
|
||||
``queue_name`` is the name that you give to the queue. The name must not
|
||||
exceed 64 bytes in length, and it is limited to US-ASCII letters, digits,
|
||||
underscores, and hyphens.
|
||||
|
||||
|
||||
Normal response codes: 204
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queue_name: queue_name
|
||||
|
||||
This operation does not accept a request body and does not return a response
|
||||
body.
|
||||
|
||||
|
||||
Get queue stats
|
||||
===============
|
||||
|
||||
.. rest_method:: GET /v2/queues/{queue_name}/stats
|
||||
|
||||
Returns statistics for the specified queue.
|
||||
|
||||
This operation returns queue statistics, including how many messages are in
|
||||
the queue, categorized by status.
|
||||
|
||||
If the value of the ``total`` attribute is 0, then ``oldest`` and ``newest``
|
||||
message statistics are not included in the response.
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queue_name: queue_name
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/queue-stats-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Pre-signed queue
|
||||
================
|
||||
|
||||
.. rest_method:: POST /v2/queues/{queue_name}/share
|
||||
|
||||
Create a pre-signed URL for a given queue.
|
||||
|
||||
.. note::
|
||||
|
||||
In the case of pre-signed URLs, the queue cannot be created lazily. This
|
||||
is to prevent cases where queues are deleted and users still have a valid
|
||||
URL. This is not a big issues in cases where there’s just 1 pool. However,
|
||||
if there’s a deployment using more than 1 type of pool, the lazily created
|
||||
queue may end up in an undesired pool and it’d be possible for an attacker
|
||||
to try a DoS on that pool. Therefore, whenever a pre-signed URL is created,
|
||||
if a pool doesn’t exist, it needs to be created.
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- Not Found (404)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queue_name: queue_name
|
||||
- paths: pre_signed_queue_paths
|
||||
- methods: pre_signed_queue_methods
|
||||
- expires: pre_signed_queue_expires
|
||||
|
||||
Request Example
|
||||
---------------
|
||||
|
||||
.. literalinclude:: samples/queue-pre-signed-request.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- project: project_id
|
||||
- paths: pre_signed_queue_paths
|
||||
- methods: pre_signed_queue_methods
|
||||
- expires: pre_signed_queue_expires
|
||||
- signature: pre_signed_queue_signature
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/queue-pre-signed-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Purge queue
|
||||
===========
|
||||
|
||||
.. rest_method:: POST /v2/queues/{queue_name}/purge
|
||||
|
||||
Purge particular resource of the queue.
|
||||
|
||||
.. note::
|
||||
|
||||
Now Zaqar supports to purge "messages" and "subscriptions" resource from
|
||||
a queue.
|
||||
|
||||
Normal response codes: 204
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queue_name: queue_name
|
||||
- resource_types: resource_types
|
||||
|
||||
Request Example
|
||||
---------------
|
||||
|
||||
.. literalinclude:: samples/purge-queue-request.json
|
||||
:language: javascript
|
||||
@ -1,4 +0,0 @@
|
||||
{
|
||||
"ttl": 300,
|
||||
"grace": 300
|
||||
}
|
||||
@ -1,12 +0,0 @@
|
||||
{
|
||||
"messages": [
|
||||
{
|
||||
"body": {
|
||||
"event": "BackupStarted"
|
||||
},
|
||||
"age": 239,
|
||||
"href": "/v2/queues/demoqueue/messages/51db6f78c508f17ddc924357?claim_id=51db7067821e727dc24df754",
|
||||
"ttl": 300
|
||||
}
|
||||
]
|
||||
}
|
||||
@ -1,15 +0,0 @@
|
||||
{
|
||||
"age": 57,
|
||||
"href": "/v2/queues/demoqueue/claims/51db7067821e727dc24df754",
|
||||
"messages": [
|
||||
{
|
||||
"body": {
|
||||
"event": "BackupStarted"
|
||||
},
|
||||
"age": 296,
|
||||
"href": "/v2/queues/demoqueue/messages/51db6f78c508f17ddc924357?claim_id=51db7067821e727dc24df754",
|
||||
"ttl": 300
|
||||
}
|
||||
],
|
||||
"ttl": 300
|
||||
}
|
||||
@ -1,4 +0,0 @@
|
||||
{
|
||||
"ttl": 300,
|
||||
"grace": 300
|
||||
}
|
||||
@ -1,3 +0,0 @@
|
||||
{
|
||||
"pool_group": "testgroup"
|
||||
}
|
||||
@ -1,22 +0,0 @@
|
||||
{
|
||||
"flavors": [
|
||||
{
|
||||
"href": "/v2/flavors/test_flavor1",
|
||||
"pool_group": "testgroup",
|
||||
"name": "test_flavor1",
|
||||
"pool": "testgroup"
|
||||
},
|
||||
{
|
||||
"href": "/v2/flavors/test_flavor2",
|
||||
"pool_group": "testgroup",
|
||||
"name": "test_flavor2",
|
||||
"pool": "testgroup"
|
||||
}
|
||||
],
|
||||
"links": [
|
||||
{
|
||||
"href": "/v2/flavors?marker=test_flavor2",
|
||||
"rel": "next"
|
||||
}
|
||||
]
|
||||
}
|
||||
@ -1,12 +0,0 @@
|
||||
{
|
||||
"href": "/v2/flavors/testflavor",
|
||||
"capabilities": [
|
||||
"FIFO",
|
||||
"CLAIMS",
|
||||
"DURABILITY",
|
||||
"AOD",
|
||||
"HIGH_THROUGHPUT"
|
||||
],
|
||||
"pool_group": "testgroup",
|
||||
"name": "testflavor"
|
||||
}
|
||||
@ -1,3 +0,0 @@
|
||||
{
|
||||
"pool_group": "testgroup"
|
||||
}
|
||||
@ -1,12 +0,0 @@
|
||||
{
|
||||
"href": "/v2/flavors/testflavor",
|
||||
"pool_group": "testgroup",
|
||||
"name": "testflavor",
|
||||
"capabilities": [
|
||||
"FIFO",
|
||||
"CLAIMS",
|
||||
"DURABILITY",
|
||||
"AOD",
|
||||
"HIGH_THROUGHPUT"
|
||||
]
|
||||
}
|
||||
@ -1,48 +0,0 @@
|
||||
{
|
||||
"catalog_reachable": true,
|
||||
"redis": {
|
||||
"storage_reachable": true,
|
||||
"operation_status": {
|
||||
"post_messages": {
|
||||
"seconds": 0.027673959732055664,
|
||||
"ref": null,
|
||||
"succeeded": true
|
||||
},
|
||||
"delete_messages": {
|
||||
"seconds": 0.0028481483459472656,
|
||||
"ref": null,
|
||||
"succeeded": true
|
||||
},
|
||||
"delete_queue": {
|
||||
"seconds": 0.017709016799926758,
|
||||
"ref": null,
|
||||
"succeeded": true
|
||||
},
|
||||
"bulk_delete_messages": {
|
||||
"seconds": 0.03959178924560547,
|
||||
"ref": null,
|
||||
"succeeded": true
|
||||
},
|
||||
"create_queue": {
|
||||
"seconds": 0.021075963973999023,
|
||||
"ref": null,
|
||||
"succeeded": true
|
||||
},
|
||||
"list_messages": {
|
||||
"seconds": 0.00003504753112792969,
|
||||
"ref": null,
|
||||
"succeeded": true
|
||||
},
|
||||
"delete_claim": {
|
||||
"seconds": 0.0006170272827148438,
|
||||
"ref": null,
|
||||
"succeeded": true
|
||||
},
|
||||
"claim_messages": {
|
||||
"seconds": 0.008388042449951172,
|
||||
"ref": null,
|
||||
"succeeded": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -1,15 +0,0 @@
|
||||
{
|
||||
"messages": [
|
||||
{
|
||||
"body": {
|
||||
"current_bytes": "0",
|
||||
"event": "BackupProgress",
|
||||
"total_bytes": "99614720"
|
||||
},
|
||||
"age": 443,
|
||||
"href": "/v2/queues/beijing/messages/578f0055508f153f256f717f",
|
||||
"id": "578f0055508f153f256f717f",
|
||||
"ttl": 3600
|
||||
}
|
||||
]
|
||||
}
|
||||
@ -1,11 +0,0 @@
|
||||
{
|
||||
"body": {
|
||||
"current_bytes": "0",
|
||||
"event": "BackupProgress",
|
||||
"total_bytes": "99614720"
|
||||
},
|
||||
"age": 1110,
|
||||
"href": "/v2/queues/beijing/messages/578f0055508f153f256f717f",
|
||||
"id": "578f0055508f153f256f717f",
|
||||
"ttl": 3600
|
||||
}
|
||||
@ -1,32 +0,0 @@
|
||||
{
|
||||
"messages": [
|
||||
{
|
||||
"body": {
|
||||
"current_bytes": "0",
|
||||
"event": "BackupProgress",
|
||||
"total_bytes": "99614720"
|
||||
},
|
||||
"age": 482,
|
||||
"href": "/v2/queues/beijing/messages/578edfe6508f153f256f717b",
|
||||
"id": "578edfe6508f153f256f717b",
|
||||
"ttl": 3600
|
||||
},
|
||||
{
|
||||
"body": {
|
||||
"current_bytes": "0",
|
||||
"event": "BackupProgress",
|
||||
"total_bytes": "99614720"
|
||||
},
|
||||
"age": 456,
|
||||
"href": "/v2/queues/beijing/messages/578ee000508f153f256f717d",
|
||||
"id": "578ee000508f153f256f717d",
|
||||
"ttl": 3600
|
||||
}
|
||||
],
|
||||
"links": [
|
||||
{
|
||||
"href": "/v2/queues/beijing/messages?marker=17&echo=true",
|
||||
"rel": "next"
|
||||
}
|
||||
]
|
||||
}
|
||||
@ -1,18 +0,0 @@
|
||||
{
|
||||
"messages": [
|
||||
{
|
||||
"ttl": 300,
|
||||
"body": {
|
||||
"event": "BackupStarted",
|
||||
"backup_id": "c378813c-3f0b-11e2-ad92-7823d2b0f3ce"
|
||||
}
|
||||
},
|
||||
{
|
||||
"body": {
|
||||
"event": "BackupProgress",
|
||||
"current_bytes": "0",
|
||||
"total_bytes": "99614720"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
@ -1,6 +0,0 @@
|
||||
{
|
||||
"resources": [
|
||||
"/v2/queues/demoqueue/messages/51db6f78c508f17ddc924357",
|
||||
"/v2/queues/demoqueue/messages/51db6f78c508f17ddc924358"
|
||||
]
|
||||
}
|
||||
@ -1,8 +0,0 @@
|
||||
{
|
||||
"weight": 100,
|
||||
"uri": "mongodb://127.0.0.1:27017",
|
||||
"options":{
|
||||
"max_retry_sleep": 1
|
||||
},
|
||||
"group": "poolgroup"
|
||||
}
|
||||
@ -1,24 +0,0 @@
|
||||
{
|
||||
"pools": [
|
||||
{
|
||||
"href": "/v2/pools/test_pool1",
|
||||
"group": "poolgroup",
|
||||
"name": "test_pool1",
|
||||
"weight": 60,
|
||||
"uri": "mongodb://192.168.1.10:27017"
|
||||
},
|
||||
{
|
||||
"href": "/v2/pools/test_pool2",
|
||||
"group": "poolgroup",
|
||||
"name": "test_pool2",
|
||||
"weight": 40,
|
||||
"uri": "mongodb://192.168.1.20:27017"
|
||||
}
|
||||
],
|
||||
"links": [
|
||||
{
|
||||
"href": "/v2/pools?marker=test_pool2",
|
||||
"rel": "next"
|
||||
}
|
||||
]
|
||||
}
|
||||
@ -1,7 +0,0 @@
|
||||
{
|
||||
"href": "/v2/pools/test_pool",
|
||||
"group": "testpoolgroup",
|
||||
"name": "test_pool",
|
||||
"weight": 100,
|
||||
"uri": "mongodb://127.0.0.1:27017"
|
||||
}
|
||||
@ -1,8 +0,0 @@
|
||||
{
|
||||
"weight": 60,
|
||||
"uri": "mongodb://127.0.0.1:27017",
|
||||
"options":{
|
||||
"max_retry_sleep": 1
|
||||
},
|
||||
"group": "newpoolgroup"
|
||||
}
|
||||
@ -1,7 +0,0 @@
|
||||
{
|
||||
"href": "/v2/pools/test_pool",
|
||||
"group": "newpoolgroup",
|
||||
"name": "test_pool",
|
||||
"weight": 60,
|
||||
"uri": "mongodb://127.0.0.1:27017"
|
||||
}
|
||||
@ -1,3 +0,0 @@
|
||||
{
|
||||
"resource_types": ["messages", "subscriptions"]
|
||||
}
|
||||
@ -1,5 +0,0 @@
|
||||
{
|
||||
"_max_messages_post_size": 262144,
|
||||
"_default_message_ttl": 3600,
|
||||
"description": "Queue for international traffic billing."
|
||||
}
|
||||
@ -1,5 +0,0 @@
|
||||
{
|
||||
"paths": ["messages", "claims", "subscriptions"],
|
||||
"methods": ["GET", "POST", "PUT", "PATCH"],
|
||||
"expires": "2016-09-01T00:00:00"
|
||||
}
|
||||
@ -1,16 +0,0 @@
|
||||
{
|
||||
"project": "2887aabf368046a3bb0070f1c0413470",
|
||||
"paths": [
|
||||
"/v2/queues/test/messages",
|
||||
"/v2/queues/test/claims"
|
||||
"/v2/queues/test/subscriptions"
|
||||
],
|
||||
"expires": "2016-09-01T00:00:00",
|
||||
"methods": [
|
||||
"GET",
|
||||
"PATCH",
|
||||
"POST",
|
||||
"PUT"
|
||||
],
|
||||
"signature": "6a63d63242ebd18c3518871dda6fdcb6273db2672c599bf985469241e9a1c799"
|
||||
}
|
||||
@ -1,5 +0,0 @@
|
||||
{
|
||||
"_max_messages_post_size": 262144,
|
||||
"_default_message_ttl": 3600,
|
||||
"description": "Queue used for billing."
|
||||
}
|
||||
@ -1,7 +0,0 @@
|
||||
{
|
||||
"messages":{
|
||||
"claimed": 10,
|
||||
"total": 20,
|
||||
"free": 10
|
||||
}
|
||||
}
|
||||
@ -1,7 +0,0 @@
|
||||
[
|
||||
{
|
||||
"op": "replace",
|
||||
"path": "/metadata/max_timeout",
|
||||
"value": 100
|
||||
}
|
||||
]
|
||||
@ -1,3 +0,0 @@
|
||||
{
|
||||
"max_timeout": 100
|
||||
}
|
||||
@ -1,22 +0,0 @@
|
||||
{
|
||||
"queues":[
|
||||
{
|
||||
"href":"/v2/queues/beijing",
|
||||
"name":"beijing"
|
||||
},
|
||||
{
|
||||
"href":"/v2/queues/london",
|
||||
"name":"london"
|
||||
},
|
||||
{
|
||||
"href":"/v2/queues/wellington",
|
||||
"name":"wellington"
|
||||
}
|
||||
],
|
||||
"links":[
|
||||
{
|
||||
"href":"/v2/queues?marker=wellington",
|
||||
"rel":"next"
|
||||
}
|
||||
]
|
||||
}
|
||||
@ -1,5 +0,0 @@
|
||||
{
|
||||
"subscriber":"http://10.229.49.117:5679",
|
||||
"ttl":3600,
|
||||
"options":{}
|
||||
}
|
||||
@ -1,8 +0,0 @@
|
||||
{
|
||||
"subscriber":"mailto:test@gmail.com",
|
||||
"ttl":3600,
|
||||
"options":{
|
||||
"from": "Jack",
|
||||
"subject": "Hello"
|
||||
}
|
||||
}
|
||||
@ -1,3 +0,0 @@
|
||||
{
|
||||
"subscription_id": "57692ab13990b48c644bb7e6"
|
||||
}
|
||||
@ -1,10 +0,0 @@
|
||||
{
|
||||
"age": 1632,
|
||||
"id": "576b54963990b48c644bb7e7",
|
||||
"subscriber": "http://10.229.49.117:5679",
|
||||
"source": "test",
|
||||
"ttl": 3600,
|
||||
"options": {
|
||||
"name": "test"
|
||||
}
|
||||
}
|
||||
@ -1,7 +0,0 @@
|
||||
{
|
||||
"subscriber":"http://10.229.49.117:1234",
|
||||
"ttl":360,
|
||||
"options":{
|
||||
"name": "test"
|
||||
}
|
||||
}
|
||||
@ -1,26 +0,0 @@
|
||||
{
|
||||
"links": [
|
||||
{
|
||||
"href": "/v2/queues/test/subscriptions?marker=57692ab13990b48c644bb7e6",
|
||||
"rel": "next"
|
||||
}
|
||||
],
|
||||
"subscriptions": [
|
||||
{
|
||||
"age": 13,
|
||||
"id": "57692aa63990b48c644bb7e5",
|
||||
"subscriber": "http://10.229.49.117:5678",
|
||||
"source": "test",
|
||||
"ttl": 360,
|
||||
"options": {}
|
||||
},
|
||||
{
|
||||
"age": 2,
|
||||
"id": "57692ab13990b48c644bb7e6",
|
||||
"subscriber": "http://10.229.49.117:5679",
|
||||
"source": "test",
|
||||
"ttl": 360,
|
||||
"options": {}
|
||||
}
|
||||
]
|
||||
}
|
||||
@ -1,55 +0,0 @@
|
||||
{
|
||||
"versions":[
|
||||
{
|
||||
"status":"DEPRECATED",
|
||||
"updated":"2014-9-11T17:47:05Z",
|
||||
"media-types":[
|
||||
{
|
||||
"base":"application/json",
|
||||
"type":"application/vnd.openstack.messaging-v1+json"
|
||||
}
|
||||
],
|
||||
"id":"1",
|
||||
"links":[
|
||||
{
|
||||
"href":"/v1/",
|
||||
"rel":"self"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"status":"SUPPORTED",
|
||||
"updated":"2014-9-24T04:06:47Z",
|
||||
"media-types":[
|
||||
{
|
||||
"base":"application/json",
|
||||
"type":"application/vnd.openstack.messaging-v1_1+json"
|
||||
}
|
||||
],
|
||||
"id":"1.1",
|
||||
"links":[
|
||||
{
|
||||
"href":"/v1.1/",
|
||||
"rel":"self"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"status":"CURRENT",
|
||||
"updated":"2014-9-24T04:06:47Z",
|
||||
"media-types":[
|
||||
{
|
||||
"base":"application/json",
|
||||
"type":"application/vnd.openstack.messaging-v2+json"
|
||||
}
|
||||
],
|
||||
"id":"2",
|
||||
"links":[
|
||||
{
|
||||
"href":"/v2/",
|
||||
"rel":"self"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
@ -1,229 +0,0 @@
|
||||
============================
|
||||
Subscriptions(subscriptions)
|
||||
============================
|
||||
Subscriptions are relationships between queue/topic and the targeted
|
||||
subscribers. After created subscriptions for a particular subscriber, like an
|
||||
email or a webhook, then when new messages posted to the queue, the subscriber
|
||||
will be notified automatically.
|
||||
|
||||
List Subscriptions
|
||||
==================
|
||||
|
||||
.. rest_method:: GET /v2/queues/{queue_name}/subscriptions
|
||||
|
||||
Lists a queue's subscriptions.
|
||||
|
||||
This operation lists subscriptions for a queue. The subscriptions are sorted
|
||||
alphabetically by name.
|
||||
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queue_name: queue_name
|
||||
|
||||
|
||||
Query Parameters
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- limit: limit
|
||||
- marker: marker
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- subscriptions: subscriptions
|
||||
- links: links
|
||||
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/subscriptions-list-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Create Subscription
|
||||
===================
|
||||
|
||||
.. rest_method:: POST /v2/queues/{queue_name}/subscriptions
|
||||
|
||||
Creates a subscription.
|
||||
|
||||
This operation creates a new subscription.
|
||||
|
||||
|
||||
Normal response codes: 201
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queue_name: queue_name
|
||||
- subscriber: subscriber
|
||||
- ttl: subscription_ttl
|
||||
- options: subscription_options
|
||||
|
||||
|
||||
Request Example
|
||||
---------------
|
||||
|
||||
.. literalinclude:: samples/subscription-create-request-http.json
|
||||
:language: javascript
|
||||
|
||||
.. literalinclude:: samples/subscription-create-request-mail.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- subscription_id: subscription_id
|
||||
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/subscription-create-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Update Subscription
|
||||
===================
|
||||
|
||||
.. rest_method:: PATCH /v2/queues/{queue_name}/subscriptions/{subscription_id}
|
||||
|
||||
Updates a subscription.
|
||||
|
||||
Normal response codes: 204
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- Not Found (404)
|
||||
- Conflict (409)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queue_name: queue_name
|
||||
- subscription_id: subscription_id_path
|
||||
- subscriber: subscriber
|
||||
- ttl: subscription_ttl
|
||||
- options: subscription_options
|
||||
|
||||
|
||||
Request Example
|
||||
---------------
|
||||
|
||||
.. literalinclude:: samples/subscription-update-request.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
This operation does not return a response body.
|
||||
|
||||
|
||||
Show Subscription Details
|
||||
=========================
|
||||
|
||||
.. rest_method:: GET /v2/queues/{queue_name}/subscriptions/{subscription_id}
|
||||
|
||||
Shows details for a subscription.
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queue_name: queue_name
|
||||
- subscription_id: subscription_id_path
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- age: subscription_age
|
||||
- id: subscription_id
|
||||
- subscriber: subscriber
|
||||
- source: subscription_source
|
||||
- ttl: subscription_ttl
|
||||
- options: subscription_options
|
||||
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/subscription-show-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Delete Subscription
|
||||
===================
|
||||
|
||||
.. rest_method:: DELETE /v2/queues/{queue_name}/subscriptions/{subscription_id}
|
||||
|
||||
Deletes the specified subscription.
|
||||
|
||||
|
||||
Normal response codes: 204
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queue_name: queue_name
|
||||
- subscription_id: subscription_id_path
|
||||
|
||||
|
||||
This operation does not accept a request body and does not return a response
|
||||
body.
|
||||
@ -1,40 +0,0 @@
|
||||
============
|
||||
API Versions
|
||||
============
|
||||
|
||||
The Zaqar API only supports ''major versions'' expressed in request URLs.
|
||||
|
||||
|
||||
List major versions
|
||||
===================
|
||||
|
||||
.. rest_method:: GET /
|
||||
|
||||
Gets the home document.
|
||||
|
||||
This operation gets the home document.
|
||||
|
||||
The entire API is discoverable from a single starting point, the home document. To explore the entire API, you need to know only this one URI. This document is cacheable.
|
||||
|
||||
The home document lets you write clients by using relational links, so clients do not have to construct their own URLs. You can click through and view the JSON doc in your browser.
|
||||
|
||||
For more information about home documents, see `http://tools.ietf.org/html/draft-nottingham-json-home-02 <http://tools.ietf.org/html/draft-nottingham-json-home-02>`__.
|
||||
|
||||
|
||||
Normal response codes: 300
|
||||
Error response codes:
|
||||
|
||||
- serviceUnavailable (503)
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- versions: versions
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/versions-list-response.json
|
||||
:language: javascript
|
||||
@ -1,4 +0,0 @@
|
||||
gevent>=1.0.1
|
||||
marktime>=0.2.0
|
||||
python-zaqarclient>=1.1.0
|
||||
os-client-config>=1.13.1 # Apache-2.0
|
||||
@ -1,15 +0,0 @@
|
||||
====================
|
||||
Enabling in Devstack
|
||||
====================
|
||||
|
||||
1. Download DevStack::
|
||||
|
||||
$ git clone https://git.openstack.org/openstack-dev/devstack
|
||||
$ cd devstack
|
||||
|
||||
2. Add the following repo as an external repository::
|
||||
|
||||
[[local|localrc]]
|
||||
enable_plugin zaqar https://git.openstack.org/openstack/zaqar
|
||||
|
||||
3. Run ``./stack.sh``
|
||||
@ -1,73 +0,0 @@
|
||||
#!/bin/bash
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
# not use this file except in compliance with the License. You may obtain
|
||||
# a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
# License for the specific language governing permissions and limitations
|
||||
# under the License.
|
||||
|
||||
# This script is executed inside gate_hook function in devstack gate.
|
||||
|
||||
OVERRIDE_ENABLED_SERVICES="mysql,key,tempest,zaqar-websocket,zaqar-wsgi"
|
||||
|
||||
export DEVSTACK_GATE_ZAQAR=1
|
||||
export DEVSTACK_GATE_INSTALL_TESTONLY=1
|
||||
export DEVSTACK_GATE_NO_SERVICES=1
|
||||
export DEVSTACK_GATE_TEMPEST=0
|
||||
export DEVSTACK_GATE_EXERCISES=0
|
||||
export DEVSTACK_GATE_TIMEOUT=90
|
||||
export KEEP_LOCALRC=1
|
||||
|
||||
export DEVSTACK_GATE_ZAQAR_TEST_SUITE=$1
|
||||
# NOTE(flaper87): Backwards compatibility until `project-config`'s
|
||||
# patch lands.
|
||||
export DEVSTACK_GATE_ZAQAR_BACKEND=${2:-$DEVSTACK_GATE_ZAQAR_TEST_SUITE}
|
||||
if [ "$DEVSTACK_GATE_ZAQAR_BACKEND" == "swift" ]; then
|
||||
OVERRIDE_ENABLED_SERVICES+=,s-proxy,s-object,s-container,s-account
|
||||
fi
|
||||
export DEVSTACK_LOCAL_CONFIG+=$"
|
||||
ZAQAR_BACKEND=$DEVSTACK_GATE_ZAQAR_BACKEND"
|
||||
export OVERRIDE_ENABLED_SERVICES
|
||||
|
||||
function run_devstack_gate() {
|
||||
$BASE/new/devstack-gate/devstack-vm-gate.sh
|
||||
}
|
||||
|
||||
function run_tempest_tests() {
|
||||
export DEVSTACK_GATE_TEMPEST=1
|
||||
export DEVSTACK_GATE_TEMPEST_NOTESTS=1
|
||||
run_devstack_gate
|
||||
|
||||
cd $BASE/new/tempest/
|
||||
sudo -E testr init
|
||||
sudo -E tox -eall-plugin zaqar
|
||||
}
|
||||
|
||||
function run_zaqarclient_tests() {
|
||||
run_devstack_gate
|
||||
cd $BASE/new/python-zaqarclient
|
||||
|
||||
source $BASE/new/devstack/openrc
|
||||
cat /etc/mongodb.conf
|
||||
ZAQARCLIENT_AUTH_FUNCTIONAL=1 nosetests tests.functional
|
||||
}
|
||||
|
||||
case "$DEVSTACK_GATE_ZAQAR_TEST_SUITE" in
|
||||
tempest)
|
||||
run_tempest_tests
|
||||
;;
|
||||
zaqarclient)
|
||||
run_zaqarclient_tests
|
||||
;;
|
||||
*)
|
||||
# NOTE(flaper87): Eventually, this will error
|
||||
run_zaqarclient_tests
|
||||
;;
|
||||
esac
|
||||
|
||||
@ -1,39 +0,0 @@
|
||||
#!/bin/bash
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
# not use this file except in compliance with the License. You may obtain
|
||||
# a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
# License for the specific language governing permissions and limitations
|
||||
# under the License.
|
||||
|
||||
# This script is executed inside post_test_hook function in devstack gate.
|
||||
|
||||
# source $BASE/new/devstack/openrc admin admin
|
||||
|
||||
function generate_test_results {
|
||||
if [ -f .testrepository/0 ]; then
|
||||
sudo .tox/py27-gate/bin/testr last --subunit > $WORKSPACE/testrepository.subunit
|
||||
sudo mv $WORKSPACE/testrepository.subunit $BASE/logs/testrepository.subunit
|
||||
sudo .tox/py27-gate/bin/python /usr/local/jenkins/slave_scripts/subunit2html.py $BASE/logs/testrepository.subunit $BASE/logs/testr_results.html
|
||||
sudo gzip -9 $BASE/logs/testrepository.subunit
|
||||
sudo gzip -9 $BASE/logs/testr_results.html
|
||||
sudo chown jenkins:jenkins $BASE/logs/testrepository.subunit.gz $BASE/logs/testr_results.html.gz
|
||||
sudo chmod a+r $BASE/logs/testrepository.subunit.gz $BASE/logs/testr_results.html.gz
|
||||
fi
|
||||
}
|
||||
|
||||
set -x
|
||||
|
||||
export ZAQAR_DIR="$BASE/new/zaqar"
|
||||
sudo chown -R stack:stack $ZAQAR_DIR
|
||||
cd $ZAQAR_DIR
|
||||
|
||||
# Collect and parse result
|
||||
generate_test_results
|
||||
exit $EXIT_CODE
|
||||
@ -1,320 +0,0 @@
|
||||
#!/bin/bash
|
||||
#
|
||||
# lib/zaqar
|
||||
# Install and start **Zaqar** service
|
||||
|
||||
# To enable a minimal set of Zaqar services, add the following to localrc:
|
||||
#
|
||||
# enable_service zaqar-websocket zaqar-wsgi
|
||||
#
|
||||
# Dependencies:
|
||||
# - functions
|
||||
# - OS_AUTH_URL for auth in api
|
||||
# - DEST set to the destination directory
|
||||
# - SERVICE_PASSWORD, SERVICE_TENANT_NAME for auth in api
|
||||
# - STACK_USER service user
|
||||
|
||||
# stack.sh
|
||||
# ---------
|
||||
# install_zaqar
|
||||
# install_zaqarui
|
||||
# configure_zaqar
|
||||
# init_zaqar
|
||||
# start_zaqar
|
||||
# stop_zaqar
|
||||
# cleanup_zaqar
|
||||
# cleanup_zaqar_mongodb
|
||||
|
||||
# Save trace setting
|
||||
XTRACE=$(set +o | grep xtrace)
|
||||
set +o xtrace
|
||||
|
||||
|
||||
# Functions
|
||||
# ---------
|
||||
|
||||
# Test if any Zaqar services are enabled
|
||||
# is_zaqar_enabled
|
||||
function is_zaqar_enabled {
|
||||
[[ ,${ENABLED_SERVICES} =~ ,"zaqar" ]] && return 0
|
||||
return 1
|
||||
}
|
||||
|
||||
# cleanup_zaqar() - Cleans up general things from previous
|
||||
# runs and storage specific left overs.
|
||||
function cleanup_zaqar {
|
||||
if [ "$ZAQAR_BACKEND" = 'mongodb' ] ; then
|
||||
cleanup_zaqar_mongodb
|
||||
fi
|
||||
}
|
||||
|
||||
# cleanup_zaqar_mongodb() - Remove residual data files, anything left over from previous
|
||||
# runs that a clean run would need to clean up
|
||||
function cleanup_zaqar_mongodb {
|
||||
if ! timeout $SERVICE_TIMEOUT sh -c "while ! mongo zaqar --eval 'db.dropDatabase();'; do sleep 1; done"; then
|
||||
die $LINENO "Mongo DB did not start"
|
||||
else
|
||||
full_version=$(mongo zaqar --eval 'db.dropDatabase();')
|
||||
mongo_version=`echo $full_version | cut -d' ' -f4`
|
||||
required_mongo_version='2.2'
|
||||
if [[ $mongo_version < $required_mongo_version ]]; then
|
||||
die $LINENO "Zaqar needs Mongo DB version >= 2.2 to run."
|
||||
fi
|
||||
fi
|
||||
}
|
||||
|
||||
# configure_zaqarclient() - Set config files, create data dirs, etc
|
||||
function configure_zaqarclient {
|
||||
setup_develop $ZAQARCLIENT_DIR
|
||||
}
|
||||
|
||||
# configure_zaqar() - Set config files, create data dirs, etc
|
||||
function configure_zaqar {
|
||||
setup_develop $ZAQAR_DIR
|
||||
|
||||
[ ! -d $ZAQAR_CONF_DIR ] && sudo mkdir -m 755 -p $ZAQAR_CONF_DIR
|
||||
sudo chown $USER $ZAQAR_CONF_DIR
|
||||
|
||||
if [[ -f $ZAQAR_DIR/etc/policy.json.sample ]]; then
|
||||
cp -p $ZAQAR_DIR/etc/policy.json.sample $ZAQAR_POLICY_CONF
|
||||
fi
|
||||
|
||||
[ ! -d $ZAQAR_API_LOG_DIR ] && sudo mkdir -m 755 -p $ZAQAR_API_LOG_DIR
|
||||
sudo chown $USER $ZAQAR_API_LOG_DIR
|
||||
|
||||
iniset $ZAQAR_CONF DEFAULT debug True
|
||||
iniset $ZAQAR_CONF DEFAULT unreliable True
|
||||
iniset $ZAQAR_CONF DEFAULT admin_mode True
|
||||
iniset $ZAQAR_CONF DEFAULT enable_deprecated_api_versions 1,1.1
|
||||
iniset $ZAQAR_CONF signed_url secret_key notreallysecret
|
||||
|
||||
if is_service_enabled key; then
|
||||
iniset $ZAQAR_CONF DEFAULT auth_strategy keystone
|
||||
fi
|
||||
|
||||
iniset $ZAQAR_CONF storage message_pipeline zaqar.notification.notifier
|
||||
|
||||
# Enable pooling by default for now
|
||||
iniset $ZAQAR_CONF DEFAULT admin_mode True
|
||||
iniset $ZAQAR_CONF 'drivers:transport:websocket' bind $ZAQAR_SERVICE_HOST
|
||||
iniset $ZAQAR_CONF 'drivers:transport:websocket' port $ZAQAR_WEBSOCKET_PORT
|
||||
iniset $ZAQAR_CONF drivers transport websocket
|
||||
|
||||
configure_auth_token_middleware $ZAQAR_CONF zaqar $ZAQAR_AUTH_CACHE_DIR
|
||||
|
||||
iniset $ZAQAR_CONF trustee auth_type password
|
||||
iniset $ZAQAR_CONF trustee auth_url $KEYSTONE_AUTH_URI
|
||||
iniset $ZAQAR_CONF trustee username $ZAQAR_TRUSTEE_USER
|
||||
iniset $ZAQAR_CONF trustee password $ZAQAR_TRUSTEE_PASSWORD
|
||||
iniset $ZAQAR_CONF trustee user_domain_id $ZAQAR_TRUSTEE_DOMAIN
|
||||
|
||||
iniset $ZAQAR_CONF DEFAULT pooling True
|
||||
iniset $ZAQAR_CONF 'pooling:catalog' enable_virtual_pool True
|
||||
|
||||
# NOTE(flaper87): Configure mongodb regardless so we can use it as a pool
|
||||
# in tests.
|
||||
configure_mongodb
|
||||
|
||||
if [ "$ZAQAR_BACKEND" = 'mongodb' ] ; then
|
||||
iniset $ZAQAR_CONF drivers message_store mongodb
|
||||
iniset $ZAQAR_CONF 'drivers:message_store:mongodb' uri mongodb://localhost:27017/zaqar
|
||||
iniset $ZAQAR_CONF 'drivers:message_store:mongodb' database zaqar
|
||||
|
||||
iniset $ZAQAR_CONF drivers management_store mongodb
|
||||
iniset $ZAQAR_CONF 'drivers:management_store:mongodb' uri mongodb://localhost:27017/zaqar_mgmt
|
||||
iniset $ZAQAR_CONF 'drivers:management_store:mongodb' database zaqar_mgmt
|
||||
elif [ "$ZAQAR_BACKEND" = 'redis' ] ; then
|
||||
recreate_database zaqar
|
||||
iniset $ZAQAR_CONF drivers management_store sqlalchemy
|
||||
iniset $ZAQAR_CONF 'drivers:management_store:sqlalchemy' uri `database_connection_url zaqar`
|
||||
iniset $ZAQAR_CONF 'drivers:management_store:sqlalchemy' database zaqar_mgmt
|
||||
|
||||
zaqar-sql-db-manage --config-file $ZAQAR_CONF upgrade head
|
||||
|
||||
iniset $ZAQAR_CONF drivers message_store redis
|
||||
iniset $ZAQAR_CONF 'drivers:message_store:redis' uri redis://localhost:6379
|
||||
iniset $ZAQAR_CONF 'drivers:message_store:redis' database zaqar
|
||||
configure_redis
|
||||
elif [ "$ZAQAR_BACKEND" = 'swift' ] ; then
|
||||
recreate_database zaqar
|
||||
iniset $ZAQAR_CONF drivers management_store sqlalchemy
|
||||
iniset $ZAQAR_CONF 'drivers:management_store:sqlalchemy' uri `database_connection_url zaqar`
|
||||
iniset $ZAQAR_CONF 'drivers:management_store:sqlalchemy' database zaqar_mgmt
|
||||
|
||||
zaqar-sql-db-manage --config-file $ZAQAR_CONF upgrade head
|
||||
|
||||
iniset $ZAQAR_CONF drivers message_store swift
|
||||
iniset $ZAQAR_CONF 'drivers:message_store:swift' auth_url $KEYSTONE_AUTH_URI_V3
|
||||
iniset $ZAQAR_CONF 'drivers:message_store:swift' uri swift://zaqar:$SERVICE_PASSWORD@/service
|
||||
fi
|
||||
|
||||
if is_service_enabled qpid || [ -n "$RABBIT_HOST" ] && [ -n "$RABBIT_PASSWORD" ]; then
|
||||
iniset $ZAQAR_CONF DEFAULT notification_driver messaging
|
||||
iniset $ZAQAR_CONF DEFAULT control_exchange zaqar
|
||||
fi
|
||||
iniset_rpc_backend zaqar $ZAQAR_CONF DEFAULT
|
||||
|
||||
pip_install uwsgi
|
||||
iniset $ZAQAR_UWSGI_CONF uwsgi http $ZAQAR_SERVICE_HOST:$ZAQAR_SERVICE_PORT
|
||||
iniset $ZAQAR_UWSGI_CONF uwsgi harakiri 60
|
||||
iniset $ZAQAR_UWSGI_CONF uwsgi processes 1
|
||||
iniset $ZAQAR_UWSGI_CONF uwsgi threads 4
|
||||
iniset $ZAQAR_UWSGI_CONF uwsgi wsgi-file $ZAQAR_DIR/zaqar/transport/wsgi/app.py
|
||||
iniset $ZAQAR_UWSGI_CONF uwsgi master true
|
||||
iniset $ZAQAR_UWSGI_CONF uwsgi add-header "Connection: close"
|
||||
|
||||
cleanup_zaqar
|
||||
}
|
||||
|
||||
function configure_redis {
|
||||
if is_ubuntu; then
|
||||
install_package redis-server
|
||||
pip_install redis
|
||||
elif is_fedora; then
|
||||
install_package redis
|
||||
pip_install redis
|
||||
else
|
||||
exit_distro_not_supported "redis installation"
|
||||
fi
|
||||
}
|
||||
|
||||
function configure_mongodb {
|
||||
# Set nssize to 2GB. This increases the number of namespaces supported
|
||||
# per database.
|
||||
pip_install pymongo
|
||||
if is_ubuntu; then
|
||||
install_package mongodb-server
|
||||
if ! grep -qF "smallfiles = true" /etc/mongodb.conf; then
|
||||
echo "smallfiles = true" | sudo tee --append /etc/mongodb.conf > /dev/null
|
||||
fi
|
||||
restart_service mongodb
|
||||
elif is_fedora; then
|
||||
install_package mongodb
|
||||
install_package mongodb-server
|
||||
sudo sed -i '/--smallfiles/!s/OPTIONS=\"/OPTIONS=\"--smallfiles /' /etc/sysconfig/mongod
|
||||
restart_service mongod
|
||||
fi
|
||||
}
|
||||
|
||||
# init_zaqar() - Initialize etc.
|
||||
function init_zaqar {
|
||||
# Create cache dir
|
||||
sudo mkdir -p $ZAQAR_AUTH_CACHE_DIR
|
||||
sudo chown $STACK_USER $ZAQAR_AUTH_CACHE_DIR
|
||||
rm -f $ZAQAR_AUTH_CACHE_DIR/*
|
||||
}
|
||||
|
||||
# install_zaqar() - Collect source and prepare
|
||||
function install_zaqar {
|
||||
setup_develop $ZAQAR_DIR
|
||||
|
||||
if is_service_enabled horizon; then
|
||||
install_zaqarui
|
||||
fi
|
||||
}
|
||||
|
||||
function install_zaqarui {
|
||||
git_clone $ZAQARUI_REPO $ZAQARUI_DIR $ZAQARUI_BRANCH
|
||||
# NOTE(flwang): Workaround for devstack bug: 1540328
|
||||
# where devstack install 'test-requirements' but should not do it
|
||||
# for zaqar-ui project as it installs Horizon from url.
|
||||
# Remove following two 'mv' commands when mentioned bug is fixed.
|
||||
mv $ZAQARUI_DIR/test-requirements.txt $ZAQARUI_DIR/_test-requirements.txt
|
||||
setup_develop $ZAQARUI_DIR
|
||||
mv $ZAQARUI_DIR/_test-requirements.txt $ZAQARUI_DIR/test-requirements.txt
|
||||
cp -a $ZAQARUI_DIR/zaqar_ui/enabled/* $HORIZON_DIR/openstack_dashboard/local/enabled/
|
||||
if [ -d $ZAQARUI_DIR/zaqar-ui/locale ]; then
|
||||
(cd $ZAQARUI_DIR/zaqar-ui; DJANGO_SETTINGS_MODULE=openstack_dashboard.settings ../manage.py compilemessages)
|
||||
fi
|
||||
}
|
||||
|
||||
# install_zaqarclient() - Collect source and prepare
|
||||
function install_zaqarclient {
|
||||
git_clone $ZAQARCLIENT_REPO $ZAQARCLIENT_DIR $ZAQARCLIENT_BRANCH
|
||||
# NOTE(flaper87): Ideally, this should be developed, but apparently
|
||||
# there's a bug in devstack that skips test-requirements when using
|
||||
# setup_develop
|
||||
setup_install $ZAQARCLIENT_DIR
|
||||
}
|
||||
|
||||
# start_zaqar() - Start running processes, including screen
|
||||
function start_zaqar {
|
||||
cat $ZAQAR_UWSGI_CONF
|
||||
run_process zaqar-wsgi "$ZAQAR_BIN_DIR/uwsgi --ini $ZAQAR_UWSGI_CONF --pidfile2 $ZAQAR_UWSGI_MASTER_PIDFILE"
|
||||
run_process zaqar-websocket "$ZAQAR_BIN_DIR/zaqar-server --config-file $ZAQAR_CONF"
|
||||
|
||||
echo "Waiting for Zaqar to start..."
|
||||
token=$(openstack token issue -c id -f value)
|
||||
if ! timeout $SERVICE_TIMEOUT sh -c "while ! wget --no-proxy -q --header=\"Client-ID:$(uuidgen)\" --header=\"X-Auth-Token:$token\" -O- $ZAQAR_SERVICE_PROTOCOL://$ZAQAR_SERVICE_HOST:$ZAQAR_SERVICE_PORT/v2/ping; do sleep 1; done"; then
|
||||
die $LINENO "Zaqar did not start"
|
||||
fi
|
||||
}
|
||||
|
||||
# stop_zaqar() - Stop running processes
|
||||
function stop_zaqar {
|
||||
local serv
|
||||
# Kill the zaqar screen windows
|
||||
for serv in zaqar-wsgi zaqar-websocket; do
|
||||
screen -S $SCREEN_NAME -p $serv -X kill
|
||||
done
|
||||
uwsgi --stop $ZAQAR_UWSGI_MASTER_PIDFILE
|
||||
}
|
||||
|
||||
function create_zaqar_accounts {
|
||||
create_service_user "zaqar"
|
||||
|
||||
if [[ "$KEYSTONE_IDENTITY_BACKEND" = 'sql' ]]; then
|
||||
|
||||
local zaqar_service=$(get_or_create_service "zaqar" \
|
||||
"messaging" "Zaqar Service")
|
||||
get_or_create_endpoint $zaqar_service \
|
||||
"$REGION_NAME" \
|
||||
"$ZAQAR_SERVICE_PROTOCOL://$ZAQAR_SERVICE_HOST:$ZAQAR_SERVICE_PORT" \
|
||||
"$ZAQAR_SERVICE_PROTOCOL://$ZAQAR_SERVICE_HOST:$ZAQAR_SERVICE_PORT" \
|
||||
"$ZAQAR_SERVICE_PROTOCOL://$ZAQAR_SERVICE_HOST:$ZAQAR_SERVICE_PORT"
|
||||
|
||||
local zaqar_ws_service=$(get_or_create_service "zaqar-websocket" \
|
||||
"messaging-websocket" "Zaqar Websocket Service")
|
||||
get_or_create_endpoint $zaqar_ws_service \
|
||||
"$REGION_NAME" \
|
||||
"$ZAQAR_SERVICE_PROTOCOL://$ZAQAR_SERVICE_HOST:$ZAQAR_WEBSOCKET_PORT" \
|
||||
"$ZAQAR_SERVICE_PROTOCOL://$ZAQAR_SERVICE_HOST:$ZAQAR_WEBSOCKET_PORT" \
|
||||
"$ZAQAR_SERVICE_PROTOCOL://$ZAQAR_SERVICE_HOST:$ZAQAR_WEBSOCKET_PORT"
|
||||
fi
|
||||
|
||||
if [ "$ZAQAR_BACKEND" = 'swift' ] ; then
|
||||
get_or_add_user_project_role ResellerAdmin zaqar service
|
||||
fi
|
||||
}
|
||||
|
||||
if is_service_enabled zaqar-websocket || is_service_enabled zaqar-wsgi; then
|
||||
if [[ "$1" == "stack" && "$2" == "install" ]]; then
|
||||
echo_summary "Installing Zaqar"
|
||||
install_zaqarclient
|
||||
install_zaqar
|
||||
elif [[ "$1" == "stack" && "$2" == "post-config" ]]; then
|
||||
echo_summary "Configuring Zaqar"
|
||||
configure_zaqar
|
||||
configure_zaqarclient
|
||||
|
||||
if is_service_enabled key; then
|
||||
create_zaqar_accounts
|
||||
fi
|
||||
|
||||
elif [[ "$1" == "stack" && "$2" == "extra" ]]; then
|
||||
echo_summary "Initializing Zaqar"
|
||||
init_zaqar
|
||||
start_zaqar
|
||||
fi
|
||||
|
||||
if [[ "$1" == "unstack" ]]; then
|
||||
stop_zaqar
|
||||
fi
|
||||
fi
|
||||
|
||||
# Restore xtrace
|
||||
$XTRACE
|
||||
|
||||
# Local variables:
|
||||
# mode: shell-script
|
||||
# End:
|
||||
@ -1,48 +0,0 @@
|
||||
# Set up default directories
|
||||
#---------------------------
|
||||
|
||||
ZAQAR_DIR=$DEST/zaqar
|
||||
ZAQARCLIENT_DIR=$DEST/python-zaqarclient
|
||||
ZAQAR_CONF_DIR=/etc/zaqar
|
||||
ZAQAR_CONF=$ZAQAR_CONF_DIR/zaqar.conf
|
||||
ZAQAR_POLICY_CONF=$ZAQAR_CONF_DIR/policy.json
|
||||
ZAQAR_UWSGI_CONF=$ZAQAR_CONF_DIR/uwsgi.conf
|
||||
ZAQAR_UWSGI_MASTER_PIDFILE=/tmp/uwsgizaqarmasterprocess.pid
|
||||
ZAQAR_API_LOG_DIR=/var/log/zaqar
|
||||
ZAQAR_API_LOG_FILE=$ZAQAR_API_LOG_DIR/queues.log
|
||||
ZAQAR_AUTH_CACHE_DIR=${ZAQAR_AUTH_CACHE_DIR:-/var/cache/zaqar}
|
||||
|
||||
# Support potential entry-points console scripts
|
||||
ZAQAR_BIN_DIR=$(get_python_exec_prefix)
|
||||
|
||||
# Set up database backend
|
||||
ZAQAR_BACKEND=${ZAQAR_BACKEND:-mongodb}
|
||||
|
||||
# Set Zaqar repository
|
||||
ZAQAR_REPO=${ZAQAR_REPO:-${GIT_BASE}/openstack/zaqar.git}
|
||||
ZAQAR_BRANCH=${ZAQAR_BRANCH:-master}
|
||||
|
||||
# Set client library repository
|
||||
ZAQARCLIENT_REPO=${ZAQARCLIENT_REPO:-${GIT_BASE}/openstack/python-zaqarclient.git}
|
||||
ZAQARCLIENT_BRANCH=${ZAQARCLIENT_BRANCH:-master}
|
||||
|
||||
# Set Zaqar UI repository
|
||||
ZAQARUI_DIR=$DEST/zaqar-ui
|
||||
ZAQARUI_REPO=${ZAQARUI_REPO:-${GIT_BASE}/openstack/zaqar-ui.git}
|
||||
ZAQARUI_BRANCH=${ZAQARUI_BRANCH:-$ZAQAR_BRANCH}
|
||||
|
||||
# Set Zaqar Connection Info
|
||||
ZAQAR_SERVICE_HOST=${ZAQAR_SERVICE_HOST:-$SERVICE_HOST}
|
||||
ZAQAR_SERVICE_PORT=${ZAQAR_SERVICE_PORT:-8888}
|
||||
ZAQAR_WEBSOCKET_PORT=${ZAQAR_WEBSOCKET_PORT:-9000}
|
||||
ZAQAR_SERVICE_PROTOCOL=${ZAQAR_SERVICE_PROTOCOL:-$SERVICE_PROTOCOL}
|
||||
|
||||
# Set Zaqar trust configuration
|
||||
ZAQAR_TRUSTEE_USER=${ZAQAR_TRUSTEE_USER:-zaqar}
|
||||
ZAQAR_TRUSTEE_PASSWORD=${ZAQAR_TRUSTEE_PASSWORD:-$SERVICE_PASSWORD}
|
||||
ZAQAR_TRUSTEE_DOMAIN=${ZAQAR_TRUSTEE_DOMAIN:-default}
|
||||
|
||||
# Tell Tempest this project is present
|
||||
TEMPEST_SERVICES+=,zaqar
|
||||
|
||||
enable_service zaqar-websocket zaqar-wsgi
|
||||
@ -1,69 +0,0 @@
|
||||
#!/bin/bash
|
||||
#
|
||||
# Copyright 2017 Catalyst IT Ltd.
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
# not use this file except in compliance with the License. You may obtain
|
||||
# a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
# License for the specific language governing permissions and limitations
|
||||
# under the License.
|
||||
|
||||
set -o errexit
|
||||
|
||||
source $GRENADE_DIR/grenaderc
|
||||
source $GRENADE_DIR/functions
|
||||
|
||||
source $TOP_DIR/openrc admin admin
|
||||
|
||||
ZAQAR_DEVSTACK_DIR=$(cd $(dirname "$0")/.. && pwd)
|
||||
source $ZAQAR_DEVSTACK_DIR/settings
|
||||
|
||||
set -o xtrace
|
||||
|
||||
|
||||
function create {
|
||||
# TODO(flwang): Create queue, create subscriptions, post messages,
|
||||
# delete queue
|
||||
:
|
||||
}
|
||||
|
||||
function verify {
|
||||
# TODO(flwang): Get queue, get messages, get subscriptions
|
||||
:
|
||||
}
|
||||
|
||||
function verify_noapi {
|
||||
:
|
||||
}
|
||||
|
||||
function destroy {
|
||||
# TODO(flwang): Purge queue, delete queue
|
||||
:
|
||||
}
|
||||
|
||||
# Dispatcher
|
||||
case $1 in
|
||||
"create")
|
||||
create
|
||||
;;
|
||||
"verify")
|
||||
verify
|
||||
;;
|
||||
"verify_noapi")
|
||||
verify_noapi
|
||||
;;
|
||||
"destroy")
|
||||
destroy
|
||||
;;
|
||||
"force_destroy")
|
||||
set +o errexit
|
||||
destroy
|
||||
;;
|
||||
esac
|
||||
|
||||
@ -1,19 +0,0 @@
|
||||
# Grenade needs to know that Zaqar has a Grenade plugin. This is done in the
|
||||
# gate by setting GRENADE_PLUGINRC when using openstack-infra/devstack-gate.
|
||||
# That means that in the project openstack-infra/project-config we will need to
|
||||
# update the Zaqar grenade job(s) in jenkins/jobs/devstack-gate.yaml with
|
||||
# this:
|
||||
# export GRENADE_PLUGINRC="enable_grenade_plugin zaqar https://git.openstack.org/openstack/zaqar"
|
||||
# If openstack-infra/project-config is not updated then the Grenade tests will
|
||||
# never get run for Zaqar
|
||||
|
||||
register_project_for_upgrade zaqar
|
||||
|
||||
|
||||
if grep -q 'management_store *= *sqlalchemy' /etc/zaqar/zaqar.conf; then
|
||||
register_db_to_save zaqar
|
||||
fi
|
||||
|
||||
devstack_localrc base enable_service zaqar-wsgi zaqar-websocket zaqar
|
||||
|
||||
devstack_localrc target enable_service zaqar-wsgi zaqar-websocket zaqar
|
||||
@ -1,26 +0,0 @@
|
||||
#!/bin/bash
|
||||
#
|
||||
#
|
||||
|
||||
set -o errexit
|
||||
|
||||
source $GRENADE_DIR/grenaderc
|
||||
source $GRENADE_DIR/functions
|
||||
|
||||
# We need base DevStack functions for this
|
||||
source $BASE_DEVSTACK_DIR/functions
|
||||
source $BASE_DEVSTACK_DIR/stackrc # needed for status directory
|
||||
source $BASE_DEVSTACK_DIR/lib/tls
|
||||
|
||||
# Keep track of the DevStack directory
|
||||
ZAQAR_DEVSTACK_DIR=$(dirname "$0")/..
|
||||
source $ZAQAR_DEVSTACK_DIR/settings
|
||||
source $ZAQAR_DEVSTACK_DIR/plugin.sh
|
||||
|
||||
set -o xtrace
|
||||
|
||||
for serv in zaqar-websocket; do
|
||||
stop_process $serv
|
||||
done
|
||||
|
||||
uwsgi --stop $ZAQAR_UWSGI_MASTER_PIDFILE
|
||||
@ -1,108 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
|
||||
# ``upgrade-zaqar``
|
||||
|
||||
echo "*********************************************************************"
|
||||
echo "Begin $0"
|
||||
echo "*********************************************************************"
|
||||
|
||||
# Clean up any resources that may be in use
|
||||
cleanup() {
|
||||
set +o errexit
|
||||
|
||||
echo "*********************************************************************"
|
||||
echo "ERROR: Abort $0"
|
||||
echo "*********************************************************************"
|
||||
|
||||
# Kill ourselves to signal any calling process
|
||||
trap 2; kill -2 $$
|
||||
}
|
||||
|
||||
trap cleanup SIGHUP SIGINT SIGTERM
|
||||
|
||||
# Keep track of the grenade directory
|
||||
RUN_DIR=$(cd $(dirname "$0") && pwd)
|
||||
|
||||
# Source params
|
||||
source $GRENADE_DIR/grenaderc
|
||||
|
||||
source $TOP_DIR/openrc admin admin
|
||||
|
||||
# Import common functions
|
||||
source $GRENADE_DIR/functions
|
||||
|
||||
# This script exits on an error so that errors don't compound and you see
|
||||
# only the first error that occurred.
|
||||
set -o errexit
|
||||
|
||||
if grep -q 'management_store *= *mongodb' /etc/zaqar/zaqar.conf; then
|
||||
mongodump --db zaqar_mgmt --out $SAVE_DIR/zaqar-mongodb-mgmt-dump.$BASE_RELEASE
|
||||
fi
|
||||
|
||||
if grep -q 'message_store *= *mongodb' /etc/zaqar/zaqar.conf; then
|
||||
mongodump --db zaqar --out $SAVE_DIR/zaqar-mongodb-message-dump.$BASE_RELEASE
|
||||
fi
|
||||
|
||||
if grep -q 'message_store *= *redis' /etc/zaqar/zaqar.conf; then
|
||||
redis-cli save
|
||||
cp /var/lib/redis/dump.rdb $SAVE_DIR/zaqar-redis-message-dump-$BASE_RELEASE.rdb
|
||||
fi
|
||||
|
||||
# Upgrade Zaqar
|
||||
# =============
|
||||
|
||||
# Duplicate some setup bits from target DevStack
|
||||
source $TARGET_DEVSTACK_DIR/stackrc
|
||||
source $TARGET_DEVSTACK_DIR/lib/tls
|
||||
|
||||
# Keep track of the DevStack directory
|
||||
ZAQAR_DEVSTACK_DIR=$(dirname "$0")/..
|
||||
source $ZAQAR_DEVSTACK_DIR/settings
|
||||
source $ZAQAR_DEVSTACK_DIR/plugin.sh
|
||||
|
||||
# Print the commands being run so that we can see the command that triggers
|
||||
# an error. It is also useful for following allowing as the install occurs.
|
||||
set -o xtrace
|
||||
|
||||
function wait_for_keystone {
|
||||
if ! wait_for_service $SERVICE_TIMEOUT ${KEYSTONE_AUTH_URI}/v$IDENTITY_API_VERSION/; then
|
||||
die $LINENO "keystone did not start"
|
||||
fi
|
||||
}
|
||||
|
||||
# Save current config files for posterity
|
||||
[[ -d $SAVE_DIR/etc.zaqar ]] || cp -pr $ZAQAR_CONF_DIR $SAVE_DIR/etc.zaqar
|
||||
|
||||
stack_install_service zaqar
|
||||
|
||||
if grep -q 'management_store *= *sqlalchemy' /etc/zaqar/zaqar.conf; then
|
||||
zaqar-sql-db-manage --config-file $ZAQAR_CONF upgrade head || die $LINENO "DB sync error"
|
||||
fi
|
||||
|
||||
# calls upgrade-zaqar for specific release
|
||||
upgrade_project zaqar $RUN_DIR $BASE_DEVSTACK_BRANCH $TARGET_DEVSTACK_BRANCH
|
||||
|
||||
start_zaqar
|
||||
wait_for_keystone
|
||||
|
||||
|
||||
# Don't succeed unless the services come up
|
||||
ensure_services_started zaqar-server
|
||||
|
||||
if grep -q 'management_store *= *mongodb' /etc/zaqar/zaqar.conf; then
|
||||
mongodump --db zaqar_mgmt --out $SAVE_DIR/zaqar-mongodb-mgmt-dump.$TARGET_RELEASE
|
||||
fi
|
||||
|
||||
if grep -q 'message_store *= *mongodb' /etc/zaqar/zaqar.conf; then
|
||||
mongodump --db zaqar --out $SAVE_DIR/zaqar-mongodb-message-dump.$TARGET_RELEASE
|
||||
fi
|
||||
|
||||
if grep -q 'message_store *= *redis' /etc/zaqar/zaqar.conf; then
|
||||
redis-cli save
|
||||
cp /var/lib/redis/dump.rdb $SAVE_DIR/zaqar-redis-message-dump-$TARGET_RELEASE.rdb
|
||||
fi
|
||||
|
||||
set +o xtrace
|
||||
echo "*********************************************************************"
|
||||
echo "SUCCESS: End $0"
|
||||
echo "*********************************************************************"
|
||||
@ -1,2 +0,0 @@
|
||||
Message-Queuing
|
||||
===============
|
||||
@ -1,120 +0,0 @@
|
||||
..
|
||||
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
not use this file except in compliance with the License. You may obtain
|
||||
a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
License for the specific language governing permissions and limitations
|
||||
under the License.
|
||||
|
||||
==========
|
||||
CORS Guide
|
||||
==========
|
||||
|
||||
Zaqar supports Cross-Origin Resource Sharing (CORS) now. The function is
|
||||
provided by oslo.middleware. Please see `Official Doc`_ and `OpenStack Spec`_
|
||||
for more detail. This guide is mainly tell users how to use it in Zaqar.
|
||||
|
||||
|
||||
New Config Options
|
||||
------------------
|
||||
|
||||
There are some new config options.
|
||||
|
||||
**allowed_origin**
|
||||
|
||||
Indicate whether this resource may be shared with the domain received in the
|
||||
requests "origin" header. Format: "<protocol>://<host>[:<port>]", no trailing
|
||||
slash. Example: https://horizon.example.com'.
|
||||
|
||||
**allow_credentials**
|
||||
|
||||
Indicate that the actual request can include user credentials. The default
|
||||
value is True.
|
||||
|
||||
**expose_headers**
|
||||
|
||||
Indicate which headers are safe to expose to the API. Defaults to HTTP Simple
|
||||
Headers. The default value is [].
|
||||
|
||||
**max_age**
|
||||
|
||||
Maximum cache age of CORS preflight requests. The default value is 3600.
|
||||
|
||||
**allow_methods**
|
||||
|
||||
Indicate which methods can be used during the actual request. The default value
|
||||
is ['OPTIONS', 'GET', 'HEAD', 'POST', 'PUT', 'DELETE', 'TRACE', 'PATCH'].
|
||||
|
||||
**allow_headers**
|
||||
|
||||
Indicate which header field names may be used during the actual request. The
|
||||
default value is [].
|
||||
|
||||
|
||||
Request and Response example
|
||||
----------------------------
|
||||
To use CORS, you should make sure that the feature is enabled::
|
||||
|
||||
[cors]
|
||||
enabled = true
|
||||
allowed_origin = http://example
|
||||
allow_methods = GET
|
||||
|
||||
the above example config options mean that Zaqar only receive the GET request
|
||||
from http://example domain. Here are some example request:
|
||||
1. Zaqar will do nothing if the request doesn't contain "Origin" header::
|
||||
|
||||
# curl -I -X GET http://10.229.47.217:8888 -H "Accept: application/json"
|
||||
|
||||
HTTP/1.1 300 Multiple Choices
|
||||
content-length: 668
|
||||
content-type: application/json; charset=UTF-8
|
||||
Connection: close
|
||||
|
||||
2. Zaqar will return nothing in response headers if the "Origin" is not in
|
||||
``allowed_origin``::
|
||||
|
||||
# curl -I -X GET http://10.229.47.217:8888 -H "Accept: application/json" -H "Origin: http://"
|
||||
|
||||
HTTP/1.1 300 Multiple Choices
|
||||
content-length: 668
|
||||
content-type: application/json; charset=UTF-8
|
||||
Connection: close
|
||||
|
||||
In the Zaqar log, we can see a message::
|
||||
|
||||
CORS request from origin 'http://' not permitted.
|
||||
|
||||
3. Zaqar will return CORS information if the "Origin" header is in
|
||||
``allowed_origin``::
|
||||
|
||||
# curl -I -X GET http://10.229.47.217:8888 -H "Accept: application/json" -H "Origin: http://example"
|
||||
|
||||
HTTP/1.1 300 Multiple Choices
|
||||
content-length: 668
|
||||
content-type: application/json; charset=UTF-8
|
||||
Vary: Origin
|
||||
Access-Control-Allow-Origin: http://example
|
||||
Access-Control-Allow-Credentials: true
|
||||
Connection: close
|
||||
|
||||
4. Zaqar will return more information if the request doesn't follow Zaqar's\
|
||||
CORS rule::
|
||||
|
||||
# curl -I -X PUT http://10.229.47.217:8888 -H "Accept: application/json" -H "Origin: http://example"
|
||||
HTTP/1.1 405 Method Not Allowed
|
||||
content-length: 0
|
||||
content-type: application/json; charset=UTF-8
|
||||
allow: GET, OPTIONS
|
||||
Vary: Origin
|
||||
Access-Control-Allow-Origin: http://example
|
||||
Access-Control-Allow-Credentials: true
|
||||
Connection: close
|
||||
|
||||
.. _Official Doc: https://docs.openstack.org/developer/oslo.middleware/cors.html
|
||||
.. _OpenStack Spec: http://specs.openstack.org/openstack/openstack-specs/specs/cors-support.html
|
||||
@ -1,124 +0,0 @@
|
||||
..
|
||||
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
not use this file except in compliance with the License. You may obtain
|
||||
a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
License for the specific language governing permissions and limitations
|
||||
under the License.
|
||||
|
||||
================
|
||||
OSprofiler Guide
|
||||
================
|
||||
|
||||
OSprofiler is a library from oslo. It's used for performance analysis. Please
|
||||
see `Official Doc`_ for more detail.
|
||||
|
||||
Preparation
|
||||
-----------
|
||||
OSprofiler now supports some kind of backends, such as Ceilometer, ElasticSearch
|
||||
, Messaging and MongoDB.
|
||||
|
||||
.. note:: 1. Ceilometer is only used for data collection, and Messaging is only
|
||||
used for data transfer. So Ceilometer only works when Messaging is enabled.
|
||||
2. ElasticSearch and MongoDB support both data collection and transfer. So
|
||||
they can be used standalone.
|
||||
|
||||
In this guide, we take MongoDB for example.
|
||||
|
||||
There are some new config options.
|
||||
|
||||
**enabled**
|
||||
|
||||
Enables the profiling for all services on this node. Default value is False
|
||||
(fully disable the profiling feature). This function may bring down Zaqar's
|
||||
performance, so please set to disable in production environment.
|
||||
|
||||
**connection_string**
|
||||
|
||||
Connection string for a notifier backend. Default value is messaging:// which
|
||||
sets the notifier to oslo_messaging. Here we set it to "mongodb://localhost:27017"
|
||||
|
||||
**hmac_keys**
|
||||
|
||||
Secret key(s) to use for encrypting context data for performance profiling.
|
||||
This string value should have the following format: <key1>[,<key2>,...<keyn>],
|
||||
where each key is some random string. A user who triggers the profiling via
|
||||
the REST API has to set one of these keys in the headers of the REST API call
|
||||
to include profiling results of this node for this particular project.
|
||||
|
||||
**trace_wsgi_transport**, **trace_message_store** and **trace_management_store**
|
||||
|
||||
The three layers during a user's request flow. Set to True to enable tracing
|
||||
for each layer.
|
||||
|
||||
So In this example, we should add the following config options::
|
||||
|
||||
[profiler]
|
||||
enabled = True
|
||||
connection_string = mongodb://localhost:27017
|
||||
hmac_keys = 123
|
||||
trace_wsgi_transport = True
|
||||
trace_message_store = True
|
||||
trace_management_store = True
|
||||
|
||||
.. note:: If you want to use MQ and Ceilometer, please leave the
|
||||
**connection_string** empty or indicate the MQ information. And please make
|
||||
sure that the following config options have be set in Ceilometer.conf
|
||||
|
||||
::
|
||||
|
||||
[DEFAULT]
|
||||
event_dispatchers = database
|
||||
|
||||
[oslo_messaging_notifications]
|
||||
topics = notifications, profiler
|
||||
|
||||
Then restart Zaqar service
|
||||
|
||||
Command Line
|
||||
------------
|
||||
|
||||
we can use OpenStack Client to analyse the user request now. For example, if we
|
||||
want to know the performance for "queue list", we can do like this:
|
||||
|
||||
1. OpenStack Client now supports OSprofiler by default. Only thing we need to
|
||||
do is adding ``--os-profile {hmac_keys}`` in the command::
|
||||
|
||||
openstack queue list --os-profile 123
|
||||
|
||||
"123" here is what we set in Zaqar config file. After the request is done,
|
||||
OpenStack Client will return a trace ID like::
|
||||
|
||||
Trace ID: 2902c7a3-ee18-4b08-aae7-4e34388f9352
|
||||
Display trace with command:
|
||||
osprofiler trace show --html 2902c7a3-ee18-4b08-aae7-4e34388f9352
|
||||
|
||||
Now the trace information has been stored in MongoDB already.
|
||||
|
||||
2. Use the command from the openstack client return information. The osprofiler
|
||||
command uses Ceilometer for data collection by default, so we need use
|
||||
``--connection-string`` to change it to mongoDB here::
|
||||
|
||||
osprofiler trace show --html 2902c7a3-ee18-4b08-aae7-4e34388f9352 --connection-string mongodb://localhost:27017
|
||||
|
||||
Then you can see the analysis information in html format now.
|
||||
|
||||
It also supports json format::
|
||||
|
||||
osprofiler trace show --json 2902c7a3-ee18-4b08-aae7-4e34388f9352 --connection-string mongodb://localhost:27017
|
||||
|
||||
Of course it supports to save the result to a file::
|
||||
|
||||
osprofiler trace show --json 2902c7a3-ee18-4b08-aae7-4e34388f9352 --out list_test --connection-string mongodb://localhost:27017
|
||||
|
||||
Then you can open the file "list_test" to get the result.
|
||||
|
||||
.. note:: If you used MQ for data transfer, the "--connection-string" here
|
||||
could be ignored or set it to your Ceilometer endpoint.
|
||||
|
||||
.. _Official Doc: http://docs.openstack.org/developer/osprofiler/background.html
|
||||
@ -1,87 +0,0 @@
|
||||
..
|
||||
Copyright (c) 2017 OpenStack Foundation
|
||||
All Rights Reserved.
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
not use this file except in compliance with the License. You may obtain
|
||||
a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
License for the specific language governing permissions and limitations
|
||||
under the License.
|
||||
|
||||
=======================
|
||||
Guru Meditation Reports
|
||||
=======================
|
||||
|
||||
Zaqar contains a mechanism whereby developers and system administrators can
|
||||
generate a report about the state of a running Zaqar executable.
|
||||
This report is called a *Guru Meditation Report* (*GMR* for short).
|
||||
|
||||
Generating a GMR
|
||||
----------------
|
||||
|
||||
For wsgi and websocket mode, a *GMR* can be generated by sending the *USR2*
|
||||
signal to any Zaqar process with support (see below).
|
||||
The *GMR* will then be outputted standard error for that particular process.
|
||||
|
||||
For example, suppose that ``zaqar-server`` has process id ``8675``, and was
|
||||
run with ``2>/var/log/zaqar/zaqar-server-err.log``.
|
||||
Then, ``kill -USR2 8675`` will trigger the Guru Meditation report to be
|
||||
printed to ``/var/log/zaqar/zaqar-server-err.log``.
|
||||
|
||||
For uwsgi mode, user should add a configuration in Zaqar's conf file::
|
||||
|
||||
[oslo_reports]
|
||||
file_event_handler=['The path to a file to watch for changes to trigger '
|
||||
'the reports, instead of signals. Setting this option '
|
||||
'disables the signal trigger for the reports.']
|
||||
file_event_handler_interval=['How many seconds to wait between polls when '
|
||||
'file_event_handler is set, default value '
|
||||
'is 1']
|
||||
|
||||
For example, you can specify "file_event_handler=/tmp/guru_report" and
|
||||
"file_event_handler_interval=1" in Zaqar's conf file.
|
||||
|
||||
A *GMR* can be generated by "touch"ing the file which was specified in
|
||||
file_event_handler. The *GMR* will then output to standard error for
|
||||
that particular process.
|
||||
|
||||
For example, suppose that ``zaqar-server`` was run with
|
||||
``2>/var/log/zaqar/zaqar-server-err.log``, and the file path is
|
||||
``/tmp/guru_report``.
|
||||
Then, ``touch /tmp/guru_report`` will trigger the Guru Meditation report to be
|
||||
printed to ``/var/log/zaqar/zaqar-server-err.log``.
|
||||
|
||||
Structure of a GMR
|
||||
------------------
|
||||
|
||||
The *GMR* is designed to be extensible; any particular executable may add
|
||||
its own sections. However, the base *GMR* consists of several sections:
|
||||
|
||||
Package
|
||||
Shows information about the package to which this process belongs,
|
||||
including version information
|
||||
|
||||
Threads
|
||||
Shows stack traces and thread ids for each of the threads within this process
|
||||
|
||||
Green Threads
|
||||
Shows stack traces for each of the green threads within this process
|
||||
(green threads don't have thread ids)
|
||||
|
||||
Configuration
|
||||
Lists all the configuration options currently accessible via the CONF object
|
||||
for the current process
|
||||
|
||||
Extending the GMR
|
||||
-----------------
|
||||
|
||||
As mentioned above, additional sections can be added to the GMR for a
|
||||
particular executable. For more information, see the inline documentation
|
||||
about oslo.reports:
|
||||
`oslo.reports <http://docs.openstack.org/developer/oslo.reports/>`_
|
||||
@ -1,13 +0,0 @@
|
||||
====================
|
||||
Administration Guide
|
||||
====================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
subscription_confirm
|
||||
OSprofiler
|
||||
CORS
|
||||
gmr
|
||||
running_benchmark
|
||||
writing_pipeline_stages
|
||||
@ -1,184 +0,0 @@
|
||||
..
|
||||
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
not use this file except in compliance with the License. You may obtain
|
||||
a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
License for the specific language governing permissions and limitations
|
||||
under the License.
|
||||
|
||||
=================
|
||||
Running benchmark
|
||||
=================
|
||||
|
||||
Introduction
|
||||
------------
|
||||
|
||||
This document describes how to run benchmarking tool.
|
||||
|
||||
Zaqar Contributors can use this tool to test how the particular code change
|
||||
affects Zaqar's performance.
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
1. First install and run zaqar-server.
|
||||
|
||||
For example, you can setup Zaqar in development environment.
|
||||
|
||||
See :doc:`../contributor/development.environment`.
|
||||
|
||||
2. In your terminal cd into your local Zaqar repo and install additional
|
||||
requirements:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ pip install -r bench-requirements.txt
|
||||
|
||||
3. Copy the configuration file to ~/.zaqar:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ cp etc/zaqar-benchmark.conf.sample ~/.zaqar/zaqar-benchmark.conf
|
||||
|
||||
4. In this configuration file specify where zaqar-server can be found:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
server_url = http://localhost:8888
|
||||
|
||||
5. The benchmarking tool needs a set of messages to work with. Specify the path
|
||||
to the file with messages in the configuration file. Alternatively, put
|
||||
it in the directory with the configuration file and name it
|
||||
``zaqar-benchmark-messages.json``.
|
||||
As a starting point, you can use the sample file from the etc directory:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ cp etc/zaqar-benchmark-messages.json ~/.zaqar/
|
||||
|
||||
If the file is not found or no file is specified, a single hard-coded
|
||||
message is used for all requests.
|
||||
|
||||
6. Run the benchmarking tool using the following command:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ zaqar-bench
|
||||
|
||||
By default, the command will run a performance test for 5 seconds, using one
|
||||
producer process with 10 greenlet workers, and one observer process with 5
|
||||
workers. The consumer role is disabled by default.
|
||||
|
||||
You can override these defaults in the config file or on the command line
|
||||
using a variety of options. For example, the following command runs a
|
||||
performance test for 30 seconds using 4 producer processes with 20 workers
|
||||
each, plus 4 consumer processes with 20 workers each.
|
||||
|
||||
Note that the observer role is also disabled in this example by setting its
|
||||
number of workers to zero:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ zaqar-bench -pp 4 -pw 10 -cp 4 -cw 20 -ow 0 -t 30
|
||||
|
||||
By default, the results are in human-readable format. For JSON output add
|
||||
the ``--noverbose`` flag. The non-verbose output looks similar to the
|
||||
following:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ zaqar-bench --noverbose
|
||||
Using 'envvars' credentials
|
||||
Using 'keystone' authentication method
|
||||
Benchmarking Zaqar API v2...
|
||||
{"params": {"consumer": {"processes": 1, "workers": 0}, "observer": {"processes": 1, "workers": 5}, "producer": {"processes": 1, "workers": 10}}, "consumer": {"claim_total_requests": 0, "ms_per_claim": 0, "total_reqs": 0, "reqs_per_sec": 0, "successful_reqs": 0, "duration_sec": 0, "ms_per_delete": 0, "messages_processed": 0}, "producer": {"duration_sec": 8.569170951843262, "ms_per_req": 201.715140507139, "total_reqs": 29, "successful_reqs": 29, "reqs_per_sec": 3.384224700729303}, "observer": {"duration_sec": 8.481178045272827, "ms_per_req": 407.40778711107043, "total_reqs": 18, "successful_reqs": 18, "reqs_per_sec": 2.122346672115049}}
|
||||
|
||||
By default, zaqar-bench is benchmarking Zaqar API version 2. To run
|
||||
benchmark against other API versions use ``-api`` parameter. For
|
||||
example:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ zaqar-bench -api 1.1
|
||||
|
||||
Configuring zaqar-bench to use Keystone authentication
|
||||
######################################################
|
||||
|
||||
It's possible to use zaqar-bench with Keystone authentication, if your Zaqar is
|
||||
configured to use Keystone authentication method and the Keystone service is
|
||||
running. For example, this is always true when running DevStack_ with
|
||||
unmodified ``zaqar.conf``.
|
||||
|
||||
Let's configure zaqar-bench too to use Keystone:
|
||||
|
||||
#. Set zaqar-bench's authentication method to Keystone.
|
||||
|
||||
By default zaqar-bench is using ``noauth`` method. This can be changed by
|
||||
setting the environment variable ``OS_AUTH_STRATEGY`` to ``keystone``.
|
||||
|
||||
To set this environment variable:
|
||||
|
||||
* temporarily, run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ export OS_AUTH_STRATEGY=keystone
|
||||
|
||||
* permanently, add this line to your ``~/bashrc`` file:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
export OS_AUTH_STRATEGY=keystone
|
||||
|
||||
Reboot your computer or just run in the terminal where you will start
|
||||
zaqar-bench:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ source ~/.bashrc
|
||||
|
||||
#. Set Keystone credentials for zaqar-bench.
|
||||
|
||||
* If you're running Zaqar under DevStack, **you can omit this step**,
|
||||
because zaqar-bench will automatically get administrator or user
|
||||
credentials from the one of the files created by DevStack: either from
|
||||
``/etc/openstack/clouds.yaml`` file or from
|
||||
``~/.config/openstack/clouds.yaml`` file, if it exists.
|
||||
|
||||
* If you're running manually configured Zaqar with manually configured
|
||||
Keystone (not under DevStack):
|
||||
|
||||
Add these lines to your ``~/.bashrc`` file and specify the valid Keystone
|
||||
credentials:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
export OS_AUTH_URL="http://<your keystone endpoint>/v2.0"
|
||||
export OS_USERNAME="<keystone user name>"
|
||||
export OS_PASSWORD="<the user's password>"
|
||||
export OS_PROJECT_NAME="<keystone project name for the user>"
|
||||
|
||||
Reboot your computer or just run in the terminal where you will start
|
||||
zaqar-bench:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ source ~/.bashrc
|
||||
|
||||
#. Run zaqar-bench as usual, for example:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ zaqar-bench
|
||||
|
||||
If everything is properly configured, zaqar-bench must show the line
|
||||
``Using 'keystone' authentication method`` and execute without
|
||||
authentication errors.
|
||||
|
||||
|
||||
.. _DevStack: http://docs.openstack.org/developer/devstack/
|
||||
@ -1,298 +0,0 @@
|
||||
..
|
||||
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
not use this file except in compliance with the License. You may obtain
|
||||
a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
License for the specific language governing permissions and limitations
|
||||
under the License.
|
||||
|
||||
==============================
|
||||
The subscription Confirm Guide
|
||||
==============================
|
||||
|
||||
The subscription confirm feature now supports webhook and email with both
|
||||
mongoDB and redis backend.
|
||||
This guide shows how to use this feature:
|
||||
|
||||
Webhook
|
||||
-------
|
||||
|
||||
.. note::
|
||||
|
||||
You should make sure that the message notification is enabled. By default,
|
||||
the ``message_pipeline`` config option in [storage] section should be set
|
||||
like: message_pipeline = zaqar.notification.notifier
|
||||
|
||||
1. Set the config option "require_confirmation" and add the policy to the
|
||||
policy.json file. Then restart Zaqar-wsgi service::
|
||||
|
||||
In the config file:
|
||||
[notification]
|
||||
require_confirmation = True
|
||||
|
||||
In the policy.json file:
|
||||
"subscription:confirm": "",
|
||||
|
||||
2. Create a subscription.
|
||||
|
||||
Here used zaqar/samples/zaqar/subscriber_service_sample.py be the subscriber
|
||||
endpoint for example.So before the step 2, you should start the subscriber
|
||||
service first.
|
||||
The service could be started simply by the command::
|
||||
|
||||
python zaqar/samples/zaqar/subscriber_service_sample.py
|
||||
|
||||
The service's default port is 5678. If you want to use a new port, the command
|
||||
will be like::
|
||||
|
||||
python zaqar/samples/zaqar/subscriber_service_sample.py new_port_number
|
||||
|
||||
The service will not confirm the subscription automatically by default. If you
|
||||
want to do that, the command will be like::
|
||||
|
||||
python zaqar/samples/zaqar/subscriber_service_sample.py --auto-confirm
|
||||
|
||||
Then create a subscription::
|
||||
|
||||
curl -i -X POST http://10.229.47.217:8888/v2/queues/test/subscriptions \
|
||||
-H "Content-type: application/json" \
|
||||
-H "Client-ID: de305d54-75b4-431b-adb2-eb6b9e546014" \
|
||||
-H "X-Auth-Token: 440b677561454ea8a7f872201dd4e2c4" \
|
||||
-d '{"subscriber":"http://10.229.47.217:5678", "ttl":3600, "options":{}}'
|
||||
|
||||
The response::
|
||||
|
||||
HTTP/1.1 201 Created
|
||||
content-length: 47
|
||||
content-type: application/json; charset=UTF-8
|
||||
location: http://10.229.47.217:8888/v2/queues/test/subscriptions
|
||||
Connection: close
|
||||
{"subscription_id": "576256b03990b480617b4063"}
|
||||
|
||||
At the same time, If the subscriber sample service is not start by
|
||||
"--auto confirm", you will receive a POST request in the subscriber sample
|
||||
service, the request is like::
|
||||
|
||||
WARNING:root:{"UnsubscribeBody": {"confirmed": false}, "URL-Methods": "PUT",
|
||||
"X-Project-ID": "51be2c72393e457ebf0a22a668e10a64",
|
||||
"URL-Paths": "/v2/queues/test/subscriptions/576256b03990b480617b4063/confirm",
|
||||
"URL-Expires": "2016-07-06T04:35:56", "queue_name": "test",
|
||||
"SubscribeURL": ["/v2/queues/test/subscriptions/576256b03990b480617b4063/confirm"],
|
||||
"SubscribeBody": {"confirmed": true},
|
||||
"URL-Signature": "d4038a40589cdb61cd13d5a6997472f5be779db441dd8fe0c597a6e465f30c41",
|
||||
"Message": "You have chosen to subscribe to the queue: test",
|
||||
"Message_Type": "SubscriptionConfirmation"}
|
||||
10.229.47.217 - - [06/Jul/2016 11:35:56] "POST / HTTP/1.1" 200 -
|
||||
|
||||
If you start the sample service with "--auto confirm", please go to step 6
|
||||
directly, because the step 5 will be done by the service automatically.
|
||||
|
||||
3. Get the subscription.
|
||||
The request::
|
||||
|
||||
curl -i -X GET http://10.229.47.217:8888/v2/queues/test/subscriptions/576256b03990b480617b4063 \
|
||||
-H "Content-type: application/json" \
|
||||
-H "Client-ID: de305d54-75b4-431b-adb2-eb6b9e546014" \
|
||||
-H "X-Auth-Token: 440b677561454ea8a7f872201dd4e2c4"
|
||||
|
||||
The response::
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
content-length: 154
|
||||
content-type: application/json; charset=UTF-8
|
||||
Connection: close
|
||||
{"confirmed": false, "age": 73, "id": "576256b03990b480617b4063",
|
||||
"subscriber": "http://10.229.47.217:5678", "source": "test", "ttl": 3600, "options": {}}
|
||||
|
||||
You can find that the "confirmed" property is false by default.
|
||||
|
||||
4. Post a message to the subscription's queue
|
||||
The request::
|
||||
|
||||
curl -i -X POST http://10.229.47.217:8888/v2/queues/test/messages \
|
||||
-H "Content-type: application/json" \
|
||||
-H "Client-ID: de305d54-75b4-431b-adb2-eb6b9e546014" \
|
||||
-H "X-Auth-Token: 440b677561454ea8a7f872201dd4e2c4" \
|
||||
-d '{"messages": [{"ttl": 3600,"body": "test123"}]}'
|
||||
|
||||
The response::
|
||||
|
||||
HTTP/1.1 201 Created
|
||||
content-length: 68
|
||||
content-type: application/json; charset=UTF-8
|
||||
location: http://10.229.47.217:8888/v2/queues/test/messages?ids=57624dee3990b4634d71bb4a
|
||||
Connection: close
|
||||
{"resources": ["/v2/queues/test/messages/57624dee3990b4634d71bb4a"]}
|
||||
|
||||
The subscriber received nothing and you will find a log info in zaqar-wsgi.::
|
||||
|
||||
2016-07-06 11:37:57.929 98400 INFO zaqar.notification.notifier
|
||||
[(None,)2473911afe2642c0b74d7e1200d9bba7 51be2c72393e457ebf0a22a668e10a64 - - -]
|
||||
The subscriber http://10.229.47.217:5678 is not confirmed.
|
||||
|
||||
5. Use the information showed in step3 to confirm the subscription
|
||||
The request::
|
||||
|
||||
curl -i -X PUT http://10.229.47.217:8888/v2/queues/test/subscriptions/576256b03990b480617b4063/confirm \
|
||||
-H "Content-type: application/json" \
|
||||
-H "Client-ID: de305d54-75b4-431b-adb2-eb6b9e546014" \
|
||||
-H "URL-Methods: PUT" -H "X-Project-ID: 51be2c72393e457ebf0a22a668e10a64" \
|
||||
-H "URL-Signature: d28dced4eabbb09878a73d9a7a651df3a3ce5434fcdb6c3727decf6c7078b282" \
|
||||
-H "URL-Paths: /v2/queues/test/subscriptions/576256b03990b480617b4063/confirm" \
|
||||
-H "URL-Expires: 2016-06-16T08:35:12" -d '{"confirmed": true}'
|
||||
|
||||
The response::
|
||||
|
||||
HTTP/1.1 204 No Content
|
||||
location: /v2/queues/test/subscriptions/576256b03990b480617b4063/confirm
|
||||
Connection: close
|
||||
|
||||
6. Repeat step3 to get the subscription
|
||||
The request::
|
||||
|
||||
curl -i -X GET http://10.229.47.217:8888/v2/queues/test/subscriptions/576256b03990b480617b4063 \
|
||||
-H "Content-type: application/json" \
|
||||
-H "Client-ID: de305d54-75b4-431b-adb2-eb6b9e546014" \
|
||||
-H "X-Auth-Token: 440b677561454ea8a7f872201dd4e2c4"
|
||||
|
||||
The response::
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
content-length: 155
|
||||
content-type: application/json; charset=UTF-8
|
||||
Connection: close
|
||||
{"confirmed": true, "age": 1370, "id": "576256b03990b480617b4063",
|
||||
"subscriber": "http://10.229.47.217:5678", "source": "test", "ttl": 3600,
|
||||
"options": {}}
|
||||
|
||||
The subscription is confirmed now.
|
||||
|
||||
7. Repeat step4 to post a new message.
|
||||
The request::
|
||||
|
||||
curl -i -X POST http://10.229.47.217:8888/v2/queues/test/messages \
|
||||
-H "Content-type: application/json" \
|
||||
-H "Client-ID: de305d54-75b4-431b-adb2-eb6b9e546014" \
|
||||
-H "X-Auth-Token: 440b677561454ea8a7f872201dd4e2c4" \
|
||||
-d '{"messages": [{"ttl": 3600,"body": "test123"}]}'
|
||||
|
||||
The response::
|
||||
|
||||
HTTP/1.1 201 Created
|
||||
content-length: 68
|
||||
content-type: application/json; charset=UTF-8
|
||||
location: http://10.229.47.217:8888/v2/queues/test/messages?ids=5762526d3990b474c80d5483
|
||||
Connection: close
|
||||
{"resources": ["/v2/queues/test/messages/5762526d3990b474c80d5483"]}
|
||||
|
||||
Then in subscriber sample service, you will receive a request::
|
||||
|
||||
WARNING:root:{"body": {"event": "BackupStarted"}, "queue_name": "test",
|
||||
"Message_Type": "Notification", "ttl": 3600}
|
||||
10.229.47.217 - - [06/Jul/2016 13:19:07] "POST / HTTP/1.1" 200 -
|
||||
|
||||
8. Unsubscription.
|
||||
The request::
|
||||
|
||||
curl -i -X PUT http://10.229.47.217:8888/v2/queues/test/subscriptions/576256b03990b480617b4063/confirm \
|
||||
-H "Content-type: application/json" \
|
||||
-H "Client-ID: de305d54-75b4-431b-adb2-eb6b9e546014" \
|
||||
-H "URL-Methods: PUT" -H "X-Project-ID: 51be2c72393e457ebf0a22a668e10a64" \
|
||||
-H "URL-Signature: d28dced4eabbb09878a73d9a7a651df3a3ce5434fcdb6c3727decf6c7078b282" \
|
||||
-H "URL-Paths: /v2/queues/test/subscriptions/576256b03990b480617b4063/confirm" \
|
||||
-H "URL-Expires: 2016-06-16T08:35:12" -d '{"confirmed": false}'
|
||||
|
||||
The response::
|
||||
|
||||
HTTP/1.1 204 No Content
|
||||
location: /v2/queues/test/subscriptions/576256b03990b480617b4063/confirm
|
||||
Connection: close
|
||||
|
||||
Then try to post a message. The subscriber will not receive the notification
|
||||
any more.
|
||||
|
||||
Email
|
||||
-----
|
||||
|
||||
1. For the email confirmation way, also need to set the config option
|
||||
"external_confirmation_url", "subscription_confirmation_email_template" and
|
||||
"unsubscribe_confirmation_email_template".
|
||||
|
||||
The confirmation page url that will be used in email subscription confirmation
|
||||
before notification, this page is not hosted in Zaqar server, user should
|
||||
build their own web service to provide this web page.
|
||||
|
||||
The subscription_confirmation_email_template let user to customize the
|
||||
subscription confirmation email content, including topic, body and sender.
|
||||
|
||||
The unsubscribe_confirmation_email_template let user to customize the
|
||||
unsubscribe confirmation email content, including topic, body and sender too::
|
||||
|
||||
In the config file:
|
||||
[notification]
|
||||
require_confirmation = True
|
||||
external_confirmation_url = http://web_service_url/
|
||||
subscription_confirmation_email_template = topic:Zaqar Notification - Subscription Confirmation,\
|
||||
body:'You have chosen to subscribe to the queue: {0}. This queue belongs to project: {1}. To confirm this subscription, click or visit this link below: {2}',\
|
||||
sender:Zaqar Notifications <no-reply@openstack.org>
|
||||
unsubscribe_confirmation_email_template = topic: Zaqar Notification - Unsubscribe Confirmation,\
|
||||
body:'You have unsubscribed successfully to the queue: {0}. This queue belongs to project: {1}. To resubscribe this subscription, click or visit this link below: {2}',\
|
||||
sender:Zaqar Notifications <no-reply@openstack.org>
|
||||
|
||||
In the policy.json file:
|
||||
"subscription:confirm": "",
|
||||
|
||||
2. Create a subscription.
|
||||
For email confirmation, you should create a subscription like this::
|
||||
|
||||
curl -i -X POST http://10.229.47.217:8888/v2/queues/test/subscriptions \
|
||||
-H "Content-type: application/json" \
|
||||
-H "Client-ID: de305d54-75b4-431b-adb2-eb6b9e546014" \
|
||||
-H "X-Auth-Token: 440b677561454ea8a7f872201dd4e2c4" \
|
||||
-d '{"subscriber":"your email address", "ttl":3600, "options":{}}'
|
||||
|
||||
The response::
|
||||
|
||||
HTTP/1.1 201 Created
|
||||
content-length: 47
|
||||
content-type: application/json; charset=UTF-8
|
||||
location: http://10.229.47.217:8888/v2/queues/test/subscriptions
|
||||
Connection: close
|
||||
{"subscription_id": "576256b03990b480617b4063"}
|
||||
|
||||
After the subscription created, Zaqar will send a email to the email address
|
||||
of subscriber. The email specifies how to confirm the subscription.
|
||||
|
||||
3. Click the confirmation page link in the email body
|
||||
|
||||
4. The confirmation page will send the subscription confirmation request to
|
||||
Zaqar server automatically. User also can choose to unsubscribe by clicking
|
||||
the unsubscription link in this page, that will cause Zaqar to cancel this
|
||||
subscription and send another email to notify this unsubscription action.
|
||||
Zaqar providers two examples of those web pages that will help user to build
|
||||
their own pages::
|
||||
|
||||
zaqar/sample/html/subscriptionConfirmation.html
|
||||
zaqar/sample/html/unsubscriptionConfirmation.html
|
||||
|
||||
User can place those pages in web server like Apache to access them by browser,
|
||||
so the external_confirmation_url will be like this::
|
||||
|
||||
http://127.0.0.1:8080/subscriptionConfirmation.html
|
||||
|
||||
For CORS, here used zaqar/samples/html/confirmation_web_service_sample.py
|
||||
be a simple web service for example, it will relay the confirmation request to
|
||||
Zaqar Server. So before Step 3, you should start the web service first.
|
||||
The service could be started simply by the command::
|
||||
|
||||
python zaqar/samples/html/confirmation_web_service_sample.py
|
||||
|
||||
The service's default port is 5678. If you want to use a new port, the command
|
||||
will be like::
|
||||
|
||||
python zaqar/samples/html/confirmation_web_service_sample.py new_port_number
|
||||
@ -1,225 +0,0 @@
|
||||
========================================
|
||||
Writing stages for the storage pipelines
|
||||
========================================
|
||||
|
||||
Introduction
|
||||
~~~~~~~~~~~~
|
||||
|
||||
A pipeline is a set of stages needed to process a request. When a new request
|
||||
comes to Zaqar, first the message goes through the transport layer pipeline and
|
||||
then through one of the storage layer pipelines depending on the type of
|
||||
operation of each particular request. For example, if Zaqar receives a
|
||||
request to make a queue-related operation, the storage layer pipeline will be
|
||||
``queue pipeline``. Zaqar always has the actual storage controller as the
|
||||
final storage layer pipeline stage.
|
||||
|
||||
By setting the options in the ``[storage]`` section of ``zaqar.conf``
|
||||
you can add additional stages to these storage layer pipelines:
|
||||
|
||||
* **Claim pipeline**
|
||||
* **Message pipeline** with built-in stage available to use:
|
||||
|
||||
* ``zaqar.notification.notifier`` - sends notifications to the queue
|
||||
subscribers on each incoming message to the queue, i.e. enables
|
||||
notifications functionality.
|
||||
* **Queue pipeline**
|
||||
* **Subscription pipeline**
|
||||
|
||||
The storage layer pipelines options are empty by default, because additional
|
||||
stages can affect the performance of Zaqar. Depending on the stages, the
|
||||
sequence in which the option values are listed does matter or not.
|
||||
|
||||
You can add your own external stages to the storage layer pipelines.
|
||||
|
||||
Things to know before writing the stage
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Stages in the pipeline must implement storage controller methods they need
|
||||
to hook. You can find all available to hook methods in the abstract classes in
|
||||
``zaqar/storage/base.py``. For example, if you're looking for all methods
|
||||
available to hook for the queue storage layer pipeline, see ``Queue``
|
||||
class in ``zaqar/storage/base.py``. As you can see, Zaqar's built-in stage
|
||||
``zaqar.notification.notifier`` implements ``post`` method of
|
||||
``zaqar.storage.base.Message`` abstract class.
|
||||
|
||||
A stage can halt the pipeline immediate by returning a value that is not
|
||||
None; otherwise, processing will continue to the next stage, ending with the
|
||||
actual storage controller.
|
||||
|
||||
.. warning::
|
||||
|
||||
For the most of the cases it does not matter what non-None value the storage
|
||||
pipeline returns, but sometimes the returned value is used by the transport
|
||||
layer and you have to be careful. For example, during queue creation
|
||||
request, if the storage driver returns ``True``, the transport layer
|
||||
responds to the client with the ``201`` http response code, if ``False``,
|
||||
it responds with ``204`` http response code. See:
|
||||
``zaqar.transport.wsgi.v2_0.queues.ItemResource#on_put``.
|
||||
|
||||
Zaqar finds stages with their source codes through the Python entry points
|
||||
mechanism. All Python packages containing stages for Zaqar must register
|
||||
their stages under ``zaqar.storage.stages`` entry point group during their
|
||||
install either by ``setup.py`` or by ``setup.cfg``. If the stage is registered,
|
||||
and the name of the stage's entry point is specified by the user in the one of
|
||||
``zaqar.conf`` storage layer pipeline options, the stage will be loaded to
|
||||
the particular storage layer pipeline. Zaqar imports stages as plugins. See
|
||||
``zaqar.storage.pipeline#_get_storage_pipeline``.
|
||||
|
||||
For additional information about plugins see: `Stevedore - Creating Plugins`_
|
||||
and `Stevedore - Loading the Plugins`_.
|
||||
|
||||
Example of external stage (written outside Zaqar package)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This is an example of small package with a stage that can process queue-related
|
||||
requests in Zaqar. The stage does not do anything useful, but is good as
|
||||
example.
|
||||
|
||||
File tree structure of the package:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
.
|
||||
├── setup.py
|
||||
└── ubershystages
|
||||
├── __init__.py
|
||||
└── queues
|
||||
├── __init__.py
|
||||
└── lovely.py
|
||||
|
||||
2 directories, 4 files
|
||||
|
||||
``setup.py``:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from setuptools import setup, find_packages
|
||||
|
||||
setup(
|
||||
name='ubershystages',
|
||||
version='1.0',
|
||||
|
||||
description='Demonstration package for Zaqar with plugin pipeline stage',
|
||||
|
||||
author='Ubershy',
|
||||
author_email='ubershy@gmail.com',
|
||||
|
||||
url='',
|
||||
|
||||
classifiers=['Development Status :: 3 - Alpha',
|
||||
'License :: OSI Approved :: Apache Software License',
|
||||
'Programming Language :: Python',
|
||||
'Programming Language :: Python :: 2',
|
||||
'Programming Language :: Python :: 2.7',
|
||||
'Programming Language :: Python :: 3',
|
||||
'Programming Language :: Python :: 3.5',
|
||||
'Intended Audience :: Developers',
|
||||
'Environment :: Console',
|
||||
],
|
||||
|
||||
platforms=['Any'],
|
||||
|
||||
scripts=[],
|
||||
|
||||
packages=find_packages(),
|
||||
include_package_data=True,
|
||||
|
||||
entry_points={
|
||||
'zaqar.storage.stages': [
|
||||
'ubershy.lovelyplugin = ubershystages.queues.lovely:LovelyStage',
|
||||
],
|
||||
},
|
||||
|
||||
zip_safe=False,
|
||||
)
|
||||
|
||||
``lovely.py``:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class LovelyStage(object):
|
||||
"""This stage:
|
||||
1. Prints 'Lovely stage is processing request...' on each queue creation or
|
||||
deletion request.
|
||||
2. Prints 'Oh, what a lovely day!' on each creation request of a queue
|
||||
named 'lovely'.
|
||||
3. Prevents deletion of a queue named 'lovely' and prints 'Secretly keeping
|
||||
lovely queue' on such attempt.
|
||||
"""
|
||||
|
||||
def __init__(self, *args, **kwargs):
|
||||
print("Lovely stage is loaded!")
|
||||
|
||||
def create(self, name, metadata=None, project=None):
|
||||
"""Stage's method which processes queue creation request.
|
||||
|
||||
:param name: The queue name
|
||||
:param project: Project id
|
||||
"""
|
||||
|
||||
self.printprocessing()
|
||||
if name == 'lovely':
|
||||
print("Oh, what a lovely day!")
|
||||
|
||||
def delete(self, name, project=None):
|
||||
"""Stage's method which processes queue deletion request.
|
||||
|
||||
:param name: The queue name
|
||||
:param project: Project id
|
||||
:returns: Something non-None, if the queue has a name 'lovely'. It will
|
||||
stop further processing through the other stages of the pipeline, and
|
||||
the request will not reach the storage controller driver, preventing
|
||||
queue deletion from the database.
|
||||
"""
|
||||
|
||||
self.printprocessing()
|
||||
if name == 'lovely':
|
||||
print('Secretly keeping lovely queue')
|
||||
something = "shhh... it's a bad practice"
|
||||
return something
|
||||
|
||||
def printprocessing(self):
|
||||
print('Lovely stage is processing request...')
|
||||
|
||||
To install the package to the system in the root directory of the package run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# pip install -e .
|
||||
|
||||
In ``zaqar.conf`` add ``ubershy.lovelyplugin`` to the ``queue_pipeline``
|
||||
option:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[storage]
|
||||
queue_pipeline = ubershy.lovelyplugin
|
||||
|
||||
Start Zaqar:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ zaqar-server
|
||||
|
||||
If the stage has successfully loaded to Zaqar you will see amongst terminal
|
||||
output lines the ``Lovely stage is loaded!`` line. Then you can try to perform
|
||||
queue create and queue delete operations with the queue 'lovely' and see what
|
||||
will happen in Zaqar's database.
|
||||
|
||||
.. note::
|
||||
|
||||
You can hold multiple stages in one package, just be sure that all stages
|
||||
will be registered as entry points. For example, in the ``setup.py`` you
|
||||
can register additional ``ubershy.nastyplugin`` stage:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
entry_points={
|
||||
'zaqar.storage.stages': [
|
||||
'ubershy.lovelyplugin = ubershystages.queues.lovely:LovelyStage',
|
||||
'ubershy.nastyplugin = ubershystages.messages.nasty:NastyStage',
|
||||
],
|
||||
},
|
||||
|
||||
.. _`Stevedore - Creating Plugins`: http://docs.openstack.org/developer/stevedore/tutorial/creating_plugins.html
|
||||
.. _`Stevedore - Loading the Plugins`: http://docs.openstack.org/developer/stevedore/tutorial/loading.html
|
||||
@ -1,234 +0,0 @@
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
# implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
#
|
||||
# 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 os
|
||||
import sys
|
||||
|
||||
# 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('../'))
|
||||
sys.path.insert(0, os.path.abspath('./'))
|
||||
|
||||
# -- General configuration ----------------------------------------------------
|
||||
|
||||
# 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.autodoc',
|
||||
'sphinx.ext.coverage',
|
||||
'sphinx.ext.ifconfig',
|
||||
'sphinx.ext.graphviz',
|
||||
'openstackdocstheme',
|
||||
]
|
||||
|
||||
# autodoc generation is a bit aggressive and a nuisance
|
||||
# when doing heavy text edit cycles. Execute "export SPHINX_DEBUG=1"
|
||||
# in your terminal to disable
|
||||
|
||||
todo_include_todos = True
|
||||
|
||||
# The suffix of source filenames.
|
||||
source_suffix = '.rst'
|
||||
|
||||
# The encoding of source files.
|
||||
#source_encoding = 'utf-8'
|
||||
|
||||
# The master toctree document.
|
||||
master_doc = 'index'
|
||||
|
||||
# General information about the project.
|
||||
project = u'zaqar'
|
||||
copyright = u'2010-present, OpenStack Foundation'
|
||||
|
||||
# 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.
|
||||
#
|
||||
from zaqar.version import version_info
|
||||
# The full version, including alpha/beta/rc tags.
|
||||
release = version_info.release_string()
|
||||
# The short X.Y version.
|
||||
version = version_info.version_string()
|
||||
|
||||
# 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 documents that shouldn't be included in the build.
|
||||
unused_docs = [
|
||||
'api_ext/rst_extension_template',
|
||||
'installer',
|
||||
]
|
||||
|
||||
# List of directories, relative to source directory, that shouldn't be searched
|
||||
# for source files.
|
||||
exclude_trees = []
|
||||
|
||||
# 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 = False
|
||||
|
||||
# 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 = ['zaqar.']
|
||||
|
||||
# -- Options for man page output ----------------------------------------------
|
||||
|
||||
# Grouping the document tree for man pages.
|
||||
# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual'
|
||||
|
||||
# -- Options for HTML output --------------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. Major themes that come with
|
||||
# Sphinx are currently 'default' and 'sphinxdoc'.
|
||||
# html_theme_path = ["."]
|
||||
# html_theme = '_theme'
|
||||
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
|
||||
# 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
|
||||
# "<project> v<release> 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 = []
|
||||
|
||||
# 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.
|
||||
#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_use_modindex = 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, an OpenSearch description file will be output, and all pages will
|
||||
# contain a <link> tag referring to it. The value of this option must be the
|
||||
# base URL from which the finished HTML is served.
|
||||
#html_use_opensearch = ''
|
||||
|
||||
# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
|
||||
#html_file_suffix = ''
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = 'zaqardoc'
|
||||
|
||||
|
||||
# -- Options for LaTeX output -------------------------------------------------
|
||||
|
||||
# The paper size ('letter' or 'a4').
|
||||
#latex_paper_size = 'letter'
|
||||
|
||||
# The font size ('10pt', '11pt' or '12pt').
|
||||
#latex_font_size = '10pt'
|
||||
|
||||
# Grouping the document tree into LaTeX files. List of tuples
|
||||
# (source start file, target name, title, author, documentclass
|
||||
# [howto/manual]).
|
||||
latex_documents = [
|
||||
('index', 'Zaqar.tex', u'Zaqar Documentation',
|
||||
u'Anso Labs, LLC', '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
|
||||
|
||||
# Additional stuff for the LaTeX preamble.
|
||||
#latex_preamble = ''
|
||||
|
||||
# Documents to append as an appendix to all manuals.
|
||||
#latex_appendices = []
|
||||
|
||||
# If false, no module index is generated.
|
||||
#latex_use_modindex = True
|
||||
|
||||
# -- Options for openstackdocstheme -------------------------------------------
|
||||
repository_name = 'openstack/zaqar'
|
||||
bug_project = 'zaqar'
|
||||
bug_tag = ''
|
||||
@ -1,298 +0,0 @@
|
||||
..
|
||||
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
not use this file except in compliance with the License. You may obtain
|
||||
a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
License for the specific language governing permissions and limitations
|
||||
under the License.
|
||||
|
||||
====================================
|
||||
Setting up a development environment
|
||||
====================================
|
||||
|
||||
This section describes how to setup a working Python development environment
|
||||
that you can use in developing Zaqar on Ubuntu or Fedora. These instructions
|
||||
assume that you are familiar with Git. Refer to GettingTheCode_ for
|
||||
additional information.
|
||||
|
||||
.. _GettingTheCode: http://wiki.openstack.org/GettingTheCode
|
||||
|
||||
|
||||
Virtual environments
|
||||
--------------------
|
||||
|
||||
Use virtualenv_ to track and manage Python dependencies for developing and
|
||||
testing Zaqar.
|
||||
Using virtualenv_ enables you to install Python dependencies in an isolated
|
||||
virtual environment, instead of installing the packages at the system level.
|
||||
|
||||
.. _virtualenv: http://pypi.python.org/pypi/virtualenv
|
||||
|
||||
.. note::
|
||||
|
||||
Virtualenv is useful for development purposes, but is not typically used for
|
||||
full integration testing or production usage. If you want to learn about
|
||||
production best practices, check out the `OpenStack Operations Guide`_.
|
||||
|
||||
.. _`OpenStack Operations Guide`: http://docs.openstack.org/ops/
|
||||
|
||||
Install GNU/Linux system dependencies
|
||||
#####################################
|
||||
|
||||
.. note::
|
||||
|
||||
This section is tested for Zaqar on Ubuntu 14.04 (Trusty) and Fedora-based
|
||||
(RHEL 6.1) distributions. Feel free to add notes and change according to your
|
||||
experiences or operating system. Learn more about contributing to Zaqar
|
||||
documentation in the :doc:`welcome` manual.
|
||||
|
||||
Install the prerequisite packages.
|
||||
|
||||
On Ubuntu:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sudo apt-get install gcc python-pip libxml2-dev libxslt1-dev python-dev zlib1g-dev
|
||||
|
||||
On Fedora-based distributions (e.g., Fedora/RHEL/CentOS):
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sudo yum install gcc python-pip libxml2-devel libxslt-devel python-devel
|
||||
|
||||
Install MongoDB
|
||||
###############
|
||||
|
||||
You also need to have MongoDB_ installed and running.
|
||||
|
||||
.. _MongoDB: http://www.mongodb.org
|
||||
|
||||
On Ubuntu, follow the instructions in the
|
||||
`MongoDB on Ubuntu Installation Guide`_.
|
||||
|
||||
.. _`MongoDB on Ubuntu installation guide`: http://docs.mongodb.org/manual/tutorial/install-mongodb-on-ubuntu/
|
||||
|
||||
On Fedora-based distributions, follow the instructions in the
|
||||
`MongoDB on Red Hat Enterprise, CentOS, Fedora, or Amazon Linux Installation Guide`_.
|
||||
|
||||
.. _`MongoDB on Red Hat Enterprise, CentOS, Fedora, or Amazon Linux installation guide`: http://docs.mongodb.org/manual/tutorial/install-mongodb-on-red-hat-centos-or-fedora-linux/
|
||||
|
||||
.. note::
|
||||
|
||||
If you are Contributor and plan to run Unit tests on Zaqar, you may want to
|
||||
add this line to mongodb configuration file (``etc/mongod.conf`` or
|
||||
``etc/mongodb.conf`` depending on distribution):
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
smallfiles = true
|
||||
|
||||
Many Zaqar's Unit tests do not clean up their testing databases after
|
||||
executing. And database files consume much disk space even if they do not
|
||||
contain any records. This behavior will be fixed soon.
|
||||
|
||||
Getting the code
|
||||
################
|
||||
|
||||
Get the code from git.openstack.org to create a local repository with Zaqar:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ git clone https://git.openstack.org/openstack/zaqar.git
|
||||
|
||||
Configuration
|
||||
#############
|
||||
|
||||
#. From your home folder create the ``~/.zaqar`` folder. This directory holds
|
||||
the configuration files for Zaqar:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ mkdir ~/.zaqar
|
||||
|
||||
#. Generate the sample configuration file ``zaqar/etc/zaqar.conf.sample``:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ pip install tox
|
||||
$ cd zaqar
|
||||
$ tox -e genconfig
|
||||
|
||||
#. Copy the Zaqar configuration samples to the directory ``~/.zaqar/``:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ cp etc/zaqar.conf.sample ~/.zaqar/zaqar.conf
|
||||
$ cp etc/logging.conf.sample ~/.zaqar/logging.conf
|
||||
|
||||
#. Find the ``[drivers]`` section in ``~/.zaqar/zaqar.conf`` and specify
|
||||
``mongodb`` as the message store:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
message_store = mongodb
|
||||
management_store = mongodb
|
||||
|
||||
#. Then find ``[drivers:message_store:mongodb]`` and
|
||||
``[drivers:management_store:mongodb]`` sections and specify the
|
||||
:samp:`{URI}` to point to your local mongodb instance by adding this line
|
||||
to both the sections:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
uri = mongodb://$MONGODB_HOST:$MONGODB_PORT
|
||||
|
||||
By default you will have:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
uri = mongodb://127.0.0.1:27017
|
||||
|
||||
This :samp:`{URI}` points to single mongodb node which of course is not
|
||||
reliable, so you need to set in the ``[default]`` section of configuration
|
||||
file:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
unreliable = True
|
||||
|
||||
For your reference, you can omit this parameter or set it to False only
|
||||
if the provided :samp:`{URI}` to your mongodb is actually the URI to mongodb
|
||||
Replica Set or Mongos. Also it must have "Write concern" parameter set to
|
||||
``majority`` or to a number more than ``1``.
|
||||
|
||||
For example, :samp:`{URI}` to reliable mongodb can look like this:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
uri = mongodb://mydb0,mydb1,mydb2:27017/?replicaSet=foo&w=2
|
||||
|
||||
Where ``mydb0``, ``mydb1``, ``mydb2`` are addresses of the configured
|
||||
mongodb Replica Set nodes, ``replicaSet`` (Replica Set name) parameter is
|
||||
set to ``foo``, ``w`` (Write concern) parameter is set to ``2``.
|
||||
|
||||
#. For logging, find the ``[handler_file]`` section in
|
||||
``~/.zaqar/logging.conf`` and modify as desired:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
args=('zaqar.log', 'w')
|
||||
|
||||
Installing and using virtualenv
|
||||
###############################
|
||||
|
||||
#. Install virtualenv by running:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ pip install virtualenv
|
||||
|
||||
#. Create and activate a virtual environment:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ virtualenv zaqarenv
|
||||
$ source zaqarenv/bin/activate
|
||||
|
||||
#. Install Zaqar:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ pip install -e .
|
||||
|
||||
#. Install the required Python binding for MongoDB:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ pip install pymongo
|
||||
|
||||
#. Start Zaqar server in ``info`` logging mode:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ zaqar-server -v
|
||||
|
||||
Or you can start Zaqar server in ``debug`` logging mode:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ zaqar-server -d
|
||||
|
||||
#. Verify Zaqar is running by creating a queue via curl. In a separate
|
||||
terminal run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ curl -i -X PUT http://localhost:8888/v1/queues/samplequeue -H "Content-type: application/json"
|
||||
|
||||
#. Get ready to code!
|
||||
|
||||
.. note::
|
||||
|
||||
You can run the Zaqar server in the background by passing the
|
||||
``--daemon`` flag:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ zaqar-server -v --daemon
|
||||
|
||||
But with this method you will not get immediate visual feedback and it will
|
||||
be harder to kill and restart the process.
|
||||
|
||||
Troubleshooting
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
No handlers found for zaqar.client (...)
|
||||
""""""""""""""""""""""""""""""""""""""""
|
||||
|
||||
This happens because the current user cannot create the log file (for the
|
||||
default configuration in ``/var/log/zaqar/server.log``). To solve it, create
|
||||
the folder:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sudo mkdir /var/log/zaqar
|
||||
|
||||
Create the file:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sudo touch /var/log/zaqar/server.log
|
||||
|
||||
And try running the server again.
|
||||
|
||||
DevStack
|
||||
--------
|
||||
|
||||
If you want to use Zaqar in an integrated OpenStack developing environment, you
|
||||
can add it to your DevStack_ deployment.
|
||||
|
||||
To do this, you first need to add the following setting to your ``local.conf``:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
enable_plugin zaqar https://git.openstack.org/openstack/zaqar
|
||||
|
||||
Then run the ``stack.sh`` script as usual.
|
||||
|
||||
.. _DevStack: http://docs.openstack.org/developer/devstack/
|
||||
|
||||
Running tests
|
||||
-------------
|
||||
|
||||
See :doc:`running_tests` for details.
|
||||
|
||||
Running the benchmarking tool
|
||||
-----------------------------
|
||||
|
||||
See :doc:`../admin/running_benchmark` for details.
|
||||
|
||||
Contributing your work
|
||||
----------------------
|
||||
|
||||
See :doc:`welcome` and :doc:`first_patch` for details.
|
||||
@ -1,320 +0,0 @@
|
||||
..
|
||||
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
not use this file except in compliance with the License. You may obtain
|
||||
a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
License for the specific language governing permissions and limitations
|
||||
under the License.
|
||||
|
||||
================
|
||||
Your first patch
|
||||
================
|
||||
|
||||
This section describes how to create your first patch and upload it to
|
||||
Gerrit_ for reviewing.
|
||||
|
||||
|
||||
Create your contributor accounts and set up your code environment
|
||||
-----------------------------------------------------------------
|
||||
|
||||
Accounts setup
|
||||
##############
|
||||
|
||||
You will need to create a Launchpad_ account to login to the Gerrit_ review
|
||||
system dashboard.
|
||||
This is also useful for automatically crediting bug fixes to you when you
|
||||
address them with your code commits. You will also have to sign the
|
||||
`Contributors License Agreement`_ and `join the OpenStack Foundation`_.
|
||||
It is a good idea to use the same email all of these accounts to
|
||||
avoid hooks errors.
|
||||
|
||||
Visit the `Gerrit Workflow's account setup`_ section in the wiki to get
|
||||
more information on setting up your accounts.
|
||||
|
||||
.. _Launchpad: http://launchpad.net/
|
||||
.. _Gerrit: http://review.openstack.org/
|
||||
.. _`Contributors License Agreement`: http://docs.openstack.org/infra/manual/developers.html#account-setup
|
||||
.. _`join the OpenStack Foundation`: http://openstack.org/join
|
||||
.. _`Gerrit Workflow's account setup`: http://docs.openstack.org/infra/manual/developers.html#account-setup
|
||||
|
||||
SSH setup
|
||||
#########
|
||||
|
||||
You are going to need to create and upload an SSH key to Gerrit to be able to
|
||||
commit changes for review. To create an SSH key:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ ssh-keygen –t rsa
|
||||
|
||||
You can optionally enter a password to enhance security.
|
||||
|
||||
View and copy your SSH key:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ less ~/.ssh/id_rsa.pub
|
||||
|
||||
Now you can `upload the SSH key to Gerrit`_.
|
||||
|
||||
.. _`upload the SSH key to Gerrit`: https://review.openstack.org/#/settings/ssh-keys
|
||||
|
||||
Git Review installation
|
||||
#######################
|
||||
|
||||
Before you start working, make sure you have ``git-review`` installed on your
|
||||
system.
|
||||
|
||||
You can install it with the following command:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ pip install git-review
|
||||
|
||||
``Git-review`` checks if you can authenticate to Gerrit with your SSH key.
|
||||
It will ask you for your username. You can configure your Gerrit username so
|
||||
you don't have to keep re-entering it every time you want to use
|
||||
``git-review``:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ git config --global gitreview.username yourgerritusername
|
||||
|
||||
You can also save some time by entering your email and your name:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ git config --global gitreview.email "yourgerritemail"
|
||||
$ git config --global gitreview.name "Firstname Lastname"
|
||||
|
||||
You can view your Gerrit user name in the `settings page`_.
|
||||
|
||||
.. _`settings page`: https://review.openstack.org/#/settings/
|
||||
|
||||
Project setup
|
||||
#############
|
||||
|
||||
Clone the Zaqar repository with the following git command:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ git clone git://git.openstack.org/openstack/zaqar.git
|
||||
|
||||
For information on how to set up the Zaqar development environment
|
||||
see :doc:`development.environment`.
|
||||
|
||||
Before writing code, you will have to do some configurations to connect your
|
||||
local repository with Gerrit. You will only need to do this your first time
|
||||
setting up the development environment.
|
||||
|
||||
You can set ``git-review`` to configure the project and install the Gerrit
|
||||
change-id commit hook with the following command:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ cd zaqar
|
||||
$ git review -s
|
||||
|
||||
If you get the error "We don't know where your Gerrit is", you will need to add
|
||||
a new git remote. The URL should be in the error message. Copy that and create
|
||||
the new remote. It looks something like:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ git remote add gerrit ssh://<username>@review.openstack.org:29418/openstack/zaqar.git
|
||||
|
||||
In the project directory you have a hidden ``.git`` directory and a
|
||||
``.gitreview`` file. You can view them with the following command:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ ls -la
|
||||
|
||||
Making a patch
|
||||
--------------
|
||||
|
||||
Pick or report a bug
|
||||
####################
|
||||
|
||||
You can start tackling some bugs from the `bugs list in Launchpad`_.
|
||||
If you find a bug you want to work on, assign yourself. Make sure to read the
|
||||
bug report. If you need more information, ask the reporter to provide more
|
||||
details through a comment on Launchpad or through IRC or email.
|
||||
|
||||
If you find a bug, look through Launchpad to see if it has been reported. If it
|
||||
hasn't, report the bug, and ask for another developer to confirm it. You can
|
||||
start working on it if another developer confirms the bug.
|
||||
|
||||
Here are some details you might want to include when filling out a bug report:
|
||||
|
||||
* The release, or milestone, or commit ID corresponding to the software that
|
||||
you are running
|
||||
* The operating system and version where you've identified the bug
|
||||
* Steps to reproduce the bug, including what went wrong
|
||||
* Description of the expected results instead of what you saw
|
||||
* Portions of your log files so that you include only relevant excerpts
|
||||
|
||||
In the bug comments, you can contribute instructions on how to fix a given bug,
|
||||
and set the status to "Triaged".
|
||||
|
||||
You can read more about `Launchpad bugs`_ in the wiki.
|
||||
|
||||
.. _`bugs list in Launchpad`: https://bugs.launchpad.net/zaqar
|
||||
.. _`Launchpad bugs`: https://wiki.openstack.org/wiki/Bugs
|
||||
|
||||
Workflow
|
||||
########
|
||||
|
||||
Make sure your repo is up to date. You can update it with the following git
|
||||
commands:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ git remote update
|
||||
$ git checkout master
|
||||
$ git pull --ff-only origin master
|
||||
|
||||
Create a topic branch. You can create one with the following git command:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ git checkout -b TOPIC-BRANCH
|
||||
|
||||
If you are working on a blueprint, name your :samp:`{TOPIC-BRANCH}`
|
||||
``bp/BLUEPRINT`` where :samp:`{BLUEPRINT}` is the name of a blueprint in
|
||||
Launchpad (for example, "bp/authentication"). The general convention when
|
||||
working on bugs is to name the branch ``bug/BUG-NUMBER`` (for example,
|
||||
"bug/1234567").
|
||||
|
||||
Read more about the commit syntax in the `Gerrit workflow`_ wiki.
|
||||
|
||||
.. _`Gerrit workflow`: http://docs.openstack.org/infra/manual/developers.html#development-workflow
|
||||
|
||||
Common problems
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
#. You realized that you were working in master and you haven't made any
|
||||
commits. Solution:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ git checkout -b newbranch
|
||||
$ git commit -a -m "Edited"
|
||||
|
||||
If you already created the branch, omit the ``-b``.
|
||||
|
||||
You put all your changes to :samp:`{newbranch}`. Problem solved.
|
||||
|
||||
#. You realized that you were working in master and you have made commits to
|
||||
master. Solution:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ git branch newbranch
|
||||
$ git reset --hard HEAD~x
|
||||
$ git checkout newbranch
|
||||
|
||||
Where ``x`` is the number of commits you have made to master.
|
||||
And remember, you will lose any uncommitted work.
|
||||
|
||||
You put your commits in :samp:`{newbranch}`. Problem solved.
|
||||
|
||||
#. You made multiple commits and realized that Gerrit requires one commit per
|
||||
patch. Solution:
|
||||
|
||||
* You need to squash your previous commits. Make sure you are in your
|
||||
branch and follow `squashing guide`_. Then fill commit message properly.
|
||||
|
||||
You squashed your commits. Problem solved.
|
||||
|
||||
Design principles
|
||||
#################
|
||||
|
||||
Zaqar lives by the following design principles:
|
||||
|
||||
* `DRY`_
|
||||
* `YAGNI`_
|
||||
* `KISS`_
|
||||
|
||||
.. _`DRY`: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
|
||||
.. _`YAGNI`: https://en.wikipedia.org/wiki/YAGNI
|
||||
.. _`KISS`: https://en.wikipedia.org/wiki/KISS_principle
|
||||
|
||||
Try to stick to these design principles when working on your patch.
|
||||
|
||||
Test your code
|
||||
##############
|
||||
|
||||
It is important to test your code and follow the python code style guidelines.
|
||||
See :doc:`running_tests` for details on testing.
|
||||
|
||||
Submitting a patch
|
||||
------------------
|
||||
|
||||
Once you finished coding your fix, add and commit your final changes.
|
||||
Your commit message should:
|
||||
|
||||
* Provide a brief description of the change in the first line.
|
||||
* Insert a single blank line after the first line.
|
||||
* Provide a detailed description of the change in the following lines,
|
||||
breaking paragraphs where needed.
|
||||
* The first line should be limited to 50 characters and should not end with a
|
||||
period.
|
||||
* Subsequent lines should be wrapped at 72 characters.
|
||||
* Put the 'Change-id', 'Closes-Bug #NNNNN' and 'blueprint NNNNNNNNNNN'
|
||||
lines at the very end.
|
||||
|
||||
Read more about `making a good commit message`_.
|
||||
|
||||
To submit it for review use the following git command:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ git review
|
||||
|
||||
You will see the URL of your review page once it is successfully sent.
|
||||
|
||||
You can also see your reviews in :guilabel:`My Changes` in Gerrit. The first
|
||||
thing to watch for is a ``+1`` in the :guilabel:`Verified` column next to your
|
||||
patch in the server and/or client list of pending patches.
|
||||
|
||||
If the "Jenkins" user gives you a ``-1``, you'll need to check the log it posts
|
||||
to find out what gate test failed, update your patch, and resubmit.
|
||||
|
||||
You can set your patch as a :guilabel:`work in progress` if your patch is
|
||||
not ready to be merged, but you would still like some feedback from other
|
||||
developers. To do this leave a review on your patch setting
|
||||
:guilabel:`Workflow` to ``-1``.
|
||||
|
||||
Once the gate has verified your patch, other Zaqar developers will take a look
|
||||
and submit their comments. When you get two or more ``+2``'s from core
|
||||
reviewers, the patch will be approved and merged.
|
||||
|
||||
Don't be discouraged if a reviewer submits their comments with a ``-1``.
|
||||
Patches iterate through several updates and reviews before they are ready for
|
||||
merging.
|
||||
|
||||
To reply to feedback save all your comments as draft, then click on the
|
||||
:guilabel:`Review` button. When replying to feedback, you as the patch
|
||||
author can use the score of ``0``. The only exception to using the score of
|
||||
``0`` is when you discover a blocking issue and you don't want your patch to
|
||||
be merged. In which case, you can review your own patch with a ``-2``, while
|
||||
you decide whether to keep, refactor, or withdraw the patch.
|
||||
|
||||
Professional conduct
|
||||
--------------------
|
||||
|
||||
The Zaqar team holds reviewers accountable for promoting a positive,
|
||||
constructive culture within our program.
|
||||
|
||||
If you ever feel that a reviewer is not acting professionally or is violating
|
||||
the OpenStack community code of conduct, please let the PTL know immediately
|
||||
so that he or she can help resolve the issue.
|
||||
|
||||
.. _`making a good commit message`: https://wiki.openstack.org/wiki/GitCommitMessages
|
||||
.. _`squashing guide` : http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html
|
||||
@ -1,115 +0,0 @@
|
||||
..
|
||||
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
not use this file except in compliance with the License. You may obtain
|
||||
a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
License for the specific language governing permissions and limitations
|
||||
under the License.
|
||||
|
||||
=================
|
||||
Your first review
|
||||
=================
|
||||
|
||||
The review stage is a very important part in the development process. Following
|
||||
are some of the reasons this stage is important:
|
||||
|
||||
* Getting other developers feedback minimizes the risk of adding
|
||||
regressions to the code base and ensures the quality of the code being
|
||||
merged.
|
||||
* Building the community encourages everyone to review code. Everyone
|
||||
appreciates having their code reviewed.
|
||||
* Since developers are always learning from being exposed to the points of view
|
||||
of others, reviews help developers to improve their coding skills.
|
||||
* Providing a review is a great way to become familiar with the code.
|
||||
|
||||
Everyone is encourages to review code. You don't need to know every detail of
|
||||
the code base. You need to understand only what the code related to the fix
|
||||
does.
|
||||
|
||||
Step by step
|
||||
------------
|
||||
|
||||
Go to ``review.openstack.org`` and filter by `Open Zaqar fixes`_. Select a fix
|
||||
from the list to review. Try to select an easy patch for your first review.
|
||||
That will help you to gain some confidence. Download the patch to your local
|
||||
repository and test it:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ git review -d [review-id]
|
||||
|
||||
The :samp:`{review-id}` is the number in the URL (check the screenshot for more
|
||||
details).
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ git review -d 92979
|
||||
|
||||
.. image:: images/zaqar_review_id.png
|
||||
:alt: Zaqar review id
|
||||
|
||||
This git command creates a branch with the author's name and enables you to
|
||||
test the patch in your local environment.
|
||||
|
||||
* Inspect the code. Use all of the best programming practices you know as you
|
||||
review the code.
|
||||
* Give code location feedback.
|
||||
Do you consider that some code should be better located in another place
|
||||
within the file, or maybe in another file? If so, suggest this in the
|
||||
review comment and score with a ``-1`` if you think that it's that
|
||||
important.
|
||||
* Give code-style feedback.
|
||||
Do you think that the code structure could be improved? Keep the DRY,
|
||||
YAGNI and KISS principles in mind.
|
||||
* Give grammar and orthography feedback. Many of our contributors are not
|
||||
native English speakers, so it is common to find some errors of this type.
|
||||
* Make sure that:
|
||||
|
||||
* The commit message is formatted appropriately.
|
||||
Check `Git Commit Messages`_ for more information on how you should
|
||||
write a git commit message.
|
||||
* The coding style matches guidelines given in ``HACKING.rst``.
|
||||
* The patch is not too big.
|
||||
You might need to split some patches to improve cohesion and/or reduce
|
||||
size.
|
||||
* The patch does what the commit message promises.
|
||||
* Unit and functional tests are included and/or updated.
|
||||
* If during the inspection you see a specific line you would like to bring up
|
||||
to discussion in the final review, leave feedback as an inline comment in
|
||||
Gerrit. This will make the review process easier. You can also use
|
||||
prefixes described in :doc:`reviewer_guide` for Zaqar inline comments.
|
||||
* Keep in mind the :doc:`reviewer_guide` and be respectful when leaving
|
||||
feedback.
|
||||
* Hit the :guilabel:`Review` button in the web UI to publish your comments
|
||||
and assign a score.
|
||||
* Things to consider when leaving a score:
|
||||
|
||||
* You can score with a ``-1`` if you think that there are things to fix. We
|
||||
have to be careful to not stall the cycle just because a few nits, so
|
||||
downvoting also depends on the current stage of the development cycle
|
||||
and the severity of the flaw you see.
|
||||
* You can score with a "0" if you are the author of the fix and you want to
|
||||
respond to the reviewers comments, or if you are a reviewer and you want
|
||||
to point out some reminder for future developing (e.g. the deadline is
|
||||
the next day and the fix needs to be merged, but you want something to be
|
||||
improved).
|
||||
* You can score with ``+1`` if the fix works and you think that the code
|
||||
looks good, upvoting is your choice.
|
||||
* Remember to leave any comment that you think is important in the comment
|
||||
form. When you are done, click :guilabel:`Publish Comments`.
|
||||
|
||||
For more details on how to do a review, check out the `Gerrit Workflow
|
||||
Review section`_ document.
|
||||
|
||||
.. _`Open Zaqar fixes`: https://review.openstack.org/#/q/status:open+zaqar,n,z
|
||||
.. _`Git Commit Messages`: https://wiki.openstack.org/wiki/GitCommitMessages
|
||||
.. _`Gerrit Workflow Review section`: http://docs.openstack.org/infra/manual/developers.html#code-review
|
||||
|
||||
|
||||
@ -1,28 +0,0 @@
|
||||
..
|
||||
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
not use this file except in compliance with the License. You may obtain
|
||||
a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
License for the specific language governing permissions and limitations
|
||||
under the License.
|
||||
|
||||
========================
|
||||
Code reviews with Gerrit
|
||||
========================
|
||||
|
||||
Zaqar uses the `Gerrit`_ tool to review proposed code changes. The review site
|
||||
is http://review.openstack.org.
|
||||
|
||||
Gerrit is a complete replacement for GitHub pull requests. `All GitHub pull
|
||||
requests to the Zaqar repository will be ignored`.
|
||||
|
||||
See `Development Workflow with Gerrit`_ for more detailed documentation on how
|
||||
to work with Gerrit.
|
||||
|
||||
.. _Gerrit: https://www.gerritcodereview.com/
|
||||
.. _Development Workflow with Gerrit: http://docs.openstack.org/infra/manual/developers.html#development-workflow
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 76 KiB |
@ -1,42 +0,0 @@
|
||||
==================
|
||||
Contribution Guide
|
||||
==================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
welcome
|
||||
development.environment
|
||||
first_patch
|
||||
first_review
|
||||
launchpad
|
||||
gerrit
|
||||
jenkins
|
||||
reviewer_guide
|
||||
running_tests
|
||||
test_suite
|
||||
|
||||
Modules reference
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
Zaqar is composed of two layers:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
transport
|
||||
storage
|
||||
|
||||
The **transport drivers** are responsible for interacting with Zaqar clients.
|
||||
Every query made by clients is processed by the transport layer, which is in
|
||||
charge of passing this information to the backend and then returning the
|
||||
response in a format understandable by the client.
|
||||
|
||||
The **storage drivers** are responsible for interacting with the storage
|
||||
backends and, that way, store or retrieve the data coming from the transport
|
||||
layer.
|
||||
|
||||
In order to keep these layers decoupled, we have established that
|
||||
**checks should be performed in the appropriate layer**. In other words,
|
||||
transport drivers must guarantee that the incoming data is well-formed and
|
||||
storage drivers must enforce their data model stays consistent.
|
||||
@ -1,32 +0,0 @@
|
||||
..
|
||||
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
not use this file except in compliance with the License. You may obtain
|
||||
a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
License for the specific language governing permissions and limitations
|
||||
under the License.
|
||||
|
||||
===================================
|
||||
Continuous integration with Jenkins
|
||||
===================================
|
||||
|
||||
Zaqar uses a `Jenkins`_ server to automate development tasks. The Jenkins
|
||||
front-end is at http://jenkins.openstack.org. You must have an account on
|
||||
`Launchpad`_ to be able to access the OpenStack Jenkins site.
|
||||
|
||||
Jenkins performs tasks such as running static code analysis, running unit
|
||||
tests, and running functional tests. For more details on the jobs being run by
|
||||
Jenkins, see the code reviews on http://review.openstack.org. Tests are run
|
||||
automatically and comments are put on the reviews automatically with the
|
||||
results.
|
||||
|
||||
You can also get a view of the jobs that are currently running from the Zuul
|
||||
status dashboard, http://status.openstack.org/zuul/.
|
||||
|
||||
.. _Jenkins: http://jenkins-ci.org
|
||||
.. _Launchpad: http://launchpad.net
|
||||
@ -1,56 +0,0 @@
|
||||
==============================
|
||||
Project hosting with Launchpad
|
||||
==============================
|
||||
|
||||
`Launchpad`_ hosts the Zaqar project. The Zaqar project homepage on Launchpad is
|
||||
http://launchpad.net/zaqar.
|
||||
|
||||
Launchpad credentials
|
||||
---------------------
|
||||
|
||||
Creating a login on Launchpad is important even if you don't use the Launchpad
|
||||
site itself, since Launchpad credentials are used for logging in on several
|
||||
OpenStack-related sites. These sites include:
|
||||
|
||||
* `Wiki`_
|
||||
* Gerrit (see :doc:`gerrit`)
|
||||
* Jenkins (see :doc:`jenkins`)
|
||||
|
||||
Mailing list
|
||||
------------
|
||||
|
||||
The developers mailing list address is ``openstack-dev@lists.openstack.org``.
|
||||
This is a common mailing list across all OpenStack projects.
|
||||
To participate in the mailing list:
|
||||
|
||||
Subscribe at http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
|
||||
|
||||
The mailing list archives are at http://lists.openstack.org/pipermail/openstack-dev.
|
||||
|
||||
Bug tracking
|
||||
------------
|
||||
|
||||
Report Zaqar bugs at https://bugs.launchpad.net/zaqar
|
||||
|
||||
Feature requests (Blueprints)
|
||||
-----------------------------
|
||||
|
||||
Zaqar uses Launchpad Blueprints to track feature requests. Blueprints are at
|
||||
https://blueprints.launchpad.net/zaqar.
|
||||
|
||||
Technical support (Answers)
|
||||
---------------------------
|
||||
|
||||
Zaqar uses Launchpad Answers to track Zaqar technical support questions. The
|
||||
Zaqar Answers page is at https://answers.launchpad.net/zaqar.
|
||||
|
||||
Note that `Ask OpenStack`_ (which is not hosted on Launchpad) can also be used
|
||||
for technical support requests.
|
||||
|
||||
You can also reach us in ``#openstack-zaqar`` IRC channel at
|
||||
``irc.freenode.org``.
|
||||
|
||||
.. _Launchpad: http://launchpad.net
|
||||
.. _Wiki: http://wiki.openstack.org
|
||||
.. _Zaqar Team: https://launchpad.net/zaqar
|
||||
.. _Ask OpenStack: http://ask.openstack.org/
|
||||
@ -1,165 +0,0 @@
|
||||
..
|
||||
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
not use this file except in compliance with the License. You may obtain
|
||||
a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
License for the specific language governing permissions and limitations
|
||||
under the License.
|
||||
|
||||
==============
|
||||
Reviewer Guide
|
||||
==============
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
Our program follows the usual OpenStack review process, albeit with some
|
||||
important additions (see below). See also: :doc:`first_review`.
|
||||
|
||||
Be Professional
|
||||
---------------
|
||||
The PTL, with the support of the core reviewers, is ultimately responsible for
|
||||
holding contributors accountable for creating a positive, constructive, and
|
||||
productive culture. Inappropriate behavior will not be tolerated.
|
||||
(`Why this is important?`_)
|
||||
|
||||
Do This:
|
||||
|
||||
* Act professionally.
|
||||
* Treat others as friends and family.
|
||||
* Seek first to understand.
|
||||
* Be honest, transparent, and constructive.
|
||||
* Use clear, concise language.
|
||||
* Use prefixes to clarify the tone and intent of your comments.
|
||||
|
||||
Don't Do This:
|
||||
|
||||
* Use indecent, profane, or degrading language of any kind.
|
||||
* Hold a patch hostage for an ulterior motive, political or otherwise.
|
||||
* Abuse the review system to discuss big issues that would be better hashed out
|
||||
on the mailing list, in IRC, or during OpenStack Summit design sessions.
|
||||
* Engage in bullying behaviors, including but not limited to:
|
||||
|
||||
* Belittling others' opinions
|
||||
* Persistent teasing or sarcasm
|
||||
* Insulting, threatening, or yelling at someone
|
||||
* Accusing someone of being incompetent
|
||||
* Setting someone up to fail
|
||||
* Humiliating someone
|
||||
* Isolating someone from others
|
||||
* Withholding information to gain an advantage
|
||||
* Falsely accusing someone of errors
|
||||
* Sabotaging someone's work
|
||||
|
||||
Reviewing Docs
|
||||
--------------
|
||||
|
||||
When possible, enlist the help of a professional technical writer to help
|
||||
review each doc patch. All reviewers should familiarize themselves with
|
||||
`OpenStack Documentation Contributor Guide`_. When reviewing user guide
|
||||
patches, please run them through Maven and proof the resulting docs before
|
||||
giving your ``+1`` or ``+2``.
|
||||
|
||||
Reviewing Code
|
||||
--------------
|
||||
|
||||
When reviewing code patches, use your best judgment and seek to provide
|
||||
constructive feedback to the author. Compliment them on things they have done
|
||||
well, and highlight possible improvements. Also, dedicate as much time as
|
||||
necessary in order to provide a careful analysis of the code. Don't assume that
|
||||
someone else will catch any issues you yourself miss; in other words, pretend
|
||||
you are the only person reviewing a given patch. Remember, "given enough
|
||||
eyeballs, all bugs are shallow" ceases to be true the moment individual
|
||||
reviewers become complacent.
|
||||
|
||||
Some things to check when reviewing code:
|
||||
|
||||
* Patch aligns with project goals, and is ideally associated with a bp or bug.
|
||||
* Commit message is formatted appropriately and contains external references as
|
||||
needed.
|
||||
* Coding style matches guidelines given in ``HACKING.rst``.
|
||||
* Patch is cohesive and not too big to be reviewed in a timely manner (some
|
||||
patches may need to be split to improve cohesion and/or reduce size).
|
||||
* Patch does what the commit message promises.
|
||||
* Algorithms are implemented correctly, and chosen appropriately.
|
||||
* Data schemas follow best practices.
|
||||
* Unit and functional tests have been included and/or updated.
|
||||
* Code contains no bugs (pay special attention to edge cases that tests may
|
||||
have missed).
|
||||
|
||||
Use Prefixes
|
||||
------------
|
||||
|
||||
We encourage the use of prefixes to clarify the tone and intent of your review
|
||||
comments. This is one way we try to mitigate misunderstandings that can lead to
|
||||
bad designs, bad code, and bad blood.
|
||||
|
||||
.. list-table:: **Prefixes**
|
||||
:widths: 6 80 8
|
||||
:header-rows: 1
|
||||
|
||||
* - Prefix
|
||||
- What the reviewer is saying
|
||||
- Blocker?
|
||||
* - KUDO
|
||||
- You did a nice job here, and I wanted to point that out. Keep up the
|
||||
good work!
|
||||
- No
|
||||
* - TEST
|
||||
- I think you are missing a test for this feature, code branch, specific
|
||||
data input, etc.
|
||||
- Yes
|
||||
* - BUG
|
||||
- I don't think this code does what it was intended to do, or I think
|
||||
there is a general design flaw here that we need to discuss.
|
||||
- Yes
|
||||
* - SEC
|
||||
- This is a serious security vulnerability and we better address it before
|
||||
merging the code.
|
||||
- Yes
|
||||
* - PERF
|
||||
- I have a concern that this won't be fast enough or won't scale. Let's
|
||||
discuss the issue and benchmark alternatives.
|
||||
- Yes
|
||||
* - DSQ
|
||||
- I think there is something critical here that we need to discuss this in
|
||||
IRC or on the mailing list before moving forward.
|
||||
- Yes
|
||||
* - STYLE
|
||||
- This doesn't seem to be consistent with other code and with
|
||||
``HACKING.rst``
|
||||
- Yes
|
||||
* - Q
|
||||
- I don't understand something. Can you clarify?
|
||||
- Yes
|
||||
* - DRY
|
||||
- This could be modified to reduce duplication of code, data, etc.
|
||||
See also: `Wikipedia: Don't repeat yourself`_
|
||||
- Maybe
|
||||
* - YAGNI
|
||||
- This feature or flexibility probably isn't needed, or isn't worth the
|
||||
added complexity; if it is, we can always add the feature later. See
|
||||
also: `Wikipedia: You aren't gonna need it`_
|
||||
- Maybe
|
||||
* - NIT
|
||||
- This is a nitpick that I can live with if we want to merge without
|
||||
addressing it.
|
||||
- No
|
||||
* - IMO
|
||||
- I'm chiming in with my opinion in response to someone else's comment, or
|
||||
I just wanted to share an observation. Please take what I say with a
|
||||
grain of salt.
|
||||
- No
|
||||
* - FYI
|
||||
- I just wanted to share some useful information.
|
||||
- No
|
||||
|
||||
.. _`Why this is important?` : https://thoughtstreams.io/kgriffs/technical-communities/5060/
|
||||
.. _`OpenStack Documentation Contributor Guide` : http://docs.openstack.org/contributor-guide/index.html
|
||||
.. _`Wikipedia: Don't repeat yourself` : https://en.wikipedia.org/wiki/Don't_repeat_yourself
|
||||
.. _`Wikipedia: You aren't gonna need it` : https://en.wikipedia.org/wiki/Don't_repeat_yourself
|
||||
@ -1,167 +0,0 @@
|
||||
..
|
||||
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
not use this file except in compliance with the License. You may obtain
|
||||
a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
License for the specific language governing permissions and limitations
|
||||
under the License.
|
||||
|
||||
=============
|
||||
Running tests
|
||||
=============
|
||||
|
||||
Zaqar contains a suite of tests (both unit and functional) in the
|
||||
``zaqar/tests`` directory.
|
||||
|
||||
See :doc:`test_suite` for details.
|
||||
|
||||
Any proposed code change is automatically rejected by the OpenStack Jenkins
|
||||
server [#f1]_ if the change causes test failures.
|
||||
|
||||
It is recommended for developers to run the test suite before submitting patch
|
||||
for review. This allows to catch errors as early as possible.
|
||||
|
||||
Preferred way to run the tests
|
||||
------------------------------
|
||||
|
||||
The preferred way to run the unit tests is using ``tox``. It executes tests in
|
||||
isolated environment, by creating separate virtualenv and installing
|
||||
dependencies from the ``requirements.txt`` and ``test-requirements.txt`` files,
|
||||
so the only package you install is ``tox`` itself:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ pip install tox
|
||||
|
||||
See `the unit testing section of the Testing wiki page`_ for more information.
|
||||
Following are some simple examples.
|
||||
|
||||
To run the Python 2.7 tests:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ tox -e py27
|
||||
|
||||
To run the style tests:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ tox -e pep8
|
||||
|
||||
To run multiple tests separate items by commas:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ tox -e py27,py35,pep8
|
||||
|
||||
.. _the unit testing section of the Testing wiki page: https://wiki.openstack.org/wiki/Testing#Unit_Tests
|
||||
|
||||
Running a subset of tests
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Instead of running all tests, you can specify an individual directory, file,
|
||||
class or method that contains test code, i.e. filter full names of tests by a
|
||||
string.
|
||||
|
||||
To run the tests located only in the ``zaqar/tests/unit/storage``
|
||||
directory use:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ tox -e py27 zaqar.tests.unit.storage
|
||||
|
||||
To run the tests specific to the MongoDB driver in the
|
||||
``zaqar/tests/unit/storage/test_impl_mongodb.py`` file:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ tox -e py27 test_impl_mongodb
|
||||
|
||||
To run the tests in the ``MongodbMessageTests`` class in
|
||||
the ``tests/unit/storage/test_impl_mongodb.py`` file:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ tox -e py27 test_impl_mongodb.MongodbMessageTests
|
||||
|
||||
To run the ``MongodbMessageTests.test_message_lifecycle`` test method in
|
||||
the ``tests/unit/storage/test_impl_mongodb.py`` file:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ tox -e py27 test_impl_mongodb.MongodbMessageTests.test_message_lifecycle
|
||||
|
||||
Running functional tests
|
||||
------------------------
|
||||
|
||||
Zaqar's functional tests treat Zaqar as a black box. In other words, the API
|
||||
calls attempt to simulate an actual user. Unlike unit tests, the functional
|
||||
tests do not use mockendpoints.
|
||||
|
||||
Functional test modes
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Functional tests can run in integration mode and non-integration mode.
|
||||
|
||||
Integration mode
|
||||
""""""""""""""""
|
||||
|
||||
In integration mode functional tests are performed on Zaqar server instances
|
||||
running as separate processes. This is real functional testing.
|
||||
|
||||
To run functional tests in integration mode, execute:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ tox -e integration
|
||||
|
||||
Non-integration mode
|
||||
""""""""""""""""""""
|
||||
|
||||
In non-integration mode functional tests are performed on Zaqar server
|
||||
instances running as python objects. This mode doesn't guarantee enough black
|
||||
boxness for Zaqar, but tests run 10 times faster than in integration mode.
|
||||
|
||||
To run functional tests in non-integration mode, execute:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ tox -e py27 zaqar.tests.functional
|
||||
|
||||
Using a custom MongoDB instance
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If you need to run functional tests against a non-default MongoDB installation,
|
||||
you can set the ``ZAQAR_TEST_MONGODB_URL`` environment variable. For example:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ export ZAQAR_TEST_MONGODB_URL=mongodb://remote-server:27017
|
||||
|
||||
Using custom parameters
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
You can edit default functional test configuration file
|
||||
``zaqar/tests/etc/functional-tests.conf`` according to your needs.
|
||||
|
||||
For example, you want to run functional tests with keystone authentication
|
||||
enabled, input a valid set of credentials to ``[auth]`` section in
|
||||
configuration file and set ``auth_on`` parameter to ``True``.
|
||||
|
||||
Using local Mysql database
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
To use a similar testing environment with database support like upstream CI,
|
||||
you can run ``zaqar/tools/test-setup.sh`` to create a required Mysql user
|
||||
``openstack_citest`` with same password. The user is required by oslo.db's
|
||||
test. Zaqar needs it because Zaqar's sqlalchemy database migration is
|
||||
leveraging oslo.db's migration test base.
|
||||
|
||||
.. rubric:: Footnotes
|
||||
|
||||
.. [#f1] See https://docs.openstack.org/infra/system-config/jjb.html
|
||||
@ -1,32 +0,0 @@
|
||||
---------------------------------
|
||||
API reference for storage drivers
|
||||
---------------------------------
|
||||
|
||||
.. currentmodule:: zaqar.storage.base
|
||||
|
||||
.. autoclass:: DataDriverBase
|
||||
:noindex:
|
||||
:members:
|
||||
|
||||
.. autoclass:: ControlDriverBase
|
||||
:noindex:
|
||||
:members:
|
||||
|
||||
.. autoclass:: Queue
|
||||
:noindex:
|
||||
:members:
|
||||
|
||||
.. autoclass:: Message
|
||||
:noindex:
|
||||
:members:
|
||||
|
||||
.. autoclass:: Claim
|
||||
:noindex:
|
||||
:members:
|
||||
|
||||
|
||||
--------------
|
||||
MongoDB Driver
|
||||
--------------
|
||||
|
||||
.. automodule:: zaqar.storage.mongodb
|
||||
@ -1,96 +0,0 @@
|
||||
..
|
||||
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
not use this file except in compliance with the License. You may obtain
|
||||
a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
License for the specific language governing permissions and limitations
|
||||
under the License.
|
||||
|
||||
====================
|
||||
Test suite structure
|
||||
====================
|
||||
|
||||
Test types
|
||||
----------
|
||||
|
||||
There are three types of tests for Zaqar:
|
||||
|
||||
Unit tests
|
||||
Unit tests check modules separately. For example, there
|
||||
are checks for each individual method that the storage layer provides.
|
||||
|
||||
Functional tests
|
||||
Functional tests verify that the service works as expected. In particular,
|
||||
in Zaqar they exercise the API endpoints and validate that the API
|
||||
responses conform to the specs. These include positive and negative tests.
|
||||
|
||||
Tempest tests
|
||||
Tempest tests are integration tests for OpenStack [#f1]_.
|
||||
|
||||
Tempest tests for Zaqar are available in the `Tempest repository`_.
|
||||
|
||||
Refer to :doc:`running_tests` document for details on how to run Unit and
|
||||
Functional tests.
|
||||
|
||||
Refer to the `Tempest repository`_ for details on how to run Tempest tests.
|
||||
|
||||
Code structure
|
||||
--------------
|
||||
|
||||
The test suite lives in ``zaqar/tests`` directory of Zaqar:
|
||||
|
||||
* ``zaqar/tests/etc``
|
||||
Contains various configuration files for Zaqar. They help to test how Zaqar
|
||||
works in different configurations.
|
||||
|
||||
* ``zaqar/tests/functional``
|
||||
Contains functional tests.
|
||||
|
||||
* ``zaqar/tests/unit``
|
||||
Contains unit tests.
|
||||
|
||||
The base class of all test classes is located in the ``zaqar/tests/base.py``
|
||||
file.
|
||||
|
||||
Test invocation
|
||||
---------------
|
||||
|
||||
When you run tests via ``tox -e py27`` command in the root directory of Zaqar:
|
||||
|
||||
#. Tox program executes:
|
||||
|
||||
#. Looks for ``tox.ini`` file.
|
||||
#. Creates ``.tox`` directory for storing python environments.
|
||||
#. Parses this file and finds parameters for py27 testing environment.
|
||||
#. Sets this environment up and activates it.
|
||||
#. Sets environment variables for this environment that are described in
|
||||
``tox.ini``
|
||||
#. In case of Zaqar it invokes Testr program in the environment.
|
||||
|
||||
You can find more information about Tox in `OpenStack Tox testing manual`_
|
||||
and in official `Tox documentation`_.
|
||||
|
||||
#. Testr (Test Repository) program executes:
|
||||
|
||||
#. Looks for ``testr.ini`` file.
|
||||
#. Parses this file and finds parameters for executing tests.
|
||||
#. Creates ``.testrepository`` directory for storing statistics of
|
||||
executing tests.
|
||||
#. In case of Zaqar it invokes ``Subunit`` program which finds all tests and
|
||||
executes it.
|
||||
|
||||
You can find more information about Testr in `OpenStack Testr manual`_.
|
||||
|
||||
.. rubric:: Footnotes
|
||||
|
||||
.. [#f1] See http://docs.openstack.org/developer/tempest/overview.html
|
||||
|
||||
.. _`OpenStack Tox testing manual` : https://wiki.openstack.org/wiki/Testing#Unit_Testing_with_Tox
|
||||
.. _`Tox documentation` : https://tox.readthedocs.org/en/latest/
|
||||
.. _`OpenStack Testr manual` : https://wiki.openstack.org/wiki/Testr
|
||||
.. _`Tempest repository` : https://git.openstack.org/cgit/openstack/tempest
|
||||
@ -1,9 +0,0 @@
|
||||
=========
|
||||
Transport
|
||||
=========
|
||||
|
||||
.. currentmodule:: zaqar.transport.base
|
||||
|
||||
.. autoclass:: DriverBase
|
||||
:noindex:
|
||||
:members:
|
||||
@ -1,187 +0,0 @@
|
||||
..
|
||||
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
not use this file except in compliance with the License. You may obtain
|
||||
a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
License for the specific language governing permissions and limitations
|
||||
under the License.
|
||||
|
||||
========================
|
||||
Welcome new contributors
|
||||
========================
|
||||
|
||||
First Steps
|
||||
===========
|
||||
|
||||
It's very great that you're interested in contributing to Zaqar.
|
||||
|
||||
First of all, make sure you join Zaqar communication forums:
|
||||
|
||||
* Subscribe to Zaqar `mailing lists`_.
|
||||
* Join Zaqar team on IRC. You can chat with us directly in the
|
||||
``#openstack-zaqar`` channel on ``irc.freenode.org``. If you don't know
|
||||
how to use IRC, you can find some directions in `OpenStack IRC wiki`_.
|
||||
* Answer and ask questions on `Ask OpenStack`_.
|
||||
|
||||
How can I contribute?
|
||||
=====================
|
||||
|
||||
There are many ways you can contribute to Zaqar. Of course coding is one, but
|
||||
you can also join Zaqar as a tester, documenter, designer or translator.
|
||||
|
||||
Coding
|
||||
------
|
||||
|
||||
Bug fixing
|
||||
^^^^^^^^^^
|
||||
|
||||
The first area where you can help is bug fixing. ``Confirmed`` bugs are usually
|
||||
your best choice. ``Triaged`` bugs should even contain tips on how they
|
||||
should be fixed. You can find both of them in
|
||||
`Zaqar's Confirmed and Triaged bugs`_ web page.
|
||||
|
||||
Once you selected the bug you want to work on, go ahead and assign it to
|
||||
yourself, branch the code, implement the fix, and propose your change for
|
||||
review. You can find information on how to do it in
|
||||
:doc:`first_patch` manual.
|
||||
|
||||
Some easy-to-fix bugs may be marked with the ``low-hanging-fruit`` tag: those
|
||||
are good targets for a beginner.
|
||||
|
||||
Bug triaging
|
||||
^^^^^^^^^^^^
|
||||
|
||||
You can also help Zaqar with bug triaging. Reported bugs need care:
|
||||
prioritizing them correctly, confirming them, making sure they don't go stale.
|
||||
All those tasks help immensely. If you want to start contributing in coding,
|
||||
but you are not a hardcore developer, consider helping in this area.
|
||||
|
||||
Bugs can be marked with different tags according to their status:
|
||||
|
||||
* ``New`` bugs are those bugs that have been reported by a user but haven't
|
||||
been verified by the community yet.
|
||||
* ``Confirmed`` bugs are those bugs that have been reproduced by someone else
|
||||
than the reporter.
|
||||
* ``Triaged`` bugs are those bugs that have been reproduced by a core
|
||||
developer.
|
||||
* ``Incomplete`` bugs are those bugs that don't have enough information to be
|
||||
reproduced.
|
||||
* ``In Progress`` bugs are those bugs that are being fixed by some developer.
|
||||
This status is set automatically by the Gerrit review system once a fix is
|
||||
proposed by a developer. You don't need to set it manually.
|
||||
* ``Invalid`` bugs are those bugs that don't qualify as a bug. Usually a
|
||||
support request or something unrelated to the project.
|
||||
|
||||
You can learn more about this in Launchpad's `Of Bugs and Statuses`_.
|
||||
|
||||
You only have to worry about ``New`` bugs. If you can reproduce them, you can
|
||||
mark them as ``Confirmed``. If you cannot reproduce them, you can ask the
|
||||
reported to provide more information and mark them as ``Incomplete``. If you
|
||||
consider that they aren't bugs, mark them as ``Invalid`` (Be careful with this.
|
||||
Asking someone else in Zaqar is always a good idea).
|
||||
|
||||
Also, you can contribute instructions on how to fix a given bug.
|
||||
|
||||
Check out the `Bug Triage`_ wiki for more information.
|
||||
|
||||
Reviewing
|
||||
^^^^^^^^^
|
||||
|
||||
Every patch submitted to OpenStack gets reviewed before it can be approved and
|
||||
merged. Zaqar gets a lot of contributions and everyone can (and is encouraged
|
||||
to) review Zaqar's existing patches. Pick an open review and go through
|
||||
it, test it if possible, and leave a comment with a ``+1`` or ``-1`` vote
|
||||
describing what you discovered. If you're planning on submitting patches of
|
||||
your own, it's a great way to learn about what the community cares about and to
|
||||
learn about the code base.
|
||||
|
||||
Make sure you read :doc:`first_review` manual.
|
||||
|
||||
Feature development
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Once you get familiar with the code, you can start to contribute new features.
|
||||
New features get implemented every 6 months in `OpenStack development cycle`_.
|
||||
We use `Launchpad Blueprints`_ to track the design and implementation of
|
||||
significant features, and Zaqar team uses Design Summits every 6 months to
|
||||
get together and discuss things in person with the rest of the community. Code
|
||||
should be proposed for inclusion before Zaqar reach the final feature milestone
|
||||
of the development cycle.
|
||||
|
||||
Testing
|
||||
-------
|
||||
|
||||
Testing efforts are highly related to coding. If you find that there are test
|
||||
cases missing or that some tests could be improved, you are encouraged to
|
||||
report it as a bug and then provide your fix.
|
||||
|
||||
See :doc:`running_tests` and :doc:`test_suite` for information on how to run
|
||||
tests and how the tests are organized in Zaqar.
|
||||
|
||||
See :doc:`first_patch` for information on how to provide your fix.
|
||||
|
||||
|
||||
Documenting
|
||||
-----------
|
||||
|
||||
You can contribute to `Zaqar's Contributor Documentation`_ which you are
|
||||
currently reading and to `Zaqar's Wiki`_.
|
||||
|
||||
To fix a documentation bug check the bugs marked with the ``doc`` tag in
|
||||
Zaqar's bug list. In case that you want to report a documentation bug, then
|
||||
don't forget to add the ``doc`` tag to it.
|
||||
|
||||
`Zaqar's Contributor Documentation`_ is compiled from source files in ``.rst``
|
||||
(reStructuredText) format located in ``doc/source/`` directory in Zaqar
|
||||
repository. The `"openstack-manuals" project`_ houses the documentation that is
|
||||
published to ``docs.openstack.org``.
|
||||
|
||||
Before contributing to `Zaqar's Contributor Documentation`_ you have to read
|
||||
:doc:`first_patch` manual and `OpenStack Documentation Contributor Guide`_.
|
||||
|
||||
Also, you can monitor `Ask OpenStack`_ to curate the best answers that can be
|
||||
folded into the documentation.
|
||||
|
||||
Designing
|
||||
---------
|
||||
|
||||
Zaqar doesn't have a user interface yet. Zaqar team is working to
|
||||
`integrate Zaqar to the OpenStack Dashboard (Horizon)`_.
|
||||
|
||||
If you're a designer or usability professional your help will be really
|
||||
appreciated. Whether it's reviewing upcoming features as a user and giving
|
||||
feedback, designing features, testing designs or features with users, or
|
||||
helping to build use cases and requirements, everything is useful.
|
||||
|
||||
Translating
|
||||
-----------
|
||||
|
||||
You can translate Zaqar to language you know.
|
||||
Read the `Translation wiki page`_ for more information on how OpenStack manages
|
||||
translations. Zaqar has adopted Zanata, and you can use the
|
||||
`OpenStack Zanata site`_ as a starting point to translate any of the OpenStack
|
||||
projects, including Zaqar. It's easier to start translating directly on the
|
||||
`OpenStack Zanata site`_, as there is no need to download any files or
|
||||
applications to get started.
|
||||
|
||||
|
||||
.. _`mailing lists` : https://wiki.openstack.org/wiki/MailingLists
|
||||
.. _`OpenStack IRC wiki` : https://wiki.openstack.org/wiki/IRC
|
||||
.. _`Ask OpenStack` : https://ask.openstack.org/
|
||||
.. _`Zaqar's Confirmed and Triaged bugs` : https://bugs.launchpad.net/zaqar/+bugs?field.searchtext=&orderby=-importance&search=Search&field.status%3Alist=CONFIRMED&field.status%3Alist=TRIAGED&assignee_option=any&field.assignee=&field.bug_reporter=&field.bug_commenter=&field.subscriber=&field.structural_subscriber=&field.tag=&field.tags_combinator=ANY&field.has_cve.used=&field.omit_dupes.used=&field.omit_dupes=on&field.affects_me.used=&field.has_patch.used=&field.has_branches.used=&field.has_branches=on&field.has_no_branches.used=&field.has_no_branches=on&field.has_blueprints.used=&field.has_blueprints=on&field.has_no_blueprints.used=&field.has_no_blueprints=on
|
||||
.. _`Of Bugs and Statuses` : http://blog.launchpad.net/general/of-bugs-and-statuses
|
||||
.. _`Bug Triage` : https://wiki.openstack.org/wiki/BugTriage
|
||||
.. _`OpenStack development cycle` : https://wiki.openstack.org/wiki/ReleaseCycle
|
||||
.. _`Launchpad Blueprints` : https://wiki.openstack.org/wiki/Blueprints
|
||||
.. _`OpenStack Documentation Contributor Guide` : http://docs.openstack.org/contributor-guide/index.html
|
||||
.. _`Zaqar's Contributor Documentation` : http://docs.openstack.org/developer/zaqar/
|
||||
.. _`Zaqar's Wiki` : https://wiki.openstack.org/wiki/Zaqar
|
||||
.. _`"openstack-manuals" project` : https://wiki.openstack.org/wiki/Documentation
|
||||
.. _`integrate Zaqar to the OpenStack Dashboard (Horizon)` : https://blueprints.launchpad.net/zaqar/+spec/zaqar-horizon-integration
|
||||
.. _`Translation wiki page` : https://wiki.openstack.org/wiki/Translations#Translation_.26_Management
|
||||
.. _`OpenStack Zanata site` : https://translate.openstack.org/
|
||||
@ -1,77 +0,0 @@
|
||||
..
|
||||
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
not use this file except in compliance with the License. You may obtain
|
||||
a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
License for the specific language governing permissions and limitations
|
||||
under the License.
|
||||
|
||||
========
|
||||
Glossary
|
||||
========
|
||||
|
||||
Messaging Service Concepts
|
||||
==========================
|
||||
The Messaging Service is a multi-tenant, message queue implementation that
|
||||
utilizes a RESTful HTTP interface to provide an asynchronous communications
|
||||
protocol, which is one of the main requirements in today’s scalable applications.
|
||||
|
||||
.. glossary::
|
||||
|
||||
Queue
|
||||
Queue is a logical entity that groups messages. Ideally a queue is created
|
||||
per work type. For example, if you want to compress files, you would create
|
||||
a queue dedicated for this job. Any application that reads from this queue
|
||||
would only compress files.
|
||||
|
||||
Message
|
||||
Message is sent through a queue and exists until it is deleted by a recipient
|
||||
or automatically by the system based on a TTL (time-to-live) value.
|
||||
|
||||
Claim
|
||||
Claim is a mechanism to mark messages so that other workers will not process the same message.
|
||||
|
||||
Worker
|
||||
Worker is an application that reads one or multiple messages from the queue.
|
||||
|
||||
Producer
|
||||
Producer is an application that creates messages in one or multiple queues.
|
||||
|
||||
Publish - Subscribe
|
||||
Publish - Subscribe is a pattern where all worker applications have access
|
||||
to all messages in the queue. Workers can not delete or update messages.
|
||||
|
||||
Producer - Consumer
|
||||
Producer - Consumer is a pattern where each worker application that reads
|
||||
the queue has to claim the message in order to prevent duplicate processing.
|
||||
Later, when the work is done, the worker is responsible for deleting the
|
||||
message. If message is not deleted in a predefined time (claim TTL), it can
|
||||
be claimed by other workers.
|
||||
|
||||
Message TTL
|
||||
Message TTL is time-to-live value and defines how long a message will be accessible.
|
||||
|
||||
Claim TTL
|
||||
Claim TTL is time-to-live value and defines how long a message will be in
|
||||
claimed state. A message can be claimed by one worker at a time.
|
||||
|
||||
Queues Database
|
||||
Queues database stores the information about the queues and the messages
|
||||
within these queues. Storage layer has to guarantee durability and availability of the data.
|
||||
|
||||
Pooling
|
||||
If pooling enabled, queuing service uses multiple queues databases in order
|
||||
to scale horizontally. A pool (queues database) can be added anytime without
|
||||
stopping the service. Each pool has a weight that is assigned during the
|
||||
creation time but can be changed later. Pooling is done by queue which
|
||||
indicates that all messages for a particular queue can be found in the same pool (queues database).
|
||||
|
||||
Catalog Database
|
||||
If pooling is enabled, catalog database has to be created. Catalog database
|
||||
maintains ``queues`` to ``queues database`` mapping. Storage layer has
|
||||
to guarantee durability and availability of data.
|
||||
@ -1,108 +0,0 @@
|
||||
..
|
||||
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
not use this file except in compliance with the License. You may obtain
|
||||
a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
License for the specific language governing permissions and limitations
|
||||
under the License.
|
||||
|
||||
=====================================
|
||||
Welcome to the Zaqar's Documentation!
|
||||
=====================================
|
||||
|
||||
Zaqar is a multi-tenant cloud messaging and notification service for web
|
||||
and mobile developers.
|
||||
|
||||
The service features a REST API, which developers can use to send messages
|
||||
between various components of their SaaS and mobile applications, by using a
|
||||
variety of communication patterns. Underlying this API is an efficient
|
||||
messaging engine designed with scalability and security in mind. The Websocket
|
||||
API is also available.
|
||||
|
||||
Other OpenStack components can integrate with Zaqar to surface events to end
|
||||
users and to communicate with guest agents that run in the "over-cloud" layer.
|
||||
|
||||
Key features
|
||||
------------
|
||||
|
||||
Zaqar provides the following key features:
|
||||
|
||||
* Choice between two communication transports. Both with Keystone support:
|
||||
|
||||
* Firewall-friendly, **HTTP-based RESTful API**. Many of today's developers
|
||||
prefer a more web-friendly HTTP API. They value the simplicity and
|
||||
transparency of the protocol, it's firewall-friendly nature, and it's huge
|
||||
ecosystem of tools, load balancers and proxies. In addition, cloud
|
||||
operators appreciate the scalability aspects of the REST architectural
|
||||
style.
|
||||
* **Websocket-based API** for persistent connections. Websocket protocol
|
||||
provides communication over persistent connections. Unlike HTTP, where
|
||||
new connections are opened for each request/response pair, Websocket can
|
||||
transfer multiple requests/responses over single TCP connection. It saves
|
||||
much network traffic and minimizes delays.
|
||||
|
||||
* Multi-tenant queues based on Keystone project IDs.
|
||||
* Support for several common patterns including event broadcasting, task
|
||||
distribution, and point-to-point messaging.
|
||||
* Component-based architecture with support for custom backends and message
|
||||
filters.
|
||||
* Efficient reference implementation with an eye toward low latency and high
|
||||
throughput (dependent on backend).
|
||||
* Highly-available and horizontally scalable.
|
||||
* Support for subscriptions to queues. Several notification types are
|
||||
available:
|
||||
|
||||
* Email notifications.
|
||||
* Webhook notifications.
|
||||
* Websocket notifications.
|
||||
|
||||
Project scope
|
||||
-------------
|
||||
|
||||
The Zaqar API is data-oriented. That is, it does not provision message brokers
|
||||
and expose those directly to clients. Instead, the API acts as a bridge between
|
||||
the client and one or more backends. A provisioning service for message
|
||||
brokers, however useful, serves a somewhat different market from what Zaqar is
|
||||
targeting today. With that in mind, if users are interested in a broker
|
||||
provisioning service, the community should consider starting a new project to
|
||||
address that need.
|
||||
|
||||
Design principles
|
||||
-----------------
|
||||
|
||||
Zaqar, as with all OpenStack projects, is designed with the following
|
||||
guidelines in mind:
|
||||
|
||||
* **Component-based architecture.** Quickly add new behaviors
|
||||
* **Highly available and scalable.** Scale to very serious workloads
|
||||
* **Fault tolerant.** Isolated processes avoid cascading failures
|
||||
* **Recoverable.** Failures should be easy to diagnose, debug, and rectify
|
||||
* **Open standards.** Be a reference implementation for a community-driven
|
||||
|
||||
Contents
|
||||
--------
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
user/index
|
||||
admin/index
|
||||
install/index
|
||||
contributor/index
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
glossary
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -1,65 +0,0 @@
|
||||
==========================
|
||||
Messaging service overview
|
||||
==========================
|
||||
|
||||
The Message service is multi-tenant, fast, reliable, and scalable. It allows
|
||||
developers to share data between distributed application components performing
|
||||
different tasks, without losing messages or requiring each component to be
|
||||
always available.
|
||||
|
||||
The service features a RESTful API and a Websocket API, which developers can
|
||||
use to send messages between various components of their SaaS and mobile
|
||||
applications, by using a variety of communication patterns.
|
||||
|
||||
Key features
|
||||
~~~~~~~~~~~~
|
||||
|
||||
The Messaging service provides the following key features:
|
||||
|
||||
* Choice between two communication transports. Both with Identity service
|
||||
support:
|
||||
|
||||
* Firewall-friendly, **HTTP-based RESTful API**. Many of today's developers
|
||||
prefer a more web-friendly HTTP API. They value the simplicity and
|
||||
transparency of the protocol, its firewall-friendly nature, and its huge
|
||||
ecosystem of tools, load balancers and proxies. In addition, cloud
|
||||
operators appreciate the scalability aspects of the REST architectural
|
||||
style.
|
||||
* **Websocket-based API** for persistent connections. Websocket protocol
|
||||
provides communication over persistent connections. Unlike HTTP, where
|
||||
new connections are opened for each request/response pair, Websocket can
|
||||
transfer multiple requests/responses over single TCP connection. It saves
|
||||
much network traffic and minimizes delays.
|
||||
|
||||
* Multi-tenant queues based on Identity service IDs.
|
||||
* Support for several common patterns including event broadcasting, task
|
||||
distribution, and point-to-point messaging.
|
||||
* Component-based architecture with support for custom back ends and message
|
||||
filters.
|
||||
* Efficient reference implementation with an eye toward low latency and high
|
||||
throughput (dependent on back end).
|
||||
* Highly-available and horizontally scalable.
|
||||
* Support for subscriptions to queues. Several notification types are
|
||||
available:
|
||||
|
||||
* Email notifications
|
||||
* Webhook notifications
|
||||
* Websocket notifications
|
||||
|
||||
Layers of the Messaging service
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The Messaging service has following layers:
|
||||
|
||||
* The transport layer (Messaging application) which can provide these APIs:
|
||||
|
||||
* HTTP RESTful API (via ``wsgi`` driver).
|
||||
* Websocket API (via ``websocket`` driver).
|
||||
|
||||
* The storage layer which keeps all the data and metadata about queues and
|
||||
messages. It has two sub-layers:
|
||||
|
||||
* The management store database (Catalog). Can be ``MongoDB`` database (or
|
||||
``MongoDB`` replica-set) or SQL database.
|
||||
* The message store databases (Pools). Can be ``MongoDB`` database (or
|
||||
``MongoDB`` replica-set) or ``Redis`` database.
|
||||
@ -1,41 +0,0 @@
|
||||
==================
|
||||
Installation Guide
|
||||
==================
|
||||
|
||||
.. toctree::
|
||||
|
||||
get_started.rst
|
||||
install.rst
|
||||
verify.rst
|
||||
next-steps.rst
|
||||
|
||||
The Messaging service is multi-tenant, fast, reliable, and scalable. It allows
|
||||
developers to share data between distributed application components performing
|
||||
different tasks, without losing messages or requiring each component to be
|
||||
always available.
|
||||
|
||||
The service features a RESTful API and a Websocket API, which developers can
|
||||
use to send messages between various components of their SaaS and mobile
|
||||
applications, by using a variety of communication patterns.
|
||||
|
||||
This chapter assumes a working setup of OpenStack following the base
|
||||
Installation Guide.
|
||||
|
||||
|
||||
Ocata
|
||||
~~~~~
|
||||
|
||||
To install Glance, see the Ocata Image service install guide for each distribution:
|
||||
|
||||
- `Ubuntu <https://docs.openstack.org/project-install-guide/messaging/ocata/install-ubuntu.html>`__
|
||||
- `CentOS and RHEL <https://docs.openstack.org/project-install-guide/messaging/ocata/install-rdo.html>`__
|
||||
- `openSUSE and SUSE Linux Enterprise <https://docs.openstack.org/project-install-guide/messaging/ocata/install-obs.html>`__
|
||||
|
||||
Newton
|
||||
~~~~~~
|
||||
|
||||
To install Glance, see the Newton Image service install guide for each distribution:
|
||||
|
||||
- `Ubuntu <https://docs.openstack.org/project-install-guide/messaging/newton/install-ubuntu.html>`__
|
||||
- `CentOS and RHEL <https://docs.openstack.org/project-install-guide/messaging/newton/install-rdo.html>`__
|
||||
- `openSUSE and SUSE Linux Enterprise <https://docs.openstack.org/project-install-guide/messaging/newton/install-obs.html>`__
|
||||
@ -1,545 +0,0 @@
|
||||
.. _install-obs:
|
||||
|
||||
Install and configure for openSUSE and SUSE Linux Enterprise
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This section describes how to install and configure the Messaging service
|
||||
for openSUSE Leap 42.1 and SUSE Linux Enterprise Server 12 SP1.
|
||||
|
||||
This section assumes that you already have a working OpenStack environment with
|
||||
at least Identity service installed.
|
||||
|
||||
Here you can find instructions and recommended settings for installing
|
||||
Messaging service in small configuration: one web server with Messaging service
|
||||
configured to use replica-set of three ``MongoDB`` database servers. Because
|
||||
only one web server is used, the Messaging service installed by using these
|
||||
instructions can't be considered as high available, see :doc:`install`.
|
||||
|
||||
In this tutorial these server names are used as examples:
|
||||
|
||||
* Web server with Messaging service: ``WEB0.EXAMPLE-MESSAGES.NET``.
|
||||
* Database servers: ``MYDB0.EXAMPLE-MESSAGES.NET``,
|
||||
``MYDB1.EXAMPLE-MESSAGES.NET``, ``MYDB2.EXAMPLE-MESSAGES.NET``.
|
||||
* Identity service server: ``IDENTITY.EXAMPLE-MESSAGES.NET``.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
Before you install Messaging service, you must meet the following system
|
||||
requirements:
|
||||
|
||||
* Installed Identity service for user and project management.
|
||||
* Python 2.7.
|
||||
|
||||
Before you install and configure Messaging, you must create a ``MongoDB``
|
||||
replica-set of three database servers. Also you need to create service
|
||||
credentials and API endpoints in Identity.
|
||||
|
||||
#. Install and configure ``MongoDB`` replica-set on database servers:
|
||||
|
||||
#. Install ``MongoDB`` on the database servers:
|
||||
|
||||
On each database server follow the official `MongoDB installation
|
||||
instructions`_.
|
||||
|
||||
.. note::
|
||||
|
||||
Messaging service works with ``MongoDB`` versions >= 2.4
|
||||
|
||||
#. Configure ``MongoDB`` on the database servers:
|
||||
|
||||
On each database server edit configuration file: ``/etc/mongod.conf`` and
|
||||
modify as needed:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
# MongoDB sample configuration for Messaging service.
|
||||
# (For MongoDB version >= 2.6)
|
||||
# Edit according to your needs.
|
||||
systemLog:
|
||||
destination: file
|
||||
logAppend: true
|
||||
path: /var/log/mongodb/mongod.log
|
||||
|
||||
storage:
|
||||
dbPath: /var/lib/mongo
|
||||
journal:
|
||||
enabled: false
|
||||
|
||||
processManagement:
|
||||
fork: true # fork and run in background
|
||||
pidFilePath: /var/run/mongodb/mongod.pid # location of pidfile
|
||||
|
||||
net:
|
||||
port: 27017
|
||||
# bindIp: 127.0.0.1 # Listen to local interface only, comment to listen on all interfaces.
|
||||
|
||||
operationProfiling:
|
||||
slowOpThresholdMs: 200
|
||||
mode: slowOp
|
||||
|
||||
replication:
|
||||
oplogSizeMB: 2048
|
||||
replSetName: catalog
|
||||
|
||||
.. note::
|
||||
|
||||
In case of older ``MongoDB`` versions (2.4 and 2.5) the configuration
|
||||
file should be written in different format. For information about
|
||||
format for different versions see the official `MongoDB configuration
|
||||
reference`_.
|
||||
|
||||
.. warning::
|
||||
|
||||
Additional steps are required to secure ``MongoDB`` installation. You
|
||||
should modify this configuration for your security requirements. See
|
||||
the official `MongoDB security reference`_.
|
||||
|
||||
#. Start ``MongoDB`` on the database servers:
|
||||
|
||||
Start ``MongoDB`` service on all database servers:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# service mongod start
|
||||
|
||||
Make ``MongoDB`` service start automatically after reboot:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# chkconfig mongod on
|
||||
|
||||
#. Configure ``MongoDB`` Replica Set on the database servers:
|
||||
|
||||
Once you've installed ``MongoDB`` on three servers and assuming that the
|
||||
primary ``MongoDB`` server hostname is ``MYDB0.EXAMPLE-MESSAGES.NET``, go
|
||||
to ``MYDB0`` and run these commands:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# mongo local --eval "printjson(rs.initiate())"
|
||||
# mongo local --eval "printjson(rs.add('MYDB1.EXAMPLE-MESSAGES.NET'))"
|
||||
# mongo local --eval "printjson(rs.add('MYDB2.EXAMPLE-MESSAGES.NET'))"
|
||||
|
||||
.. note::
|
||||
|
||||
The database servers must have access to each other and also be
|
||||
accessible from the Messaging service web server. Configure firewalls
|
||||
on all database servers to accept incoming connections to port
|
||||
``27017`` from the needed source.
|
||||
|
||||
To check if the replica-set is established see the output of this
|
||||
command:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# mongo local --eval "printjson(rs.status())"
|
||||
|
||||
#. Source the ``admin`` credentials to gain access to admin-only CLI commands:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ . admin-openrc
|
||||
|
||||
#. To create the service credentials, complete these steps:
|
||||
|
||||
#. Create the ``zaqar`` user:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ openstack user create --domain default --password-prompt zaqar
|
||||
User Password:
|
||||
Repeat User Password:
|
||||
+-----------+----------------------------------+
|
||||
| Field | Value |
|
||||
+-----------+----------------------------------+
|
||||
| domain_id | default |
|
||||
| enabled | True |
|
||||
| id | 7b0ffc83097148dab6ecbef6ddcc46bf |
|
||||
| name | zaqar |
|
||||
+-----------+----------------------------------+
|
||||
|
||||
#. Add the ``admin`` role to the ``zaqar`` user:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ openstack role add --project service --user zaqar admin
|
||||
|
||||
.. note::
|
||||
|
||||
This command provides no output.
|
||||
|
||||
#. Create the ``zaqar`` service entity:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ openstack service create --name zaqar --description "Messaging" messaging
|
||||
+-------------+----------------------------------+
|
||||
| Field | Value |
|
||||
+-------------+----------------------------------+
|
||||
| description | Messaging |
|
||||
| enabled | True |
|
||||
| id | b39c22818be5425ba2315dd4b10cd57c |
|
||||
| name | zaqar |
|
||||
| type | messaging |
|
||||
+-------------+----------------------------------+
|
||||
|
||||
#. Create the Messaging service API endpoints:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ openstack endpoint create --region RegionOne messaging public http://WEB0.EXAMPLE-MESSAGES.NET:8888
|
||||
+--------------+---------------------------------------+
|
||||
| Field | Value |
|
||||
+--------------+---------------------------------------+
|
||||
| enabled | True |
|
||||
| id | aabca78860e74c4db0bcb36167bfe106 |
|
||||
| interface | public |
|
||||
| region | RegionOne |
|
||||
| region_id | RegionOne |
|
||||
| service_id | b39c22818be5425ba2315dd4b10cd57c |
|
||||
| service_name | zaqar |
|
||||
| service_type | messaging |
|
||||
| url | http://WEB0.EXAMPLE-MESSAGES.NET:8888 |
|
||||
+--------------+---------------------------------------+
|
||||
|
||||
$ openstack endpoint create --region RegionOne messaging internal http://WEB0.EXAMPLE-MESSAGES.NET:8888
|
||||
+--------------+---------------------------------------+
|
||||
| Field | Value |
|
||||
+--------------+---------------------------------------+
|
||||
| enabled | True |
|
||||
| id | 07f9524613de4fd3905e13a87f81fd3f |
|
||||
| interface | internal |
|
||||
| region | RegionOne |
|
||||
| region_id | RegionOne |
|
||||
| service_id | b39c22818be5425ba2315dd4b10cd57c |
|
||||
| service_name | zaqar |
|
||||
| service_type | messaging |
|
||||
| url | http://WEB0.EXAMPLE-MESSAGES.NET:8888 |
|
||||
+--------------+---------------------------------------+
|
||||
|
||||
$ openstack endpoint create --region RegionOne messaging admin http://WEB0.EXAMPLE-MESSAGES.NET:8888
|
||||
+--------------+---------------------------------------+
|
||||
| Field | Value |
|
||||
+--------------+---------------------------------------+
|
||||
| enabled | True |
|
||||
| id | 686f7b19428f4b5aa1425667dfe4f49d |
|
||||
| interface | admin |
|
||||
| region | RegionOne |
|
||||
| region_id | RegionOne |
|
||||
| service_id | b39c22818be5425ba2315dd4b10cd57c |
|
||||
| service_name | zaqar |
|
||||
| service_type | messaging |
|
||||
| url | http://WEB0.EXAMPLE-MESSAGES.NET:8888 |
|
||||
+--------------+---------------------------------------+
|
||||
|
||||
Install and configure Messaging web server
|
||||
------------------------------------------
|
||||
|
||||
Install and configure ``memcached``, ``uWSGI`` and Messaging on the web server
|
||||
``WEB0.EXAMPLE-MESSAGES.NET``.
|
||||
|
||||
#. Install ``memcached`` on web server ``WEB0.EXAMPLE-MESSAGES.NET`` in order
|
||||
to cache Identity service tokens and catalog mappings:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# zypper install memcached
|
||||
|
||||
Start ``memcached`` service:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# /etc/init.d/memcached start
|
||||
|
||||
Make ``memcached`` service start automatically after reboot:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# chkconfig memcached on
|
||||
|
||||
#. Install Messaging service and ``uWSGI``:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# zypper install python-pip
|
||||
# git clone https://git.openstack.org/openstack/zaqar.git
|
||||
# cd zaqar
|
||||
# pip install . -r ./requirements.txt --upgrade --log /tmp/zaqar-pip.log
|
||||
# pip install --upgrade pymongo gevent uwsgi
|
||||
|
||||
#. Copy the Zaqar RBAC policy sample file to the directory ``etc/zaqar/``:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# mkdir
|
||||
# cp etc/policy.json.sample /etc/zaqar/policy.json
|
||||
|
||||
#. Create log file:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# touch /var/log/zaqar-server.log
|
||||
# chown ZAQARUSER:ZAQARUSER /var/log/zaqar-server.log
|
||||
# chmod 600 /var/log/zaqar-server.log
|
||||
|
||||
Replace ``ZAQARUSER`` with the name of the user in system under which the
|
||||
Messaging service will run.
|
||||
|
||||
#. Create ``/srv/zaqar`` folder to store ``uWSGI`` configuration files.
|
||||
|
||||
#. Create ``/srv/zaqar/zaqar_uwsgi.py`` with the following content:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from keystonemiddleware import auth_token
|
||||
from zaqar.transport.wsgi import app
|
||||
|
||||
app = auth_token.AuthProtocol(app.app, {})
|
||||
|
||||
#. Increase backlog listen limit from default (128):
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# echo "net.core.somaxconn=2048" | sudo tee --append /etc/sysctl.conf
|
||||
|
||||
#. Create ``/srv/zaqar/uwsgi.ini`` file with the following content and modify
|
||||
as needed:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[uwsgi]
|
||||
https = WEB0.EXAMPLE-MESSAGES.NET:8888,PATH_TO_SERVER_CRT,PATH_TO_SERVER_PRIVATE_KEY
|
||||
pidfile = /var/run/zaqar.pid
|
||||
gevent = 2000
|
||||
gevent-monkey-patch = true
|
||||
listen = 1024
|
||||
enable-threads = true
|
||||
module = zaqar_uwsgi:app
|
||||
workers = 4
|
||||
harakiri = 60
|
||||
add-header = Connection: close
|
||||
|
||||
Replace ``PATH_TO_SERVER_CRT`` with path to the server's certificate
|
||||
(``*.crt``) and ``PATH_TO_SERVER_PRIVATE_KEY`` with path to the server's
|
||||
private key (``*.key``).
|
||||
|
||||
.. note::
|
||||
|
||||
The ``uWSGI`` configuration options above can be modified for different
|
||||
security and performance requirements including load balancing. See the
|
||||
official `uWSGI configuration reference`_.
|
||||
|
||||
#. Create Messaging service's configuration file ``/etc/zaqar.conf`` with the
|
||||
following content:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[DEFAULT]
|
||||
# Show debugging output in logs (sets DEBUG log level output)
|
||||
#debug = False
|
||||
|
||||
# Pooling and admin mode configs
|
||||
pooling = True
|
||||
admin_mode = True
|
||||
|
||||
# Log to file
|
||||
log_file = /var/log/zaqar-server.log
|
||||
|
||||
# This is taken care of in our custom app.py, so disable here
|
||||
;auth_strategy = keystone
|
||||
|
||||
# Modify to make it work with your Identity service.
|
||||
[keystone_authtoken]
|
||||
project_domain_name = Default
|
||||
user_domain_name = Default
|
||||
project_domain_id = default
|
||||
project_name = service
|
||||
user_domain_id = default
|
||||
# File path to a PEM encoded Certificate Authority to use when verifying
|
||||
# HTTPs connections. Defaults to system CAs if commented.
|
||||
cafile = PATH_TO_CA_FILE
|
||||
# Messaging service user name in Identity service.
|
||||
username = ZAQARIDENTITYUSER
|
||||
# Messaging service password in Identity service.
|
||||
password = ZAQARIDENTITYPASSWORD
|
||||
# Complete public Identity API endpoint (HTTPS protocol is more preferable
|
||||
# than HTTP).
|
||||
auth_uri = HTTPS://IDENTITY.EXAMPLE-MESSAGES.NET:5000
|
||||
# Complete admin Identity API endpoint (HTTPS protocol is more preferable
|
||||
# than HTTP).
|
||||
auth_url = HTTPS://IDENTITY.EXAMPLE-MESSAGES.NET:35357
|
||||
# Token cache time in seconds.
|
||||
token_cache_time = TOKEN_CACHE_TIME
|
||||
memcached_servers = 127.0.0.1:11211
|
||||
|
||||
[cache]
|
||||
# Dogpile.cache backend module. It is recommended that Memcache with
|
||||
# pooling (oslo_cache.memcache_pool) or Redis (dogpile.cache.redis) be
|
||||
# used in production deployments. Small workloads (single process)
|
||||
# like devstack can use the dogpile.cache.memory backend. (string
|
||||
# value)
|
||||
backend = dogpile.cache.memory
|
||||
memcache_servers = 127.0.0.1:11211
|
||||
|
||||
[drivers]
|
||||
transport = wsgi
|
||||
message_store = mongodb
|
||||
management_store = mongodb
|
||||
|
||||
[drivers:management_store:mongodb]
|
||||
# Mongodb Connection URI. If ssl connection enabled, then ssl_keyfile,
|
||||
# ssl_certfile, ssl_cert_reqs, ssl_ca_certs options need to be set
|
||||
# accordingly.
|
||||
uri = mongodb://MYDB0.EXAMPLE-MESSAGES.NET,MYDB1.EXAMPLE-MESSAGES.NET,MYDB2.EXAMPLE-MESSAGES.NET:27017/?replicaSet=catalog&w=2&readPreference=secondaryPreferred
|
||||
|
||||
# Name for the database on mongodb server.
|
||||
database = zaqarmanagementstore
|
||||
|
||||
# Number of databases across which to partition message data, in order
|
||||
# to reduce writer lock %. DO NOT change this setting after initial
|
||||
# deployment. It MUST remain static. Also, you should not need a large
|
||||
# number of partitions to improve performance, esp. if deploying
|
||||
# MongoDB on SSD storage. (integer value)
|
||||
partitions = 8
|
||||
|
||||
# Uncomment any options below if needed.
|
||||
|
||||
# Maximum number of times to retry a failed operation. Currently
|
||||
# only used for retrying a message post.
|
||||
;max_attempts = 1000
|
||||
|
||||
# Maximum sleep interval between retries (actual sleep time
|
||||
# increases linearly according to number of attempts performed).
|
||||
;max_retry_sleep = 0.1
|
||||
|
||||
# Maximum jitter interval, to be added to the sleep interval, in
|
||||
# order to decrease probability that parallel requests will retry
|
||||
# at the same instant.
|
||||
;max_retry_jitter = 0.005
|
||||
|
||||
# Frequency of message garbage collections, in seconds
|
||||
;gc_interval = 5 * 60
|
||||
|
||||
# Threshold of number of expired messages to reach in a given
|
||||
# queue, before performing the GC. Useful for reducing frequent
|
||||
# locks on the DB for non-busy queues, or for worker queues
|
||||
# which process jobs quickly enough to keep the number of in-
|
||||
# flight messages low.
|
||||
#
|
||||
# Note: The higher this number, the larger the memory-mapped DB
|
||||
# files will be.
|
||||
;gc_threshold = 1000
|
||||
|
||||
[drivers:message_store:mongodb]
|
||||
# This section has same set of available options as
|
||||
# "[drivers:management_store:mongodb]" section.
|
||||
#
|
||||
# If pooling is enabled, all pools inherit values from options in these
|
||||
# settings unless overridden in pool creation request. Also "uri" option
|
||||
# value isn't used in case of pooling.
|
||||
#
|
||||
# If ssl connection enabled, then ssl_keyfile, ssl_certfile, ssl_cert_reqs,
|
||||
# ssl_ca_certs options need to be set accordingly.
|
||||
|
||||
# Name for the database on MondoDB server.
|
||||
database = zaqarmessagestore
|
||||
|
||||
[transport]
|
||||
max_queues_per_page = 1000
|
||||
max_queue_metadata = 262144
|
||||
max_mesages_per_page = 10
|
||||
max_messages_post_size = 262144
|
||||
max_message_ttl = 1209600
|
||||
max_claim_ttl = 43200
|
||||
max_claim_grace = 43200
|
||||
|
||||
[signed_url]
|
||||
# Secret key used to encrypt pre-signed URLs. (string value)
|
||||
secret_key = SOMELONGSECRETKEY
|
||||
|
||||
Edit any options as needed, especially the options with capitalized values.
|
||||
|
||||
#. Create a service file for Messaging service
|
||||
``/etc/systemd/system/zaqaruwsgi.service``:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[Unit]
|
||||
Description=uWSGI Zaqar
|
||||
After=syslog.target
|
||||
|
||||
[Service]
|
||||
ExecStart=/usr/bin/uwsgi --ini /srv/zaqar/uwsgi.ini
|
||||
# Requires systemd version 211 or newer
|
||||
RuntimeDirectory=uwsgi
|
||||
Restart=always
|
||||
KillSignal=SIGQUIT
|
||||
Type=notify
|
||||
StandardError=syslog
|
||||
NotifyAccess=all
|
||||
User=ZAQARUSER
|
||||
Group=ZAQARUSER
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
|
||||
Replace ``ZAQARUSER`` with the name of the user in system under which the
|
||||
Messaging service will run.
|
||||
|
||||
Finalize installation
|
||||
---------------------
|
||||
|
||||
Now after you have configured the web server and the database servers to have a
|
||||
functional Messaging service, you need to start the service, make the service
|
||||
automatically start with the system and define the created ``MongoDB``
|
||||
replica-set as Messaging's pool.
|
||||
|
||||
#. Start Messaging service on the web server:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# systemctl start zaqar.uwsgi.service
|
||||
|
||||
#. Make Messaging service start automatically after reboot on the web server:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# systemctl enable zaqar.uwsgi.service
|
||||
|
||||
#. Configure pool:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# curl -i -X PUT https://WEB0.EXAMPLE-MESSAGES.NET:8888/v2/pools/POOL1 \
|
||||
-d '{"weight": 100, "uri": "mongodb://MYDB0.EXAMPLE-MESSAGES.NET,MYDB1.EXAMPLE-MESSAGES.NET,MYDB2.EXAMPLE-MESSAGES.NET:27017/?replicaSet=catalog&w=2&readPreference=secondaryPreferred", "options": {"partitions": 8}}' \
|
||||
-H "Client-ID: CLIENT_ID" \
|
||||
-H "X-Auth-Token: TOKEN" \
|
||||
-H "Content-type: application/json" \
|
||||
|
||||
Replace ``POOL1`` variable with the desired name of a pool.
|
||||
|
||||
Replace ``CLIENT_ID`` variable with the universally unique identifier (UUID)
|
||||
which can be generated by, for example, ``uuidgen`` utility.
|
||||
|
||||
Replace ``TOKEN`` variable with the authentication token retrieved from
|
||||
Identity service. If you choose not to enable Keystone authentication you
|
||||
won't have to pass a token.
|
||||
|
||||
.. note::
|
||||
|
||||
The ``options`` key in curl request above overrides any options
|
||||
(specified in configuration file or default) in
|
||||
``[drivers:message_store:mongodb]`` Messaging service configuration
|
||||
file's section.
|
||||
|
||||
.. tip::
|
||||
|
||||
In larger deployments, there should be many load balanced web servers. Also
|
||||
the management store databases and the message store databases (pools)
|
||||
should be on different ``MongoDB`` replica-sets.
|
||||
|
||||
.. _`MongoDB installation instructions`: https://docs.mongodb.org/manual/tutorial/install-mongodb-on-suse/
|
||||
.. _`MongoDB configuration reference`: https://docs.mongodb.org/v3.0/reference/configuration-options/
|
||||
.. _`MongoDB security reference`: https://docs.mongodb.org/manual/security/
|
||||
.. _`uWSGI configuration reference`: http://uwsgi-docs.readthedocs.io/en/latest/
|
||||
@ -1,545 +0,0 @@
|
||||
.. _install-rdo:
|
||||
|
||||
Install and configure for Red Hat Enterprise Linux and CentOS
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This section describes how to install and configure the Messaging service,
|
||||
code-named ``zaqar`` for Red Hat Enterprise Linux 7 and CentOS 7.
|
||||
|
||||
This section assumes that you already have a working OpenStack environment with
|
||||
at least Identity service installed.
|
||||
|
||||
Here you can find instructions and recommended settings for installing
|
||||
Messaging service in small configuration: one web server with Messaging service
|
||||
configured to use replica-set of three ``MongoDB`` database servers. Because
|
||||
only one web server is used, the Messaging service installed by using these
|
||||
instructions can't be considered as high available, see :doc:`install`.
|
||||
|
||||
In this tutorial these server names are used as examples:
|
||||
|
||||
* Web server with Messaging service: ``WEB0.EXAMPLE-MESSAGES.NET``.
|
||||
* Database servers: ``MYDB0.EXAMPLE-MESSAGES.NET``,
|
||||
``MYDB1.EXAMPLE-MESSAGES.NET``, ``MYDB2.EXAMPLE-MESSAGES.NET``.
|
||||
* Identity service server: ``IDENTITY.EXAMPLE-MESSAGES.NET``.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
Before you install Messaging service, you must meet the following system
|
||||
requirements:
|
||||
|
||||
* Installed Identity service for user and project management.
|
||||
* Python 2.7.
|
||||
|
||||
Before you install and configure Messaging, you must create a ``MongoDB``
|
||||
replica-set of three database servers. Also you need to create service
|
||||
credentials and API endpoints in Identity.
|
||||
|
||||
#. Install and configure ``MongoDB`` replica-set on database servers:
|
||||
|
||||
#. Install ``MongoDB`` on the database servers:
|
||||
|
||||
On each database server follow the official `MongoDB installation
|
||||
instructions`_.
|
||||
|
||||
.. note::
|
||||
|
||||
Messaging service works with ``MongoDB`` versions >= 2.4
|
||||
|
||||
#. Configure ``MongoDB`` on the database servers:
|
||||
|
||||
On each database server edit configuration file: ``/etc/mongod.conf`` and
|
||||
modify as needed:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
# MongoDB sample configuration for Messaging service.
|
||||
# (For MongoDB version >= 2.6)
|
||||
# Edit according to your needs.
|
||||
systemLog:
|
||||
destination: file
|
||||
logAppend: true
|
||||
path: /var/log/mongodb/mongod.log
|
||||
|
||||
storage:
|
||||
dbPath: /var/lib/mongo
|
||||
journal:
|
||||
enabled: false
|
||||
|
||||
processManagement:
|
||||
fork: true # fork and run in background
|
||||
pidFilePath: /var/run/mongodb/mongod.pid # location of pidfile
|
||||
|
||||
net:
|
||||
port: 27017
|
||||
# bindIp: 127.0.0.1 # Listen to local interface only, comment to listen on all interfaces.
|
||||
|
||||
operationProfiling:
|
||||
slowOpThresholdMs: 200
|
||||
mode: slowOp
|
||||
|
||||
replication:
|
||||
oplogSizeMB: 2048
|
||||
replSetName: catalog
|
||||
|
||||
.. note::
|
||||
|
||||
In case of older ``MongoDB`` versions (2.4 and 2.5) the configuration
|
||||
file should be written in different format. For information about
|
||||
format for different versions see the official `MongoDB configuration
|
||||
reference`_.
|
||||
|
||||
.. warning::
|
||||
|
||||
Additional steps are required to secure ``MongoDB`` installation. You
|
||||
should modify this configuration for your security requirements. See
|
||||
the official `MongoDB security reference`_.
|
||||
|
||||
#. Start ``MongoDB`` on the database servers:
|
||||
|
||||
Start ``MongoDB`` service on all database servers:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# systemctl start mongod
|
||||
|
||||
Make ``MongoDB`` service start automatically after reboot:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# systemctl enable mongod
|
||||
|
||||
#. Configure ``MongoDB`` Replica Set on the database servers:
|
||||
|
||||
Once you've installed ``MongoDB`` on three servers and assuming that the
|
||||
primary ``MongoDB`` server hostname is ``MYDB0.EXAMPLE-MESSAGES.NET``, go
|
||||
to ``MYDB0`` and run these commands:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# mongo local --eval "printjson(rs.initiate())"
|
||||
# mongo local --eval "printjson(rs.add('MYDB1.EXAMPLE-MESSAGES.NET'))"
|
||||
# mongo local --eval "printjson(rs.add('MYDB2.EXAMPLE-MESSAGES.NET'))"
|
||||
|
||||
.. note::
|
||||
|
||||
The database servers must have access to each other and also be
|
||||
accessible from the Messaging service web server. Configure firewalls
|
||||
on all database servers to accept incoming connections to port
|
||||
``27017`` from the needed source.
|
||||
|
||||
To check if the replica-set is established see the output of this
|
||||
command:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# mongo local --eval "printjson(rs.status())"
|
||||
|
||||
#. Source the ``admin`` credentials to gain access to admin-only CLI commands:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ . admin-openrc
|
||||
|
||||
#. To create the service credentials, complete these steps:
|
||||
|
||||
#. Create the ``zaqar`` user:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ openstack user create --domain default --password-prompt zaqar
|
||||
User Password:
|
||||
Repeat User Password:
|
||||
+-----------+----------------------------------+
|
||||
| Field | Value |
|
||||
+-----------+----------------------------------+
|
||||
| domain_id | default |
|
||||
| enabled | True |
|
||||
| id | 7b0ffc83097148dab6ecbef6ddcc46bf |
|
||||
| name | zaqar |
|
||||
+-----------+----------------------------------+
|
||||
|
||||
#. Add the ``admin`` role to the ``zaqar`` user:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ openstack role add --project service --user zaqar admin
|
||||
|
||||
.. note::
|
||||
|
||||
This command provides no output.
|
||||
|
||||
#. Create the ``zaqar`` service entity:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ openstack service create --name zaqar --description "Messaging" messaging
|
||||
+-------------+----------------------------------+
|
||||
| Field | Value |
|
||||
+-------------+----------------------------------+
|
||||
| description | Messaging |
|
||||
| enabled | True |
|
||||
| id | b39c22818be5425ba2315dd4b10cd57c |
|
||||
| name | zaqar |
|
||||
| type | messaging |
|
||||
+-------------+----------------------------------+
|
||||
|
||||
#. Create the Messaging service API endpoints:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ openstack endpoint create --region RegionOne messaging public http://WEB0.EXAMPLE-MESSAGES.NET:8888
|
||||
+--------------+---------------------------------------+
|
||||
| Field | Value |
|
||||
+--------------+---------------------------------------+
|
||||
| enabled | True |
|
||||
| id | aabca78860e74c4db0bcb36167bfe106 |
|
||||
| interface | public |
|
||||
| region | RegionOne |
|
||||
| region_id | RegionOne |
|
||||
| service_id | b39c22818be5425ba2315dd4b10cd57c |
|
||||
| service_name | zaqar |
|
||||
| service_type | messaging |
|
||||
| url | http://WEB0.EXAMPLE-MESSAGES.NET:8888 |
|
||||
+--------------+---------------------------------------+
|
||||
|
||||
$ openstack endpoint create --region RegionOne messaging internal http://WEB0.EXAMPLE-MESSAGES.NET:8888
|
||||
+--------------+---------------------------------------+
|
||||
| Field | Value |
|
||||
+--------------+---------------------------------------+
|
||||
| enabled | True |
|
||||
| id | 07f9524613de4fd3905e13a87f81fd3f |
|
||||
| interface | internal |
|
||||
| region | RegionOne |
|
||||
| region_id | RegionOne |
|
||||
| service_id | b39c22818be5425ba2315dd4b10cd57c |
|
||||
| service_name | zaqar |
|
||||
| service_type | messaging |
|
||||
| url | http://WEB0.EXAMPLE-MESSAGES.NET:8888 |
|
||||
+--------------+---------------------------------------+
|
||||
|
||||
$ openstack endpoint create --region RegionOne messaging admin http://WEB0.EXAMPLE-MESSAGES.NET:8888
|
||||
+--------------+---------------------------------------+
|
||||
| Field | Value |
|
||||
+--------------+---------------------------------------+
|
||||
| enabled | True |
|
||||
| id | 686f7b19428f4b5aa1425667dfe4f49d |
|
||||
| interface | admin |
|
||||
| region | RegionOne |
|
||||
| region_id | RegionOne |
|
||||
| service_id | b39c22818be5425ba2315dd4b10cd57c |
|
||||
| service_name | zaqar |
|
||||
| service_type | messaging |
|
||||
| url | http://WEB0.EXAMPLE-MESSAGES.NET:8888 |
|
||||
+--------------+---------------------------------------+
|
||||
|
||||
Install and configure Messaging web server
|
||||
------------------------------------------
|
||||
|
||||
Install and configure ``memcached``, ``uWSGI`` and Messaging on the web server
|
||||
``WEB0.EXAMPLE-MESSAGES.NET``.
|
||||
|
||||
#. Install ``memcached`` on web server ``WEB0.EXAMPLE-MESSAGES.NET`` in order
|
||||
to cache Identity service tokens and catalog mappings:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# yum install memcached
|
||||
|
||||
Start ``memcached`` service:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# systemctl start memcached
|
||||
|
||||
Make ``memcached`` service start automatically after reboot:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# systemctl enable memcached
|
||||
|
||||
#. Install Messaging service and ``uWSGI``:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# yum -y install python-pip
|
||||
# git clone https://git.openstack.org/openstack/zaqar.git
|
||||
# cd zaqar
|
||||
# pip install . -r ./requirements.txt --upgrade --log /tmp/zaqar-pip.log
|
||||
# pip install --upgrade pymongo gevent uwsgi
|
||||
|
||||
#. Copy the Zaqar RBAC policy sample file to the directory ``etc/zaqar/``:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# mkdir
|
||||
# cp etc/policy.json.sample /etc/zaqar/policy.json
|
||||
|
||||
#. Create log file:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# touch /var/log/zaqar-server.log
|
||||
# chown ZAQARUSER:ZAQARUSER /var/log/zaqar-server.log
|
||||
# chmod 600 /var/log/zaqar-server.log
|
||||
|
||||
Replace ``ZAQARUSER`` with the name of the user in system under which the
|
||||
Messaging service will run.
|
||||
|
||||
#. Create ``/srv/zaqar`` folder to store ``uWSGI`` configuration files.
|
||||
|
||||
#. Create ``/srv/zaqar/zaqar_uwsgi.py`` with the following content:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from keystonemiddleware import auth_token
|
||||
from zaqar.transport.wsgi import app
|
||||
|
||||
app = auth_token.AuthProtocol(app.app, {})
|
||||
|
||||
#. Increase backlog listen limit from default (128):
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# echo "net.core.somaxconn=2048" | sudo tee --append /etc/sysctl.conf
|
||||
|
||||
#. Create ``/srv/zaqar/uwsgi.ini`` file with the following content and modify
|
||||
as needed:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[uwsgi]
|
||||
https = WEB0.EXAMPLE-MESSAGES.NET:8888,PATH_TO_SERVER_CRT,PATH_TO_SERVER_PRIVATE_KEY
|
||||
pidfile = /var/run/zaqar.pid
|
||||
gevent = 2000
|
||||
gevent-monkey-patch = true
|
||||
listen = 1024
|
||||
enable-threads = true
|
||||
module = zaqar_uwsgi:app
|
||||
workers = 4
|
||||
harakiri = 60
|
||||
add-header = Connection: close
|
||||
|
||||
Replace ``PATH_TO_SERVER_CRT`` with path to the server's certificate
|
||||
(``*.crt``) and ``PATH_TO_SERVER_PRIVATE_KEY`` with path to the server's
|
||||
private key (``*.key``).
|
||||
|
||||
.. note::
|
||||
|
||||
The ``uWSGI`` configuration options above can be modified for different
|
||||
security and performance requirements including load balancing. See the
|
||||
official `uWSGI configuration reference`_.
|
||||
|
||||
#. Create Messaging service's configuration file ``/etc/zaqar.conf`` with the
|
||||
following content:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[DEFAULT]
|
||||
# Show debugging output in logs (sets DEBUG log level output)
|
||||
#debug = False
|
||||
|
||||
# Pooling and admin mode configs
|
||||
pooling = True
|
||||
admin_mode = True
|
||||
|
||||
# Log to file
|
||||
log_file = /var/log/zaqar-server.log
|
||||
|
||||
# This is taken care of in our custom app.py, so disable here
|
||||
;auth_strategy = keystone
|
||||
|
||||
# Modify to make it work with your Identity service.
|
||||
[keystone_authtoken]
|
||||
project_domain_name = Default
|
||||
user_domain_name = Default
|
||||
project_domain_id = default
|
||||
project_name = service
|
||||
user_domain_id = default
|
||||
# File path to a PEM encoded Certificate Authority to use when verifying
|
||||
# HTTPs connections. Defaults to system CAs if commented.
|
||||
cafile = PATH_TO_CA_FILE
|
||||
# Messaging service user name in Identity service.
|
||||
username = ZAQARIDENTITYUSER
|
||||
# Messaging service password in Identity service.
|
||||
password = ZAQARIDENTITYPASSWORD
|
||||
# Complete public Identity API endpoint (HTTPS protocol is more preferable
|
||||
# than HTTP).
|
||||
auth_uri = HTTPS://IDENTITY.EXAMPLE-MESSAGES.NET:5000
|
||||
# Complete admin Identity API endpoint (HTTPS protocol is more preferable
|
||||
# than HTTP).
|
||||
auth_url = HTTPS://IDENTITY.EXAMPLE-MESSAGES.NET:35357
|
||||
# Token cache time in seconds.
|
||||
token_cache_time = TOKEN_CACHE_TIME
|
||||
memcached_servers = 127.0.0.1:11211
|
||||
|
||||
[cache]
|
||||
# Dogpile.cache backend module. It is recommended that Memcache with
|
||||
# pooling (oslo_cache.memcache_pool) or Redis (dogpile.cache.redis) be
|
||||
# used in production deployments. Small workloads (single process)
|
||||
# like devstack can use the dogpile.cache.memory backend. (string
|
||||
# value)
|
||||
backend = dogpile.cache.memory
|
||||
memcache_servers = 127.0.0.1:11211
|
||||
|
||||
[drivers]
|
||||
transport = wsgi
|
||||
message_store = mongodb
|
||||
management_store = mongodb
|
||||
|
||||
[drivers:management_store:mongodb]
|
||||
# Mongodb Connection URI. If ssl connection enabled, then ssl_keyfile,
|
||||
# ssl_certfile, ssl_cert_reqs, ssl_ca_certs options need to be set
|
||||
# accordingly.
|
||||
uri = mongodb://MYDB0.EXAMPLE-MESSAGES.NET,MYDB1.EXAMPLE-MESSAGES.NET,MYDB2.EXAMPLE-MESSAGES.NET:27017/?replicaSet=catalog&w=2&readPreference=secondaryPreferred
|
||||
|
||||
# Name for the database on mongodb server.
|
||||
database = zaqarmanagementstore
|
||||
|
||||
# Number of databases across which to partition message data, in order
|
||||
# to reduce writer lock %. DO NOT change this setting after initial
|
||||
# deployment. It MUST remain static. Also, you should not need a large
|
||||
# number of partitions to improve performance, esp. if deploying
|
||||
# MongoDB on SSD storage. (integer value)
|
||||
partitions = 8
|
||||
|
||||
# Uncomment any options below if needed.
|
||||
|
||||
# Maximum number of times to retry a failed operation. Currently
|
||||
# only used for retrying a message post.
|
||||
;max_attempts = 1000
|
||||
|
||||
# Maximum sleep interval between retries (actual sleep time
|
||||
# increases linearly according to number of attempts performed).
|
||||
;max_retry_sleep = 0.1
|
||||
|
||||
# Maximum jitter interval, to be added to the sleep interval, in
|
||||
# order to decrease probability that parallel requests will retry
|
||||
# at the same instant.
|
||||
;max_retry_jitter = 0.005
|
||||
|
||||
# Frequency of message garbage collections, in seconds
|
||||
;gc_interval = 5 * 60
|
||||
|
||||
# Threshold of number of expired messages to reach in a given
|
||||
# queue, before performing the GC. Useful for reducing frequent
|
||||
# locks on the DB for non-busy queues, or for worker queues
|
||||
# which process jobs quickly enough to keep the number of in-
|
||||
# flight messages low.
|
||||
#
|
||||
# Note: The higher this number, the larger the memory-mapped DB
|
||||
# files will be.
|
||||
;gc_threshold = 1000
|
||||
|
||||
[drivers:message_store:mongodb]
|
||||
# This section has same set of available options as
|
||||
# "[drivers:management_store:mongodb]" section.
|
||||
#
|
||||
# If pooling is enabled, all pools inherit values from options in these
|
||||
# settings unless overridden in pool creation request. Also "uri" option
|
||||
# value isn't used in case of pooling.
|
||||
#
|
||||
# If ssl connection enabled, then ssl_keyfile, ssl_certfile, ssl_cert_reqs,
|
||||
# ssl_ca_certs options need to be set accordingly.
|
||||
|
||||
# Name for the database on MondoDB server.
|
||||
database = zaqarmessagestore
|
||||
|
||||
[transport]
|
||||
max_queues_per_page = 1000
|
||||
max_queue_metadata = 262144
|
||||
max_mesages_per_page = 10
|
||||
max_messages_post_size = 262144
|
||||
max_message_ttl = 1209600
|
||||
max_claim_ttl = 43200
|
||||
max_claim_grace = 43200
|
||||
|
||||
[signed_url]
|
||||
# Secret key used to encrypt pre-signed URLs. (string value)
|
||||
secret_key = SOMELONGSECRETKEY
|
||||
|
||||
Edit any options as needed, especially the options with capitalized values.
|
||||
|
||||
#. Create a service file for Messaging service
|
||||
``/etc/systemd/system/zaqaruwsgi.service``:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[Unit]
|
||||
Description=uWSGI Zaqar
|
||||
After=syslog.target
|
||||
|
||||
[Service]
|
||||
ExecStart=/usr/bin/uwsgi --ini /srv/zaqar/uwsgi.ini
|
||||
# Requires systemd version 211 or newer
|
||||
RuntimeDirectory=uwsgi
|
||||
Restart=always
|
||||
KillSignal=SIGQUIT
|
||||
Type=notify
|
||||
StandardError=syslog
|
||||
NotifyAccess=all
|
||||
User=ZAQARUSER
|
||||
Group=ZAQARUSER
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
|
||||
Replace ``ZAQARUSER`` with the name of the user in system under which the
|
||||
Messaging service will run.
|
||||
|
||||
Finalize installation
|
||||
---------------------
|
||||
|
||||
Now after you have configured the web server and the database servers to have a
|
||||
functional Messaging service, you need to start the service, make the service
|
||||
automatically start with the system and define the created ``MongoDB``
|
||||
replica-set as Messaging's pool.
|
||||
|
||||
#. Start Messaging service on the web server:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# systemctl start zaqar.uwsgi.service
|
||||
|
||||
#. Make Messaging service start automatically after reboot on the web server:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# systemctl enable zaqar.uwsgi.service
|
||||
|
||||
#. Configure pool:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# curl -i -X PUT https://WEB0.EXAMPLE-MESSAGES.NET:8888/v2/pools/POOL1 \
|
||||
-d '{"weight": 100, "uri": "mongodb://MYDB0.EXAMPLE-MESSAGES.NET,MYDB1.EXAMPLE-MESSAGES.NET,MYDB2.EXAMPLE-MESSAGES.NET:27017/?replicaSet=catalog&w=2&readPreference=secondaryPreferred", "options": {"partitions": 8}}' \
|
||||
-H "Client-ID: CLIENT_ID" \
|
||||
-H "X-Auth-Token: TOKEN" \
|
||||
-H "Content-type: application/json" \
|
||||
|
||||
Replace ``POOL1`` variable with the desired name of a pool.
|
||||
|
||||
Replace ``CLIENT_ID`` variable with the universally unique identifier (UUID)
|
||||
which can be generated by, for example, ``uuidgen`` utility.
|
||||
|
||||
Replace ``TOKEN`` variable with the authentication token retrieved from
|
||||
Identity service. If you choose not to enable Keystone authentication you
|
||||
won't have to pass a token.
|
||||
|
||||
.. note::
|
||||
|
||||
The ``options`` key in curl request above overrides any options
|
||||
(specified in configuration file or default) in
|
||||
``[drivers:message_store:mongodb]`` Messaging service configuration
|
||||
file's section.
|
||||
|
||||
.. tip::
|
||||
|
||||
In larger deployments, there should be many load balanced web servers. Also
|
||||
the management store databases and the message store databases (pools)
|
||||
should be on different ``MongoDB`` replica-sets.
|
||||
|
||||
.. _`MongoDB installation instructions`: https://docs.mongodb.org/manual/tutorial/install-mongodb-on-red-hat/
|
||||
.. _`MongoDB configuration reference`: https://docs.mongodb.org/v3.0/reference/configuration-options/
|
||||
.. _`MongoDB security reference`: https://docs.mongodb.org/manual/security/
|
||||
.. _`uWSGI configuration reference`: http://uwsgi-docs.readthedocs.io/en/latest/
|
||||
@ -1,529 +0,0 @@
|
||||
.. _install-ubuntu:
|
||||
|
||||
Install and configure for Ubuntu
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This section describes how to install and configure the Messaging service
|
||||
for Ubuntu 14.04 (LTS).
|
||||
|
||||
This section assumes that you already have a working OpenStack environment with
|
||||
at least Identity service installed.
|
||||
|
||||
Here you can find instructions and recommended settings for installing
|
||||
Messaging service in small configuration: one web server with Messaging service
|
||||
configured to use replica-set of three ``MongoDB`` database servers. Because
|
||||
only one web server is used, the Messaging service installed by using these
|
||||
instructions can't be considered as high available, see :doc:`install`.
|
||||
|
||||
In this tutorial these server names are used as examples:
|
||||
|
||||
* Web server with Messaging service: ``WEB0.EXAMPLE-MESSAGES.NET``.
|
||||
* Database servers: ``MYDB0.EXAMPLE-MESSAGES.NET``,
|
||||
``MYDB1.EXAMPLE-MESSAGES.NET``, ``MYDB2.EXAMPLE-MESSAGES.NET``.
|
||||
* Identity service server: ``IDENTITY.EXAMPLE-MESSAGES.NET``.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
Before you install Messaging service, you must meet the following system
|
||||
requirements:
|
||||
|
||||
* Installed Identity service for user and project management.
|
||||
* Python 2.7.
|
||||
|
||||
Before you install and configure Messaging, you must create a ``MongoDB``
|
||||
replica-set of three database servers. Also you need to create service
|
||||
credentials and API endpoints in Identity.
|
||||
|
||||
#. Install and configure ``MongoDB`` replica-set on database servers:
|
||||
|
||||
#. Install ``MongoDB`` on the database servers:
|
||||
|
||||
On each database server follow the official `MongoDB installation
|
||||
instructions`_.
|
||||
|
||||
.. note::
|
||||
|
||||
Messaging service works with ``MongoDB`` versions >= 2.4
|
||||
|
||||
#. Configure ``MongoDB`` on the database servers:
|
||||
|
||||
On each database server edit configuration file: ``/etc/mongod.conf`` and
|
||||
modify as needed:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
# MongoDB sample configuration for Messaging service.
|
||||
# (For MongoDB version >= 2.6)
|
||||
# Edit according to your needs.
|
||||
systemLog:
|
||||
destination: file
|
||||
logAppend: true
|
||||
path: /var/log/mongodb/mongod.log
|
||||
|
||||
storage:
|
||||
dbPath: /var/lib/mongo
|
||||
journal:
|
||||
enabled: false
|
||||
|
||||
processManagement:
|
||||
fork: true # fork and run in background
|
||||
pidFilePath: /var/run/mongodb/mongod.pid # location of pidfile
|
||||
|
||||
net:
|
||||
port: 27017
|
||||
# bindIp: 127.0.0.1 # Listen to local interface only, comment to listen on all interfaces.
|
||||
|
||||
operationProfiling:
|
||||
slowOpThresholdMs: 200
|
||||
mode: slowOp
|
||||
|
||||
replication:
|
||||
oplogSizeMB: 2048
|
||||
replSetName: catalog
|
||||
|
||||
.. note::
|
||||
|
||||
In case of older ``MongoDB`` versions (2.4 and 2.5) the configuration
|
||||
file should be written in different format. For information about
|
||||
format for different versions see the official `MongoDB configuration
|
||||
reference`_.
|
||||
|
||||
.. warning::
|
||||
|
||||
Additional steps are required to secure ``MongoDB`` installation. You
|
||||
should modify this configuration for your security requirements. See
|
||||
the official `MongoDB security reference`_.
|
||||
|
||||
#. Start ``MongoDB`` on the database servers:
|
||||
|
||||
Start ``MongoDB`` service on all database servers:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# service mongodb start
|
||||
|
||||
#. Configure ``MongoDB`` Replica Set on the database servers:
|
||||
|
||||
Once you've installed ``MongoDB`` on three servers and assuming that the
|
||||
primary ``MongoDB`` server hostname is ``MYDB0.EXAMPLE-MESSAGES.NET``, go
|
||||
to ``MYDB0`` and run these commands:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# mongo local --eval "printjson(rs.initiate())"
|
||||
# mongo local --eval "printjson(rs.add('MYDB1.EXAMPLE-MESSAGES.NET'))"
|
||||
# mongo local --eval "printjson(rs.add('MYDB2.EXAMPLE-MESSAGES.NET'))"
|
||||
|
||||
.. note::
|
||||
|
||||
The database servers must have access to each other and also be
|
||||
accessible from the Messaging service web server. Configure firewalls
|
||||
on all database servers to accept incoming connections to port
|
||||
``27017`` from the needed source.
|
||||
|
||||
To check if the replica-set is established see the output of this
|
||||
command:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# mongo local --eval "printjson(rs.status())"
|
||||
|
||||
#. Source the ``admin`` credentials to gain access to admin-only CLI commands:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ . admin-openrc
|
||||
|
||||
#. To create the service credentials, complete these steps:
|
||||
|
||||
#. Create the ``zaqar`` user:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ openstack user create --domain default --password-prompt zaqar
|
||||
User Password:
|
||||
Repeat User Password:
|
||||
+-----------+----------------------------------+
|
||||
| Field | Value |
|
||||
+-----------+----------------------------------+
|
||||
| domain_id | default |
|
||||
| enabled | True |
|
||||
| id | 7b0ffc83097148dab6ecbef6ddcc46bf |
|
||||
| name | zaqar |
|
||||
+-----------+----------------------------------+
|
||||
|
||||
#. Add the ``admin`` role to the ``zaqar`` user:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ openstack role add --project service --user zaqar admin
|
||||
|
||||
.. note::
|
||||
|
||||
This command provides no output.
|
||||
|
||||
#. Create the ``zaqar`` service entity:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ openstack service create --name zaqar --description "Messaging" messaging
|
||||
+-------------+----------------------------------+
|
||||
| Field | Value |
|
||||
+-------------+----------------------------------+
|
||||
| description | Messaging |
|
||||
| enabled | True |
|
||||
| id | b39c22818be5425ba2315dd4b10cd57c |
|
||||
| name | zaqar |
|
||||
| type | messaging |
|
||||
+-------------+----------------------------------+
|
||||
|
||||
#. Create the Messaging service API endpoints:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ openstack endpoint create --region RegionOne messaging public http://WEB0.EXAMPLE-MESSAGES.NET:8888
|
||||
+--------------+---------------------------------------+
|
||||
| Field | Value |
|
||||
+--------------+---------------------------------------+
|
||||
| enabled | True |
|
||||
| id | aabca78860e74c4db0bcb36167bfe106 |
|
||||
| interface | public |
|
||||
| region | RegionOne |
|
||||
| region_id | RegionOne |
|
||||
| service_id | b39c22818be5425ba2315dd4b10cd57c |
|
||||
| service_name | zaqar |
|
||||
| service_type | messaging |
|
||||
| url | http://WEB0.EXAMPLE-MESSAGES.NET:8888 |
|
||||
+--------------+---------------------------------------+
|
||||
|
||||
$ openstack endpoint create --region RegionOne messaging internal http://WEB0.EXAMPLE-MESSAGES.NET:8888
|
||||
+--------------+---------------------------------------+
|
||||
| Field | Value |
|
||||
+--------------+---------------------------------------+
|
||||
| enabled | True |
|
||||
| id | 07f9524613de4fd3905e13a87f81fd3f |
|
||||
| interface | internal |
|
||||
| region | RegionOne |
|
||||
| region_id | RegionOne |
|
||||
| service_id | b39c22818be5425ba2315dd4b10cd57c |
|
||||
| service_name | zaqar |
|
||||
| service_type | messaging |
|
||||
| url | http://WEB0.EXAMPLE-MESSAGES.NET:8888 |
|
||||
+--------------+---------------------------------------+
|
||||
|
||||
$ openstack endpoint create --region RegionOne messaging admin http://WEB0.EXAMPLE-MESSAGES.NET:8888
|
||||
+--------------+---------------------------------------+
|
||||
| Field | Value |
|
||||
+--------------+---------------------------------------+
|
||||
| enabled | True |
|
||||
| id | 686f7b19428f4b5aa1425667dfe4f49d |
|
||||
| interface | admin |
|
||||
| region | RegionOne |
|
||||
| region_id | RegionOne |
|
||||
| service_id | b39c22818be5425ba2315dd4b10cd57c |
|
||||
| service_name | zaqar |
|
||||
| service_type | messaging |
|
||||
| url | http://WEB0.EXAMPLE-MESSAGES.NET:8888 |
|
||||
+--------------+---------------------------------------+
|
||||
|
||||
Install and configure Messaging web server
|
||||
------------------------------------------
|
||||
|
||||
Install and configure ``memcached``, ``uWSGI`` and Messaging on the web server
|
||||
``WEB0.EXAMPLE-MESSAGES.NET``.
|
||||
|
||||
#. Install ``memcached`` on web server ``WEB0.EXAMPLE-MESSAGES.NET`` in order
|
||||
to cache Identity service tokens and catalog mappings:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# apt-get install memcached
|
||||
|
||||
Start ``memcached`` service:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# service memcached start
|
||||
|
||||
#. Install Messaging service and ``uWSGI``:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# apt-get install python-pip
|
||||
# git clone https://git.openstack.org/openstack/zaqar.git
|
||||
# cd zaqar
|
||||
# pip install . -r ./requirements.txt --upgrade --log /tmp/zaqar-pip.log
|
||||
# pip install --upgrade pymongo gevent uwsgi
|
||||
|
||||
#. Copy the Zaqar RBAC policy sample file to the directory ``etc/zaqar/``:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# mkdir
|
||||
# cp etc/policy.json.sample /etc/zaqar/policy.json
|
||||
|
||||
#. Create log file:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# touch /var/log/zaqar-server.log
|
||||
# chown ZAQARUSER:ZAQARUSER /var/log/zaqar-server.log
|
||||
# chmod 600 /var/log/zaqar-server.log
|
||||
|
||||
Replace ``ZAQARUSER`` with the name of the user in system under which the
|
||||
Messaging service will run.
|
||||
|
||||
#. Create ``/srv/zaqar`` folder to store ``uWSGI`` configuration files.
|
||||
|
||||
#. Create ``/srv/zaqar/zaqar_uwsgi.py`` with the following content:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from keystonemiddleware import auth_token
|
||||
from zaqar.transport.wsgi import app
|
||||
|
||||
app = auth_token.AuthProtocol(app.app, {})
|
||||
|
||||
#. Increase backlog listen limit from default (128):
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# echo "net.core.somaxconn=2048" | sudo tee --append /etc/sysctl.conf
|
||||
|
||||
#. Create ``/srv/zaqar/uwsgi.ini`` file with the following content and modify
|
||||
as needed:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[uwsgi]
|
||||
https = WEB0.EXAMPLE-MESSAGES.NET:8888,PATH_TO_SERVER_CRT,PATH_TO_SERVER_PRIVATE_KEY
|
||||
pidfile = /var/run/zaqar.pid
|
||||
gevent = 2000
|
||||
gevent-monkey-patch = true
|
||||
listen = 1024
|
||||
enable-threads = true
|
||||
module = zaqar_uwsgi:app
|
||||
workers = 4
|
||||
harakiri = 60
|
||||
add-header = Connection: close
|
||||
|
||||
Replace ``PATH_TO_SERVER_CRT`` with path to the server's certificate
|
||||
(``*.crt``) and ``PATH_TO_SERVER_PRIVATE_KEY`` with path to the server's
|
||||
private key (``*.key``).
|
||||
|
||||
.. note::
|
||||
|
||||
The ``uWSGI`` configuration options above can be modified for different
|
||||
security and performance requirements including load balancing. See the
|
||||
official `uWSGI configuration reference`_.
|
||||
|
||||
#. Create Messaging service's configuration file ``/etc/zaqar.conf`` with the
|
||||
following content:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[DEFAULT]
|
||||
# Show debugging output in logs (sets DEBUG log level output)
|
||||
#debug = False
|
||||
|
||||
# Pooling and admin mode configs
|
||||
pooling = True
|
||||
admin_mode = True
|
||||
|
||||
# Log to file
|
||||
log_file = /var/log/zaqar-server.log
|
||||
|
||||
# This is taken care of in our custom app.py, so disable here
|
||||
;auth_strategy = keystone
|
||||
|
||||
# Modify to make it work with your Identity service.
|
||||
[keystone_authtoken]
|
||||
project_domain_name = Default
|
||||
user_domain_name = Default
|
||||
project_domain_id = default
|
||||
project_name = service
|
||||
user_domain_id = default
|
||||
# File path to a PEM encoded Certificate Authority to use when verifying
|
||||
# HTTPs connections. Defaults to system CAs if commented.
|
||||
cafile = PATH_TO_CA_FILE
|
||||
# Messaging service user name in Identity service.
|
||||
username = ZAQARIDENTITYUSER
|
||||
# Messaging service password in Identity service.
|
||||
password = ZAQARIDENTITYPASSWORD
|
||||
# Complete public Identity API endpoint (HTTPS protocol is more preferable
|
||||
# than HTTP).
|
||||
auth_uri = HTTPS://IDENTITY.EXAMPLE-MESSAGES.NET:5000
|
||||
# Complete admin Identity API endpoint (HTTPS protocol is more preferable
|
||||
# than HTTP).
|
||||
auth_url = HTTPS://IDENTITY.EXAMPLE-MESSAGES.NET:35357
|
||||
# Token cache time in seconds.
|
||||
token_cache_time = TOKEN_CACHE_TIME
|
||||
memcached_servers = 127.0.0.1:11211
|
||||
|
||||
[cache]
|
||||
# Dogpile.cache backend module. It is recommended that Memcache with
|
||||
# pooling (oslo_cache.memcache_pool) or Redis (dogpile.cache.redis) be
|
||||
# used in production deployments. Small workloads (single process)
|
||||
# like devstack can use the dogpile.cache.memory backend. (string
|
||||
# value)
|
||||
backend = dogpile.cache.memory
|
||||
memcache_servers = 127.0.0.1:11211
|
||||
|
||||
[drivers]
|
||||
transport = wsgi
|
||||
message_store = mongodb
|
||||
management_store = mongodb
|
||||
|
||||
[drivers:management_store:mongodb]
|
||||
# Mongodb Connection URI. If ssl connection enabled, then ssl_keyfile,
|
||||
# ssl_certfile, ssl_cert_reqs, ssl_ca_certs options need to be set
|
||||
# accordingly.
|
||||
uri = mongodb://MYDB0.EXAMPLE-MESSAGES.NET,MYDB1.EXAMPLE-MESSAGES.NET,MYDB2.EXAMPLE-MESSAGES.NET:27017/?replicaSet=catalog&w=2&readPreference=secondaryPreferred
|
||||
|
||||
# Name for the database on mongodb server.
|
||||
database = zaqarmanagementstore
|
||||
|
||||
# Number of databases across which to partition message data, in order
|
||||
# to reduce writer lock %. DO NOT change this setting after initial
|
||||
# deployment. It MUST remain static. Also, you should not need a large
|
||||
# number of partitions to improve performance, esp. if deploying
|
||||
# MongoDB on SSD storage. (integer value)
|
||||
partitions = 8
|
||||
|
||||
# Uncomment any options below if needed.
|
||||
|
||||
# Maximum number of times to retry a failed operation. Currently
|
||||
# only used for retrying a message post.
|
||||
;max_attempts = 1000
|
||||
|
||||
# Maximum sleep interval between retries (actual sleep time
|
||||
# increases linearly according to number of attempts performed).
|
||||
;max_retry_sleep = 0.1
|
||||
|
||||
# Maximum jitter interval, to be added to the sleep interval, in
|
||||
# order to decrease probability that parallel requests will retry
|
||||
# at the same instant.
|
||||
;max_retry_jitter = 0.005
|
||||
|
||||
# Frequency of message garbage collections, in seconds
|
||||
;gc_interval = 5 * 60
|
||||
|
||||
# Threshold of number of expired messages to reach in a given
|
||||
# queue, before performing the GC. Useful for reducing frequent
|
||||
# locks on the DB for non-busy queues, or for worker queues
|
||||
# which process jobs quickly enough to keep the number of in-
|
||||
# flight messages low.
|
||||
#
|
||||
# Note: The higher this number, the larger the memory-mapped DB
|
||||
# files will be.
|
||||
;gc_threshold = 1000
|
||||
|
||||
[drivers:message_store:mongodb]
|
||||
# This section has same set of available options as
|
||||
# "[drivers:management_store:mongodb]" section.
|
||||
#
|
||||
# If pooling is enabled, all pools inherit values from options in these
|
||||
# settings unless overridden in pool creation request. Also "uri" option
|
||||
# value isn't used in case of pooling.
|
||||
#
|
||||
# If ssl connection enabled, then ssl_keyfile, ssl_certfile, ssl_cert_reqs,
|
||||
# ssl_ca_certs options need to be set accordingly.
|
||||
|
||||
# Name for the database on MondoDB server.
|
||||
database = zaqarmessagestore
|
||||
|
||||
[transport]
|
||||
max_queues_per_page = 1000
|
||||
max_queue_metadata = 262144
|
||||
max_mesages_per_page = 10
|
||||
max_messages_post_size = 262144
|
||||
max_message_ttl = 1209600
|
||||
max_claim_ttl = 43200
|
||||
max_claim_grace = 43200
|
||||
|
||||
[signed_url]
|
||||
# Secret key used to encrypt pre-signed URLs. (string value)
|
||||
secret_key = SOMELONGSECRETKEY
|
||||
|
||||
Edit any options as needed, especially the options with capitalized values.
|
||||
|
||||
#. Create an upstart config, it could be named as ``/etc/init/zaqar.conf``:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
description "Zaqar api server"
|
||||
author "Your Name <yourname@example.com>"
|
||||
|
||||
start on runlevel [2345]
|
||||
stop on runlevel [!2345]
|
||||
|
||||
chdir /var/run
|
||||
|
||||
pre-start script
|
||||
mkdir -p /var/run/zaqar
|
||||
chown zaqar:zaqar /var/run/zaqar
|
||||
|
||||
mkdir -p /var/lock/zaqar
|
||||
chown zaqar:root /var/lock/zaqar
|
||||
end script
|
||||
|
||||
exec /usr/bin/uwsgi --master --emperor /etc/zaqar/uwsgi
|
||||
|
||||
|
||||
Finalize installation
|
||||
---------------------
|
||||
|
||||
Now after you have configured the web server and the database servers to have a
|
||||
functional Messaging service, you need to start the service, make the service
|
||||
automatically start with the system and define the created ``MongoDB``
|
||||
replica-set as Messaging's pool.
|
||||
|
||||
#. Start Messaging service on the web server:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# systemctl start zaqar.uwsgi.service
|
||||
|
||||
#. Make Messaging service start automatically after reboot on the web server:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# systemctl enable zaqar.uwsgi.service
|
||||
|
||||
#. Configure pool:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# curl -i -X PUT https://WEB0.EXAMPLE-MESSAGES.NET:8888/v2/pools/POOL1 \
|
||||
-d '{"weight": 100, "uri": "mongodb://MYDB0.EXAMPLE-MESSAGES.NET,MYDB1.EXAMPLE-MESSAGES.NET,MYDB2.EXAMPLE-MESSAGES.NET:27017/?replicaSet=catalog&w=2&readPreference=secondaryPreferred", "options": {"partitions": 8}}' \
|
||||
-H "Client-ID: CLIENT_ID" \
|
||||
-H "X-Auth-Token: TOKEN" \
|
||||
-H "Content-type: application/json" \
|
||||
|
||||
Replace ``POOL1`` variable with the desired name of a pool.
|
||||
|
||||
Replace ``CLIENT_ID`` variable with the universally unique identifier (UUID)
|
||||
which can be generated by, for example, ``uuidgen`` utility.
|
||||
|
||||
Replace ``TOKEN`` variable with the authentication token retrieved from
|
||||
Identity service. If you choose not to enable Keystone authentication you
|
||||
won't have to pass a token.
|
||||
|
||||
.. note::
|
||||
|
||||
The ``options`` key in curl request above overrides any options
|
||||
(specified in configuration file or default) in
|
||||
``[drivers:message_store:mongodb]`` Messaging service configuration
|
||||
file's section.
|
||||
|
||||
.. tip::
|
||||
|
||||
In larger deployments, there should be many load balanced web servers. Also
|
||||
the management store databases and the message store databases (pools)
|
||||
should be on different ``MongoDB`` replica-sets.
|
||||
|
||||
.. _`MongoDB installation instructions`: https://docs.mongodb.org/manual/tutorial/install-mongodb-on-ubuntu/
|
||||
.. _`MongoDB configuration reference`: https://docs.mongodb.org/v3.0/reference/configuration-options/
|
||||
.. _`MongoDB security reference`: https://docs.mongodb.org/manual/security/
|
||||
.. _`uWSGI configuration reference`: http://uwsgi-docs.readthedocs.io/en/latest/
|
||||
@ -1,35 +0,0 @@
|
||||
.. _install:
|
||||
|
||||
Install and configure
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This section describes how to install and configure the Messaging service,
|
||||
code-named zaqar.
|
||||
|
||||
This section assumes that you already have a working OpenStack environment with
|
||||
at least Identity service installed.
|
||||
|
||||
Note that installation and configuration vary by distribution.
|
||||
|
||||
.. toctree::
|
||||
|
||||
install-obs.rst
|
||||
install-rdo.rst
|
||||
install-ubuntu.rst
|
||||
|
||||
Possible Minimum Scalable HA Setup
|
||||
----------------------------------
|
||||
|
||||
Scalable HA (High availability) setup is out of scope in this chapter.
|
||||
|
||||
For a HA setup, a load balancer has to be placed in front of the web servers.
|
||||
|
||||
To provide high availability with minimum administration overhead for storage
|
||||
use ``MongoDB`` driver and for transport use ``wsgi`` driver.
|
||||
|
||||
To have a small footprint while providing HA, you can use two web servers which
|
||||
will host the application and three ``MongoDB`` servers (configured as
|
||||
replica-set) which will host Messaging service's management store and
|
||||
message store databases. At larger scale, the management store database and the
|
||||
message store database are advised to be hosted on different ``MongoDB``
|
||||
replica sets.
|
||||
@ -1,9 +0,0 @@
|
||||
.. _next-steps:
|
||||
|
||||
Next steps
|
||||
~~~~~~~~~~
|
||||
|
||||
Your OpenStack environment now includes the Messaging service.
|
||||
|
||||
To add additional services, see the
|
||||
`additional documentation on installing OpenStack <http://docs.openstack.org/#install-guides>`_ .
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue
Block a user