diff --git a/README.md b/README.md index b848fbf..342ae1a 100644 --- a/README.md +++ b/README.md @@ -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/ @@ -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 - ``` + ``` + ./get-started.sh + ``` -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 - ``` + ``` + ./get-started.sh + ``` + + _Note: The 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/. @@ -113,55 +117,59 @@ _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 +Found stack: with ClusterSrvAddress: mongodb+srv://cluster-1.5hmwe.mongodb.net STACK_ROLE={ "StackResources": [ { - "StackName": "NewRoleBased-1", + "StackName": "", ... 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 + ./teardown.sh ``` +- 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 : + ``` + aws cloudformation delete-stack --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 : - ``` - aws cloudformation delete-stack --stack-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 . @@ -169,7 +177,6 @@ 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 @@ -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. @@ -211,7 +218,6 @@ source <(aws sts assume-role --role-arn arn:aws:iam:::role/Mon #### AWS::IAM::Role MongoDB-Atlas-CloudFormation-User - ``` aws cloudformation create-stack \ --capabilities CAPABILITY_NAMED_IAM \ diff --git a/get-started.sh b/get-started.sh index bf7a00f..4d8aab9 100755 --- a/get-started.sh +++ b/get-started.sh @@ -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} ] @@ -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 ... " @@ -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} \ diff --git a/teardown.sh b/teardown.sh index 08eb0c8..d57d432 100755 --- a/teardown.sh +++ b/teardown.sh @@ -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} \