Amazon DocumentDB Quick Start Using AWS CloudFormation

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

These instructions use an AWS 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 AWS 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 AWS CloudFormation stack is intended as for a tutorial purpose 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.

Prerequisites

Before you create an Amazon DocumentDB (with MongoDB compatibility) 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 AWS CloudFormation stack:

AWS Managed Policies

  • AWSCloudFormationReadOnlyAccess

  • AmazonDocDBFullAccess

Additional IAM Permissions

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

  1. {
  2.    "Version": "2012-10-17",
  3.    "Statement": [{
  4.       "Effect": "Allow",
  5.       "Action": [
  6.         "iam:GetSSHPublicKey",
  7.         "iam:ListSSHPublicKeys",
  8.         "iam:CreateRole",
  9.         "iam:CreatePolicy",
  10.         "iam:PutRolePolicy",
  11.         "iam:CreateInstanceProfile",
  12.         "iam:AddRoleToInstanceProfile",
  13.         "iam:GetAccountSummary",
  14.         "iam:ListAccountAliases",
  15.         "iam:PassRole",
  16.         "iam:GetRole",
  17.         "iam:DeleteRole",
  18.         "iam:RemoveRoleFromInstanceProfile",
  19.         "iam:DeleteRolePolicy",
  20.         "iam:DeleteInstanceProfile",
  21.         "cloudformation:*Stack",
  22.         "ec2:DescribeKeyPairs",
  23.         "ec2:*Vpc",
  24.         "ec2:DescribeInternetGateways",
  25.         "ec2:*InternetGateway",
  26.         "ec2:createTags",
  27.         "ec2:*VpcAttribute",
  28.         "ec2:DescribeRouteTables",
  29.         "ec2:*RouteTable",
  30.         "ec2:*Subnet",
  31.         "ec2:*SecurityGroup",
  32.         "ec2:AuthorizeSecurityGroupIngress",
  33.         "ec2:DescribeVpcEndpoints",
  34.         "ec2:*VpcEndpoint",
  35.         "ec2:*SubnetAttribute",
  36.         "ec2:*Route",
  37.         "ec2:*Instances",
  38.         "ec2:DeleteVpcEndpoints"
  39.       ],
  40.       "Resource": "*"
  41.     }
  42.    ]
  43. }

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 AWS 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 AWS CloudFormation Stack

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

  1. Sign in to the AWS Management Console at https://console.aws.amazon.com/.

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

    RegionView TemplateView in DesignerLaunch
    US East (Ohio)View TemplateView in DesignerQuick Start using AWS CloudFormation - 图1
    US East (N. Virginia)View TemplateView in Designer

    Quick Start using AWS CloudFormation - 图2

    US West (Oregon)

    		View TemplateView in DesignerQuick Start using AWS CloudFormation - 图3

    Asia Pacific (Mumbai)

    		View TemplateView in DesignerQuick Start using AWS CloudFormation - 图4

    Asia Pacific (Seoul)

    		View TemplateView in DesignerQuick Start using AWS CloudFormation - 图5

    Asia Pacific (Singapore)

    		View TemplateView in DesignerQuick Start using AWS CloudFormation - 图6

    Asia Pacific (Sydney)

    		View TemplateView in DesignerQuick Start using AWS CloudFormation - 图7

    Asia Pacific (Tokyo)

    		View TemplateView in DesignerQuick Start using AWS CloudFormation - 图8

    Canada (Central)

    		View TemplateView in DesignerQuick Start using AWS CloudFormation - 图9

    Europe (Frankfurt)

    		View TemplateView in DesignerQuick Start using AWS CloudFormation - 图10

    Europe (Ireland)

    		View TemplateView in DesignerQuick Start using AWS CloudFormation - 图11

    Europe (London)

    		View TemplateView in DesignerQuick Start using AWS CloudFormation - 图12

    Europe (Paris)

    		View TemplateView in DesignerQuick Start using AWS CloudFormation - 图13

  3. 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 AWS 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 AWS Region you chose.

    When you launch an AWS 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 AWS CloudFormation Designer page of the console. Scroll to the Resources section and modify it to include DeletionProtection, as follows. For more information about using AWS CloudFormation Designer, see What Is AWS CloudFormation Designer?.

      JSON:

      1. "Resources": {
      2.     "DBCluster": {
      3.         "Type": "AWS::DocDB::DBCluster",
      4.         "DeletionPolicy": "Delete",
      5.         "Properties": {
      6.             "DBClusterIdentifier": {
      7.                 "Ref": "DBClusterName"
      8.             },
      9.             "MasterUsername": {
      10.                 "Ref": "MasterUser"
      11.             },
      12.             "MasterUserPassword": { 
      13.                 "Ref": "MasterPassword"
      14.             }, 
      15.             "DeletionProtection": "true"
      16.         }
      17.     },

      YAML:

      1. Resources:
      2.   DBCluster:
      3.     Type: 'AWS::DocDB::DBCluster'
      4.     DeletionPolicy: Delete
      5.     Properties:
      6.       DBClusterIdentifier: !Ref DBClusterName
      7.       MasterUsername: !Ref MasterUser
      8.       MasterUserPassword: !Ref MasterPassword
      9.       DeletionProtection: 'true'

    3. Choose Create Stack ( Quick Start using AWS CloudFormation - 图14 ) 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.

  4. 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 AWS 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 AWS 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.

  1. Choose **Next** to save your changes and continue.

  1. 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 AWS CloudFormation can create, modify, or delete resources in the stack. If you don’t choose a role, AWS 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, AWS 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 AWS CloudFormation to monitor when creating and updating the stack. If the operation breaches an alarm threshold, AWS 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

          AWS CloudFormation termination protection is different from the Amazon DocumentDB concept of deletion protection. For more information, see Termination Protection and Deletion Protection.

  1. Choose **Next** to continue.

  1. 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 AWS 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 AWS 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 AWS Management Console, AWS CLI, and CloudFormation. For more information on enabling and disabling deletion protection for an Amazon DocumentDB cluster, see Deletion Protection.