Skip to content

Latest commit

 

History

History
121 lines (96 loc) · 7.35 KB

setup.md

File metadata and controls

121 lines (96 loc) · 7.35 KB
Raw

Amazon DocumentDB ODBC Driver Setup

Topics

Prerequisites

DocumentDB Cluster

If you don't already have an Amazon DocumentDB cluster, there are a number of ways to get started.

Note that DocumentDB is a Virtual Private Cloud (VPC) only service. If you will be connecting from a local machine outside the cluster's VPC, you will need to create an SSH connection to an Amazon EC2 instance. In this case, launch your cluster using the instructions in Connect with EC2. See Using an SSH Tunnel to Connect to Amazon DocumentDB for more information on SSH tunneling and when you might need it.

JRE or JDK

Depending on your BI application, you may need to ensure a 64-bit JRE or JDK installation version 8 or later is installed on your computer. You can download the Java SE Runtime Environment 8 here.

DocumentDB ODBC Driver

Download the DocumentDB ODBC driver here. Choose the proper installer. (e.g., documentdb-odbc-1.0.0.msi). Follow the installation guide

Specifying the Amazon RDS Certificate Authority Certificate File

If you are connecting to a TLS-enabled cluster, you may want to specify the Amazon RDS Certificate Authority certificate on your connection string. By default, an Amazon RDS Certificate Authority root certificate has been embedded in the ODBC driver which should work when connecting to Amazon DocumentDB clusters using SSL/TLS encryption. However, if you want to provide a new Amazon RDS Certificate Authority root certificate, follow the directions below:

  1. Download the root CA certificate

  2. It is recommended to relocate the file to your user's home directory: $HOME for Windows or ~ for MacOS/Linux.

  3. Add the TLS_CA_FILE option to your ODBC connection string. For example:

    DRIVER={Amazon DocumentDB};HOSTNAME=localhost:27017;DATABASE=customer;TLS_ALLOW_INVALID_HOSTNAMES=true;TLS_CA_FILE=rds-ca-2019-root.pem

To determine whether your cluster is TLS-enabled, you can check the value of your cluster's tls parameter.

Using an SSH Tunnel to Connect to Amazon DocumentDB

Amazon DocumentDB (with MongoDB compatibility) clusters are deployed within an Amazon Virtual Private Cloud (Amazon VPC). They can be accessed directly by Amazon EC2 instances or other AWS services that are deployed in the same Amazon VPC. Additionally, Amazon DocumentDB can be accessed by EC2 instances or other AWS services in different VPCs in the same AWS Region or other Regions via VPC peering.

However, suppose that your use case requires that you (or your application) access your Amazon DocumentDB resources from outside the cluster's VPC. This will be the case for most users not running their application on a VM in the same VPC as the DocumentDB cluster. When connecting from outside the VPC, you can use SSH tunneling (also known as port forwarding) to access your Amazon DocumentDB resources.

There are two options to create an SSH tunnel:

  1. Internally, using the SSH tunnel options (minimally, sshUser, sshHost, and sshPrivateKeyFile).
  2. Externally, using the ssh application. For further information on creating an external SSH tunnel, please refer to the documentation on Connecting from Outside an Amazon VPC

The ODBC Connection String When Using an SSH Tunnel

To create an SSH tunnel, you need an Amazon EC2 instance running in the same Amazon VPC as your Amazon DocumentDB cluster. You can either use an existing EC2 instance in the same VPC as your cluster or create one. Connecting from outside the Amazon VPC using an SSH tunnel will have the following impact on the ODBC connection string:

  1. If your cluster has Transport Layer Security (TLS) enabled, you will need to add the tlsAllowInvalidHostNames=true option.
  2. For external SSH, since the SSH tunnel is running on your local computer, the host name must be set to localhost.
  3. For external SSH, if your local port (-L <local-port>:<cluster-host>:<remote-port>) configured for the SSH tunnel is not the default port (27017) for Amazon DocumentDB, ensure the connection string host setting for your SSH tunnel is properly set in the ODBC connection string.
  4. The REPLICA_SET option is not supported when using an SSH tunnel.

Using an External SSH Tunnel to Connect to Amazon DocumentDB

Start an SSH port-forwarding tunnel to the cluster with the following command:

ssh -i <ssh-key-pair-filename>.pem -N -L <local-port>:<cluster-host>:<remote-port> <ec2-username>@<public-IPv4-DNS-name>
  • The -L flag defines the port forwarded to the remote host and remote port. Adding the -N flag means do not execute a remote command
  • Ensure you have read access permission for the file <ssh-key-pair-filename>.pem. To enable read access permission you can run the following command: chmod 400 <ssh-key-pair-filename>.pem.

This is a prerequisite for connecting to any BI tool running on a client outside your VPC.

Example: Given the following

  • <cluster-host> = sample-cluster.node.us-east-1.docdb.amazonaws.com

  • <public-IPv4-DNS-name> = ec2-34-229-221-164.compute-1.amazonaws.com

  • <local-port> = 27117

  • <remote-port> = 27017

  • <ssh-key-pair-filename>.pem = ~/.ssh/ec2Access.pem

  • <ec2-username> = ubuntu

    The SSH tunnel command would look like:

    ssh -i ~/.ssh/ec2Access.pem -N -L 27117:sample-cluster.node.us-east-1.docdb.amazonaws.com:27017 [email protected]

    The ODBC connection string for connecting to the TLS-enabled Amazon DocumentDB cluster with <database-name> = customer would look like:

    DRIVER={Amazon DocumentDB};HOSTNAME=localhost:27117;DATABASE=customer;TLS_ALLOW_INVALID_HOSTNAMES=true

For further information on SSH tunneling , please refer to the documentation on Connecting from Outside an Amazon VPC.

Driver Setup in BI Applications

The ODBC driver is compatible with a number of BI tools. Instructions are outlined here for:

  1. Microsoft Power BI

For other BI tools, please refer to that tool's product documentation.