Skip to content
This repository was archived by the owner on Sep 18, 2024. It is now read-only.

Changed name of varibles to make it easier to follow and understand #6

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Changed name of varibles to make it easier to follow and understand #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
156 changes: 81 additions & 75 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,33 +4,32 @@ Repository to help getting started with using MongoDB Atlas with AWS CloudFormat

## Information


This Get-Started project provides a quick and simple way to use the
This Get-Started project provides a quick and simple way to use the
[MongoDB Atlas on AWS](https://aws.amazon.com/quickstart/architecture/mongodb-atlas/) Quick Start
which uses the [MongoDB Atlas CloudFormation resources](https://github.com/mongodb/mongodbatlas-cloudformation-resources/tree/master/cfn-resources)
to provision a complete MongoDB Atlas deployment. This includes:

* 1 MongoDB Atlas project
* 1 MongoDB Atlas M10 cluster
* 1 AWS IAM role
* 1 MongoDB Atlas database user (Type: AWS IAM role)
* 1 MongoDB Atlas project IP Access List entry
- 1 MongoDB Atlas project
- 1 MongoDB Atlas M10 cluster
- 1 AWS IAM role
- 1 MongoDB Atlas database user (Type: AWS IAM role)
- 1 MongoDB Atlas project IP Access List entry

The outputs include an AWS Lambda-ready IAM role and connection string to your MongoDB Atlas cluster.

*NOTE* Running this project will incur charges on AWS and MongoDB Atlas.
_NOTE_ Running this project will incur charges on AWS and MongoDB Atlas.

## Pre-requisites
## Pre-requisites

### AWS Tooling

In order to use this Get-Started project, you need to install the AWS CLI on your machine.
You can download and install from https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html

You will also need an AWS account with appropriate CloudFormation and IAM permissions.
You will also need an AWS account with appropriate CloudFormation and IAM permissions.
Please see the section [AWS IAM Permissions](#aws-iam-permissions) for details.

### Docker
### Docker

You will need to have Docker running on your machine. You can download and install Docker from https://docs.docker.com/install/

Expand All @@ -40,70 +39,75 @@ The best way to manage your MongoDB Atlas API Keys today is via the [mongocli](h

### MongoDB Atlas

In order to execute the code example, you need to:
In order to execute the code example, you need to:

* Sign up for a [MongoDB Atlas account](https://www.mongodb.com/cloud/atlas/register)
* Skip the cluster deployment options
* Go to Billing and add a credit card to your account
* Create an organization-level [MongoDB Atlas Programmatic API Key](https://docs.atlas.mongodb.com/configure-api-access#programmatic-api-keys) with an IP Access List entry. The key needs `Organization Project Creator` permissions.
- Sign up for a [MongoDB Atlas account](https://www.mongodb.com/cloud/atlas/register)
- Skip the cluster deployment options
- Go to Billing and add a credit card to your account
- Create an organization-level [MongoDB Atlas Programmatic API Key](https://docs.atlas.mongodb.com/configure-api-access#programmatic-api-keys) with an IP Access List entry. The key needs `Organization Project Creator` permissions.

Once created, run `mongocli config` and enter the Atlas private API key you just created, along with your Atlas public API key and organization ID.

## Execution Steps
## Execution Steps

### Deploy MongoDB Atlas CFN Resources into your AWS Region

#### `get-setup.sh`

1. Execute the helper shell setup script to complete this step. This will package and deploy the MongoDB Atlas CloudFormation resources into your current default AWS region:
1. Execute the helper shell setup script to complete this step. This will package and deploy the MongoDB Atlas CloudFormation resources into your current default AWS region:

```
./get-setup.sh
```
```
./get-setup.sh
```

You can optionally pass in the AWS region or change your local AWS CLI configuration.
You can optionally pass in the AWS region or change your local AWS CLI configuration.

```
./get-setup.sh us-west-2
```
or
```
aws configure set region eu-west-3
./get-setup.sh
```
Note this step can take up to 45 minutes to run.
Run this step once in each region you wish to use.
```
./get-setup.sh us-west-2
```

or

```
aws configure set region eu-west-3
./get-setup.sh
```

Once complete, you will find a set of CFN Stacks for the MongoDB Atlas resources.
Note this step can take up to 45 minutes to run.
Run this step once in each region you wish to use.

Once complete, you will find a set of CFN Stacks for the MongoDB Atlas resources.

#### `get-started.sh`

2. Execute the helper shell starter script, optionally providing a MongoDB Atlas project name. The output from `get-setup.sh` helper script will inform you of the details for your new MongoDB Atlas deployment, including AWS IAM role and cluster connection string information for you applications. Note this step typically takes 7-10 minutes.
2. Execute the helper shell starter script, optionally providing a MongoDB Atlas project name. The output from `get-setup.sh` helper script will inform you of the details for your new MongoDB Atlas deployment, including AWS IAM role and cluster connection string information for you applications. Note this step typically takes 7-10 minutes.

If you have installed `mongocli`, run:
If you have installed `mongocli`, run:

```
./get-started.sh <GETSTARTED_NAME>
```
```
./get-started.sh <STACK_NAME>
```

Or you can explicitly set the API key or get prompted:
Or you can explicitly set the API key or get prompted:

```
./get-started.sh <PUBLIC_KEY> <PRIVATE_KEY> <ORG_ID> <GETSTARTED_NAME>
```
```
./get-started.sh <PUBLIC_KEY> <PRIVATE_KEY> <ORG_ID> <STACK_NAME>
```

_Note: The <STACK\*NAME> will be the name of the stack in AWS ***and*** the name of the project in MonogDB Atlas._

Once successful, you should be able to access your new deployment through the AWS console, AWS CLI, MongoDB Atlas console, or `mongocli`.
Once successful, you should be able to access your new deployment through the AWS console, AWS CLI, MongoDB Atlas console, or `mongocli`.

## Connecting to your cluster

You can see the connection information in the AWS CloudFormation stack output.

```bash
GETSTARTED_NAME="get-started-aws-quickstart"
STACK_NAME="get-started-aws-quickstart"
MDB=$(aws cloudformation list-exports | \
jq -r --arg stackname "${GETSTARTED_NAME}" \
jq -r --arg stackname "${STACK_NAME}" \
'.Exports[] | select(.Name==$stackname+"-ClusterSrvAddress") | .Value')
echo "Found stack:${GETSTARTED_NAME} with ClusterSrvAddress: ${MDB}"
echo "Found stack:${STACK_NAME} with ClusterSrvAddress: ${MDB}"
```

_Note_ This example requires the `jq` tool. See https://stedolan.github.io/jq/download/.
Expand All @@ -113,63 +117,66 @@ _Note_ This example requires the `jq` tool. See https://stedolan.github.io/jq/do
There is a helper script [test-iam-mongo-connection.sh](./test-iam-mongo-connection.sh) available to script passing AWS IAM session credentials into the `mongo` shell. To use this, pass the STACK_NAME as a parameter:

```bash
./test-iam-mongo-connection.sh NewRoleBased-1
Found stack:NewRoleBased-1 with ClusterSrvAddress: mongodb+srv://cluster-1.5hmwe.mongodb.net
./test-iam-mongo-connection.sh <STACK_NAME>
Found stack:<STACK_NAME> with ClusterSrvAddress: mongodb+srv://cluster-1.5hmwe.mongodb.net
STACK_ROLE={
"StackResources": [
{
"StackName": "NewRoleBased-1",
"StackName": "<STACK_NAME>",
...
MongoDB shell version v4.4.1
connecting to: mongodb://cluster-1-shard-00-00.5hmwe.mongodb.net:27017,cluster-1-shard-00-01.5hmwe.mongodb.net:27017,cluster-1-shard-00-02.5hmwe.mongodb.net:27017/admin?authMechanism=MONGODB-AWS&authmechanismproperties=AWS_SESSION_TOKEN%3AIQoJb3JpZ2luX2VjEMv%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJIMEYCIQDQ4mV7RtfYCLrQwBg
...
PRIMARY>
```
```

## Tear Down
## Tear Down

To remove the environment setup (deleting traces of this get-started project):

* Delete the Quick Start stack from the AWS console or CLI, or by using this helper script:
Delete the Quick Start stack from the AWS console or CLI, or by using the helper script

- Helper script:
```
./teardown.sh <GETSTARTED_NAME>
./teardown.sh <STACK_NAME>
```
- AWS CLI:
- Terminate the `get-started.sh` process if it's running. This is to stop the web service on `localhost:3000`.
- Delete the AWS CloudFormation stack created, by default this will have the <STACK_NAME>:
```
aws cloudformation delete-stack --stack-name <STACK_NAME>
```
- Remove the Docker volumes
- Remove the Docker image

* Terminate the `get-started.sh` process if it's running. This is to stop the web service on `localhost:3000`.
* Delete the AWS CloudFormation stack created, by default this will have the <Quick Start-Name>:
```
aws cloudformation delete-stack --stack-name <Quick Start-Name>
```
* Remove the Docker volumes
* Remove the Docker image

## About

This project is part of the MongoDB Get-Started code examples. Please see [get-started-readme](https://github.com/mongodb-developer/get-started-readme) for more information.
## About

This project is part of the MongoDB Get-Started code examples. Please see [get-started-readme](https://github.com/mongodb-developer/get-started-readme) for more information.

## Developer Notes

Not required unless needing to refesh with latest resource source code.
This will build a fresh image of the resources for stable distribution.

Build Docker image with a tag name. Within the top level directory execute:
```
docker build . -t mongodb-developer/get-started-aws-cfn
```
This will build a docker image with a tag name `get-started-aws-cfn`.
Build Docker image with a tag name. Within the top level directory execute:

```
docker build . -t mongodb-developer/get-started-aws-cfn
```

This will build a docker image with a tag name `get-started-aws-cfn`.

*NOTE* Currently the source repositories are private which will prevent a clean build without proper Github ssh access. A pre-build image has been upload for convience until these repos become public: `mongodb-developer/get-started-aws-cfn`.
_NOTE_ Currently the source repositories are private which will prevent a clean build without proper Github ssh access. A pre-build image has been upload for convience until these repos become public: `mongodb-developer/get-started-aws-cfn`.

To build the container - need this:

```
export DOCKER_BUILDKIT=1
docker build --ssh github=$HOME/.ssh/id_rsa -t atlas-aws .
```

This docker image is currently built internally and published to:


public.ecr.aws/u1r4t8v5/mongodb-developer/get-started-aws-cfn:latest

## Troubleshoot
Expand All @@ -183,13 +190,13 @@ docker run -it public.ecr.aws/u1r4t8v5/mongodb-developer/get-started-aws-cfn "he
# MongoDB Atlas AWS CloudFormation Resources & Quickstart
```

## AWS IAM permissions
## AWS IAM permissions

This project requires various kinds of AWS permissions.
This project requires various kinds of AWS permissions.

To run the setup step (`[get-setup.sh](./get-setup.sh)`) AWS team account owners should be able to assume the [policy-quickstart-mongodb-atlas-installer.yaml](./policy-quickstart-mongodb-atlas-installer.yaml) sample permission set. This step requires above average permissions.

For the started step (`[get-started.sh](./get-started.sh)`) AWS users should be able to assume the [policy-quickstart-mongodb-atlas-user.yaml](./policy-quickstart-mongodb-atlas-user.yaml) sample permission set.
For the started step (`[get-started.sh](./get-started.sh)`) AWS users should be able to assume the [policy-quickstart-mongodb-atlas-user.yaml](./policy-quickstart-mongodb-atlas-user.yaml) sample permission set.

We've included a sample minimal example set of policies, which you can assume safely and use with this project.

Expand All @@ -211,7 +218,6 @@ source <(aws sts assume-role --role-arn arn:aws:iam::<YOUR_AWS_ACCOUNT>:role/Mon

#### AWS::IAM::Role MongoDB-Atlas-CloudFormation-User


```
aws cloudformation create-stack \
--capabilities CAPABILITY_NAMED_IAM \
Expand Down
12 changes: 6 additions & 6 deletions get-started.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,13 @@ if [ $# -lt 2 ]; then
PUBLIC_KEY=$(echo ${MCLI_ARGS} | cut -d' ' -f1)
PRIVATE_KEY=$(echo ${MCLI_ARGS} | cut -d' ' -f2)
ORG_ID=$(echo ${MCLI_ARGS} | cut -d' ' -f3)
QUICKSTART_NAME=${1:-"get-started-aws-quickstart"}
STACK_NAME=${1:-"get-started-aws-quickstart"}
fi
else
PUBLIC_KEY=${1}
PRIVATE_KEY=${2}
ORG_ID=${3}
QUICKSTART_NAME=${4:-"get-started-aws-quickstart"}
STACK_NAME=${4:-"get-started-aws-quickstart"}
fi

if [ -z ${PUBLIC_KEY} ]
Expand All @@ -33,7 +33,7 @@ IMAGE_REPO=${IMAGE_REPO:-public.ecr.aws/u1r4t8v5/}
IMAGE=${IMAGE:-mongodb-developer/get-started-aws-cfn:latest}
IMG="${IMAGE_REPO}${IMAGE}"

echo "Launching new quickstart stack name: ${QUICKSTART_NAME}"
echo "Launching new quickstart stack name: ${STACK_NAME}"
echo "Running Docker image: ${IMG}"
echo "Executing ... "

Expand All @@ -50,9 +50,9 @@ docker run -it --rm \
export ATLAS_PUBLIC_KEY=${PUBLIC_KEY}; \
export ATLAS_PRIVATE_KEY=${PRIVATE_KEY}; \
export ATLAS_ORG_ID=${ORG_ID}; \
export PROJECT_NAME=${QUICKSTART_NAME}; \
./scripts/launch-new-quickstart.sh ${QUICKSTART_NAME}; \
export PROJECT_NAME=${STACK_NAME}; \
./scripts/launch-new-quickstart.sh ${STACK_NAME}; \
echo 'Stack created.';"

echo "Checking stack events from local machine:"
aws cloudformation describe-stack-events --stack-name ${QUICKSTART_NAME} \
aws cloudformation describe-stack-events --stack-name ${STACK_NAME} \
8 changes: 4 additions & 4 deletions teardown.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
#!/usr/bin/env bash

QUICKSTART_NAME=${1:-"get-started-aws-quickstart"}
STACK_NAME=${1:-"get-started-aws-quickstart"}
IMAGE="${2:-atlas-aws}"
echo "Executing ... "
echo "Tearing down quickstart stack name: ${QUICKSTART_NAME}"
echo "Tearing down quickstart stack name: ${STACK_NAME}"

docker run -it --rm \
-v $HOME/.aws:/root/.aws \
-v get-started-aws:/cache \
-v "$(pwd)":/workspace \
-w /workspace/atlas-aws "${IMAGE}" \
"aws cloudformation delete-stack --stack-name ${QUICKSTART_NAME}; \
"aws cloudformation delete-stack --stack-name ${STACK_NAME}; \
echo 'Stack deleted.';"

echo "Checking stack events from local machine:"
aws cloudformation describe-stack-events --stack-name ${QUICKSTART_NAME} \
aws cloudformation describe-stack-events --stack-name ${STACK_NAME} \