Prerequisites Launching an Amazon DocumentDB Amazon CloudFormation Stack Accessing the Amazon DocumentDB Cluster Termination Protection and Deletion Protection

Amazon DocumentDB Quick Start Using Amazon CloudFormation

This section contains steps and other information to help you get started quickly with Amazon DocumentDB (with MongoDB compatibility) using Amazon CloudFormation. For general information about Amazon DocumentDB, see What Is Amazon DocumentDB (with MongoDB Compatibility).

These instructions use an Amazon CloudFormation template to create a cluster and instances in your default Amazon VPC. For instructions on creating these resources yourself, see Get Started with Amazon DocumentDB.

Important

The Amazon CloudFormation stack that is created by this template creates multiple resources, including resources in Amazon DocumentDB (for example, a cluster and instances) and Amazon Elastic Compute Cloud (for example, a subnet group).

Some of these resources are not free-tier resources. For pricing information, see Amazon DocumentDB Pricing and Amazon EC2 Pricing. You can delete the stack when you are finished with it to stop any charges.

This Amazon CloudFormation stack is intended for tutorial purposes only. If you use this template for a production environment, we recommend that you use stricter IAM policies and security. For information about securing resources, see Amazon VPC Security and Amazon EC2 Network and Security.

Topics

Prerequisites
Launching an Amazon DocumentDB Amazon CloudFormation Stack
Accessing the Amazon DocumentDB Cluster
Termination Protection and Deletion Protection

Prerequisites

Before you create an Amazon DocumentDB cluster, you must have the following:

A default Amazon VPC
The required IAM permissions

Required IAM Permissions

The following permissions allow you to create resources for the Amazon CloudFormation stack:

Amazon Managed Policies

AWSCloudFormationReadOnlyAccess
AmazonDocDBFullAccess

Additional IAM Permissions

The following policy outlines the additional permissions that are required to create and delete this Amazon CloudFormation stack.


{
   "Version": "2012-10-17",
   "Statement": [
       {
            "Effect": "Allow",
            "Action": [
                "iam:GetSSHPublicKey",
                "iam:ListSSHPublicKeys",
                "iam:CreateRole",
                "iam:CreatePolicy",
                "iam:PutRolePolicy",
                "iam:CreateInstanceProfile",
                "iam:AddRoleToInstanceProfile",
                "iam:GetAccountSummary",
                "iam:ListAccountAliases",
                "iam:GetRole",
                "iam:DeleteRole",
                "iam:RemoveRoleFromInstanceProfile",
                "iam:DeleteRolePolicy",
                "iam:DeleteInstanceProfile",
                "cloudformation:*Stack",
                "ec2:DescribeKeyPairs",
                "ec2:*Vpc",
                "ec2:DescribeInternetGateways",
                "ec2:*InternetGateway",
                "ec2:createTags",
                "ec2:*VpcAttribute",
                "ec2:DescribeRouteTables",
                "ec2:*RouteTable",
                "ec2:*Subnet",
                "ec2:*SecurityGroup",
                "ec2:AuthorizeSecurityGroupIngress",
                "ec2:DescribeVpcEndpoints",
                "ec2:*VpcEndpoint",
                "ec2:*SubnetAttribute",
                "ec2:*Route",
                "ec2:*Instances",
                "ec2:DeleteVpcEndpoints"
            ],
            "Resource": "*"
        },
        {
            "Sid": "iamPassRole",
            "Effect": "Allow",
            "Action": "iam:PassRole",
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "iam:PassedToService": "rds.amazonaws.com"
                }
            }
        }
   ]
}

Note

The bolded permissions in the preceding policy are only required to delete a stack: iam:DeleteRole, iam:RemoveRoleFromInstanceProfile, iam:DeleteRolePolicy, iam:DeleteInstanceProfile, and ec2:DeleteVpcEndpoints. Also note that ec2:*Vpc grants ec2:DeleteVpc permissions.

Amazon EC2 Key Pair

You must have a key pair (and the PEM file) available in the Region where you will create the Amazon CloudFormation stack. If you need to create a key pair, see Creating a Key Pair Using Amazon EC2 in the Amazon EC2 User Guide for Linux Instances.

Launching an Amazon DocumentDB Amazon CloudFormation Stack

This section describes how to launch and configure an Amazon DocumentDB Amazon CloudFormation stack.

The following table lists the Amazon DocumentDB stack templates for each Amazon Web Services Region. Choose Launch Stack for the Amazon Web Services Region you want to launch your stack in.

Region	View Template	View in Designer
US East (Ohio)	View Template	View in Designer
US East (N. Virginia)	View Template	View in Designer
US West (Oregon)	View Template	View in Designer
Asia Pacific (Mumbai)	View Template	View in Designer
Asia Pacific (Seoul)	View Template	View in Designer
Asia Pacific (Singapore)	View Template	View in Designer
Asia Pacific (Sydney)	View Template	View in Designer
Asia Pacific (Tokyo)	View Template	View in Designer
Canada (Central)	View Template	View in Designer
Europe (Frankfurt)	View Template	View in Designer
Europe (Ireland)	View Template	View in Designer
Europe (London)	View Template	View in Designer
Europe (Paris)	View Template	View in Designer

Create stack — Describes the Amazon DocumentDB template that you selected. Every stack is based on a template — a JSON or YAML file — that contains configuration about the Amazon resources you want to include in the stack. Because you chose to launch a stack from the provided templates above, your template has already been configured to create an Amazon DocumentDB stack for the Amazon Web Services Region you chose.

When you launch an Amazon CloudFormation stack, deletion protection for your Amazon DocumentDB cluster is disabled by default. If you want to enable deletion protection for your cluster, complete the following steps. Otherwise, choose Next to continue to the next step.

To enable deletion protection for your Amazon DocumentDB cluster:
1. Choose View in Designer from the bottom right corner of the Create stack page.
2. Modify the template using the integrated JSON and YAML editor in the resulting Amazon CloudFormation Designer page of the console. Scroll to the Resources section and modify it to include DeletionProtection, as follows. For more information about using Amazon CloudFormation Designer, see What Is Amazon CloudFormation Designer?.
  
  JSON:
```
"Resources": {
    "DBCluster": {
        "Type": "AWS::DocDB::DBCluster",
        "DeletionPolicy": "Delete",
        "Properties": {
            "DBClusterIdentifier": {
                "Ref": "DBClusterName"
            },
            "MasterUsername": {
                "Ref": "MasterUser"
            },
            "MasterUserPassword": { 
                "Ref": "MasterPassword"
            }, 
            "DeletionProtection": "true"
        }
    },
```
  YAML:
```
Resources:
  DBCluster:
    Type: 'AWS::DocDB::DBCluster'
    DeletionPolicy: Delete
    Properties:
      DBClusterIdentifier: !Ref DBClusterName
      MasterUsername: !Ref MasterUser
      MasterUserPassword: !Ref MasterPassword
      DeletionProtection: 'true'
```
3. Choose Create Stack ( ) from the top left corner of the page to save your changes and create a stack with these changes enabled.
4. After you save your changes, you will be redirected to the Create stack page.
5. Choose Next to continue.
Specify stack details — Enter the stack name and parameters for your template. Parameters are defined in your template and allow you to input custom values when you create or update a stack.
- Under Stack name, enter a name for your stack or accept the provided name. The stack name can include letters (A—Z and a—z), numbers (0—9), and dashes (—).
- Under Parameters, enter the following details:
  - DBClusterName — Enter a name for your Amazon DocumentDB cluster or accept the provided name.
    
    Cluster naming constraints:
    Length is [1—63] letters, numbers, or hyphens.
    
    First character must be a letter.
    
    Cannot end with a hyphen or contain two consecutive hyphens.
    
    Must be unique for all clusters across Amazon RDS, Neptune, and Amazon DocumentDB per Amazon Web Services account, per Region.
  - DBInstanceClass — From the drop-down list, select the instance class for your Amazon DocumentDB cluster.
  - DBInstanceName — Enter a name for your Amazon DocumentDB instance or accept the provided name.
    
    Instance naming constraints:
    Length is [1—63] letters, numbers, or hyphens.
    
    First character must be a letter.
    
    Cannot end with a hyphen or contain two consecutive hyphens.
    
    Must be unique for all instances across Amazon RDS, Neptune, and Amazon DocumentDB per Amazon Web Services account, per Region.
  - MasterPassword — The database admin account password.
  - MasterUser — The database admin account username. The MasterUser must begin with a letter and can contain only alphanumeric characters.
Choose Next to save your changes and continue.
Configure stack options — Configure your stack's tags, permissions, and additional options.
- Tags — Specify tags (key-value) pairs to apply to your resources in your stack. You can add up to 50 unique tags for each stack.
- Permissions — Optional. Choose an IAM role to explicitly define how Amazon CloudFormation can create, modify, or delete resources in the stack. If you don't choose a role, Amazon CloudFormation uses permissions based on your user credentials. Before you specify a service role, ensure that you have permission to pass it (iam:PassRole). The iam:PassRole permission specifies which roles you can use.
  
  Note
  When you specify a service role, Amazon CloudFormation always uses that role for all operations that are performed on that stack. Other users that have permissions to perform operations on this stack will be able to use this role, even if they don't have permission to pass it. If the role includes permissions that the user shouldn't have, you can unintentionally escalate a user's permissions. Ensure that the role grants least privilege..
- Advanced options — You can set the following advanced options:
  - Stack policy — Optional. Defines the resources that you want to protect from unintentional updates during a stack update. By default, all resources can be updated during a stack update.
    
    You can enter the stack policy directly as JSON, or upload a JSON file containing the stack policy. For more information, see Prevent Updates to Stack Resources.
  - Rollback configuration — Optional. Specify CloudWatch Logs alarms for Amazon CloudFormation to monitor when creating and updating the stack. If the operation breaches an alarm threshold, Amazon CloudFormation rolls it back.
  - Notification options — Optional. Specify topics for Simple Notification System (SNS).
  - Stack creation options — Optional. You can specify the following options:
    Rollback on failure — Whether or not the stack should be rolled back if the stack creation fails.
    
    Timeout —The number of minutes before a stack creation times out.
    
    Termination protection — Prevents the stack from being accidentally deleted.
    
    Note
    Amazon CloudFormation termination protection is different from the Amazon DocumentDB concept of deletion protection. For more information, see Termination Protection and Deletion Protection.
Choose Next to continue.
Review <stack-name> — Review your stack template, details, and configuration options. You can also open a quick-create link at the bottom of the page to create stacks with the same basic configurations as this one.
- Choose Create to create the stack.
- Alternatively, you can choose Create change set. A change set is a preview of how this stack will be configured before creating the stack. This allows you to examine various configurations before executing the change set.

Accessing the Amazon DocumentDB Cluster

Once the Amazon CloudFormation stack has been completed, you can use an Amazon EC2 instance to connect to your Amazon DocumentDB cluster. For information about connecting to an Amazon EC2 instance using SSH, see Connect to Your Linux Instance in the Amazon EC2 User Guide for Linux Instances.

After you are connected, see the following sections, which contain information about using Amazon DocumentDB.

Termination Protection and Deletion Protection

It is an Amazon DocumentDB best practice to enable deletion protection and termination protection. CloudFormation termination protection is a distinctly different feature from the Amazon DocumentDB deletion protection feature.

Termination protection — You can prevent a stack from being accidentally deleted by enabling termination protection for your CloudFormation stack. If a user attempts to delete a stack with termination protection enabled on it, the deletion fails and the stack remains unchanged. Termination protection is disabled by default when you create a stack using CloudFormation. You can enable termination protection on a stack when you create it. For more information, see Setting Amazon CloudFormation Stack Options.
Deletion protection — Amazon DocumentDB also provides the ability to enable deletion protection for a cluster. If a user attempts to delete an Amazon DocumentDB cluster with deletion protection enabled on it, the deletion fails and the cluster remains unchanged. Deletion protection, when enabled, safeguards against accidental deletes from the Amazon DocumentDB Amazon Web Services Management Console, Amazon CLI, and CloudFormation. For more information on enabling and disabling deletion protection for an Amazon DocumentDB cluster, see Deletion protection.

Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Get Started Guide

MongoDB Compatibility