Creating an Amazon DocumentDB Subnet Group

    A subnet group is a named set of subnets (or AZs) that allows you to specify the availability zones that you want to use to for launching Amazon DocumentDB instances. For example, in a cluster with three instances, it is recommended that each of those instances are provisioned in separate AZs—doing so optimizes for high availability. Thus, if a single AZ fails, it will only affect a single instance.

    Currently, Amazon DocumentDB instances can be provisioned in up to three AZs. Even if a subnet group has more than three subnets, you will only be able to use three of those subnets to create an Amazon DocumentDB cluster. Therefore, we recommend that when you create a subnet group that you only choose the three subnets of which you want to deploy your instances.

    For example: A cluster is created and Amazon DocumentDB choose AZs {1A, 1B, and 1C}. If you attempt to create an instance in AZ {1D} the API call will fail. However, if you choose to create an instance, without specifying the particular AZ, then Amazon DocumentDB will choose an AZ on your behalf. Amazon DocumentDB uses an algorithm to load balance the instances across AZs to help you achieve high availability. If three instances are provisioned, by default, they will be provisioned across three AZs and will not be provisioned all in a single AZ.

    Best Practices

    • Unless you have a specific reason, always create a subnet group with three subnets. This ensures that clusters with three or more instances will be able to achieve higher availability as instances will be provisioned across three AZs.
    • Always spread instances across multiple AZs to achieve high availability. Never place all instances for a cluster in a single AZ.
    • Because failover events can happen at any time, you should not assume that a primary instance or replica instances will always be in a particular AZ.

    You can use the AWS Management Console or AWS CLI to create an Amazon DocumentDB subnet group.

    Use the following steps to create an Amazon DocumentDB subnet group.

    To create an Amazon DocumentDB subnet group

    1. Sign in to the AWS Management Console, and open the Amazon DocumentDB console at https://console.aws.amazon.com/docdb.

    2. In the navigation pane, choose Subnet groups, then choose Create.

      Tip

      If you don’t see the navigation pane on the left side of your screen, choose the menu icon () in the upper-left corner of the page.

    3. On the Create subnet group page:

        1. Name—Enter a meaningful name for the subnet group.

        2. Description—Enter a description for the subnet group.

      2. In the Add subnets section:

        1. VPC—In the list, choose a VPC for this subnet group.

        2. Do one of the following:

          • To include all subnets in the chosen VPC, choose Add all the subnets related to this VPC.

          • To specify subnets for this subnet group, do the following for each Availability Zone for which you want to include subnets. You must include at least two Availability Zones.

            1. Availability zone—In the list, choose an Availability Zone.

            2. Subnet—In the list, choose a subnet from the chosen Availability Zone for this subnet group.

            3. Choose Add subnet.

    4. Choose Create. When the subnet group is created, it is listed with your other subnet groups.

      ![

    Using the AWS CLI

    Parameters:

    For Linux, macOS, or Unix:

    1. aws docdb describe-db-subnet-groups \
    2.     --db-subnet-group-name default \
    3.     --query 'DBSubnetGroups[*].[DBSubnetGroupName,Subnets[*].[SubnetAvailabilityZone.Name,SubnetIdentifier]]'

    For Windows:

    Output from this operation looks something like the following (JSON format).

    1. [
    2.     [
    3.         "default",
    4.         [
    5.             [
    6.                 "us-east-1a",
    7.                 "subnet-4e26d263"
    8.             ],
    9.             [
    10.                 "us-east-1c",
    11.                 "subnet-afc329f4"
    13.             [
    14.                 "us-east-1e",
    15.                 "subnet-b3806e8f"
    16.             ],
    17.             [
    18.                 "us-east-1d",
    19.             ],
    20.             [
    21.                 "us-east-1b",
    22.                 "subnet-991cb8d0"
    23.             ],
    24.             [
    25.                 "us-east-1f",
    26.                 "subnet-29ab1025"
    28.         ]
    29.     ]
    30. ]

    Using the output from the previous operation, you can create a new subnet group. The new subnet group must include subnets from at least two Availability Zones.

    Parameters:

    • --db-subnet-group-name—Required. The name for this subnet group.

    • --db-subnet-group-description—Required. The description of this subnet group.

    • --subnet-ids—Required. A list of subnets to include in this subnet group. Example: subnet-53ab3636.

    • --Tags—Optional. A list of tags (key-value pairs) to attach to this subnet group.

    The following code creates the subnet group sample-subnet-group with three subnets, subnet-4e26d263, subnet-afc329f4, and subnet-b3806e8f.

    For Linux, macOS, or Unix:

    1. aws docdb create-db-subnet-group ^
    2.     --db-subnet-group-name sample-subnet-group ^
    3.     --db-subnet-group-description "A sample subnet group" ^
    4.     --subnet-ids subnet-4e26d263 subnet-afc329f4 subnet-b3806e8f ^

    Output from this operation looks something like the following (JSON format).