diff --git a/source/tutorial/add-shards-to-shard-cluster.txt b/source/tutorial/add-shards-to-shard-cluster.txt index c92b54e4e85..1df17896f7d 100644 --- a/source/tutorial/add-shards-to-shard-cluster.txt +++ b/source/tutorial/add-shards-to-shard-cluster.txt @@ -7,11 +7,10 @@ Add Shards to an Existing Cluster Synopsis -------- -This document outlines the procedure for adding a :term:`shard` to an -existing :term:`shard cluster`. If you have a shard cluster as your -data set grows, you will add additional shards. See the -":doc:`/administration/sharding`" document for additional sharding -procedures. +This document describes how to add a :term:`shard` to an +existing :term:`shard cluster`. If you have a shard cluster, then as your +data set grows you will add additional shards. For additional sharding +procedures, see :doc:`/administration/sharding`. Concerns -------- @@ -19,26 +18,26 @@ Concerns Distributing :term:`chunks ` among your cluster requires some capacity to support the migration process. When adding a shard to your cluster, you should always ensure that your cluster has enough -capacity to support the migration without impacting legitimate +capacity to support the migration without affecting legitimate production traffic. In production environments, all shards should be :term:`replica sets `. Furthermore, *all* interaction with your sharded -cluster should pass through a :program:`mongos` instance, and this +cluster should pass through a :program:`mongos` instance. This tutorial assumes that you already have a :program:`mongo` shell connection to a :program:`mongos` instance. Process ------- -First, you need to tell the cluster where to find the individual +Tell the cluster where to find the individual shards. You can do this using the :dbcommand:`addShard` command: .. code-block:: javascript db.runCommand( { addShard: mongodb0.example.net, name: "mongodb0" } ) -More practically you will use the :func:`sh.addShard()` helper: +Optionally you can use the :func:`sh.addShard()` helper: .. code-block:: javascript @@ -64,14 +63,14 @@ For example: replicaSetName/,, - For example, if the name of the replica set is "``repl0``", then + For example, if the name of the replica set is ``repl0``, then your :func:`sh.addShard` command would be: .. code-block:: javascript sh.addShard( "repl0/mongodb0.example.net:27027,mongodb1.example.net:27017,mongodb2.example.net:27017" ) -Repeat this step for each shards in your cluster. +Repeat this step for each shard in your cluster. .. optional:: @@ -83,16 +82,18 @@ Repeat this step for each shards in your cluster. db.runCommand( { addShard: mongodb0.example.net, name: "mongodb0" } ) sh.addShard( mongodb0.example.net, name: "mongodb0" ) - If you do not specify a shard name, then MongoDB will assign a + If you do not specify a shard name, then MongoDB assigns a name upon creation. .. note:: It may take some time for :term:`chunks ` to migrate to the new - shard, because the system must copy data from one :program:`mongod` + shard because the system must copy data from one :program:`mongod` instance to another while maintaining data consistency. - See the ":ref:`Balancing and Distribution `" - section for an overview of the balancing operation and the - ":ref:`Balancing Internals `" section - for additional information. + For an overview of the balancing operation, + see the :ref:`Balancing and Distribution ` + section. + + For additional information on balancing, see the + :ref:`Balancing Internals ` section. diff --git a/source/tutorial/deploy-shard-cluster.txt b/source/tutorial/deploy-shard-cluster.txt index 549f92febb7..b37f8a1d908 100644 --- a/source/tutorial/deploy-shard-cluster.txt +++ b/source/tutorial/deploy-shard-cluster.txt @@ -7,26 +7,24 @@ Deploy a Shard Cluster Synopsis -------- -This document outlines the full procedure for deploying a -:term:`shard cluster` in MongoDB. Use the -":doc:`/tutorial/convert-replica-set-to-replicated-shard-cluster`" -procedure if you have an existing replica set. If you have a -standalone :program:`mongod` instance you can use this tutorial to -deploy a shard cluster. +This document describes how to deploy a :term:`shard cluster` for a +standalone :program:`mongod` instance. + +To deploy a shard cluster for an existing replica set, see instead +:doc:`/tutorial/convert-replica-set-to-replicated-shard-cluster`. Requirements ------------ -See the ":ref:`Requirements for Shard Clusters -`" section for more information about potential -requirements for shard cluster. +Before deploying a shard cluster, see the requirements listed in +:ref:`Requirements for Shard Clusters `. .. warning:: Sharding and "localhost" Addresses - If you use either "localhost" or "``127.0.0.1``" as the hostname - portion of any host identifier, either the ``host`` argument to + If you use either "localhost" or ``127.0.0.1`` as the hostname + portion of any host identifier, for example as the ``host`` argument to :dbcommand:`addShard` or the value to the :option:`mongos --configdb` - run time option, then you must use "localhost" or "``127.0.0.1``" + run time option, then you must use "localhost" or ``127.0.0.1`` for *all* host settings. If you mix localhost addresses and remote host address, MongoDB will produce errors. @@ -40,97 +38,89 @@ Begin by configuring three config servers. These are very small :program:`mongod` instances that provide cluster metadata. You must have exactly *three* instances in production deployments. For redundancy these instances should run on different systems and -servers. +servers. It's important to separate config server :program:`mongod` +instances to provide redundancy and to ensure that cluster +metadata is secure and durable. + +Because the config server :program:`mongod` instances receive relatively +little traffic and demand only a small portion of system resources, you +can run the instances on systems that run other services, such as on +shards or on servers that run :program:`mongos`. -At a system prompt use the following command to start a config server: +To start a config server, type the following command at a system prompt: .. code-block:: sh mongod --configsvr -The :option:`--configsrv` stores config database in the `configdb/` -subdirectory of the :setting:`dbpath` directory, which is -``/data/db/`` by default. Additionally, a config server instance will -be accessible via port ``27019``. You may use other :doc:`mongod -runtime options ` in addition to -:setting:`configsvr` as needed. +The :option:`--configsrv` stores a config database in the `configdb/` +subdirectory of the :setting:`dbpath` directory. By default, the +:setting:`dbpath` directory is ``/data/db/``. The config server instance +is accessible via port ``27019``. In addition to :setting:`configsvr`, +use other :doc:`mongod runtime options ` +as needed. Repeat this process for all three config servers. -.. note:: - - It's important to separate config server :program:`mongod` - instances to provide redundancy and ensure that the cluster - metadata is secure and durable. Nevertheless, config - :program:`mongod` instances themselves do not demand a large number - of system resources and receive relatively little traffic. As a - result you may choose to run config server instances on a system - that also runs another service: on three of the shards, on a server - that has a :program:`mongos`, or another component of your - infrastructure. - Start ``mongos`` Instances ~~~~~~~~~~~~~~~~~~~~~~~~~~ -All operations against a shard cluster use a :program:`mongos` -instance to route queries and operations to the appropriate shards, -and to interact with the configdb instances. :program:`mongos` -instances are lightweight and a shard cluster can have many -:program:`mongos` instances: typically, you will run one -:program:`mongos` instance on each of your application servers. +All operations against a shard cluster go through the :program:`mongos` +instance. The :program:`mongos` instance routes queries and operations +to the appropriate shards and interacts with the configdb instances. + +:program:`mongos` instances are lightweight, and a shard cluster can +have multiple instances. Typically, you run one :program:`mongos` +instance on each of your application servers. + +You must specify three config servers. Use resolvable host names for +all hosts, using DNS or your system's hostfile to provide operational +flexibility. + +The :program:`mongos` instance runs on the default MongoDB port of ``27017``. Use the following command at a system prompt to start a -:program:`mongos`: +:program:`mongos` instance: .. code-block:: sh mongos --configdb config0.mongodb.example.net,config1.mongodb.example.net,config2.mongodb.example.net --port 27017 -This invocation assumes that you have config servers running on the -following hosts: +The above example assumes that you have config servers running on the following hosts: - ``config0.mongodb.example.net`` - ``config1.mongodb.example.net`` - ``config2.mongodb.example.net`` -The :program:`mongos` will run on the default MongoDB port of -``27017``. - -You must specify three config servers. Use resolvable host names for -all hosts, using DNS or your systems hostfile to provide operational -flexibility. - Add Shards to the Cluster ~~~~~~~~~~~~~~~~~~~~~~~~~ In a production shard cluster, each shard is itself a :term:`replica -set`. Deploy at least two replica sets, for use as shards. See -":doc:`/tutorial/deploy-replica-set`" for instructions regarding -replica set deployment. When you have two active and functioning -replica sets, continue below. +set`. You must deploy at least two replica sets for use as shards. For +instructions on deploying replica sets, see +:doc:`/tutorial/deploy-replica-set`. -Log into a :program:`mongos` using the :program:`mongo` shell. If the -:program:`mongos` is accessible at ``mongos0.mongodb.example.net`` on -port ``27017`` then this invocation would resemble: +When you have two active and functioning replica sets, perform the procedure here: + +Using the :program:`mongo` shell, log into a :program:`mongos`. For example, +if the :program:`mongos` is accessible at +``mongos0.mongodb.example.net`` on port ``27017`` you would type: .. code-block:: sh mongo mongos0.mongodb.example.net -Then, use the :func:`sh.addShard()` to add each shard to the cluster. +To add each shard to the cluster, Use :func:`sh.addShard()`. For +example, to add two shards with the hostnames ``shard0.example.net`` and +``shard1.example.net`` on port ``27017``, type:. sh.addShard( "shard0.example.net" ) sh.addShard( "shard1.example.net" ) -This will add two shards with the hostnames ``shard0.example.net`` and -``shard1.example.net`` on port ``27017``. - -.. note:: In production deployments, all shards should be replica sets. - .. versionchanged:: 2.0.3 After version 2.0.3, you may use the above form to add replica - sets to a cluster and the cluster will automatically discover + sets to a cluster. The cluster will automatically discover the members of the replica set and adjust its configuration accordingly. @@ -138,7 +128,7 @@ This will add two shards with the hostnames ``shard0.example.net`` and following form: the replica set name, followed by a forward slash, followed by a comma-separated list of seeds for the replica set. For example, if the name of the replica set is - "``repl0``", then your :func:`sh.addShard` command might resemble: + ``repl0``, then your :func:`sh.addShard` command might resemble: .. code-block:: javascript @@ -162,28 +152,26 @@ connected to a :program:`mongos` instance in your cluster: sh.enableSharding("records") -Where ``records`` is the name of the database that holds a collection -that you want to shard. :func:`sh.enableSharding()` is a wrapper +Where ``records`` is the name of the database that holds the collection +you want to shard. :func:`sh.enableSharding()` is a wrapper around the :dbcommand:`enableSharding` :term:`database command`. You -may enable sharding for as many databases as you like in your -deployment. +can enable sharding for multiple databases in your deployment. Enable Sharding for Collections ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Finally, you may enable sharding on a per-collection basis. Because +You can enable sharding on a per-collection basis. Because MongoDB uses "range based sharding," you must specify a :term:`shard -key` that MongoDB can use to distribute your documents among the -shards. See the section of this manual that provides an :ref:`overview -of shard keys ` as well as the section that -explores the :ref:`features of good shard keys in-depth -`. - -Enable sharding for a collection using the -:func:`sh.shardCollection()` helper in the :program:`mongo` shell, -which provides a wrapper around the :dbcommand:`shardCollection` -:term:`database command`. The shell helper has the following prototype -form: +key` MongoDB can use to distribute your documents among the +shards. For more information, see the sections of this manual that give +an :ref:`overview of shard keys ` and that +give an in-depth exploration of the +:ref:`features of good shard keys `. + +To enable sharding for a collection, use the +:func:`sh.shardCollection()` helper in the :program:`mongo` shell. +The helper provides a wrapper around the :dbcommand:`shardCollection` +:term:`database command` and has the following prototype form: .. code-block:: javascript @@ -240,6 +228,6 @@ In order, these operations shard: ``{ "hashed_id": 1 }``. This shard key distributes documents by the value of the - ``hashed_id`` field. Presumably this is a is a computed value that - holds the hash of some value in your documents, and will be able to + ``hashed_id`` field. Presumably this is a computed value that + holds the hash of some value in your documents and is able to evenly distribute documents throughout your cluster. diff --git a/source/tutorial/remove-shards-from-cluster.txt b/source/tutorial/remove-shards-from-cluster.txt index 91d9cb2a46d..6ef0e1513b2 100644 --- a/source/tutorial/remove-shards-from-cluster.txt +++ b/source/tutorial/remove-shards-from-cluster.txt @@ -7,17 +7,20 @@ Remove Shards from an Existing Shard Cluster Synopsis -------- -This document describes the process for safely migrating data from a +This document describes how to safely migrate data from a shard so that you may decommission the systems that provide for the -purpose of migration, or downsizing a cluster in response to actual -use. +purpose of migration, or downsizing a cluster in response to actual use. -This process is only required if you need to migrate all data from an +.. The above sentence doesn't make sense to me +.. from "the systems that provide..." onward. -BG + +This process is required only if you need to migrate all data from an existing shard cluster and decommission that cluster. *Do not* use this procedure to migrate an entire shard to new hardware. To migrate an entire shard to new hardware, migrate individual shards as if they were independent replica sets. + .. TODO do we have a document outlining this in more detail? .. DOCS-94 will lead to a tutorial about cluster migrations. In the @@ -33,7 +36,6 @@ This outlines the process for removing shards: - Remove the shard from the cluster's configuration. - Procedure --------- @@ -43,19 +45,18 @@ Complete this procedure by connecting to any :program:`mongos` in the cluster using the :program:`mongo` shell. You can only remove a shard by its shard name. To discover or -confirm the name of a shard using the :dbcommand:`listshards` or -:dbcommand:`printShardingStatus` commands or the :func:`sh.status()` -shell helper. +confirm the name of a shard, use the :dbcommand:`listshards` command, +:dbcommand:`printShardingStatus` command, or :func:`sh.status()` shell helper. -The following example will remove shard named ``mongodb0``. +The example commands in this document remove a shard named ``mongodb0``. .. note:: To successfully migrate data from a shard, the :term:`balancer` process **must** be active. Check the balancer state using the :func:`sh.getBalancerState()` helper in the :program:`mongo` - shell. See this section on :ref:`balancer operations - ` for more information. + shell. For more information, see the section on :ref:`balancer operations + `. Remove Chunks from the Shard @@ -68,46 +69,46 @@ begins "draining" chunks from the shard you are removing. db.runCommand( { removeshard: "mongodb0" } ) -This operation will return a response immediately. For example: +This operation returns an immediate response. For example: .. code-block:: javascript { msg : "draining started successfully" , state: "started" , shard :"mongodb0" , ok : 1 } Depending on your network capacity and the amount of data in your -cluster, this operation can take anywhere from a few minutes to +cluster, this operation can take from a few minutes to several days to complete. Check the Status of the Migration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can run the :dbcommand:`removeShard` again at any stage of the -process to check the progress of the migration, as follows: +To check the progress of the migration, +run :dbcommand:`removeShard` again at any stage of the +process, as follows: .. code-block:: javascript db.runCommand( { removeshard: "mongodb0" } ) -The output will resemble the following document: +The output resembles the following document: .. code-block:: javascript { msg: "draining ongoing" , state: "ongoing" , remaining: { chunks: 42, dbs : 1 }, ok: 1 } In the ``remaining`` sub document, a counter displays the remaining number -of chunks that MongoDB must migrate to other shards, and the number of +of chunks that MongoDB must migrate to other shards and the number of MongoDB databases that have "primary" status on this shard. Continue checking the status of the `removeshard` command until the -number of chunks remaining is 0, then you can proceed to the next -step. +number of chunks remaining is 0. Then proceed to the next step. Move Unsharded Databases ~~~~~~~~~~~~~~~~~~~~~~~~ -Databases with non-sharded collections store these collections on a -single shard, known as the "primary" shard for that database. The -following step is necessary only when the shard you want to remove is +Databases with non-sharded collections store the collections on a +single shard known as the "primary" shard for that database. The +following step is necessary only when the shard to remove is also the "primary" shard for one or more databases. Issue the following command at the :program:`mongo` shell: @@ -116,7 +117,7 @@ Issue the following command at the :program:`mongo` shell: db.runCommand( { movePrimary: "myapp", to: "mongodb1" }) -This command will migrate all remaining non-sharded data in the +This command migrates all remaining non-sharded data in the database named ``myapp`` to the shard named ``mongodb1``. .. warning:: @@ -142,11 +143,11 @@ information and finalize the removal, as follows: db.runCommand( { removeshard: "mongodb0" } ) -When successful, the response will be the following: +A success message appears at completion: .. code-block:: javascript { msg: "remove shard completed successfully" , stage: "completed", host: "mongodb0", ok : 1 } When the value of "state" is "completed", you may safely stop the -``mongodb0`` shard. +``mongodb0`` shard. \ No newline at end of file