# Understanding Amazon DocumentDB endpoints
You can use Amazon DocumentDB (with MongoDB compatibility) endpoints to connect to a cluster or instance. Amazon DocumentDB has three different types of endpoints, each with its own purpose.
**Topics**
+ [Finding a cluster's endpoints](db-cluster-endpoints-find.md)
+ [Finding an instance's endpoint](db-instance-endpoint-find.md)
+ [Connecting to endpoints](endpoints-connecting.md)
**Cluster endpoint**
A cluster endpoint is an endpoint for an Amazon DocumentDB cluster that connects to the current primary instance for the cluster. Each Amazon DocumentDB cluster has a single cluster endpoint and one primary instance. In case of a failover, the cluster endpoint is remapped to the new primary instance.
**Reader endpoint**
A reader endpoint is an endpoint for an Amazon DocumentDB cluster that connects to one of the available replicas for that cluster. Each Amazon DocumentDB cluster has a reader endpoint. If there is more than one replica, the reader endpoint directs each connection request to one of the Amazon DocumentDB replicas.
**Instance endpoint**
An instance endpoint is an endpoint that connects to a specific instance. Each instance in a cluster, regardless of whether it is a primary or replica instance, has its own unique instance endpoint. It is best to not use instance endpoints in your application. This is because they can change roles in case of a failover, thus requiring code changes in your application.
# Finding a cluster's endpoints
You can find a cluster's cluster endpoint and reader endpoint using the Amazon DocumentDB console or AWS CLI.
------
#### [ Using the AWS Management Console ]
**To find a cluster's endpoints using the console:**
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 **Clusters**.
1. From the list of clusters, choose the name of the cluster you are interested in.
1. On the cluster details page, select the **Configuration** tab. In the **Configurations and status** section, you will find the **Cluster endpoint** and **Reader endpoint**.
![\[Configurations and status section showing the cluster and reader endpoints.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/db-cluster-endpoints.png)
1. To connect to this cluster, select the **Connectivity & security** tab. Locate the connection string for the `mongo` shell and the connection string that can be used in the application code to connect to your cluster.
![\[Connect section showing a string to connect to the instance with the mongo shell and a string to connect to the cluster with an application.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/cluster-connection-strings.png)
------
#### [ Using the AWS CLI ]
To find the cluster and reader endpoints for your cluster using the AWS CLI, run the `describe-db-clusters` command with these parameters.
**Parameters**
+ **--db-cluster-identifier**—Optional. Specifies the cluster to return endpoints for. If omitted, returns endpoints for up to 100 of your clusters.
+ **--query**—Optional. Specifies the fields to display. Helpful by reducing the amount of data that you need to view to find the endpoints. If omitted, all information about a cluster is returned.
+ **--region**—Optional. Use the `--region` parameter to specify the Region that you want to apply the command to. If omitted, your default Region is used.
**Example**
The following example returns the `DBClusterIdentifier`, endpoint (cluster endpoint), and `ReaderEndpoint` for `sample-cluster`.
For Linux, macOS, or Unix:
```
aws docdb describe-db-clusters \
--region us-east-1 \
--db-cluster-identifier sample-cluster \
--query 'DBClusters[*].[DBClusterIdentifier,Port,Endpoint,ReaderEndpoint]'
```
For Windows:
```
aws docdb describe-db-clusters ^
--region us-east-1 ^
--db-cluster-identifier sample-cluster ^
--query 'DBClusters[*].[DBClusterIdentifier,Port,Endpoint,ReaderEndpoint]'
```
Output from this operation looks something like the following (JSON format).
```
[
[
"sample-cluster",
27017,
"sample-cluster.cluster-corlsfccjozr.us-east-1.docdb.amazonaws.com",
"sample-cluster.cluster-ro-corlsfccjozr.us-east-1.docdb.amazonaws.com"
]
]
```
Now that you have the cluster endpoint, you can connect to the cluster using either `mongo` or `mongodb`. For more information, see [Connecting to endpoints](endpoints-connecting.md).
------
# Finding an instance's endpoint
You can find the endpoint for an instance using the Amazon DocumentDB console or the AWS CLI.
------
#### [ Using the AWS Management Console ]
**To find an instance's endpoint using the console**
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 **Clusters**.
**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. In the Clusters navigation box, you’ll see the column **Cluster Identifier**. Your instances are listed under clusters, similar to the screenshot below.
![\[Clusters table showing list of clusters under Cluster identifier column, with instances nested inside clusters.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/choose-clusters.png)
1. Check the box to the left of the instance you are interested in.
1. Scroll down to the **Details** section then locate the instance endpoint.
![\[Console screenshot showing the details page with the instance endpoint highlighted.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/db-instance-endpoint.png)
1. To connect to this instance, scroll up to the **Connect** section. Locate the connection string for the `mongo` shell and a connection string that can be used in your application code to connect to your instance.
![\[Console screenshot showing the Connect section with mongo shell and application connection strings highlighted.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/instance-connection-strings.png)
------
#### [ Using the AWS CLI ]
To find the instance endpoint using the AWS CLI, run the following command with these arguments.
**Arguments**
+ **--db-instance-identifier**—Optional. Specifies the instance to return the endpoint for. If omitted, returns the endpoint for up to 100 of your instances.
+ **--query**—Optional. Specifies the fields to display. Helpful by reducing the amount of data that you need to view to find the endpoints. If omitted, all information on an instance is returned. The `Endpoint` field has three members, so listing it in the query as in the following example returns all three members. If you're only interested in some of the `Endpoint` members, replace `Endpoint` in the query with the members you're interested in, as in the second example.
+ **--region**—Optional. Use the `--region` parameter to specify the Region that you want to apply the command to. If omitted, your default Region is used.
**Example**
For Linux, macOS, or Unix:
```
aws docdb describe-db-instances \
--region us-east-1 \
--db-instance-identifier sample-cluster-instance \
--query 'DBInstances[*].[DBInstanceIdentifier,Endpoint]'
```
For Windows:
```
aws docdb describe-db-instances ^
--region us-east-1 ^
--db-instance-identifier sample-cluster-instance ^
--query 'DBInstances[*].[DBInstanceIdentifier,Endpoint]'
```
Output from this operation looks something like the following (JSON format).
```
[
[
"sample-cluster-instance",
{
"Port": 27017,
"Address": "sample-cluster-instance.corcjozrlsfc.us-east-1.docdb.amazonaws.com",
"HostedZoneId": "Z2R2ITUGPM61AM"
}
]
]
```
Reducing the output to eliminate the endpoint's `HostedZoneId`, you can modify your query by specifying `Endpoint.Port` and `Endpoint.Address`.
For Linux, macOS, or Unix:
```
aws docdb describe-db-instances \
--region us-east-1 \
--db-instance-identifier sample-cluster-instance \
--query 'DBInstances[*].[DBInstanceIdentifier,Endpoint.Port,Endpoint.Address]'
```
For Windows:
```
aws docdb describe-db-instances ^
--region us-east-1 ^
--db-instance-identifier sample-cluster-instance ^
--query 'DBInstances[*].[DBInstanceIdentifier,Endpoint.Port,Endpoint.Address]'
```
Output from this operation looks something like the following (JSON format).
```
[
[
"sample-cluster-instance",
27017,
"sample-cluster-instance.corcjozrlsfc.us-east-1.docdb.amazonaws.com"
]
]
```
Now that you have the instance endpoint, you can connect to the instance using either `mongo` or `mongodb`. For more information, see [Connecting to endpoints](endpoints-connecting.md).
------
# Connecting to endpoints
When you have your endpoint, either cluster or instance, you can connect to it using the `mongo` shell or a connection string.
## Connecting using the mongo shell
Use the following structure to construct the string that you need to connect to your cluster or instance using the `mongo` shell:
```
mongo \
--ssl \
--host Endpoint:Port \
--sslCAFile global-bundle.pem \
--username UserName \
--password Password
```
**`mongo` shell examples**
Connect to a cluster:
```
mongo \
--ssl \
--host sample-cluster.corcjozrlsfc.us-east-1.docdb.amazonaws.com:27017 \
--sslCAFile global-bundle.pem \
--username UserName \
--password Password
```
Connect to an instance:
```
mongo \
--ssl \
--host sample-cluster-instance.corcjozrlsfc.us-east-1.docdb.amazonaws.com:27017 \
--sslCAFile global-bundle.pem \
--username UserName \
--password Password
```
## Connecting using a connection string
Use the following structure to construct the connection string that you need to connect to your cluster or instance.
```
mongodb://UserName:Password@endpoint:port?replicaSet=rs0&ssl_ca_certs=global-bundle.pem
```
**Connection string examples**
Connect to a cluster:
```
mongodb://UserName:Password@sample-cluster.cluster-corlsfccjozr.us-east-1.docdb.amazonaws.com:27017?replicaSet=rs0&ssl_ca_certs=global-bundle.pem
```
Connect to an instance:
```
mongodb://UserName:Password@sample-cluster-instance.cluster-corlsfccjozr.us-east-1.docdb.amazonaws.com:27017?replicaSet=rs0&ssl_ca_certs=global-bundle.pem
```