# Managing Amazon DocumentDB subnet groups
A virtual private cloud (VPC) is a virtual network dedicated to your AWS account. It is logically isolated from other virtual networks in the AWS Cloud. You can launch your AWS resources, such as Amazon DocumentDB clusters, into your Amazon VPC. You can specify an IP address range for the VPC, add subnets, associate security groups, and configure route tables.
A subnet is a range of IP addresses in your Amazon VPC. You can launch AWS resources into a specified subnet. Use a *public* subnet for resources that must be connected to the internet. Use a *private* subnet for resources that won't be connected to the internet. For more information about public and private subnets, see [VPC and Subnet Basics](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html#vpc-subnet-basics) in the *Amazon Virtual Private Cloud User Guide*.
A DB subnet group is a collection of subnets that you create in a VPC that you then designate for your clusters. A subnet group allows you to specify a particular VPC when creating clusters. If you use the `default` subnet group, it spans all subnets in the VPC.
Each DB subnet group should have subnets in at least two Availability Zones in a given Region. When creating a DB cluster in a VPC, you must select a DB subnet group. Amazon DocumentDB uses that DB subnet group and your preferred Availability Zone to select a subnet and an IP address within that subnet to associate with your cluster. If the primary instance fails, Amazon DocumentDB can promote a corresponding replica instance to be the new primary. It can then create a new replica instance using an IP address of the subnet in which the previous primary was located.
When Amazon DocumentDB creates an instance in a VPC, it assigns a network interface to your cluster by using an IP address selected from your DB subnet group. We strongly recommend that you use the DNS name because the underlying IP address can change during failover. For more information, see [Amazon DocumentDB endpoints](how-it-works.md#how-it-works.endpoints).
For information about creating your own VPC and subnets, see [Working with VPCs and Subnets](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-vpcs.html) in the *Amazon Virtual Private Cloud User Guide*.
**Topics**
+ [Creating an Amazon DocumentDB subnet group](document-db-subnet-group-create.md)
+ [Describing an Amazon DocumentDB subnet group](document-db-subnet-group-describe.md)
+ [Modifying an Amazon DocumentDB subnet group](document-db-subnet-group-modify.md)
+ [Deleting an Amazon DocumentDB subnet group](document-db-subnet-group-delete.md)
# Creating an Amazon DocumentDB subnet group
When creating an Amazon DocumentDB cluster, you must choose a Amazon VPC and corresponding subnet group within that Amazon VPC to launch your cluster. Subnets determine the availability zone and IP range within the availability zone that you want to use to launch an instance.
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 \$11A, 1B, and 1C\$1. If you attempt to create an instance in AZ \$11D\$1 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.
## How to create a subnet group
You can use the AWS Management Console or AWS CLI to create an Amazon DocumentDB subnet group:
------
#### [ Using the AWS Management Console ]
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](https://console.aws.amazon.com/docdb).
1. 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 (![\[Hamburger menu icon with three horizontal lines.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-menu-icon.png)) in the upper-left corner of the page.
1. On the **Create subnet group** page:
1. In the **Subnet group details** section:
1. **Name**—Enter a meaningful name for the subnet group.
1. **Description**—Enter a description for the subnet group.
1. In the **Add subnets** section:
1. **VPC**—In the list, choose a VPC for this subnet group.
1. 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.
1. **Subnet**—In the list, choose a subnet from the chosen Availability Zone for this subnet group.
1. Choose **Add subnet**.
1. Choose **Create**. When the subnet group is created, it is listed with your other subnet groups.
![\[Screenshot: Showing the details of a subnet group.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-subnet-groups-list.png)
------
#### [ Using the AWS CLI ]
Before you can create a subnet group using the AWS CLI, you must first determine which subnets are available. Run the following AWS CLI operation to list the Availability Zones and their subnets.
**Parameters:**
+ **--db-subnet-group**—Optional. Specifying a particular subnet group lists the Availability Zones and subnets for that group. Omitting this parameter lists Availability Zones and subnets for all your subnet groups. Specifying the `default` subnet group lists all the VPC's subnets.
**Example**
For Linux, macOS, or Unix:
```
aws docdb describe-db-subnet-groups \
--db-subnet-group-name default \
--query 'DBSubnetGroups[*].[DBSubnetGroupName,Subnets[*].[SubnetAvailabilityZone.Name,SubnetIdentifier]]'
```
For Windows:
```
aws docdb describe-db-subnet-groups ^
--db-subnet-group-name default ^
--query 'DBSubnetGroups[*].[DBSubnetGroupName,Subnets[*].[SubnetAvailabilityZone.Name,SubnetIdentifier]]'
```
Output from this operation looks something like the following (JSON format).
```
[
[
"default",
[
[
"us-east-1a",
"subnet-4e26d263"
],
[
"us-east-1c",
"subnet-afc329f4"
],
[
"us-east-1e",
"subnet-b3806e8f"
],
[
"us-east-1d",
"subnet-53ab3636"
],
[
"us-east-1b",
"subnet-991cb8d0"
],
[
"us-east-1f",
"subnet-29ab1025"
]
]
]
]
```
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:
```
aws docdb create-db-subnet-group \
--db-subnet-group-name sample-subnet-group \
--db-subnet-group-description "A sample subnet group" \
--subnet-ids subnet-4e26d263 subnet-afc329f4 subnet-b3806e8f \
--tags Key=tag1,Value=One Key=tag2,Value=2
```
For Windows:
```
aws docdb create-db-subnet-group ^
--db-subnet-group-name sample-subnet-group ^
--db-subnet-group-description "A sample subnet group" ^
--subnet-ids subnet-4e26d263 subnet-afc329f4 subnet-b3806e8f ^
--tags Key=tag1,Value=One Key=tag2,Value=2
```
Output from this operation looks something like the following (JSON format).
```
{
"DBSubnetGroup": {
"DBSubnetGroupDescription": "A sample subnet group",
"DBSubnetGroupName": "sample-subnet-group",
"Subnets": [
{
"SubnetAvailabilityZone": {
"Name": "us-east-1a"
},
"SubnetIdentifier": "subnet-4e26d263",
"SubnetStatus": "Active"
},
{
"SubnetAvailabilityZone": {
"Name": "us-east-1c"
},
"SubnetIdentifier": "subnet-afc329f4",
"SubnetStatus": "Active"
},
{
"SubnetAvailabilityZone": {
"Name": "us-east-1e"
},
"SubnetIdentifier": "subnet-b3806e8f",
"SubnetStatus": "Active"
}
],
"VpcId": "vpc-91280df6",
"DBSubnetGroupArn": "arn:aws:rds:us-east-1:123SAMPLE012:subgrp:sample-subnet-group",
"SubnetGroupStatus": "Complete"
}
}
```
------
# Describing an Amazon DocumentDB subnet group
You can use the AWS Management Console or the AWS CLI to get the details of an Amazon DocumentDB subnet group.
------
#### [ Using the AWS Management Console ]
The following procedure shows you how to get the details of an Amazon DocumentDB subnet group.
**To find the details of a subnet group**
1. Sign in to the AWS Management Console, and open the Amazon DocumentDB console at [https://console.aws.amazon.com/docdb](https://console.aws.amazon.com/docdb).
1. In the navigation pane, choose **Subnet groups**.
**Tip**
If you don't see the navigation pane on the left side of your screen, choose the menu icon (![\[Hamburger menu icon with three horizontal lines.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-menu-icon.png)) in the upper-left corner of the page.
1. To see the details of a subnet group, choose the name of that subnet group.
![\[Screenshot: Showing the details of a subnet group.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-subnet-group-details.png)
------
#### [ Using the AWS CLI ]
To find the details of an Amazon DocumentDB subnet group, use the `describe-db-subnet-groups` operation with the following parameter.
**Parameter**
+ `--db-subnet=group-name`—Optional. If included, details for the named subnet group are listed. If omitted, details for up to 100 subnet groups are listed.
**Example**
The following code lists details for the `sample-subnet-group` subnet group that we created in the [Creating an Amazon DocumentDB subnet group](document-db-subnet-group-create.md) section.
For Linux, macOS, or Unix:
```
aws docdb describe-db-subnet-groups \
--db-subnet-group-name sample-subnet-group
```
For Windows:
```
aws docdb describe-db-subnet-groups ^
--db-subnet-group-name sample-subnet-group
```
Output from this operation looks something like the following (JSON format).
```
{
"DBSubnetGroup": {
"DBSubnetGroupArn": "arn:aws:rds:us-east-1:123SAMPLE012:subgrp:sample-subnet-group",
"VpcId": "vpc-91280df6",
"SubnetGroupStatus": "Complete",
"DBSubnetGroupName": "sample-subnet-group",
"Subnets": [
{
"SubnetAvailabilityZone": {
"Name": "us-east-1a"
},
"SubnetStatus": "Active",
"SubnetIdentifier": "subnet-4e26d263"
},
{
"SubnetAvailabilityZone": {
"Name": "us-east-1c"
},
"SubnetStatus": "Active",
"SubnetIdentifier": "subnet-afc329f4"
},
{
"SubnetAvailabilityZone": {
"Name": "us-east-1e"
},
"SubnetStatus": "Active",
"SubnetIdentifier": "subnet-b3806e8f"
}
],
"DBSubnetGroupDescription": "A sample subnet group"
}
}
```
------
# Modifying an Amazon DocumentDB subnet group
You can use the AWS Management Console or AWS CLI to modify a subnet group's description or to add or remove subnets from an Amazon DocumentDB subnet group. However, you cannot modify the `default` subnet group.
------
#### [ Using the AWS Management Console ]
You can use the AWS Management Console to change a subnet group's description or to add and remove subnets. Remember that when you're finished, you must have at least two Availability Zones associated with your subnet group.
**To modify your subnet group**
1. Sign in to the AWS Management Console, and open the Amazon DocumentDB console at [https://console.aws.amazon.com/docdb](https://console.aws.amazon.com/docdb).
1. In the navigation pane, choose **Subnet groups**. Then choose the button to the left of the subnet group's name. Remember that you can't modify the `default` subnet group.
**Tip**
If you don't see the navigation pane on the left side of your screen, choose the menu icon (![\[Hamburger menu icon with three horizontal lines.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-menu-icon.png)) in the upper-left corner of the page.
1. Choose **Actions**, and then choose **Modify**.
1. **Description**—To change the description of your subnet group, enter a new description.
1. To change the subnets associated with your subnet group, in the **Add subnets** section, do any one or more of the following:
+ To remove all subnets from this subnet group, choose **Remove all**.
+ To remove specific subnets from this subnet group, choose **Remove** for each subnet you want to remove.
+ To add all the subnets associated with this VPC, choose **Add all the subnets related to this VPC**.
+ To add specific subnets to this subnet group, do the following for each Availability Zone for which you want to add a subnet.
1. **Availability zone**—In the list, choose a new Availability Zone.
1. **Subnet**—In the list, choose a subnet from the chosen Availability Zone for this subnet group.
1. Choose **Add subnet**.
1. In the confirmation dialog box:
+ To make these changes to the subnet group, choose **Modify**.
+ To keep the subnet group unchanged, choose **Cancel**.
------
#### [ Using the AWS CLI ]
You can use the AWS CLI to change a subnet group's description or to add and remove subnets. Remember that when you're finished, you must have at least two Availability Zones associated with your subnet group. You can't modify the `default` subnet group.
**Parameters:**
+ `--db-subnet-group-name`—Required. The name of the Amazon DocumentDB subnet group you are modifying.
+ `--subnet-ids`—Required. A list of all the subnets that you want in the subnet group after this change is done.
**Important**
Any subnets currently in the subnet group that are not included in this list are removed from the subnet group. If you want to keep any of the subnets currently in the subnet group, you must include them in this list.
+ `--db-subnet-group-description`—Optional. The description of the subnet group.
**Example**
The following code modifies the description and replaces the existing subnets with the subnets `subnet-991cb8d0`, `subnet-53ab3636`, and `subnet-29ab1025`.
For Linux, macOS, or Unix:
```
aws docdb modify-db-subnet-group \
--db-subnet-group-name sample-subnet-group \
--subnet-ids subnet-991cb8d0 subnet-53ab3636 subnet-29ab1025 \
--db-subnet-group-description "Modified subnet group"
```
For Windows:
```
aws docdb modify-db-subnet-group ^
--db-subnet-group-name sample-subnet-group ^
--subnet-ids subnet-991cb8d0 subnet-53ab3636 subnet-29ab1025 ^
--db-subnet-group-description "Modified subnet group"
```
Output from this operation looks something like the following (JSON format). Notice that this is the same subnet group that was created in the [Creating an Amazon DocumentDB subnet group](document-db-subnet-group-create.md) section. However, the subnets in the subnet group are replaced with those listed in the `modify-db-subnet-group` operation.
```
{
"DBSubnetGroup": {
"DBSubnetGroupArn": "arn:aws:rds:us-east-1:123SAMPLE012:subgrp:sample-subnet-group",
"DBSubnetGroupDescription": "Modified subnet group",
"SubnetGroupStatus": "Complete",
"Subnets": [
{
"SubnetAvailabilityZone": {
"Name": "us-east-1d"
},
"SubnetStatus": "Active",
"SubnetIdentifier": "subnet-53ab3636"
},
{
"SubnetAvailabilityZone": {
"Name": "us-east-1b"
},
"SubnetStatus": "Active",
"SubnetIdentifier": "subnet-991cb8d0"
},
{
"SubnetAvailabilityZone": {
"Name": "us-east-1f"
},
"SubnetStatus": "Active",
"SubnetIdentifier": "subnet-29ab1025"
}
],
"VpcId": "vpc-91280df6",
"DBSubnetGroupName": "sample-subnet-group"
}
}
```
------
# Deleting an Amazon DocumentDB subnet group
You can use the AWS Management Console or AWS CLI to delete an Amazon DocumentDB subnet group. However, you cannot delete the `default` subnet group.
------
#### [ Using the AWS Management Console ]
You can use the AWS Management Console to delete a subnet group. But you can't delete the `default` subnet group.
**To delete a subnet group**
1. Sign in to the AWS Management Console, and open the Amazon DocumentDB console at [https://console.aws.amazon.com/docdb](https://console.aws.amazon.com/docdb).
1. In the navigation pane, choose **Subnet groups**. Then choose the button to the left of the subnet group's name. Remember that you can't delete the `default` subnet group.
**Tip**
If you don't see the navigation pane on the left side of your screen, choose the menu icon (![\[Hamburger menu icon with three horizontal lines.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-menu-icon.png)) in the upper-left corner of the page.
1. Choose **Actions**, and then choose **Delete**.
1. In the confirmation dialog box:
+ To delete the subnet group, choose **Delete**.
+ To keep the subnet group, choose **Cancel**.
------
#### [ Using the AWS CLI ]
To delete an Amazon DocumentDB subnet group using the AWS CLI, use the `delete-db-subnet-group` operation with the following parameter.
**Parameter**
+ `--db-subnet-group-name`—Required. The name of the Amazon DocumentDB subnet group to delete. Remember that you can't delete the `default` subnet group.
**Example**
The following code deletes `sample-subnet-group`.
For Linux, macOS, or Unix:
```
aws docdb delete-db-subnet-group \
--db-subnet-group-name sample-subnet-group
```
For Windows:
```
aws docdb delete-db-subnet-group ^
--db-subnet-group-name sample-subnet-group
```
This operation produces no output.
------