Skip to content

Commit 578bc77

Browse files
sarahsimperssarahsimpers
authored
(DOCSP-22334) Adds reference section and cluster configuration file info (#58)
* (DOCSP-22334) Adds reference section and cluster configuration file info * Adds example files, updates required fields * Adds multi-cloud examples * Removes YAML examples and info * Updates submodule to match master * Includes changes from Corry's copy review * Fixes build errors from primary term addition
1 parent 4236979 commit 578bc77

File tree

6 files changed

+264
-0
lines changed

6 files changed

+264
-0
lines changed

‎snooty.toml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,9 @@ atlas-cli-version = "1.1.5"
2929
cloudgov = ":atlas:`MongoDB Atlas for Government </government>`"
3030
cloudgov-short = "AtlasGov"
3131
cluster = "cluster"
32+
Cluster = "Cluster"
3233
clusters = "clusters"
34+
Clusters = "Clusters"
3335
data-lake = "Atlas Data Lake"
3436
data-lake-short = "Data Lake"
3537
data-lake-stores = "data stores"

‎source/cluster-config-file.txt

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
.. _atlas-cli-cluster-config-file:
2+
3+
==============================
4+
{+Cluster+} Configuration File
5+
==============================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
You can use a {+cluster+} configuration file to specify the settings
14+
required when you create or update a {+cluster+} using the
15+
{+atlas-cli+}. The {+atlas-cli+} accepts ``.json``
16+
{+cluster+} configuration files.
17+
18+
Use the following resources to:
19+
20+
- Learn the :ref:`required settings <required-cluster-settings>` you
21+
can specify in the {+cluster+} configuration file.
22+
- View and copy :ref:`sample configuration files
23+
<example-cluster-config-file>`.
24+
25+
.. _required-cluster-settings:
26+
27+
Required {+Cluster+} Settings
28+
-----------------------------
29+
30+
|service| requires the following settings to create a {+cluster+} with
31+
the {+atlas-cli+}. You must specify these {+cluster+} settings either
32+
in the configuration file or as flags in the command:
33+
34+
.. list-table::
35+
:header-rows: 1
36+
:widths: 20 10 70
37+
38+
* - Field
39+
- Type
40+
- Description
41+
42+
* - ``clusterType``
43+
- string
44+
- Human-readable label that indicates the type of {+cluster+} to
45+
create. Values include: ``REPLICASET``, ``SHARDED``, or
46+
``GEOSHARDED``.
47+
48+
* - ``name``
49+
- string
50+
- Human-readable label that identifies the {+cluster+}.
51+
52+
* - ``replicationSpecs``
53+
- array
54+
- List that contains the configuration settings for your
55+
{+cluster+} regions and the hardware provisioned in them.
56+
57+
* - ``replicationSpecs.``
58+
``regionConfigs``
59+
- array
60+
- List that contains the hardware specifications for the nodes set
61+
within the region that you specify. Each ``regionConfigs``
62+
object describes the region's priority in elections and the
63+
number and type of MongoDB nodes that |service| deploys to the
64+
region.
65+
66+
Each ``regionConfigs`` object must have either an
67+
``analyticsSpecs`` object, ``electableSpecs`` object, or
68+
``readOnlySpecs`` object.
69+
70+
- Shared {+clusters+} require only ``electableSpecs``.
71+
- Dedicated {+clusters+} can specify any of these
72+
specifications, but must have at least one ``electableSpecs``
73+
object within a ``replicationSpec``.
74+
- Every hardware specification must use the same
75+
``instanceSize``.
76+
77+
* - ``replicationSpecs.``
78+
``regionConfigs.electableSpecs``
79+
- object
80+
- Hardware specifications for electable nodes in the region.
81+
Electable nodes can become the
82+
:manual:`primary </core/replica-set-members/#std-label-replica-set-primary-member>` and can enable
83+
local reads.
84+
85+
* - ``replicationSpecs.``
86+
``regionConfigs.``
87+
``electableSpecs.instanceSize``
88+
- string
89+
- Hardware specification for the instance sizes in this region. To
90+
learn more, see :ref:`create-cluster-instance`.
91+
92+
* - ``replicationSpecs``
93+
``.regionConfigs.``
94+
``electableSpecs.nodeCount``
95+
- number
96+
- Number of electable nodes for |service| to deploy to the region.
97+
Electable nodes can become the
98+
:manual:`primary </core/replica-set-members/#std-label-replica-set-primary-member>` and can enable
99+
local reads.
100+
101+
The combined electableSpecs.nodeCount across all
102+
replicationSpecs[n].regionConfigs[m] objects must total 3, 5, or
103+
7.
104+
105+
* - ``replicationSpecs.``
106+
``regionConfigs.priority``
107+
- Integer
108+
- Precedence that is given to this region when a primary election
109+
occurs.
110+
111+
If your region has set ``electableSpecs.nodeCount`` to ``1`` or
112+
higher, it must have a priority of exactly one (1) less than
113+
another region in the ``replicationSpecs[n].regionConfigs[m]``
114+
array. The highest-priority region must have a priority of
115+
``7``. The lowest possible priority is ``1``.
116+
117+
The priority ``7`` region identifies the preferred region of the
118+
{+cluster+}. |service| places the
119+
:manual:`primary </core/replica-set-members/#std-label-replica-set-primary-member>` node in the
120+
preferred region.
121+
122+
* - ``replicationSpecs.``
123+
``regionConfigs.providerName``
124+
- string
125+
- Human-readable label that identifies your cloud service
126+
provider. Values include: ``AWS``, ``AZURE``, or ``GCP``.
127+
128+
To create a multi-cloud {+cluster+}, specify more than one
129+
service provider for your ``regionConfigs`` objects. To
130+
learn more, see the :ref:`multi-cloud example configuration file
131+
<multi-cloud-example-cluster-config-file>`
132+
133+
* - ``replicationSpecs.``
134+
``regionConfigs.regionName``
135+
- string
136+
- Human-readable label that indicates the physical location of
137+
your {+cluster+} nodes. The region you choose can affect network
138+
latency for clients accessing your databases.
139+
140+
For a complete list of region name values, refer to the the
141+
cloud provider reference pages:
142+
143+
- :atlas:`AWS </reference/amazon-aws/#amazon-aws>>`
144+
- :atlas:`GCP </reference/google-gcp/#google-gcp>`
145+
- :atlas:`Azure </reference/microsoft-azure/#microsoft-azure>`
146+
147+
.. _optional-cluster-settings:
148+
149+
Optional and Conditional {+Cluster+} Settings
150+
---------------------------------------------
151+
152+
Your {+cluster+} configuration file may contain additional optional or
153+
conditional {+cluster+} settings. For a full list of available
154+
settings, see the API documentation for
155+
:atlas:`Create One Multi-Cloud Cluster from One Project
156+
</reference/api-resources-spec/#operation/createOneAdvancedClusterFromOneProject>`.
157+
158+
.. _example-cluster-config-file:
159+
160+
Example Cluster Configuration File
161+
----------------------------------
162+
163+
To create a {+cluster+} using a single cloud provider, specify the same
164+
service provider for your ``regionConfigs`` objects as shown in the
165+
following example file:
166+
167+
.. literalinclude:: /includes/json-cluster-config-file.json
168+
169+
.. _multi-cloud-example-cluster-config-file:
170+
171+
Multi-Cloud Example Cluster Configuration File
172+
----------------------------------------------
173+
174+
To create a multi-cloud {+cluster+}, specify more than one
175+
service provider for your ``regionConfigs`` objects as shown in the
176+
following example file:
177+
178+
.. literalinclude:: /includes/json-cluster-config-file-multi.json

‎source/includes/json-cluster-config-file-multi.json

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
{
2+
"name":"myCluster",
3+
"clusterType":"REPLICASET",
4+
"replicationSpecs":[
5+
{
6+
"regionConfigs":[
7+
{
8+
"electableSpecs":{
9+
"instanceSize":"M30",
10+
"nodeCount":1
11+
},
12+
"priority":7,
13+
"providerName":"AWS",
14+
"regionName":"EU_WEST_1"
15+
},
16+
{
17+
"electableSpecs":{
18+
"instanceSize":"M30",
19+
"nodeCount":1
20+
},
21+
"priority":6,
22+
"providerName":"GCP",
23+
"regionName":"CENTRAL_US"
24+
},
25+
{
26+
"electableSpecs":{
27+
"instanceSize":"M30",
28+
"nodeCount":1
29+
},
30+
"priority":5,
31+
"providerName":"AZURE",
32+
"regionName":"US_EAST_2"
33+
}
34+
]
35+
}
36+
]
37+
}

‎source/includes/json-cluster-config-file.json

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
{
2+
"name":"myCluster",
3+
"clusterType":"REPLICASET",
4+
"replicationSpecs":[
5+
{
6+
"regionConfigs":[
7+
{
8+
"electableSpecs":{
9+
"instanceSize":"M30",
10+
"nodeCount":1
11+
},
12+
"priority":7,
13+
"providerName":"AWS",
14+
"regionName":"EU_WEST_1"
15+
},
16+
{
17+
"electableSpecs":{
18+
"instanceSize":"M30",
19+
"nodeCount":1
20+
},
21+
"priority":6,
22+
"providerName":"AWS",
23+
"regionName":"US_EAST_1"
24+
},
25+
{
26+
"electableSpecs":{
27+
"instanceSize":"M30",
28+
"nodeCount":1
29+
},
30+
"priority":5,
31+
"providerName":"AWS",
32+
"regionName":"US_WEST_1"
33+
}
34+
]
35+
}
36+
]
37+
}

‎source/index.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,4 +116,5 @@ Learn the {+atlas-cli+} commands and optimize your workflow with advanced tutori
116116
/configure-optional-settings
117117
/atlas-cli-tutorials
118118
Atlas CLI Commands </command/atlas>
119+
/reference
119120
/atlas-cli-changelog

‎source/reference.txt

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
2+
=========
3+
Reference
4+
=========
5+
6+
.. toctree::
7+
:titlesonly:
8+
9+
/cluster-config-file

0 commit comments

Comments
 (0)