mongo-orchestration


Namemongo-orchestration JSON
Version 0.8.0 PyPI version JSON
download
home_pagehttps://github.com/10gen/mongo-orchestration
SummaryRestful service for managing MongoDB servers
upload_time2023-05-18 15:37:54
maintainer
docs_urlNone
authorMongoDB, Inc.
requires_python>=3.6
licensehttp://www.apache.org/licenses/LICENSE-2.0.html
keywords mongo-orchestration mongodb mongo rest testing
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            -------------------
Mongo Orchestration
-------------------

See the `wiki <https://github.com/10gen/mongo-orchestration/wiki>`__
for documentation.

Mongo Orchestration is an HTTP server that provides a REST API for
creating and managing MongoDB configurations on a single host.

**THIS PROJECT IS FOR TESTING OF MONGODB DRIVERS.**

Features
--------

-  Start and stop mongod servers, replica sets, and sharded clusters on the host running mongo-orchestration.
-  Add and remove replica set members.
-  Add and remove shards and mongos routers.
-  Reset replica sets and clusters to restart all members that were
   stopped.
-  Freeze secondary members of replica sets.
-  Retrieve information about MongoDB resources.
-  Interaction all through REST interface.
-  Launch simple local servers using ``mongo-launch`` CLI tool.

Requires
--------

-  `Python >=3.7 <http://www.python.org/download/>`__
-  `bottle>=0.12.7 <https://pypi.python.org/pypi/bottle>`__
-  `pymongo>=3.0.2,<4 <https://pypi.python.org/pypi/pymongo>`__
-  `cheroot>=5.11 <https://pypi.python.org/pypi/cheroot/>`__

Installation
------------

The easiest way to install Mongo Orchestration is with `pip <https://pypi.python.org/pypi/pip>`__:

::

    pip install mongo-orchestration

You can also install the development version of Mongo Orchestration
manually:

::

    git clone https://github.com/10gen/mongo-orchestration.git
    cd mongo-orchestration
    pip install .

Cloning the `repository <https://github.com/10gen/mongo-orchestration>`__ this way will also give you access to the tests for Mongo Orchestration as well as the ``mo`` script. Note that you may
have to run the above commands with ``sudo``, depending on where you're
installing Mongo Orchestration and what privileges you have.
Installation will place a ``mongo-orchestration`` script on your path.

Usage
-----

::

    mongo-orchestration [-h] [-f CONFIG] [-e ENV] [--no-fork] [-b BIND IP="localhost"] [-p PORT]
                        [-s {auto,cheroot,wsgiref}] [--socket-timeout-ms MILLIS]
                        [--pidfile PIDFILE] [--enable-majority-read-concern] {start,stop,restart}


Arguments:

-  **-h** - show help
-  **-f, --config** - path to config file
-  **-e, --env** - default release to use, as specified in the config
   file
-  **--no-fork** - run server in foreground
-  **-b, --bind** - host on which Mongo Orchestration and subordinate mongo processes should listen for requests. Defaults to "localhost".
-  **-s, --server** - HTTP backend to use: one of `auto`, `cheroot`, or `wsgiref`. `auto`
   configures bottle to automatically choose an available backend.
-  **-p** - port number (8889 by default)
-  **--socket-timeout-ms** - socket timeout when connecting to MongoDB servers
-  **--pidfile** - location where mongo-orchestration should place its pid file
-  **--enable-majority-read-concern** - enable "majority" read concern on server versions that support it.
-  **start/stop/restart**: start, stop, or restart the server,
   respectively

In addition, Mongo Orchestration can be influenced by the
``MONGO_ORCHESTRATION_HOME`` environment variable, which informs the
server where to find the "configurations" directory for presets as well
as where to put the log and pid files.

Examples
~~~~~~~~

``mongo-orchestration start``

Starts Mongo Orchestration as service on port 8889.

``mongo-orchestration stop``

Stop the server.

``mongo-orchestration -f mongo-orchestration.config -e 30-release -p 8888 --no-fork start``

Starts Mongo Orchestration on port 8888 using ``30-release`` defined in
``mongo-orchestration.config``. Stops with *Ctrl+C*.

If you have installed mongo-orchestration but you're still getting
``command not found: mongo-orchestration`` this means that the script was
installed to a directory that is not on your ``PATH``. As an alternative use:

``python -m mongo_orchestration.server start``

Configuration File
~~~~~~~~~~~~~~~~~~

Mongo Orchestration may be given a JSON configuration file with the
``--config`` option specifying where to find MongoDB binaries. See
`mongo-orchestration.config <https://github.com/10gen/mongo-orchestration/blob/master/mongo-orchestration.config>`__
for an example. When no configuration file is provided, Mongo
Orchestration uses whatever binaries are on the user's PATH.

Predefined Configurations
-------------------------

Mongo Orchestration has a set of predefined
`configurations <https://github.com/10gen/mongo-orchestration/tree/master/mongo_orchestration/configurations>`__
that can be used to start, restart, or stop MongoDB processes. You can
use a tool like ``curl`` to send these files directly to the Mongo
Orchestration server, or use the ``mo`` script in the ``scripts``
directory (in the `repository <https://github.com/10gen/mongo-orchestration>`__ only). Some examples:

-  Start a single node without SSL or auth:

   ::

       mo configurations/servers/clean.json start

-  Get the status of a single node without SSL or auth:

   ::

       mo configurations/servers/clean.json status

-  Stop a single node without SSL or auth:

   ::

       mo configurations/servers/clean.json stop

-  Start a replica set with ssl and auth:

   ::

       mo configurations/replica_sets/ssl_auth.json start

-  Use ``curl`` to create a basic sharded cluster with the id
   "myCluster":

   ::

       curl -XPUT http://localhost:8889/v1/sharded_clusters/myCluster \
                  -d@configurations/sharded_clusters/basic.json

Note that in order to run the ``mo`` script, you need to be in the same
directory as "configurations".

**Helpful hint**: You can prettify JSON responses from the server by
piping the response into ``python -m json.tool``, e.g.:

::

    $ curl http://localhost:8889/v1/servers/myServer | python -m json.tool

    {
        "id": "myServer",
        "mongodb_uri": "mongodb://localhost:1025",
        "orchestration": "servers",
        "procInfo": {
            "alive": true,
            "name": "mongod",
            "optfile": "/var/folders/v9/spc2j6cx3db71l/T/mongo-KHUACD",
            "params": {
                "dbpath": "/var/folders/v9/spc2j6cx3db71l/T/mongo-vAgYaQ",
                "ipv6": true,
                "journal": true,
                "logappend": true,
                "oplogSize": 100,
                "port": 1025
            },
            "pid": 51320
        },
        // etc.
    }

Mongo Launch
------------

The ``mongo-launch`` CLI tool allows you to spin up servers locally
with minimal configuration.

..

    mongo-launch --help
    Usage: launch.py [single|replica|shard] [ssl] [auth]

..

    mongo-orchestration start
    mongo-launch replica ssl auth

Tests
-----

In order to run the tests, you should first clone the `repository <https://github.com/10gen/mongo-orchestration>`__.

Run all tests
~~~~~~~~~~~~~

``python -m unittest``

Run a test module
~~~~~~~~~~~~~~~~~

``python -m unittest tests.test_servers``

Run a single test case
~~~~~~~~~~~~~~~~~~~~~~

``python -m unittest tests.test_servers.ServerSSLTestCase``

Run a single test method
~~~~~~~~~~~~~~~~~~~~~~~~

``python -m unittest tests.test_servers.ServerSSLTestCase.test_ssl_auth``

Run a single test example for debugging with verbose and immediate stdout output
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``python -m unittest -v tests.test_servers.ServerSSLTestCase``

Changelog
---------

Changes in Version 0.8.0 (2023-05-16)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Add ``mongo-launch`` CLI tool.
- Upgrade to PyMongo 4.x and set up GitHub Actions testing.
- Remove support for managing MongoDB 3.4 or earlier servers.
- Remove support for Python 3.5 or earlier.
- Replaced dependency on CherryPy with cheroot. `-s auto` is the new default
  and `-s cherrypy` is no longer supported.
- Remove transactionLifetimeLimitSeconds default.

Changes in Version 0.7.0 (2021-04-06)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Remove support for managing MongoDB 2.4 servers.
- Add support for Python 3.8 and 3.9.
- Add support for MongoDB 4.2 and 4.4.
- Upgrade from pymongo 3.5.1 to 3.X latest. (#284).
- Ensure createUser succeeds on all replica set members. (#282)
- Create admin user with both SCRAM-SHA-256 and SCRAM-SHA-1. (#281)
- Wait for mongo-orchestration server to fully terminate in "stop". (#276)
- Allow starting clusters with enableTestCommands=0. (#269)
- Decrease transactionLifetimeLimitSeconds on 4.2+ by default. (#267)
- Increase maxTransactionLockRequestTimeoutMillis by default. (#270)
- Reduce periodicNoopIntervalSecs for faster driver change stream testing. (#283)
- Enable ztsd compression by default on 4.2+ (#263)

Changes in Version 0.6.12 (2018-12-14)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Allow running the mongo-orchestration server over IPv6 localhost. (#237)
- Increase default mongodb server logging verbosity. (#255)
- Fixed a bug when shutting down clusters where mongo-orchestration would
  hang forever if the server had already exited. (#253)

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/10gen/mongo-orchestration",
    "name": "mongo-orchestration",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.6",
    "maintainer_email": "",
    "keywords": "mongo-orchestration,mongodb,mongo,rest,testing",
    "author": "MongoDB, Inc.",
    "author_email": "mongodb-user@googlegroups.com",
    "download_url": "https://files.pythonhosted.org/packages/80/bc/46ec328dcb9abcc8e9956c02378bfd4bfb053cb94fcf40b62b75f900d147/mongo-orchestration-0.8.0.tar.gz",
    "platform": "any",
    "description": "-------------------\nMongo Orchestration\n-------------------\n\nSee the `wiki <https://github.com/10gen/mongo-orchestration/wiki>`__\nfor documentation.\n\nMongo Orchestration is an HTTP server that provides a REST API for\ncreating and managing MongoDB configurations on a single host.\n\n**THIS PROJECT IS FOR TESTING OF MONGODB DRIVERS.**\n\nFeatures\n--------\n\n-  Start and stop mongod servers, replica sets, and sharded clusters on the host running mongo-orchestration.\n-  Add and remove replica set members.\n-  Add and remove shards and mongos routers.\n-  Reset replica sets and clusters to restart all members that were\n   stopped.\n-  Freeze secondary members of replica sets.\n-  Retrieve information about MongoDB resources.\n-  Interaction all through REST interface.\n-  Launch simple local servers using ``mongo-launch`` CLI tool.\n\nRequires\n--------\n\n-  `Python >=3.7 <http://www.python.org/download/>`__\n-  `bottle>=0.12.7 <https://pypi.python.org/pypi/bottle>`__\n-  `pymongo>=3.0.2,<4 <https://pypi.python.org/pypi/pymongo>`__\n-  `cheroot>=5.11 <https://pypi.python.org/pypi/cheroot/>`__\n\nInstallation\n------------\n\nThe easiest way to install Mongo Orchestration is with `pip <https://pypi.python.org/pypi/pip>`__:\n\n::\n\n    pip install mongo-orchestration\n\nYou can also install the development version of Mongo Orchestration\nmanually:\n\n::\n\n    git clone https://github.com/10gen/mongo-orchestration.git\n    cd mongo-orchestration\n    pip install .\n\nCloning the `repository <https://github.com/10gen/mongo-orchestration>`__ this way will also give you access to the tests for Mongo Orchestration as well as the ``mo`` script. Note that you may\nhave to run the above commands with ``sudo``, depending on where you're\ninstalling Mongo Orchestration and what privileges you have.\nInstallation will place a ``mongo-orchestration`` script on your path.\n\nUsage\n-----\n\n::\n\n    mongo-orchestration [-h] [-f CONFIG] [-e ENV] [--no-fork] [-b BIND IP=\"localhost\"] [-p PORT]\n                        [-s {auto,cheroot,wsgiref}] [--socket-timeout-ms MILLIS]\n                        [--pidfile PIDFILE] [--enable-majority-read-concern] {start,stop,restart}\n\n\nArguments:\n\n-  **-h** - show help\n-  **-f, --config** - path to config file\n-  **-e, --env** - default release to use, as specified in the config\n   file\n-  **--no-fork** - run server in foreground\n-  **-b, --bind** - host on which Mongo Orchestration and subordinate mongo processes should listen for requests. Defaults to \"localhost\".\n-  **-s, --server** - HTTP backend to use: one of `auto`, `cheroot`, or `wsgiref`. `auto`\n   configures bottle to automatically choose an available backend.\n-  **-p** - port number (8889 by default)\n-  **--socket-timeout-ms** - socket timeout when connecting to MongoDB servers\n-  **--pidfile** - location where mongo-orchestration should place its pid file\n-  **--enable-majority-read-concern** - enable \"majority\" read concern on server versions that support it.\n-  **start/stop/restart**: start, stop, or restart the server,\n   respectively\n\nIn addition, Mongo Orchestration can be influenced by the\n``MONGO_ORCHESTRATION_HOME`` environment variable, which informs the\nserver where to find the \"configurations\" directory for presets as well\nas where to put the log and pid files.\n\nExamples\n~~~~~~~~\n\n``mongo-orchestration start``\n\nStarts Mongo Orchestration as service on port 8889.\n\n``mongo-orchestration stop``\n\nStop the server.\n\n``mongo-orchestration -f mongo-orchestration.config -e 30-release -p 8888 --no-fork start``\n\nStarts Mongo Orchestration on port 8888 using ``30-release`` defined in\n``mongo-orchestration.config``. Stops with *Ctrl+C*.\n\nIf you have installed mongo-orchestration but you're still getting\n``command not found: mongo-orchestration`` this means that the script was\ninstalled to a directory that is not on your ``PATH``. As an alternative use:\n\n``python -m mongo_orchestration.server start``\n\nConfiguration File\n~~~~~~~~~~~~~~~~~~\n\nMongo Orchestration may be given a JSON configuration file with the\n``--config`` option specifying where to find MongoDB binaries. See\n`mongo-orchestration.config <https://github.com/10gen/mongo-orchestration/blob/master/mongo-orchestration.config>`__\nfor an example. When no configuration file is provided, Mongo\nOrchestration uses whatever binaries are on the user's PATH.\n\nPredefined Configurations\n-------------------------\n\nMongo Orchestration has a set of predefined\n`configurations <https://github.com/10gen/mongo-orchestration/tree/master/mongo_orchestration/configurations>`__\nthat can be used to start, restart, or stop MongoDB processes. You can\nuse a tool like ``curl`` to send these files directly to the Mongo\nOrchestration server, or use the ``mo`` script in the ``scripts``\ndirectory (in the `repository <https://github.com/10gen/mongo-orchestration>`__ only). Some examples:\n\n-  Start a single node without SSL or auth:\n\n   ::\n\n       mo configurations/servers/clean.json start\n\n-  Get the status of a single node without SSL or auth:\n\n   ::\n\n       mo configurations/servers/clean.json status\n\n-  Stop a single node without SSL or auth:\n\n   ::\n\n       mo configurations/servers/clean.json stop\n\n-  Start a replica set with ssl and auth:\n\n   ::\n\n       mo configurations/replica_sets/ssl_auth.json start\n\n-  Use ``curl`` to create a basic sharded cluster with the id\n   \"myCluster\":\n\n   ::\n\n       curl -XPUT http://localhost:8889/v1/sharded_clusters/myCluster \\\n                  -d@configurations/sharded_clusters/basic.json\n\nNote that in order to run the ``mo`` script, you need to be in the same\ndirectory as \"configurations\".\n\n**Helpful hint**: You can prettify JSON responses from the server by\npiping the response into ``python -m json.tool``, e.g.:\n\n::\n\n    $ curl http://localhost:8889/v1/servers/myServer | python -m json.tool\n\n    {\n        \"id\": \"myServer\",\n        \"mongodb_uri\": \"mongodb://localhost:1025\",\n        \"orchestration\": \"servers\",\n        \"procInfo\": {\n            \"alive\": true,\n            \"name\": \"mongod\",\n            \"optfile\": \"/var/folders/v9/spc2j6cx3db71l/T/mongo-KHUACD\",\n            \"params\": {\n                \"dbpath\": \"/var/folders/v9/spc2j6cx3db71l/T/mongo-vAgYaQ\",\n                \"ipv6\": true,\n                \"journal\": true,\n                \"logappend\": true,\n                \"oplogSize\": 100,\n                \"port\": 1025\n            },\n            \"pid\": 51320\n        },\n        // etc.\n    }\n\nMongo Launch\n------------\n\nThe ``mongo-launch`` CLI tool allows you to spin up servers locally\nwith minimal configuration.\n\n..\n\n    mongo-launch --help\n    Usage: launch.py [single|replica|shard] [ssl] [auth]\n\n..\n\n    mongo-orchestration start\n    mongo-launch replica ssl auth\n\nTests\n-----\n\nIn order to run the tests, you should first clone the `repository <https://github.com/10gen/mongo-orchestration>`__.\n\nRun all tests\n~~~~~~~~~~~~~\n\n``python -m unittest``\n\nRun a test module\n~~~~~~~~~~~~~~~~~\n\n``python -m unittest tests.test_servers``\n\nRun a single test case\n~~~~~~~~~~~~~~~~~~~~~~\n\n``python -m unittest tests.test_servers.ServerSSLTestCase``\n\nRun a single test method\n~~~~~~~~~~~~~~~~~~~~~~~~\n\n``python -m unittest tests.test_servers.ServerSSLTestCase.test_ssl_auth``\n\nRun a single test example for debugging with verbose and immediate stdout output\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n``python -m unittest -v tests.test_servers.ServerSSLTestCase``\n\nChangelog\n---------\n\nChanges in Version 0.8.0 (2023-05-16)\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n- Add ``mongo-launch`` CLI tool.\n- Upgrade to PyMongo 4.x and set up GitHub Actions testing.\n- Remove support for managing MongoDB 3.4 or earlier servers.\n- Remove support for Python 3.5 or earlier.\n- Replaced dependency on CherryPy with cheroot. `-s auto` is the new default\n  and `-s cherrypy` is no longer supported.\n- Remove transactionLifetimeLimitSeconds default.\n\nChanges in Version 0.7.0 (2021-04-06)\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n- Remove support for managing MongoDB 2.4 servers.\n- Add support for Python 3.8 and 3.9.\n- Add support for MongoDB 4.2 and 4.4.\n- Upgrade from pymongo 3.5.1 to 3.X latest. (#284).\n- Ensure createUser succeeds on all replica set members. (#282)\n- Create admin user with both SCRAM-SHA-256 and SCRAM-SHA-1. (#281)\n- Wait for mongo-orchestration server to fully terminate in \"stop\". (#276)\n- Allow starting clusters with enableTestCommands=0. (#269)\n- Decrease transactionLifetimeLimitSeconds on 4.2+ by default. (#267)\n- Increase maxTransactionLockRequestTimeoutMillis by default. (#270)\n- Reduce periodicNoopIntervalSecs for faster driver change stream testing. (#283)\n- Enable ztsd compression by default on 4.2+ (#263)\n\nChanges in Version 0.6.12 (2018-12-14)\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n- Allow running the mongo-orchestration server over IPv6 localhost. (#237)\n- Increase default mongodb server logging verbosity. (#255)\n- Fixed a bug when shutting down clusters where mongo-orchestration would\n  hang forever if the server had already exited. (#253)\n",
    "bugtrack_url": null,
    "license": "http://www.apache.org/licenses/LICENSE-2.0.html",
    "summary": "Restful service for managing MongoDB servers",
    "version": "0.8.0",
    "project_urls": {
        "Homepage": "https://github.com/10gen/mongo-orchestration"
    },
    "split_keywords": [
        "mongo-orchestration",
        "mongodb",
        "mongo",
        "rest",
        "testing"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "46e51b4f8523f517174b16c9adadf84cb4e3ac1fe93d31ef7771d2d994945d6f",
                "md5": "08c7a54ce6530244071069f9819b10f1",
                "sha256": "8c8fc3208fde6bbfc445477c572080aecd92cd3660461d2459b2d01e7541e67e"
            },
            "downloads": -1,
            "filename": "mongo_orchestration-0.8.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "08c7a54ce6530244071069f9819b10f1",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.6",
            "size": 74605,
            "upload_time": "2023-05-18T15:37:51",
            "upload_time_iso_8601": "2023-05-18T15:37:51.402274Z",
            "url": "https://files.pythonhosted.org/packages/46/e5/1b4f8523f517174b16c9adadf84cb4e3ac1fe93d31ef7771d2d994945d6f/mongo_orchestration-0.8.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "80bc46ec328dcb9abcc8e9956c02378bfd4bfb053cb94fcf40b62b75f900d147",
                "md5": "0d524aad69bd559f2c75c1060a67225e",
                "sha256": "9cb17a4f1a19d578a04c34ef51f4d5bc2a1c768f4968948792f330644c9398f6"
            },
            "downloads": -1,
            "filename": "mongo-orchestration-0.8.0.tar.gz",
            "has_sig": false,
            "md5_digest": "0d524aad69bd559f2c75c1060a67225e",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.6",
            "size": 72465,
            "upload_time": "2023-05-18T15:37:54",
            "upload_time_iso_8601": "2023-05-18T15:37:54.942595Z",
            "url": "https://files.pythonhosted.org/packages/80/bc/46ec328dcb9abcc8e9956c02378bfd4bfb053cb94fcf40b62b75f900d147/mongo-orchestration-0.8.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-05-18 15:37:54",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "10gen",
    "github_project": "mongo-orchestration",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "mongo-orchestration"
}
        
Elapsed time: 0.07008s