diff --git a/source/administration/replica-sets.txt b/source/administration/replica-sets.txt index ae8d97bff39..b13208a4d72 100644 --- a/source/administration/replica-sets.txt +++ b/source/administration/replica-sets.txt @@ -38,6 +38,7 @@ specific administrative tasks related to replica set operation. /tutorial/configure-a-non-voting-replica-set-member /tutorial/configure-secondary-only-replica-set-member /tutorial/configure-replica-set-secondary-sync-target + /tutorial/configure-replica-set-tag-sets /tutorial/reconfigure-replica-set-with-unavailable-members .. seealso:: diff --git a/source/core/read-preference.txt b/source/core/read-preference.txt index 44883affd83..d69a54f9ccf 100644 --- a/source/core/read-preference.txt +++ b/source/core/read-preference.txt @@ -257,40 +257,6 @@ operations to specific members, based on custom parameters. - Write concerns ignore the value of a tag to when selecting a member *except* to consider whether or not the value is unique. -A tag set for a read operation may resemble the following document: - -.. code-block:: javascript - - { "disk": "ssd", "use": "reporting" } - -To fulfill the request, a member would need to have both of these tags. -Therefore the following tag sets, would satisfy this -requirement: - -.. code-block:: javascript - - { "disk": "ssd", "use": "reporting" } - { "disk": "ssd", "use": "reporting", "rack": 1 } - { "disk": "ssd", "use": "reporting", "rack": 4 } - { "disk": "ssd", "use": "reporting", "mem": "64"} - -However, the following tag sets would *not* be able to fulfill this query: - -.. code-block:: javascript - - { "disk": "ssd" } - { "use": "reporting" } - { "disk": "ssd", "use": "production" } - { "disk": "ssd", "use": "production", "rack": 3 } - { "disk": "spinning", "use": "reporting", "mem": "32" } - -Therefore, tag sets make it possible to ensure that read operations -target specific members in a particular data center or -:program:`mongod` instances designated for a particular class of -operations, such as reporting or analytics. -For information on configuring tag sets, see -:ref:`replica-set-configuration-tag-sets` in the -:doc:`/reference/replica-configuration` document. You can specify tag sets with the following read preference modes: - :readmode:`primaryPreferred` @@ -312,6 +278,9 @@ All interfaces use the same :ref:`member selection logic member to which to direct read operations, basing the choice on read preference mode and tag sets. +For information on configuring tag sets, see +:doc:`/tutorial/configure-replica-set-tag-sets`. + For more information on how read preference :ref:`modes ` interact with tag sets, see the documentation for each read preference mode. diff --git a/source/reference/replica-configuration.txt b/source/reference/replica-configuration.txt index d5ebc8b77b3..394f50a5bf2 100644 --- a/source/reference/replica-configuration.txt +++ b/source/reference/replica-configuration.txt @@ -7,7 +7,7 @@ Replica Set Configuration Synopsis -------- -This reference provides an overview of all possible replica set +This reference provides an overview of replica set configuration options and settings. Use :method:`rs.conf()` in the :program:`mongo` shell to retrieve this @@ -175,6 +175,9 @@ Configuration Variables :method:`db.getLastError()` (i.e. :dbcommand:`getLastError`.) + For procedures on configuring tag sets, see + :doc:`/tutorial/configure-replica-set-tag-sets`. + .. data:: local.system.replset.members[n].slaveDelay *Optional*. @@ -414,276 +417,3 @@ use the following form: disconnect. This is by design. While this typically takes 10-20 seconds, attempt to make these changes during scheduled maintenance periods. - -.. index:: replica set; tag sets -.. index:: read preference; tag sets -.. index:: tag sets; configuration -.. _replica-set-configuration-tag-sets: - -Tag Sets --------- - -Tag sets provide custom and configurable :term:`write concern` -and :term:`read preferences ` -for a :term:`replica set`. This section outlines the process -for specifying tags for a replica set, for more information see the -full documentation of the behavior of ref:`tags sets for write concern -` and :ref:`tag sets for read preference -`. - -.. important:: - - Custom read preferences and write concerns evaluate tags sets in - different ways. - - Read preferences consider the value of a tag when selecting a member - to read from. - - Write concerns do not utilize the value of a tag to select a - member except to consider whether or not the value is unique. - -Configure tag sets by adding fields and values to the document stored -in the :data:`~local.system.replset.members[n].tags`. Consider the -following examples: - -Configure Tag Sets -~~~~~~~~~~~~~~~~~~ - -Given the following replica set configuration: - -.. code-block:: javascript - - { - "_id" : "rs0", - "version" : 1, - "members" : [ - { - "_id" : 0, - "host" : "mongodb0.example.net:27017" - }, - { - "_id" : 1, - "host" : "mongodb1.example.net:27017" - }, - { - "_id" : 2, - "host" : "mongodb2.example.net:27017" - } - ] - } - -You could add the tag sets, to the members of this replica set, -with the following command sequence in the :program:`mongo` shell: - -.. code-block:: javascript - - conf = rs.conf() - conf.members[0].tags = { "dc": "east", "use": "production" } - conf.members[1].tags = { "dc": "east", "use": "reporting" } - conf.members[2].tags = { "use": "production" } - rs.reconfig(conf) - -After this operation the output of :method:`rs.conf()`, would -resemble the following: - -.. code-block:: javascript - - { - "_id" : "rs0", - "version" : 2, - "members" : [ - { - "_id" : 0, - "host" : "mongodb0.example.net:27017", - "tags" : { - "dc": "east", - "use": "production" - } - }, - { - "_id" : 1, - "host" : "mongodb1.example.net:27017", - "tags" : { - "dc": "east", - "use": "reporting" - } - }, - { - "_id" : 2, - "host" : "mongodb2.example.net:27017", - "tags" : { - "use": "production" - } - } - ] - } - - -Configure Tag Sets for Custom Multi-Data Center Write Concern Mode -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Given a five member replica set with members in two data centers: - -1. a facility ``VA`` tagged ``dc.va`` - -2. a facility ``GTO`` tagged ``dc.gto`` - -Create a custom write concern to require confirmation from two -data centers using replica set tags, using the following sequence -of operations in the :program:`mongo` shell: - -#. Create the replica set configuration object ``conf``: - - .. code-block:: javascript - - conf = rs.conf() - -#. Add tags to the replica set members reflecting their locations: - - .. code-block:: javascript - - conf.members[0].tags = { "dc.va": "rack1"} - conf.members[1].tags = { "dc.va": "rack2"} - conf.members[2].tags = { "dc.gto": "rack1"} - conf.members[3].tags = { "dc.gto": "rack2"} - conf.members[4].tags = { "dc.va": "rack1"} - rs.reconfig(conf) - -#. Create a custom - :data:`~local.system.replset.settings.getLastErrorModes` setting to - ensure that the write operation will propagate to at least one member - of each facility: - - .. code-block:: javascript - - conf.settings = { getLastErrorModes: { MultipleDC : { "dc.va": 1, "dc.gto": 1}} - -#. Reconfigure the replica set using the new ``conf`` configuration - object: - - .. code-block:: javascript - - rs.reconfig(conf) - -To ensure that a write operation propagators to at least one member of -the set in both facilities, then use the ``MultipleDC`` write concern -mode, as follows: - -.. code-block:: javascript - - db.runCommand( { getLastError: 1, w: "MultipleDC" } ) - -Alternatively, if you want to ensure that each write operation -propagates to at least 2 racks in each facility, reconfigure the -replica set as follows in the :program:`mongo` shell: - -#. Create the replica set configuration object ``conf``: - - .. code-block:: javascript - - conf = rs.conf() - -#. Redefine the - :data:`~local.system.replset.settings.getLastErrorModes` value to - require two different values of both ``dc.va`` and ``dc.gto``: - - .. code-block:: javascript - - conf.settings = { getLastErrorModes: { MultipleDC : { "dc.va": 2, "dc.gto": 2}} - -#. Reconfigure the replica set using the new ``conf`` configuration - object: - - .. code-block:: javascript - - rs.reconfig(conf) - -Now, the following write concern operation will only return after the -write operation propagates to at least two different racks in the -each facility: - -.. code-block:: javascript - - db.runCommand( { getLastError: 1, w: "MultipleDC" } ) - -Configure Tag Sets for Functional Segregation of Read and Write Operations -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Given a replica set with tag sets that reflect: - -- data center facility, - -- physical rack location of instance, and - -- storage system (i.e. disk) type. - -Where each member of the set has a tag set that resembles one of the -following: [#read-and-write-tags]_ - -.. code-block:: javascript - - {"dc.va": "rack1", disk:"ssd", ssd: "installed" } - {"dc.va": "rack2", disk:"raid"} - {"dc.gto": "rack1", disk:"ssd", ssd: "installed" } - {"dc.gto": "rack2", disk:"raid"} - {"dc.va": "rack1", disk:"ssd", ssd: "installed" } - -To target a read operation to a member of the replica set with an -disk type of ``ssd``, you could use the following tag set: - -.. code-block:: javascript - - { disk: "ssd" } - -However, to create comparable write concern modes, you would specify a -different set of -:data:`~local.system.replset.settings.getLastErrorModes` -configuration. Consider the following sequence of operations in -the :program:`mongo` shell: - -#. Create the replica set configuration object ``conf``: - - .. code-block:: javascript - - conf = rs.conf() - -#. Redefine the - :data:`~local.system.replset.settings.getLastErrorModes` value to - configure two write concern modes: - - .. code-block:: javascript - - conf.settings = { - "getLastErrorModes" : { - "ssd" : { - "ssd" : 1 - }, - "MultipleDC" : { - "dc.va" : 1, - "dc.gto" : 1 - } - } - } - -#. Reconfigure the replica set using the new ``conf`` configuration - object: - - .. code-block:: javascript - - rs.reconfig(conf) - -Now, you can specify the ``MultipleDC`` write concern mode, as in the -following operation, to ensure that a write operation propagates to -each data center. - -.. code-block:: javascript - - db.runCommand( { getLastError: 1, w: "MultipleDC" } ) - -Additionally, you can specify the ``ssd`` write concern mode, as in -the following operation, to ensure that a write operation propagates -to at least one instance with an SSD. - -.. [#read-and-write-tags] Since read preferences and write concerns - use the value of fields in tag sets differently, larger - deployments will have some redundancy. diff --git a/source/tutorial.txt b/source/tutorial.txt index 709a6035aea..408f9899439 100644 --- a/source/tutorial.txt +++ b/source/tutorial.txt @@ -53,6 +53,7 @@ Replica Sets - :doc:`/tutorial/configure-a-hidden-replica-set-member` - :doc:`/tutorial/configure-a-non-voting-replica-set-member` - :doc:`/tutorial/configure-secondary-only-replica-set-member` +- :doc:`/tutorial/configure-tag-sets` - :doc:`/tutorial/manage-chained-replication` - :doc:`/tutorial/reconfigure-replica-set-with-unavailable-members` - :doc:`/tutorial/recover-data-following-unexpected-shutdown` diff --git a/source/tutorial/configure-replica-set-tag-sets.txt b/source/tutorial/configure-replica-set-tag-sets.txt new file mode 100644 index 00000000000..5bef983536e --- /dev/null +++ b/source/tutorial/configure-replica-set-tag-sets.txt @@ -0,0 +1,298 @@ +.. index:: replica set; tag sets +.. index:: read preference; tag sets +.. index:: tag sets; configuration +.. _replica-set-configuration-tag-sets: + +============================== +Configure Replica Set Tag Sets +============================== + +.. default-domain:: mongodb + +Tag sets let you customize :term:`write concern` and :term:`read +preferences ` for a :term:`replica set`. Tag sets are +stored in the system.replset collection, in the :data:`members[n].tags +subdocument <~local.system.replset.members[n].tags>`. + +.. note:: + + Custom read preferences and write concerns evaluate tags sets in + different ways: + + - Read preferences consider the value of a tag when selecting a + member to read from. + + - Write concerns do not utilize the value of a tag to select a member + except to consider whether or not the value is unique. + +A tag set for a read operation may resemble the following document: + +.. code-block:: javascript + + { "disk": "ssd", "use": "reporting" } + +To fulfill the request, a member would need to have both of these tags. +Therefore the following tag sets, would satisfy this requirement: + +.. code-block:: javascript + + { "disk": "ssd", "use": "reporting" } + { "disk": "ssd", "use": "reporting", "rack": 1 } + { "disk": "ssd", "use": "reporting", "rack": 4 } + { "disk": "ssd", "use": "reporting", "mem": "64"} + +The following tag sets would *not* be able to fulfill this query: + +.. code-block:: javascript + + { "disk": "ssd" } + { "use": "reporting" } + { "disk": "ssd", "use": "production" } + { "disk": "ssd", "use": "production", "rack": 3 } + { "disk": "spinning", "use": "reporting", "mem": "32" } + +This document describes how to add tag sets. For conceptual information +on tag sets, see :ref:`replica-set-write-concern` and +:ref:`replica-set-read-preference-tag-sets`. + +Add Tag Sets to a Replica Set +----------------------------- + +Given the following replica set configuration: + +.. code-block:: javascript + + { + "_id" : "rs0", + "version" : 1, + "members" : [ + { + "_id" : 0, + "host" : "mongodb0.example.net:27017" + }, + { + "_id" : 1, + "host" : "mongodb1.example.net:27017" + }, + { + "_id" : 2, + "host" : "mongodb2.example.net:27017" + } + ] + } + +You could add the tag sets to the members of this replica set +with the following command sequence in the :program:`mongo` shell: + +.. code-block:: javascript + + conf = rs.conf() + conf.members[0].tags = { "dc": "east", "use": "production" } + conf.members[1].tags = { "dc": "east", "use": "reporting" } + conf.members[2].tags = { "use": "production" } + rs.reconfig(conf) + +After this operation the output of :method:`rs.conf()` would +resemble the following: + +.. code-block:: javascript + + { + "_id" : "rs0", + "version" : 2, + "members" : [ + { + "_id" : 0, + "host" : "mongodb0.example.net:27017", + "tags" : { + "dc": "east", + "use": "production" + } + }, + { + "_id" : 1, + "host" : "mongodb1.example.net:27017", + "tags" : { + "dc": "east", + "use": "reporting" + } + }, + { + "_id" : 2, + "host" : "mongodb2.example.net:27017", + "tags" : { + "use": "production" + } + } + ] + } + + +Custom Multi-Datacenter Write Concerns +-------------------------------------- + +Given a five member replica set with members in two data centers: + +1. a facility ``VA`` tagged ``dc.va`` + +2. a facility ``GTO`` tagged ``dc.gto`` + +Create a custom write concern to require confirmation from two +data centers using replica set tags, using the following sequence +of operations in the :program:`mongo` shell: + +#. Create the replica set configuration object ``conf``: + + .. code-block:: javascript + + conf = rs.conf() + +#. Add tags to the replica set members reflecting their locations: + + .. code-block:: javascript + + conf.members[0].tags = { "dc.va": "rack1"} + conf.members[1].tags = { "dc.va": "rack2"} + conf.members[2].tags = { "dc.gto": "rack1"} + conf.members[3].tags = { "dc.gto": "rack2"} + conf.members[4].tags = { "dc.va": "rack1"} + rs.reconfig(conf) + +#. Create a custom + :data:`~local.system.replset.settings.getLastErrorModes` setting to + ensure that the write operation will propagate to at least one member + of each facility: + + .. code-block:: javascript + + conf.settings = { getLastErrorModes: { MultipleDC : { "dc.va": 1, "dc.gto": 1}} + +#. Reconfigure the replica set using the new ``conf`` configuration + object: + + .. code-block:: javascript + + rs.reconfig(conf) + +To ensure that a write operation propagators to at least one member of +the set in both facilities, then use the ``MultipleDC`` write concern +mode, as follows: + +.. code-block:: javascript + + db.runCommand( { getLastError: 1, w: "MultipleDC" } ) + +Alternatively, if you want to ensure that each write operation +propagates to at least 2 racks in each facility, reconfigure the +replica set as follows in the :program:`mongo` shell: + +#. Create the replica set configuration object ``conf``: + + .. code-block:: javascript + + conf = rs.conf() + +#. Redefine the + :data:`~local.system.replset.settings.getLastErrorModes` value to + require two different values of both ``dc.va`` and ``dc.gto``: + + .. code-block:: javascript + + conf.settings = { getLastErrorModes: { MultipleDC : { "dc.va": 2, "dc.gto": 2}} + +#. Reconfigure the replica set using the new ``conf`` configuration + object: + + .. code-block:: javascript + + rs.reconfig(conf) + +Now, the following write concern operation will only return after the +write operation propagates to at least two different racks in the +each facility: + +.. code-block:: javascript + + db.runCommand( { getLastError: 1, w: "MultipleDC" } ) + +Configure Tag Sets for Functional Segregation of Read and Write Operations +-------------------------------------------------------------------------- + +Given a replica set with tag sets that reflect: + +- data center facility, + +- physical rack location of instance, and + +- storage system (i.e. disk) type. + +Where each member of the set has a tag set that resembles one of the +following: [#read-and-write-tags]_ + +.. code-block:: javascript + + {"dc.va": "rack1", disk:"ssd", ssd: "installed" } + {"dc.va": "rack2", disk:"raid"} + {"dc.gto": "rack1", disk:"ssd", ssd: "installed" } + {"dc.gto": "rack2", disk:"raid"} + {"dc.va": "rack1", disk:"ssd", ssd: "installed" } + +To target a read operation to a member of the replica set with an +disk type of ``ssd``, you could use the following tag set: + +.. code-block:: javascript + + { disk: "ssd" } + +However, to create comparable write concern modes, you would specify a +different set of +:data:`~local.system.replset.settings.getLastErrorModes` +configuration. Consider the following sequence of operations in +the :program:`mongo` shell: + +#. Create the replica set configuration object ``conf``: + + .. code-block:: javascript + + conf = rs.conf() + +#. Redefine the + :data:`~local.system.replset.settings.getLastErrorModes` value to + configure two write concern modes: + + .. code-block:: javascript + + conf.settings = { + "getLastErrorModes" : { + "ssd" : { + "ssd" : 1 + }, + "MultipleDC" : { + "dc.va" : 1, + "dc.gto" : 1 + } + } + } + +#. Reconfigure the replica set using the new ``conf`` configuration + object: + + .. code-block:: javascript + + rs.reconfig(conf) + +Now, you can specify the ``MultipleDC`` write concern mode, as in the +following operation, to ensure that a write operation propagates to +each data center. + +.. code-block:: javascript + + db.runCommand( { getLastError: 1, w: "MultipleDC" } ) + +Additionally, you can specify the ``ssd`` write concern mode, as in +the following operation, to ensure that a write operation propagates +to at least one instance with an SSD. + +.. [#read-and-write-tags] Since read preferences and write concerns + use the value of fields in tag sets differently, larger + deployments will have some redundancy.