Skip to content

DOCS-1081 split tag set examples into a tutorial #864

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

DOCS-1081 split tag set examples into a tutorial #864

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions source/administration/replica-sets.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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::
Expand Down
37 changes: 3 additions & 34 deletions source/core/read-preference.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand All @@ -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
<replica-set-read-preference-modes>` interact with tag sets, see the
documentation for each read preference mode.
Expand Down
278 changes: 4 additions & 274 deletions source/reference/replica-configuration.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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*.
Expand Down Expand Up @@ -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 <read preference>`
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
<replica-set-write-concern>` and :ref:`tag sets for read preference
<replica-set-read-preference-tag-sets>`.

.. 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.
1 change: 1 addition & 0 deletions source/tutorial.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
Loading