diff --git a/source/core/sharded-cluster-components.txt b/source/core/sharded-cluster-components.txt index 04eed14d858..1b3af1146f0 100644 --- a/source/core/sharded-cluster-components.txt +++ b/source/core/sharded-cluster-components.txt @@ -19,8 +19,8 @@ Sharded Cluster Components A MongoDB :term:`sharded cluster` consists of the following components: * :doc:`shard `: Each shard contains a - subset of the sharded data. Each shard can be deployed as a :term:`replica - set`. + subset of the sharded data. As of MongoDB 3.6, shards must be deployed + as a :term:`replica set`. * :doc:`/core/sharded-cluster-query-router`: The ``mongos`` acts as a query router, providing an interface between client applications and the diff --git a/source/core/sharded-cluster-shards.txt b/source/core/sharded-cluster-shards.txt index b6458be8dce..0056198af27 100644 --- a/source/core/sharded-cluster-shards.txt +++ b/source/core/sharded-cluster-shards.txt @@ -14,8 +14,8 @@ A :term:`shard` contains a subset of sharded data for a :term:`sharded cluster`. Together, the cluster's shards hold the entire data set for the cluster. -Shards should be deployed as a :term:`replica set` to provide redundancy and -high availability. +As of MongoDB 3.6, shards must be deployed as a :term:`replica set` to +provide redundancy and high availability. Users, clients, or applications should only directly connect to a shard to perform local administrative and maintenance operations. diff --git a/source/includes/apiargs-dbcommand-addShard-field.yaml b/source/includes/apiargs-dbcommand-addShard-field.yaml index 11a1777db5d..66f36776c7e 100644 --- a/source/includes/apiargs-dbcommand-addShard-field.yaml +++ b/source/includes/apiargs-dbcommand-addShard-field.yaml @@ -1,8 +1,14 @@ arg_name: field description: | - The hostname and port of the :binary:`~bin.mongod` instance to be added - as a shard. To add a replica set as a shard, specify the name - of the replica set and the hostname and port of a member of the replica set. + The replica set name and hostname of at least one member of the + shard's replica set. Include the port number if the instance is + running on a non-standard port. All additional hostnames must be comma + separated and belong to the same replica set. For example: + + .. code-block:: sh + + /<:port>,<:port>, ... + interface: dbcommand name: addShard operation: addShard diff --git a/source/includes/apiargs-method-sh.addShard-param.yaml b/source/includes/apiargs-method-sh.addShard-param.yaml index 89fbc6aea2c..63b316dd833 100644 --- a/source/includes/apiargs-method-sh.addShard-param.yaml +++ b/source/includes/apiargs-method-sh.addShard-param.yaml @@ -1,9 +1,14 @@ arg_name: param description: | - The hostname of either a standalone database instance or of a replica - set. Include the port number if the instance is running on a - non-standard port. Include the replica set name if the instance is a - replica set, as explained below. + The replica set name and hostname of at least one member of the + shard's replica set. Include the port number if the instance is + running on a non-standard port. All additional hostnames must be comma + separated and belong to the same replica set. For example: + + .. code-block:: sh + + /<:port>,<:port>, ... + interface: method name: host operation: sh.addShard diff --git a/source/includes/fact-bind-ip-sharded-clusters.rst b/source/includes/fact-bind-ip-sharded-clusters.rst new file mode 100644 index 00000000000..cc9c664b589 --- /dev/null +++ b/source/includes/fact-bind-ip-sharded-clusters.rst @@ -0,0 +1,9 @@ +.. note:: + + The :option:`--bind_ip ` option must be specified when + the sharded cluster members are run on different hosts or if + remote clients connect to the sharded cluster. If you are + deploying the entire sharded cluster on a single host and + do not require external client connections, you can omit the + :option:`--bind_ip ` option. For more information, see + :ref:`3.6-bind_ip-compatibility`. \ No newline at end of file diff --git a/source/includes/options-conf.yaml b/source/includes/options-conf.yaml index 706d944a774..9f23f181835 100644 --- a/source/includes/options-conf.yaml +++ b/source/includes/options-conf.yaml @@ -1379,6 +1379,13 @@ description: | - Start this instance as a :term:`shard`. The instance starts on port ``27018`` by default. post: | + .. note:: + + Setting ``sharding.clusterRole`` requires the :binary:`~bin.mongod` + instance to be running with replication. To deploy the instance as + a replica set member, use the :setting:`~replication.replSetName` + setting and specify the name of the replica set to join. + The {{role}} setting is available only for :binary:`~bin.mongod`. --- program: conf diff --git a/source/includes/options-mongod.yaml b/source/includes/options-mongod.yaml index 62570a3a149..0397e0ce9cd 100644 --- a/source/includes/options-mongod.yaml +++ b/source/includes/options-mongod.yaml @@ -1140,6 +1140,21 @@ description: | Configures this {{program}} instance as a shard in a sharded cluster. The default port for these instances is ``27018``. + + .. important:: + + .. versionchanged:: 3.6 + + You must deploy shards as replica sets with the :option:`--replSet` + option or :setting:`~replication.replSetName` setting + specified. To deploy sharded clusters with shard replica + sets, follow the appropriate tutorial depending on your + :ref:`sharding strategy`: + + - :doc:`/tutorial/deploy-sharded-cluster-hashed-sharding` + + - :doc:`/tutorial/deploy-sharded-cluster-ranged-sharding` + optional: false --- program: mongod diff --git a/source/includes/steps-3.6-upgrade-sharded-cluster.yaml b/source/includes/steps-3.6-upgrade-sharded-cluster.yaml index e09501e4799..308f1e58ec0 100644 --- a/source/includes/steps-3.6-upgrade-sharded-cluster.yaml +++ b/source/includes/steps-3.6-upgrade-sharded-cluster.yaml @@ -38,38 +38,38 @@ title: "Upgrade the config servers." level: 4 ref: 3.6-upgrade-config-servers content: |- - If the config servers are replica sets: - 1. Upgrade the :ref:`secondary ` members of the replica set one at a time: a. Shut down the secondary :binary:`~bin.mongod` instance and replace the |oldversion| binary with the |newversion| binary. - #. Start the |newversion| binary with both the ``--configsvr``, - ``--port`` options, - - If the sharded cluster members are run on different hosts or - if you wish remote clients to connect to the sharded cluster, - you must also specify ``--bind_ip`` (or the - :setting:`net.bindIp` setting). For more information, see - :ref:`3.6-bind_ip-compatibility`. + #. Start the |newversion| binary with the :option:`--configsvr `, + :option:`--replSet `, :option:`--port `, and :option:`--bind_ip ` + options. Include any optional command line options used by the + previous deployment: + .. cssclass:: copyable-code .. code-block:: sh - mongod --configsvr --port --dbpath --bind_ip localhost, + mongod --configsvr --replSet --port --dbpath --bind_ip localhost, + + .. include:: /includes/fact-bind-ip-sharded-clusters.rst If using a :doc:`configuration file `, update the file to specify :setting:`sharding.clusterRole: configsvr - ` and :setting:`net.port` (and - :setting:`net.bindIp` setting if needed) and start the - |newversion| binary: + `, :setting:`replication.replSetName`, + :setting:`net.port`, and :setting:`net.bindIp`, + then start the |newversion| binary: + .. cssclass:: copyable-code .. code-block:: yaml sharding: clusterRole: configsvr + replication: + replSetName: net: port: bindIp: localhost, @@ -90,6 +90,7 @@ content: |- :method:`rs.stepDown()` to step down the primary and force an election of a new primary: + .. cssclass:: copyable-code .. code-block:: javascript rs.stepDown() @@ -99,31 +100,32 @@ content: |- the stepped-down primary and replace the :binary:`~bin.mongod` binary with the |newversion| binary. - #. Start the |newversion| binary with both the ``--configsvr`` and - ``--port`` options: - - If the sharded cluster members are run on different hosts or - if you wish remote clients to connect to the sharded cluster, - you must also specify ``--bind_ip`` (or the - :setting:`net.bindIp` setting). For more information, see - :ref:`3.6-bind_ip-compatibility`. + #. Start the |newversion| binary with the :option:`--configsvr `, + :option:`--replSet `, :option:`--port `, and :option:`--bind_ip ` + options. Include any optional command line options used by the + previous deployment: + .. cssclass:: copyable-code .. code-block:: sh - mongod --configsvr --port --dbpath --bind_ip localhost, + mongod --configsvr --replSet --port --dbpath --bind_ip localhost, + .. include:: /includes/fact-bind-ip-sharded-clusters.rst If using a :doc:`configuration file `, update the file to specify :setting:`sharding.clusterRole: configsvr - ` and :setting:`net.port` (and - :setting:`net.bindIp` setting if needed), and start the - |newversion| binary: + `, :setting:`replication.replSetName`, + :setting:`net.port`, and :setting:`net.bindIp`, + then start the |newversion| binary: + .. cssclass:: copyable-code .. code-block:: yaml sharding: clusterRole: configsvr + replication: + replSetName: net: port: bindIp: localhost, @@ -136,7 +138,11 @@ title: Upgrade the shards. level: 4 ref: 3.6-upgrade-shards content: |- - Upgrade the shards one at a time. If the shards are replica sets, for each shard: + Upgrade the shards one at a time. If you are running standalone + shards, first convert them to a + :doc:`replica set`. + + For each shard: 1. Upgrade the :ref:`secondary ` members of the replica set one at a time: @@ -144,29 +150,31 @@ content: |- a. Shut down the :binary:`~bin.mongod` instance and replace the |oldversion| binary with the |newversion| binary. - #. Start the |newversion| binary with the ``--shardsvr`` and - ``--port`` command line options. - - If the sharded cluster members are run on different hosts or - if you wish remote clients to connect to the sharded cluster, - you must also specify ``--bind_ip`` (or the - :setting:`net.bindIp` setting). For more information, see - :ref:`3.6-bind_ip-compatibility`. + #. Start the |newversion| binary with the :option:`--shardsvr `, + :option:`--replSet `, :option:`--port `, and :option:`--bind_ip ` + options. Include any optional command line options used by the + previous deployment: + .. cssclass:: copyable-code .. code-block:: sh - mongod --shardsvr --port --dbpath --bind_ip localhost, + mongod --shardsvr --replSet --port --dbpath --bind_ip localhost, + + .. include:: /includes/fact-bind-ip-sharded-clusters.rst - Of if using a :doc:`configuration file + If using a :doc:`configuration file `, update the file to - include :setting:`sharding.clusterRole: shardsvr - ` and :setting:`net.port` (and - :setting:`net.bindIp` setting if needed) and start: + include :setting:`sharding.clusterRole: shardsvr `, + :setting:`replication.replSetName`, :setting:`net.port`, and + :setting:`net.bindIp`, then start the |newversion| binary: + .. cssclass:: copyable-code .. code-block:: yaml sharding: clusterRole: shardsvr + replication: + replSetName: net: port: bindIp: localhost, @@ -188,6 +196,7 @@ content: |- :method:`rs.stepDown()` to step down the primary and force an election of a new primary: + .. cssclass:: copyable-code .. code-block:: javascript rs.stepDown() @@ -199,30 +208,32 @@ content: |- 1. Shut down the stepped-down primary and replace the :binary:`~bin.mongod` binary with the |newversion| binary. - #. Start the |newversion| binary with the ``--shardsvr`` and - ``--port`` command line options. - - If the sharded cluster members are run on different hosts or - if you wish remote clients to connect to the sharded cluster, - you must also specify ``--bind_ip`` (or the - :setting:`net.bindIp` setting). For more information, see - :ref:`3.6-bind_ip-compatibility`. + #. Start the |newversion| binary with the :option:`--shardsvr `, + :option:`--replSet `, :option:`--port `, and :option:`--bind_ip ` + options. Include any optional command line options used by the + previous deployment: + .. cssclass:: copyable-code .. code-block:: sh - mongod --shardsvr --port --dbpath --bind_ip localhost, + mongod --shardsvr --replSet --port --dbpath --bind_ip localhost, - Of if using a :doc:`configuration file + .. include:: /includes/fact-bind-ip-sharded-clusters.rst + + If using a :doc:`configuration file `, update the file to specify :setting:`sharding.clusterRole: shardsvr - ` and :setting:`net.port` (and - :setting:`net.bindIp` setting if needed) and start the + `, :setting:`replication.replSetName`, + :setting:`net.port`, and :setting:`net.bindIp`, then start the |newversion| binary: + .. cssclass:: copyable-code .. code-block:: yaml sharding: clusterRole: shardsvr + replication: + replSetName: net: port: bindIp: localhost, @@ -245,6 +256,7 @@ content: |- :setting:`net.bindIp` setting). For more information, see :ref:`3.6-bind_ip-compatibility`. + .. cssclass:: copyable-code .. code-block:: sh mongos --configdb csReplSet/,, --bind_ip localhost, @@ -259,7 +271,6 @@ content: |- :method:`sh.setBalancerState()` to re-enable the balancer: .. cssclass:: copyable-code - .. code-block:: javascript sh.setBalancerState(true) @@ -286,9 +297,11 @@ action: On a :binary:`~bin.mongos` instance, run the :dbcommand:`setFeatureCompatibilityVersion` command in the ``admin`` database: + copyable: true language: javascript code: | db.adminCommand( { setFeatureCompatibilityVersion: "3.6" } ) + post: | This command must perform writes to an internal system collection. If for any reason the command does not complete diff --git a/source/includes/steps-deploy-sharded-cluster-shard-replica.yaml b/source/includes/steps-deploy-sharded-cluster-shard-replica.yaml index 26863f45fec..abaf5ff359f 100644 --- a/source/includes/steps-deploy-sharded-cluster-shard-replica.yaml +++ b/source/includes/steps-deploy-sharded-cluster-shard-replica.yaml @@ -44,7 +44,7 @@ action: following example: language: sh code: | - mongod --keyFile --shardsvr --replSet --dbpath + mongod --keyFile --shardsvr --replSet --dbpath post: | .. include:: /includes/extracts/default-bind-ip-security-additional-command-line.rst --- diff --git a/source/reference/command/addShard.txt b/source/reference/command/addShard.txt index a339b98ea60..689037f8901 100644 --- a/source/reference/command/addShard.txt +++ b/source/reference/command/addShard.txt @@ -15,19 +15,11 @@ Definition .. dbcommand:: addShard - Adds either a database instance or a :term:`replica set` to a - :term:`sharded cluster`. The optimal configuration is to deploy - shards across replica sets. + Adds a :term:`replica set` to a :term:`sharded cluster`. Run :dbcommand:`addShard` when connected to a :binary:`~bin.mongos` - instance. The command takes the following form when adding a single - database instance as a shard: - - .. code-block:: javascript - - { addShard: "<:port>", maxSize: , name: "" } - - When adding a replica set as a shard, use the following form: + instance. The command takes the following form when adding a replica + set as a shard: .. code-block:: javascript @@ -66,25 +58,15 @@ Hidden Members Examples -------- -The following command adds the database instance running on -port ``27027`` on the host ``mongodb0.example.net`` as a shard: +The following command adds a replica set as a shard: .. code-block:: javascript - db.adminCommand({addShard: "mongodb0.example.net:27027"}) + use admin + db.runCommand( { addShard: "repl0/mongodb3.example.net:27327"} ) .. warning:: Do not use ``localhost`` for the hostname unless your :term:`configuration server ` is also running on ``localhost``. - -The following command adds a replica set as a shard: - -.. code-block:: javascript - - use admin - db.runCommand( { addShard: "repl0/mongodb3.example.net:27327"} ) - -You may specify all members in the replica set. All additional -hostnames must be members of the same replica set. diff --git a/source/reference/method/sh.addShard.txt b/source/reference/method/sh.addShard.txt index f613107c272..28d81ca4ec9 100644 --- a/source/reference/method/sh.addShard.txt +++ b/source/reference/method/sh.addShard.txt @@ -15,10 +15,8 @@ Definition .. method:: sh.addShard(host) - Adds a database instance or replica set to a :term:`sharded cluster`. - The optimal configuration is to deploy shards across :term:`replica - sets `. This method must be run on a :binary:`~bin.mongos` - instance. + Adds a :term:`replica set` to a :term:`sharded cluster`. This method + must be run on a :binary:`~bin.mongos` instance. The :method:`sh.addShard()` method has the following parameter: @@ -28,17 +26,7 @@ Definition .. code-block:: javascript - sh.addShard("") - - The ``host`` parameter can be in any - of the following forms: - - .. code-block:: none - - [hostname] - [hostname]:[port] - [replica-set-name]/[hostname] - [replica-set-name]/[hostname]:port + sh.addShard("/<:port>") .. warning:: @@ -71,7 +59,7 @@ Hidden Members Example ------- -To add a shard on a replica set, specify the name of the replica set and +To add a shard, specify the name of the replica set and the hostname of at least one member of the replica set, as a seed. If you specify additional hostnames, all must be members of the same replica set. diff --git a/source/release-notes/3.6-upgrade-sharded-cluster.txt b/source/release-notes/3.6-upgrade-sharded-cluster.txt index 4b56d329472..d8e695772cb 100644 --- a/source/release-notes/3.6-upgrade-sharded-cluster.txt +++ b/source/release-notes/3.6-upgrade-sharded-cluster.txt @@ -40,6 +40,14 @@ clients to connect to your sharded cluster. For more information, see :ref:`3.6-bind_ip-compatibility` +Shard Servers Require Replication +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Starting in MongoDB 3.6, :binary:`~bin.mongod` instances with the shard +server role must be replica set members. The following procedure uses +the :option:`--replSet ` option to deploy the instance as a member of the +specified replica set. + Prerequisites ------------- diff --git a/source/release-notes/3.6.txt b/source/release-notes/3.6.txt index 05f61d10ad1..b52f69b3b98 100644 --- a/source/release-notes/3.6.txt +++ b/source/release-notes/3.6.txt @@ -571,6 +571,9 @@ Sharded Clusters - The ``config.system.sessions`` collection in the ``config`` database may now be sharded. +- To upgrade your sharded cluster to version 3.6, the shard servers must + be running as a replica set. + General Enhancements -------------------- diff --git a/source/tutorial/deploy-sharded-cluster-hashed-sharding.txt b/source/tutorial/deploy-sharded-cluster-hashed-sharding.txt index 9d1af2e49ae..0c5ec43369f 100644 --- a/source/tutorial/deploy-sharded-cluster-hashed-sharding.txt +++ b/source/tutorial/deploy-sharded-cluster-hashed-sharding.txt @@ -147,13 +147,7 @@ Add Shards to the Cluster ~~~~~~~~~~~~~~~~~~~~~~~~~ In the :binary:`~bin.mongo` shell connected to the :binary:`~bin.mongos`, use -the :method:`sh.addShard()` method to add each shard to the cluster. If -the shard is a replica set, specify the name of the replica set and -specify a member of the set. - -.. tip:: - - In production deployments, *all* shards should be replica sets. +the :method:`sh.addShard()` method to add each shard to the cluster. The following operation adds a single shard replica set to the cluster: @@ -163,15 +157,6 @@ The following operation adds a single shard replica set to the cluster: Repeat to add all shards. -If in a development environment, the shard is a standalone -:binary:`~bin.mongod` instance, specify the instance's hostname and port. -The following operation is an example of adding a standalone -:binary:`~bin.mongod` shard to the cluster: - -.. code-block:: javascript - - sh.addShard( "s1-mongo1.example.net:27018") - .. _deploy-hashed-sharded-cluster-shard-database: Enable Sharding for a Database diff --git a/source/tutorial/deploy-sharded-cluster-ranged-sharding.txt b/source/tutorial/deploy-sharded-cluster-ranged-sharding.txt index 76ae2761ea3..1d2fee5bda9 100644 --- a/source/tutorial/deploy-sharded-cluster-ranged-sharding.txt +++ b/source/tutorial/deploy-sharded-cluster-ranged-sharding.txt @@ -141,13 +141,7 @@ Add Shards to the Cluster ~~~~~~~~~~~~~~~~~~~~~~~~~ In the :binary:`~bin.mongo` shell connected to the :binary:`~bin.mongos`, use -the :method:`sh.addShard()` method to add each shard to the cluster. If -the shard is a replica set, specify the name of the replica set and -specify a member of the set. - -.. tip:: - - In production deployments, *all* shards should be replica sets. +the :method:`sh.addShard()` method to add each shard to the cluster. The following operation adds a single shard replica set to the cluster: @@ -157,15 +151,6 @@ The following operation adds a single shard replica set to the cluster: Repeat to add all shards. -If in a development environment, the shard is a standalone -:binary:`~bin.mongod` instance, specify the instance's hostname and port. -The following operation is an example of adding a standalone -:binary:`~bin.mongod` shard to the cluster: - -.. code-block:: javascript - - sh.addShard( "s1-mongo1.example.net:27018") - .. _deploy-ranged-sharded-cluster-shard-database: Enable Sharding for a Database