Repository files navigation

UseAWS CloudFormation to manageMongoDB Atlas. See ourdocumentation for quick starts and common questions. For a list of supported resources, seehere.

See thecfn examples to setup prerequisites and get started with your first cluster using our sample CloudFormation Stack templates. Follow the steps inActivate the MongoDB Atlas CloudFormation public extensions for each AWS Account and Region where you want to deploy your MongoDB Atlas resources.

See thecdk examples to setup prerequisites and get started with your first cluster using our AWS CDK sample code.

1. Any third-party resource must support all CRUD operations. MongoDB Atlas for CloudFormation does not support the following MongoDB Atlas resources because they do not support all CRUD operations:

• cloud-backup-snapshot-export-job
• cloud-provider-access
• federated-settings-identity-provider
• federated-settings-org-configs

CloudFormation import is supported for MongoDB Atlas resources. This allows you to bring existing resources under CloudFormation management. For more details, please seeResource Import Operations section.

Feature requests can be submitted atfeedback.mongodb.com - just select "Atlas CloudFormation Resources" as the category or vote for an already suggested feature.

Support for the MongoDB Atlas Resource Provider for CloudFormation is provided under MongoDB Atlas support plans, starting with Developer. Please submit support questions via theSupport Portal. Support questions submitted under the Issues section of this repo are monitored but have no SLA and are best effort. Bugs should be filed under the Issues section of this repo.

Please note:

• In order to ensure the highest quality experience and support, we only support resources published via theAWS Cloudformation Third Party registry (select "Third party" asProvider and search by "MongoDB::Atlas"). Any usage outside of this workflow is not supported or recommended.

• New features, functionality, and fix bugs are only included in the latest release. Hence, we strongly encourage all users to always update to the latest version to benefit from these improvements. See theUpgrade the MongoDB Atlas CloudFormation public extensions for how to upgrade.

Atlas API keys Configuration are required for both CloudFormation and CDK resources, and this Atlas API key pair are provided as input by the use of a Profile

AWS CloudFormation limits Third Parties from using non-AWS API Keys as either hardcoded secrets in CloudFormation templates or via CDK, hence we now require all the users store MongoDB Atlas API Keys viaAWS Secrets Manager.

NOTE: the process for configuring the PROFILE is the same and is required both for CloudFormation and CDK

You'll need to generate an API key pair (public and private keys) for your Atlas organization and configure them to grant CloudFormation access to your Atlas project.Refer to theAtlas documentation for detailed instructions.

To use Atlas CloudFormation resources, you must configure a "profile" with your API keys usingAWS Secrets Manager.

The secret should follow this format:

SecretName: cfn/atlas/profile/{ProfileName}SecretValue: {"PublicKey": "YourPublicKey", "PrivateKey": "YourPrivateKey"}

To create a new secret for a default profile, use thePROFILE SECRET TEMPLATE file provided in this repository.The secret must exist in the same AWS account and AWS region where the Cloudformation stack is run.

Here are some examples of how to use this template:

  ProfileName: default  SecretName: cfn/atlas/profile/default  SecretValue = {"PublicKey": "YourPublicKey", "PrivateKey": "YourPrivateKey"}

  ProfileName: testProfile  SecretName: cfn/atlas/profile/testProfile  SecretValue = {"PublicKey": "YourPublicKey", "PrivateKey": "YourPrivateKey"}

Note: If you want to use an AWS KMS key to handle encryption of your secret, see theConfigure your KMS Key Policy documentation.

All Atlas CloudFormation resources include a "Profile" property that specifies which profile to use. You'll need to provide the profile you created in the previous step to the CloudFormation template.

Note that if you don't provide a profile, the resource will use a default profile (will try to get a secret named cfn/atlas/profile/default). We recommend always specifying the profile to avoid any unexpected behavior.

Once you've provided the profile, you can deploy the CloudFormation stack using the AWS Console or the AWS CLI. Refer to the AWS documentation for instructions on how to deploy CloudFormation stacks.

IMPORTANT: when specifying the profile in your CloudFormation template, you must specify the Profile Name, NOT the Secret Name

Correct usage:

  "Profile" : "ProfileName"

Incorrect usage:

  "Profile" : "cfn/atlas/profile/ProfileName"

Logging for AWS CloudFormation Public extensions is currently disabled. AWS is evaluating if logging is useful for consumers of third party extensions, if this is something you need or would like to request please open a ticket directly with AWS Support.

See ourCONTRIBUTING.md guide.

• After 5 days of no activity (no comments or commits on an issue/PR) we automatically tag it as "stale" and add a message:This issue/PR has gone 5 days without any activity and meets the project's definition of "stale". This will be auto-closed if there is no new activity over the next 5 days. If the issue is still relevant and active, you can simply comment with a "bump" to keep it open, or add the label "not_stale". Thanks for keeping our repository healthy!
• After 5 more days of no activity we automatically close the issue/PR.

Our support will prioritise issues that contain all the required information that follows the following principles:

• We should be able to make no changes to your provided script andsuccessfully run a local execution reproducing the issue.
  • This means that you should kindlyprovide all the required instructions. This includes but not limited to:
    • CFN resource template used to reproduce the issue
    • CFN resource version and AWS region used to reproduce the issue
  • Issues thatcannot be properly reproduced will be de-prioritised in favour of the ones that succeed.
• Before opening an issue, you have to try to specifically isolate it to theCFN MongoDB Atlas resource byremoving as many dependencies as possible. If the issue only happens with other dependencies, then:
  • If other CFN resources are required, please make sure you also include those.Same "one-click reproducible issue" principle applies.
  • If external components are required to replicate it, please make sure you also provides instructions on those parts.

The following are common issues encountered when using AWS CloudFormation/CDK with MongoDB Atlas Resources:

1. Activate the 3rd-party extension for each resource (i.e.MONGODB::ATLAS::[RESOURCE-NAME]) in each AWS region and from each AWS account that you wish to deploy.
2. Ensure you have a sufficiently strong AWS IAM Activation Role attached to each 3rd-party extension.
   • For sample IAM Role seehere
3. Ensure your activated 3rd-party public extension matches name exactly toMONGODB::ATLAS::[RESOURCE-NAME].
   • You might need to delete private extension if this namespace is already occupied.
4. Ensure your MongoDB Atlas Programmatic API Keys (PAKs) being used with CloudFormation have sufficiently strong permissions (Organization Project Creator or Organization Owner)
5. Ensure your MongoDB Atlas PAKs have correct IP Address / CIDR range access.
   • For testing purposes with caution you can open keys to all access by adding “0.0.0.0/1” and “128.0.0.0/1” (do not use for production workloads).
6. How to determine which IP address AWS CloudFormation uses to deploy MongoDB Atlas resouces with my Atlas Programmatic API Keys (PAK)?
   • When you deploy MongoDB Atlas using CloudFormation with your Atlas PAK, CloudFormation will default to use the IP address of the machine that you are making the API call from.
   • The machine making the API call to the 3rd-party MongoDB Atlas API would be various AWS servers hosting Lambda functions and won't be static.
   • Review theAWS IP address ranges and contact AWS Support directly who can help confirm the CIDR range to be used in your Atlas PAK IP Whitelist.

The problem might be due to the IAM role:

1. Misconfigured IAM Role's trust relationship
2. Activate Type IAM Role deleted

The problem is caused by incorrect trust relationships linked to the role that you used to activate CFN resources or run the CFN stack. To resolve the issue, ensure that your IAM role's trust relationships includeresources.cloudformation.amazonaws.com,cloudformation.amazonaws.com,lambda.amazonaws.com. The following YAML code shows an example of the correct trust relationships:

AssumeRolePolicyDocument:Version:'2012-10-17'Statement:    -Effect:AllowPrincipal:Service:       -lambda.amazonaws.com       -resources.cloudformation.amazonaws.com       -cloudformation.amazonaws.comAction:sts:AssumeRole

Use theexecution-role.yaml file to generate an IAM role that you can use to activate the CFN resources and run your CFN stacks.

Alternatively, you can set the trust relationships of your role via AWS Console: in the IAM dashboard, select your role and clickTrust Relationships:

The IAM Role used to Activate the resource type might have been deleted (also applies when using a different IAM Role when creating the stack).To verify this you can:

1. 
2. 
3. 
   • Ensure this IAM Role exists

The problem is caused by using the project resource identifier (ID + Profile Name) as the input parameterProjectID of another CFN resource. The correct approach is to useGetAttr function to get the ProjectId from the project resource and use that value as input parameter to the next CFN resource.Example of correct use of GetAtt (seeproject-cluster.json):

"AtlasCluster": {"Type":"MongoDB::atlas::Cluster","Properties": {"ProjectId": {"Fn::GetAtt": ["Project","Id"          ]        },"Name": {"Ref":"ClusterName"        },

The problem is that Atlas resources are using your network container. If your Atlas project has a cluster or a network peering resource, you can't delete the network container.To make sure your CFN stack deletes clusters and network peering resources before attempting to delete the network container, you should addDependsOn to your cluster resource.

Resources:Cluster:Type:'MongoDB::Atlas::Cluster'DependsOn:NetworkContainerProperties:Profile:"default"Name:MyCluster.........NetworkContainer:Type:'MongoDB::Atlas::NetworkContainer'Properties:Profile:"default"AtlasCidrBlock:192.168.0.0/21RegionName:EU_WEST_1ProjectId:'YOUR-PROJECT-ID'NetworkPeering:Type:'MongoDB::Atlas::NetworkPeering'DependsOn:NetworkContainerProperties:Profile:"default"ProjectId:'YOUR-PROJECT-ID'ContainerId:!GetAtt "NetworkContainer.Id"AccepterRegionName:"eu-west-1"AwsAccountId:"YOUR-AWS-ACCOUNT-ID"RouteTableCIDRBlock:"10.0.0.0/16"VpcId:"YOUR-VPC-ID"