MongoDB Atlas AWS CloudFormation Resources & AWS Partner Solution Deployments

Use AWS CloudFormation to manage MongoDB Atlas.

Partner Solutions (formally AWS Quick Starts) are automated reference deployments built by Amazon Web Services (AWS) solutions architects and AWS Partners. Partner Solutions help you deploy popular technologies to AWS according to AWS best practices. The quickest way to get started is to launch the official MongoDB Atlas on AWS Partner Solution Deployment directly from the AWS Management Console.

Getting Started

MongoDB Atlas CloudFormation

See the cfn examples to setup prerequisites and get started with your first cluster using our sample CloudFormation Stack templates.

MongoDB Atlas AWS CDK

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

Limitations

1. Resource import is not supported for third-party resources.

2. 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

Support, Bugs, Feature Requests

Feature requests can be submitted at feedback.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 within the Atlas UI. In addition, support questions submitted under the Issues section of this repo are also being monitored. Bugs should be filed under the Issues section of this repo.

MongoDB Atlas API Keys Credential Management

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 via AWS Secrets Manager.

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

1. Configure your MongoDB Atlas API Keys

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 the Atlas documentation for detailed instructions.

2. Configure your Profile

To use Atlas CloudFormation resources, you must configure a "profile" with your API keys using AWS 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 the PROFILE SECRET TEMPLATE file provided in this repository.

Here are some examples of how to use this template:

Example 1

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

Example 2

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

Note: If you want to use a AWS KMS key to handle encyption of your secret you must define the appropriate resource policies so that AWS Secrets Manager has access to the key. The following AWS documentation describes a key policy that allows access through AWS Secrets Manager for all principals in the account that are authorized to use AWS Secrets Manager.

3. Provide the profile to your CloudFormation template

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

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.

Contributing

See our CONTRIBUTING.md guide.

Issues

Autoclose stale issues and PRs

• 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.

One-click reproducible issues principle

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 and successfully run a local execution reproducing the issue.
  • This means that you should kindly provide 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 that cannot 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 the CFN MongoDB Atlas resource by removing 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.

Troubleshooting

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 see here
3. Ensure your activated 3rd-party public extension matches name exactly to MONGODB::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 the AWS IP address ranges and contact AWS Support directly who can help confirm the CIDR range to be used in your Atlas PAK IP Whitelist.

Error: The CFN stack remains in the CREATE_IN_PROGRESS state before failing after an hour or so

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 include resources.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: Allow
      Principal:
       Service:
       - lambda.amazonaws.com
       - resources.cloudformation.amazonaws.com
       - cloudformation.amazonaws.com
      Action: sts:AssumeRole

Use the execution-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 click Trust Relationships:

Error: 404 (request "INVALID_GROUP_ID") An invalid group ID |default was specified

The problem is caused by using the project resource identifier (ID + Profile Name) as the input parameter ProjectID of another CFN resource. The correct approach is to use GetAttr 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 (see project-cluster.json):

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

Error: The CFN stack failed to delete MongoDB::Atlas::NetworkContainer with the error 409 (request "CONTAINERS_IN_USE"). You cannot modify in-use containers; the container still contains resources."

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 add DependsOn to your cluster resource.

Resources:
  Cluster:
    Type: 'MongoDB::Atlas::Cluster'
    DependsOn: NetworkContainer
    Properties:
      Profile: "default"
      Name: MyCluster
      .........
  NetworkContainer:
    Type: 'MongoDB::Atlas::NetworkContainer'
    Properties:
      Profile: "default"
      AtlasCidrBlock: 192.168.0.0/21
      RegionName: EU_WEST_1
      ProjectId: 'YOUR-PROJECT-ID'
  NetworkPeering:
    Type: 'MongoDB::Atlas::NetworkPeering'
    DependsOn: NetworkContainer
    Properties:
      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"