You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by va...@apache.org on 2019/04/02 15:57:44 UTC
[couchdb-documentation] branch reshard-docs created (now 531e2d6)
This is an automated email from the ASF dual-hosted git repository.
vatamane pushed a change to branch reshard-docs
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git.
at 531e2d6 Add _reshard HTTP API reference documentation
This branch includes the following new commits:
new 531e2d6 Add _reshard HTTP API reference documentation
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
[couchdb-documentation] 01/01: Add _reshard HTTP API reference
documentation
Posted by va...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
vatamane pushed a commit to branch reshard-docs
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git
commit 531e2d638b11d1cb27774c313d3f13fd39335653
Author: Nick Vatamaniuc <va...@apache.org>
AuthorDate: Tue Apr 2 11:56:41 2019 -0400
Add _reshard HTTP API reference documentation
Related to the main PR: https://github.com/apache/couchdb/pull/1972
---
src/api/server/common.rst | 485 ++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 485 insertions(+)
diff --git a/src/api/server/common.rst b/src/api/server/common.rst
index 752c522..1cdc787 100644
--- a/src/api/server/common.rst
+++ b/src/api/server/common.rst
@@ -1675,3 +1675,488 @@ You can verify the change by obtaining a list of UUIDs:
:>header Content-Type: :mimetype:`image/x-icon`
:code 200: Request completed successfully
:code 404: The requested content could not be found
+
+.. _api/server/_reshard:
+
+=============
+``/_reshard``
+=============
+
+.. versionadded:: 2.4
+
+.. http:get:: /_reshard
+ :synopsis: Retrieve summary information about resharding on the cluster
+
+ Returns a count of completed, failed, running, stopped, and total jobs
+ along with the state of resharding on the cluster.
+
+ :<header Accept: - :mimetype:`application/json`
+ :>header Content-Type: - :mimetype:`application/json`
+
+ :>json string state: ``stopped`` or ``running``
+ :>json string state_reason: ``null`` or string describing additional
+ information or reason associated with the state
+ :>json number completed: Count of completed resharding jobs
+ :>json number failed: Count of failed resharding jobs
+ :>json number running: Count of running resharding jobs
+ :>json number stopped: Count of stopped resharding jobs
+ :>json number total: Total count of resharding jobs
+
+ :code 200: Request completed successfully
+ :code 401: CouchDB Server Administrator privileges required
+
+ **Request**:
+
+ .. code-block:: http
+
+ GET /_reshard HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "completed": 21,
+ "failed": 0,
+ "running": 3,
+ "state": "running",
+ "state_reason": null,
+ "stopped": 0,
+ "total": 24
+ }
+
+.. http:get:: /_reshard/state
+ :synopsis: Retrieve the state of resharding on the cluster
+
+ Returns the resharding state and optional information about the state.
+
+ :<header Accept: - :mimetype:`application/json`
+ :>header Content-Type: - :mimetype:`application/json`
+
+ :>json string state: ``stopped`` or ``running``
+ :>json string state_reason: Additional information or reason associated
+ with the state
+
+ :code 200: Request completed successfully
+ :code 401: CouchDB Server Administrator privileges required
+
+ **Request**:
+
+ .. code-block:: http
+
+ GET /_reshard/state HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "reason": null,
+ "state": "running"
+ }
+
+.. http:put:: /_reshard/state
+ :synopsis: Change resharding state on the cluster
+
+ Change the resharding state on the cluster. The states are
+ ``stopped`` or ``running``. This starts and stops global resharding on all
+ the nodes of the cluster. If there are any running jobs, they
+ will be stopped when the state changes to ``stopped``. When the state
+ changes back to ``running`` those job will continue running.
+
+ :<header Accept: - :mimetype:`application/json`
+ :>header Content-Type: - :mimetype:`application/json`
+
+ :<json string state: ``stopped`` or ``running``
+ :<json string state_reason: Optional string describing additional
+ information or reason associated with the state
+
+ :>json boolean ok: ``true``
+
+ :code 200: Request completed successfully
+ :code 401: CouchDB Server Administrator privileges required
+
+ **Request**:
+
+ .. code-block:: http
+
+ PUT /_reshard/state HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+
+ {
+ "state": "stopped",
+ "reason": "Rebalancing in progress"
+ }
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "ok": true
+ }
+
+.. http:get:: /_reshard/jobs
+ :synopsis: Retrieve information about all the resharding jobs on the cluster
+
+ Get information about the resharding job identified by ``jobid``.
+
+ .. note:: The shape of the response and the ``total_rows`` and ``offset``
+ field in particular are meant to be consistent with the
+ ``_scheduler/jobs`` endpoint.
+
+ :<header Accept: - :mimetype:`application/json`
+ :>header Content-Type: - :mimetype:`application/json`
+
+ :>json list jobs: Array of json objects, one for each resharding job. For
+ the fields of each job see the /_reshard/job/{jobid}
+ endpoint.
+ :>json number offset: Offset in the list of jobs object. Currently
+ hard-coded at ``0``.
+ :>json number total_rows: Total number of resharding jobs on the cluster.
+
+ :code 200: Request completed successfully
+ :code 401: CouchDB Server Administrator privileges required
+
+ **Request**:
+
+ .. code-block:: http
+
+ GET /_reshard/jobs HTTP/1.1
+ Accept: application/json
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "jobs": [
+ {
+ "history": [
+ {
+ "detail": null,
+ "timestamp": "2019-03-28T15:28:02Z",
+ "type": "new"
+ },
+ {
+ "detail": "initial_copy",
+ "timestamp": "2019-03-28T15:28:02Z",
+ "type": "running"
+ },
+ ...
+ ],
+ "id": "001-171d1211418996ff47bd610b1d1257fc4ca2628868def4a05e63e8f8fe50694a",
+ "job_state": "completed",
+ "node": "node1@127.0.0.1",
+ "source": "shards/00000000-1fffffff/d1.1553786862",
+ "split_state": "completed",
+ "start_time": "2019-03-28T15:28:02Z",
+ "state_info": {},
+ "target": [
+ "shards/00000000-0fffffff/d1.1553786862",
+ "shards/10000000-1fffffff/d1.1553786862"
+ ],
+ "type": "split",
+ "update_time": "2019-03-28T15:28:08Z"
+ },
+ ...
+ ],
+ "offset": 0,
+ "total_rows": 24
+ }
+
+.. http:get:: /_reshard/jobs/{jobid}
+ :synopsis: Retrieve information about a particular resharding job
+
+ Get information about the resharding job identified by ``jobid``.
+
+ :<header Accept: - :mimetype:`application/json`
+ :>header Content-Type: - :mimetype:`application/json`
+
+ :>json string id: Job ID.
+ :>json string type: Currently only ``split`` is implemented.
+ :>json string job_state: The running state of the job. Could be one of
+ ``new``, ``running``, ``stopped``, ``completed``
+ or ``failed``.
+ :>json string split_state: The state of shard splitting. The state specific
+ to ``split`` jobs and indicate how far the shard
+ splitting has progressed. This can be one of
+ ``new``, ``initial_copy``, ``topoff1``,
+ ``build_indices``, ``topoff2``,
+ ``copy_local_docs``, ``update_shardmap``,
+ ``wait_source_close``, ``topoff3``,
+ ``source_delete`` or ``completed``. The
+ progression will be linearly through those
+ states from ``new`` to ``completed``.
+ :>json object state_info: Optional additional info associated with the current state.
+ :>json string source: For ``split`` jobs this will be the source shard.
+ :>json list target: For ``split`` jobs this will be a list of two or more
+ target shards.
+ :>json string start_time: A timestamp when this job had started running.
+ :>json string update_time: A timestamp indicated when this job was last updated.
+ :>json list history: List of json object recording a job's state transition.
+
+ :code 200: Request completed successfully
+ :code 401: CouchDB Server Administrator privileges required
+
+ **Request**:
+
+ .. code-block:: http
+
+ GET /_reshard/jobs/001-171d1211418996ff47bd610b1d1257fc4ca2628868def4a05e63e8f8fe50694a HTTP/1.1
+ Accept: application/json
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+
+ "id": "001-171d1211418996ff47bd610b1d1257fc4ca2628868def4a05e63e8f8fe50694a",
+ "job_state": "completed",
+ "node": "node1@127.0.0.1",
+ "source": "shards/00000000-1fffffff/d1.1553786862",
+ "split_state": "completed",
+ "start_time": "2019-03-28T15:28:02Z",
+ "state_info": {},
+ "target": [
+ "shards/00000000-0fffffff/d1.1553786862",
+ "shards/10000000-1fffffff/d1.1553786862"
+ ],
+ "type": "split",
+ "update_time": "2019-03-28T15:28:08Z",
+ "history": [
+ {
+ "detail": null,
+ "timestamp": "2019-03-28T15:28:02Z",
+ "type": "new"
+ },
+ {
+ "detail": "initial_copy",
+ "timestamp": "2019-03-28T15:28:02Z",
+ "type": "running"
+ },
+ ...
+ ]
+ }
+
+.. http:post:: /_reshard/jobs/{jobid}
+ :synopsis: Create one or more resharding jobs
+
+ Create one or more resharding jobs. Depending what fields are specified in
+ the request, one or more resharding jobs will be created. The response is
+ a json array of results. Each result object represents a single resharding
+ job on a particular node, in a particular range. Some of the responses
+ could be successful and some could fail. Successful results will have the
+ ``"ok": true`` and an ``"id": {jobid}`` fields and values. A failed job
+ result object will have an ``"error": "{error_message}"`` field and value.
+
+ :<header Accept: - :mimetype:`application/json`
+ :>header Content-Type: - :mimetype:`application/json`
+
+ :<json string type: Type of job. Currently only ``"split"`` is accepted. As
+ only shard splitting is implemented.
+
+ :<json string db: Database to split. This is the database name at the
+ cluster level, not the shard name. This is mutually
+ exclusive with the ``"shard``" field.
+ :<json string node: Only split shards located on this node. This is an
+ optional parameter. The value should be one of the
+ nodes returned from the ``_membership`` endpoint
+ response.
+ :<json string range: Only split shards copies in the given range. The
+ range format is ``hhhhhhhh-hhhhhhhh`` where ``h`` is a
+ hexadecimal digit. This format is used since this is how the
+ ranges are represented in the file system. This is
+ parameter is optional and is mutually exclusive
+ with the ``"shard"`` field.
+ :<json string shard: Split a particular shard. The shard should be
+ specified as ``"shards/{range}/{db}.{suffix}"``. Where
+ ``range`` has the ``hhhhhhhh-hhhhhhhh`` format, ``db``
+ is the database name, and ``suffix`` is the shard
+ (timestamp) suffix.
+
+ :>json boolean ok: ``true`` if job created successfully. Indicates a job
+ was created successfully Mutually exclusive with
+ ``error`` field.
+
+ :<json string error: Error message if a job could be not be created.
+ Mutually exclusive with ``"ok"`` field.
+
+ :<json string shard: The source shard if the job is of type ``split``.
+
+ :<json string node: Cluster node where the job was created and is running.
+
+ :code 201: One or more jobs were successfully created
+ :code 404: Db, node, range or shard was not found
+ :code 401: CouchDB Server Administrator privileges required
+
+ **Request**:
+
+ .. code-block:: http
+
+ POST /_reshard/jobs HTTP/1.1
+ Accept: application/json
+ Content-Type: application/json
+
+ {
+ "db": "db3",
+ "range": "80000000-ffffffff",
+ "type": "split"
+ }
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 201 Created
+ Content-Type: application/json
+
+ [
+ {
+ "id": "001-30d7848a6feeb826d5e3ea5bb7773d672af226fd34fd84a8fb1ca736285df557",
+ "node": "node1@127.0.0.1",
+ "ok": true,
+ "shard": "shards/80000000-ffffffff/db3.1554148353"
+ },
+ {
+ "id": "001-c2d734360b4cb3ff8b3feaccb2d787bf81ce2e773489eddd985ddd01d9de8e01",
+ "node": "node2@127.0.0.1",
+ "ok": true,
+ "shard": "shards/80000000-ffffffff/db3.1554148353"
+ }
+ ]
+
+.. http:delete:: /_reshard/jobs/{jobid}
+ :synopsis: Remove a shard splitting job
+
+ If the job is running, stop the job and then remove it.
+
+ :>json boolean ok: ``true`` if job was removed successfully.
+
+ :code 200: The job was removed successfully
+ :code 404: The job was not found
+ :code 401: CouchDB Server Administrator privileges required
+
+ **Request**:
+
+ .. code-block:: http
+
+ DELETE /_reshard/jobs/001-171d1211418996ff47bd610b1d1257fc4ca2628868def4a05e63e8f8fe50694a HTTP/1.1
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "ok": true
+ }
+
+.. http:get:: /_reshard/jobs/{jobid}/state
+ :synopsis: Retrieve the state of a single resharding job
+
+ Returns the running state of a resharding job identified by ``jobid``.
+
+ :<header Accept: - :mimetype:`application/json`
+ :>header Content-Type: - :mimetype:`application/json`
+
+ :<json string state: One of ``new``, ``running``, ``stopped``,
+ ``completed`` or ``failed``.`stopped``,
+ ``running``
+ :<json string state_reason: Additional information associated with the
+ state
+
+ :code 200: Request completed successfully
+ :code 404: The job was not found
+ :code 401: CouchDB Server Administrator privileges required
+
+ **Request**:
+
+ .. code-block:: http
+
+ GET /_reshard/jobs/001-b3da04f969bbd682faaab5a6c373705cbcca23f732c386bb1a608cfbcfe9faff/state HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "reason": null,
+ "state": "running"
+ }
+
+.. http:put:: /_reshard/jobs/{jobid}/state
+ :synopsis: Change the state of a resharding job
+
+ Change the state of a particular resharding job identified by ``jobid``.
+ The state can be changed from ``stopped`` to ``running`` or from
+ ``running`` to ``stopped``. If an individual job is ``stopped`` via this
+ API it will stay ``stopped`` even after the global resharding state is
+ toggled from ``stopped`` to ``running``. If the job is already
+ ``completed`` its state will stay ``completed`` and will not be restarted
+ by this API endpoint.
+
+ :<header Accept: - :mimetype:`application/json`
+ :>header Content-Type: - :mimetype:`application/json`
+
+ :<json string state: ``stopped`` or ``running``
+ :<json string state_reason: Optional string describing additional
+ information or reason associated with the state
+
+ :>json boolean ok: ``true``
+
+ :code 200: Request completed successfully
+ :code 404: The job was not found
+ :code 401: CouchDB Server Administrator privileges required
+
+ **Request**:
+
+ .. code-block:: http
+
+ PUT /_reshard/state/001-b3da04f969bbd682faaab5a6c373705cbcca23f732c386bb1a608cfbcfe9faff/state HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+
+ {
+ "state": "stopped",
+ "reason": "Rebalancing in progress"
+ }
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "ok": true
+ }