Skip to content

Commit dca3229

Browse files
jwilliams-mongojwilliams-mongo
authored
(DOCSP-10321): Terraform Integration with VSCE (mongodb#16)
* (DOCSP-10321): Terraform Integration with VSCE * (DOCSP-10321): minor tweaks * (DOCSP-10321): copy review feedback
1 parent 5c51e15 commit dca3229

10 files changed

+570
-1
lines changed

‎source/connect.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,9 @@ or sharded cluster host.
2727
installation, offers a free tier to get started, and provides a
2828
copyable URI to easily connect |vsce| to your deployment.
2929

30+
To create an |service| cluster using a Terraform template included
31+
with |vsce|, see :ref:`vsce-create-cluster-terraform`.
32+
3033
If you need to install |vsce|, see :ref:`vsce-install` for instructions.
3134

3235
Considerations

‎source/create-cluster-terraform.txt

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
.. _vsce-create-cluster-terraform:
2+
3+
===========================================================
4+
Create an |service| Cluster from a Template using Terraform
5+
===========================================================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
.. include:: /includes/fact-vsce-preview.rst
16+
17+
This page outlines how to use the |service| template for Terraform files
18+
included with the MongoDB Extension for |vscode-short| to create
19+
Shared Tier |service| clusters.
20+
21+
After loading the template, you configure the cluster and provide
22+
details about your |service| account. You then use Terraform
23+
commands to plan, apply, and destroy your |service| cluster.
24+
25+
Prerequisites
26+
-------------
27+
28+
Before you use the |service| template for Terraform files
29+
included with the MongoDB Extension for |vscode-short|, you must:
30+
31+
- :ref:`vsce-install`
32+
- `Install Terraform
33+
<https://learn.hashicorp.com/terraform/getting-started/install.html>`__
34+
- Have an :atlas:`Atlas account</tutorial/create-atlas-account/>`.
35+
- Have an :atlas:`Atlas organization </tutorial/manage-organizations/>`.
36+
- Have an :atlas:`API key in an organization
37+
</tutorial/manage-programmatic-access/>` with the
38+
``Organization Owner`` or ``Organization Project Creator``
39+
:atlas:`role </reference/user-roles>`.
40+
41+
Procedures
42+
----------
43+
44+
Create an |service| Terraform File using the Template
45+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
46+
47+
Use the |service| template for Terraform files included with the |vsce|
48+
to configure an |service| cluster:
49+
50+
.. include:: /includes/steps/atlas-terraform-file-from-template.rst
51+
52+
Create the |service| Cluster using Terraform
53+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
54+
55+
After you create a Terraform file using the template, create the
56+
|service| cluster:
57+
58+
.. include:: /includes/steps/create-atlas-cluster-terraform.rst
59+
60+
Delete the |service| Cluster using Terraform
61+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
62+
63+
.. warning::
64+
65+
Deleting a cluster destroys databases, collections, and documents
66+
stored on it **and** all other resources defined in the Terraform
67+
configuration in which you configured the cluster.
68+
69+
Proceed with caution.
70+
71+
To delete the |service| cluster:
72+
73+
.. include:: /includes/steps/delete-atlas-cluster-terraform.rst

‎source/includes/list-tables/command-palette-options.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
.. list-table::
22
:header-rows: 1
3-
:widths: 33 33 34
3+
:widths: 33 33 33
44

55
* - Operating System
66
- Method

‎source/includes/steps-atlas-terraform-file-from-template.yaml

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
---
2+
title: "In |vscode-short|, create a new file."
3+
ref: create-file-vscode
4+
level: 4
5+
content: |
6+
7+
.. list-table::
8+
:header-rows: 1
9+
:widths: 33 33 33
10+
11+
* - Operating System
12+
- Method
13+
- Actions
14+
15+
* - Any
16+
- |vscode-short| Menu
17+
- :guilabel:`File` > :guilabel:`New File`
18+
19+
* - MacOS
20+
- Keyboard Shortcut
21+
- Press ``Command`` + ``N``
22+
23+
* - Windows and Linux
24+
- Keyboard Shortcut
25+
- Press ``Control`` + ``N``
26+
27+
---
28+
title: "Save the file. Name it ``main.tf``."
29+
ref: change-language
30+
level: 4
31+
content: |
32+
33+
.. note::
34+
35+
``main.tf`` is the recommended filename for the entry point to a
36+
Terraform module.
37+
38+
---
39+
title: "In the ``main.tf`` file, type ``atlas``, then press the **Enter** or **Return** key."
40+
ref: bootstrap-atlas
41+
level: 4
42+
content: |
43+
44+
The MongoDB Extension for VSCode populates the file with an example
45+
configuration using the `MongoDB Atlas
46+
<https://www.terraform.io/docs/providers/mongodbatlas/index.html>`__
47+
Terraform provider to create a Shared Tier |service| cluster.
48+
49+
---
50+
title: "Update the |service| Terraform configuration to configure your cluster."
51+
level: 4
52+
ref: update-config
53+
content: |
54+
55+
The cursor moves to select the value of the ``name`` argument of the
56+
``mongodbatlas_project`` resource.
57+
58+
Provide values for the following arguments to configure your cluster:
59+
60+
.. tip::
61+
62+
Press the **Tab** key to select to the next argument in
63+
the template that you should update.
64+
65+
.. list-table::
66+
:header-rows: 1
67+
:widths: 33 33 33
68+
69+
* - Attribute
70+
- Value
71+
72+
* - | ``mongodbatlas_project``
73+
| ``.name``
74+
- Name of the |service| project that this configuration creates.
75+
76+
* - | ``mongodbatlas_cluster``
77+
| ``.name``
78+
- Name of the |service| cluster that this configuration creates.
79+
80+
* - | ``mongodbatlas_cluster``
81+
| ``.backing_provider_name``
82+
- Provider on which the |service| cluster that this configuration
83+
creates is hosted. Choose one of the following accepted values:
84+
85+
- ``AWS``
86+
- ``AZURE``
87+
- ``GCP``
88+
89+
* - | ``mongodbatlas_cluster``
90+
| ``.provider_region_name``
91+
- Region to which the |service| cluster that this configuration
92+
creates is deployed. Ensure that the region you chose supports
93+
|service| clusters of the instance size you want to deploy.
94+
95+
By default the template provisions Shared Tier clusters:
96+
``M2`` and ``M5``.
97+
98+
For details about the instance sizes that each provider and
99+
region supports, see the following sections in the |service|
100+
documentation:
101+
102+
- :atlas:`Amazon Web Services </reference/amazon-aws/>`
103+
- :atlas:`Google Cloud Platform </reference/google-gcp/>`
104+
- :atlas:`Microsoft Azure </reference/microsoft-azure/>`
105+
106+
* - | ``mongodbatlas_cluster``
107+
| ``.provider_instance_size_name``
108+
- Instance size of the |service| cluster that this configuration
109+
creates.
110+
111+
Either:
112+
113+
- Choose one of the Shared Tier instance sizes included in the
114+
template: ``M2`` or ``M5``.
115+
- Enter another instance size that |service| supports for your
116+
chosen provider and region.
117+
118+
For details about the instance sizes that each provider and
119+
region supports, see the following sections in the |service|
120+
documentation:
121+
122+
- :atlas:`Amazon Web Services </reference/amazon-aws/>`
123+
- :atlas:`Google Cloud Platform </reference/google-gcp/>`
124+
- :atlas:`Microsoft Azure </reference/microsoft-azure/>`
125+
126+
* - | ``mongodbatlas_cluster``
127+
| ``.disk_size_gbs``
128+
- Disk size of the |service| cluster that this configuration
129+
creates. Ensure that you provide a value that is equal to or
130+
less than the maximum disk size for the instance size you
131+
chose.
132+
133+
- For ``M2`` clusters, enter ``2``.
134+
- For ``M5`` clusters, enter ``5``.
135+
136+
For details about the disk sizes that each provider supports
137+
for each instance size, see the following sections in the
138+
|service| documentation:
139+
140+
- :atlas:`Amazon Web Services </reference/amazon-aws/>`
141+
- :atlas:`Google Cloud Platform </reference/google-gcp/>`
142+
- :atlas:`Microsoft Azure </reference/microsoft-azure/>`
143+
144+
---
145+
title: "Update the ``local`` variables."
146+
level: 4
147+
ref: update-local-variables
148+
content: |
149+
150+
.. warning::
151+
152+
The ``local`` variables contain sensitive information. **Do not**
153+
check these values in to a repository that is available publicly.
154+
155+
Provide values for the following ``local`` variables:
156+
157+
.. list-table::
158+
:header-rows: 1
159+
:widths: 50 50
160+
161+
* - Variable
162+
- Value
163+
164+
* - ``mongodb_atlas_api_pub_key``
165+
- |service| public API key.
166+
167+
* - ``mongodb_atlas_api_pri_key``
168+
- |service| private API key.
169+
170+
* - ``mongodb_atlas_org_id``
171+
- |service| organization ID in which you want to create a
172+
project.
173+
174+
* - ``mongodb_atlas_database_username``
175+
- Username of the MongoDB database user that |service| creates
176+
for your cluster.
177+
178+
* - ``mongodb_atlas_database_user_password``
179+
- Password for the MongoDB database user named in
180+
``mongodb_atlas_database_username``.
181+
182+
* - ``mongodb_atlas_whitelistip``
183+
- IP address or CIDR block from which your |service| cluster is
184+
accessible.
185+
186+
.. admonition:: Use an Input Variables File to Maximize security
187+
:class: admonition-example
188+
189+
To maximize security, consider taking the following steps:
190+
191+
a. Define the ``local`` variables in an `input variables
192+
<https://learn.hashicorp.com/terraform/getting-started/variables.html>`__
193+
file.
194+
195+
.. example::
196+
197+
.. code-block:: none
198+
199+
variable "mongodb_atlas_api_pub_key" {
200+
default = "my-public-key"
201+
}
202+
203+
variable "mongodb_atlas_api_pri_key" {
204+
default = "my-private-key"
205+
}
206+
207+
#. Exclude the input variables file from your repository. For
208+
example, add the filename to the ``.gitignore`` file for your
209+
repository.
210+
#. Reference variables from the input variables file in the
211+
``main.tf`` file by prefacing them with ``vars.``.
212+
213+
.. example::
214+
215+
.. code-block:: none
216+
217+
provider "mongodbatlas" {
218+
public_key = vars.mongodb_atlas_api_pub_key
219+
private_key = vars.mongodb_atlas_api_pri_key
220+
}
221+
---
222+
title: "Add optional configuration options to the ``main.tf`` file."
223+
level: 4
224+
ref: optional-tf-config
225+
content: |
226+
227+
For a complete list of supported configuration options, see the
228+
`MongoDB Atlas Terraform Provider documentation
229+
<https://www.terraform.io/docs/providers/mongodbatlas/index.html>`__.
230+
231+
.. note::
232+
233+
Shared Tier |service| clusters don't support all configurations
234+
available with the MongoDB Atlas Terraform provider. For a list of
235+
unsupported configurations, see the :atlas:`Atlas documentation
236+
</reference/free-shared-limitations/>`.
237+
238+
---
239+
title: "Save the ``main.tf`` file."
240+
level: 4
241+
ref: save-file
242+
...

0 commit comments

Comments
 (0)