> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt # Guidance for Atlas Orgs, Projects, and Clusters Organizations, projects, and clusters are the building blocks of your Atlas enterprise estate: - At the organization level, you can implement security controls and create users that work across one or more projects. - Projects offer a more fine-grained security isolation and authorization boundary. - Clusters are your cloud databases in Atlas. Use the foundational guidance on this page to design the layout of your organizations, projects, and clusters based on your company's hierarchy and expected number of clusters and projects. This guidance helps you optimize your security and performance from the start while aligning with your enterprise's billing and access needs. **Note:** The MongoDB Atlas Shared Responsibility Model defines the complementary duties of MongoDB and its customers in maintaining a secure and resilient data environment. Under this framework, MongoDB manages the security and operational integrity of the underlying platform, while customers are responsible for the configuration, management, and data policies of their specific deployments. For a detailed breakdown of ownership across security and operational excellence, see [Shared Responsibility Model.](https://www.mongodb.com/resources/products/fundamentals/shared-responsibility) ## Features for Atlas Orgs, Projects, and Clusters You can use the following levels of hierarchy to define security settings and governance for your Atlas enterprise estate: | Atlas Hierarchy Level | Description | | --- | --- | | (Optional) Paying Organization | One [organization](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-organization) can be a paying organization for other organization(s). A paying organization lets you set up [cross-organization billing](https://www.mongodb.com/docs/atlas/billing/#std-label-cross-org-billing) to share a billing subscription across multiple organizations. To learn more about setting up your paying organization when you establish the Atlas subscription, see [Manage Billing](https://www.mongodb.com/docs/atlas/billing/). In order to enable cross-organization billing, the user performing the action must have an Org Owner or Billing Admin role of both organizations that they wish to link. To learn more, see [User Roles.](https://www.mongodb.com/docs/atlas/reference/user-roles/) A paying organization is common for large enterprises with many BU (Business Unit)s or departments that operate independently but where the contract or bill is owned by a central authority. | | [organization](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-organization) | An [organization](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-organization) can contain many projects, and it provides a container to apply shared integration and security settings across those projects and the clusters therein. If you manage multiple Atlas organizations, the [Atlas Federation Management Console](https://www.mongodb.com/docs/atlas/security/federated-authentication.md#std-label-atlas-federated-authentication) allows users with an Org Owner role to manage IdPs (Identity Providers) for SSO (Single Sign-On), then link them to multiple organizations. An organization often maps to a BU (Business Unit) or department within a company. The built-in Atlas Cost Explorer aggregates cloud spend at the organization level and breaks out line items at the project-level and cluster level below it. You can customize further by leveraging the billing API. | | [project](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-project) | Security configuration for the data plane (including database clusters, network security, and other data services) occurs at the project-level. A [project](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-project) often maps to an application and environment (for example: Customer Portal app - Production environment). For each project, based on the selected cloud provider, there is one dedicated VPC or VNet per region in AWS and Azure. | | [cluster](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-cluster) | Atlas provisions each [cluster](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-cluster) within the dedicated VPC/VNet(s) for a project. The security configuration is shared among clusters in the project, except for database user roles and authorization, which you can apply to actions on a [cluster](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-cluster), database, and collection level. | ![An image showing org, project, and cluster hierarchy.](/_includes/images/atlas-project-hierarchy.png) ## Recommendations for Atlas Orgs, Projects, and Clusters ### Multi-Region and Multi-Cloud Deployment Recommendations For multi-region and multi-cloud deployments, consider the following additional recommendations to optimize performance, security, and compliance across geographic boundaries: #### Network Architecture and Latency - Deploy clusters in regions closest to your application users to minimize latency. - Use dedicated VPCs/VNets per region within each project to maintain network isolation. - Configure [private endpoints](https://www.mongodb.com/docs/atlas/security-private-endpoint/) in each region where you deploy clusters to ensure secure, low-latency connections. #### Data Locality and Compliance - Create separate projects for different regulatory jurisdictions (for example, GDPR-compliant EU project, SOX-compliant US project) to ensure data residency requirements are met. - Use [Global Clusters](https://www.mongodb.com/docs/atlas/global-clusters/) with zone sharding to automatically route reads and writes to the appropriate geographic region based on shard key values. - Tag projects and clusters with data classification and regional compliance requirements for audit and governance purposes. #### Cross-Region Disaster Recovery - Deploy clusters with read replicas in multiple regions to enable failover capabilities. - Maintain consistent backup schedules across all regions within the same application environment. - Test disaster recovery procedures regularly across regions to ensure business continuity. #### Multi-Cloud Considerations - Use consistent naming conventions across cloud providers to simplify management and monitoring. - Standardize security configurations across all cloud environments within the same project. - Consider cloud provider-specific features and limitations when planning cross-cloud data replication and network connectivity. ### All Deployment Paradigm Recommendations The following recommendations apply to all [deployment paradigms.](https://www.mongodb.com/docs/atlas/architecture/current/deployment-paradigms.md#std-label-arch-center-paradigms) #### Development, Testing, Staging, and Production Environments We recommend that you use the following four environments to isolate your sandbox and test projects and clusters from your application projects and clusters: | Environment | Description | | --- | --- | | Development (Dev) | Allow developers to freely try new things in a safe sandbox environment. | | Testing (Test) | Test specific components or functions created in the dev environment. | | Staging | Stage all components and functions together to make sure the entire application works as expected before deploying to production. Staging is similar to the test environment, but ensures that new components work well with existing components. | | Production (Prod) | The back end for your application that is live for your end users. | #### Local Atlas Deployments For development and testing purposes, developers can use the Atlas CLI to [create a local Atlas deployment](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-deploy-local/). By working locally from their machines, developers can cut down on costs for external development and testing environments. Developers can also [run Atlas CLI commands with Docker](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-docker/) to build, run, and manage local Atlas deployments using containers. Containers are standardized units that contain all of the software needed to run an application. Containerization allows developers to build local Atlas deployments in secure, reliable, and portable test environments. To learn more, see [Create a Local Atlas Deployment with Docker.](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-deploy-docker/) #### Org and Project Hierarchies Generally, we recommend a paying organization that is managed centrally, and one organization for each BU (Business Unit) or department that is linked to the paying org. Then, create a project with one cluster each for your lower (dev or test) and upper environments; you can create clusters in these projects. To learn more, see the following information for [Recommended Hierarchy.](https://www.mongodb.com/docs/atlas/architecture/current/hierarchy.md#std-label-project-hierarchy-1) If you will easily hit the 250 project limit per organization, we recommend creating one organization per environment, such as one each for lower and upper environments, or one each for dev, test, staging, and production. This setup has the benefit of additional isolation. You can also increase the limits. To learn more, see [Atlas Service Limits.](https://www.mongodb.com/docs/atlas/reference/atlas-limits/) Network and security configurations, such as allowed IPs and API keys, are shared at the project level, so if you need fine grained access controls for teams working on different applications, we recommend that you create separate projects for each application. #### Recommended Hierarchy Consider the following hierarchy, which creates fewer Atlas organizations, if you have common teams and permissions across the BU (Business Unit) and less than the raiseable limit of 250 projects per organization. ![An image showing a paying organization with other organizations nested beneath it.](/_includes/images/paying-org-hierarchy.svg) #### Recommended Hierarchy 2: Decentralized Business Units/Departments Consider the following hierarchy if your organization is highly decentralized without a centralized function to serve as the contract and billing owner. In this hierarchy, each BU (Business Unit), department, or team has their own Atlas organization. This hierarchy is useful if each of your teams is fairly independent, they don't share people or permissions within the company, or they want to buy credits themselves through the cloud provider marketplace or directly with their own contract. There is no paying organization in this hierarchy. ![An image showing multiple organizations without a paying organization above them.](/_includes/images/no-paying-org-hierarchy.svg) #### Cluster Hierarchy To maintain isolation between environments, we recommend that you deploy each cluster within its own project, as shown in the following diagram. This allows administrators to maintain different project configurations between environments and uphold the principle of least privilege, which states that users should only be granted the least level of access necessary for their role. Particularly in production environments, we recommend that you create separate projects for each application and environment pair. As these configurations are managed at the project level, this approach reduces the potential for your needing to manually transfer data between production environment clusters should these requirements change for a given application. You can share project-level configurations such as private endpoints and CMKs across clusters with automation tooling, such as Terraform, at cluster creation. Moreover, automating cluster creation can yield cost savings by standardizing the creation of parallel higher and lower environments for production and development environments respectively. To learn more, see [When to Consider Multiple Clusters Per Project.](https://www.mongodb.com/docs/atlas/architecture/current/hierarchy.md#std-label-hierarchy-multiple-clusters) ![An image showing one deployment per project in each organization.](/_includes/images/deployment-hierarchy.svg) #### When to Consider Multiple Clusters Per Project The following diagram shows an organization whose projects each contain multiple Atlas clusters, grouped by environment. Deploying multiple clusters within the same project simplifies administration when one application uses multiple backing clusters, or the same team is responsible for multiple applications across environments. This eases the setup cost for features such as private endpoints and customer-managed keys, because all clusters in the same project share the same project configuration. However, this cluster hierarchy may violate the principle of least privilege. Deploy multiple clusters within the same project only if both of the following are true: - Each team member with access to the project is working on all other applications and clusters in the project. - You are creating clusters for development and testing environments. In staging and production environments, we recommend that clusters in the same project should belong to the same application and be administered by the same team. ![An image showing deployments grouped by environment.](/_includes/images/alt-deployment-by-environment.svg) #### Resource Tagging We recommend that you [tag clusters or projects](https://www.mongodb.com/docs/atlas/database-deployment-tags/) with the following details to enable easy parsing for reporting and integrations: - BU (Business Unit) or Department - Team name - Application name - Environment - Version - Email contact - Criticality (indicates the tier of data stored on the cluster, including any sensitive classifications such as PII (Personally Identifiable Information) or PHI (Protected Health Information)) To learn more about parsing billing data using tags, see [Features for Atlas Billing Data.](https://www.mongodb.com/docs/atlas/architecture/current/billing-data.md#std-label-arch-center-billing-data) #### Atlas Cluster Size Guide In a dedicated deployment (cluster size `M10`+), Atlas allocates resources exclusively. We recommend dedicated deployments for production use cases because they provide higher security and performance than shared clusters. The following cluster size guide uses "t-shirt sizing," a common analogy used in software development and infrastructure to describe capacity planning in a simplified manner. Use t-shirt sizing recommendations only as approximate starting points in your sizing analysis. Sizing a cluster is an iterative process based on changing resource needs, performance requirements, workload characteristics, and growth expectations. **Important:** This guidance excludes mission-critical applications, high-memory workloads, and high-CPU workloads. For these use cases, contact [MongoDB Support](https://support.mongodb.com/welcome) for customized guidance. You can estimate the cluster resources that your deployment requires by using your organization's approximate data size and workload: - **Total Storage Required**: 50% of the total raw data size - **Total RAM Required**: 10% of the total raw data size - **Total CPU Cores Required**: expected peak read/write database operations per second รท 4000 - **Total Storage IOPS Required**: expected peak read/write database operations per second (min IOPS = 5%, max IOPS = 95%) Use the following cluster size guide to select a cluster tier that ensures performance without over-provisioning. This table displays the default storage and performance capabilities for each cluster tier, as well as whether or not the cluster tier is suitable for staging and production environments. The cluster size guide also includes expected values for a cluster's total data size and default IOPS, which you can augment with additional configurations. Note that the following storage recommendations are per shard, not for the entire cluster. To learn more, see [Guidance for Atlas Scalability.](https://www.mongodb.com/docs/atlas/architecture/current/scalability.md#std-label-arch-center-scalability) | T-Shirt Size | Cluster Tier | Storage Range: AWS/Google Cloud/Azure | CPUs (#) | Default RAM | Default IOPS | Expected Median Data Size | Expected Peak Reads / Writes | Suitable For | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Small | `M10` | 2 GB to 128 GB | 2 | 2 GB | 1000 | 1 GB to 10 GB | 200 | Dev/Test only | | Med | `M30` | 8 GB to 512 GB | 2 | 8 GB | 3000 | 20 GB to 50 GB | 3000 | Prod | | Large | `M50` | 8 GB to 4 TB | 16 | 32 GB | 3000 | 360 GB to 420 GB | 11000 | Prod | | X-Large | `M80` | 8 GB to 4 TB | 32 | 128 GB | 3000 | 1200 GB to 1750 GB | 39000 | Prod | `M10` is a shared CPU tier. For highly-regulated industries or sensitive data, your minimum and smallest starting tier should be `M30`. For example, consider a fictional fintech company, MongoFinance, that must store a total of 400 GB of processed data. At peak activity, MongoFinance employees and customers perform up to 3000 reads or writes to MongoFinance databases per second. MongoFinance's storage and performance requirements are best satisfied by a large, or `M50`, cluster tier. To learn more about cluster tiers and the regions that support them, see the Atlas documentation for each cloud provider: - [AWS](https://www.mongodb.com/docs/atlas/reference/amazon-aws/) - [Azure](https://www.mongodb.com/docs/atlas/reference/microsoft-azure/) - [Google Cloud](https://www.mongodb.com/docs/atlas/reference/google-gcp/) ## Automation Examples: Atlas Orgs, Projects, and Clusters **Tip:** For Terraform examples that enforce our recommendations across all pillars, see one of the following examples in GitHub: - [Staging/Prod](https://github.com/mongodb/docs/blob/main/content/atlas-architecture/current/source/includes/examples/tf-staging-prod-complete/) - [Dev/Test](https://github.com//mongodb/docs/blob/main/content/atlas-architecture/current/source/includes/examples/tf-dev-test-complete/) The following examples create organizations, projects, and clusters using Atlas [tools for automation.](https://www.mongodb.com/docs/atlas/architecture/current/automation.md#std-label-arch-center-automation) These examples also apply other recommended configurations, including: ### Dev and Test Environments - Cluster tier set to `M10` for a dev/test environment. Use the [cluster size guide](https://www.mongodb.com/docs/atlas/architecture/current/hierarchy.md#std-label-arch-center-cluster-size-guide) to learn the recommended cluster tier for your application size. - Single Region, 3-Node Replica Set / Shard deployment topology. - Our examples use AWS, Azure, and Google Cloud interchangeably. You can use any of these three cloud providers, but you must change the region name to match the cloud provider. To learn about the cloud providers and their regions, see [Cloud Providers.](https://www.mongodb.com/docs/atlas/reference/cloud-providers/) ### CLI **Note:** Before you can create resources with the Atlas CLI, you must: - [Create your paying organization](https://www.mongodb.com/docs/atlas/billing/#configure-a-paying-organization) and [create an API key](https://www.mongodb.com/docs/atlas/configure-api-access/) for the paying organization. - [Install the Atlas CLI](https://www.mongodb.com/docs/atlas/cli/current/install-atlas-cli/) - [Connect from the Atlas CLI](https://www.mongodb.com/docs/atlas/cli/current/connect-atlas-cli/) using the steps for Programmatic Use. ### Create the Organizations Run the following command for each BU (Business Unit). Change the IDs and names to use your actual values: ```text atlas organizations create ConsumerProducts --ownerId 508bb8f5f11b8e3488a0e99e --apiKeyRole ORG_OWNER --apiKeyDescription consumer-products-key ``` For more configuration options and info about this example, see [atlas organizations create.](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-organizations-create.md#std-label-atlas-organizations-create) You can create an organization and link it to your paying organization programmatically by using the Atlas Administration API. To do so, send a `POST` request to the `https://cloud.mongodb.com/api/atlas/v2/orgs` endpoint, and specify the paying organization ID in the `federationSettingsId` field. The requesting service account or API key must have the "Organization Owner" role and the requesting organization must be a paying organization. The following example uses `cURL` to send the request: ```bash curl --location '/api/atlas/v2/orgs?envelope=false&pretty=false' \ --header 'Content-Type: application/vnd.atlas.2023-01-01+json' \ --header 'Accept: application/vnd.atlas.2023-01-01+json' \ --data '{ "name": "", "apiKey": { "desc": "", "roles": [ "ORG_MEMBER" ] }, "federationSettingsId": "", "orgOwnerId": "", "skipDefaultAlertsSettings": false }' ``` To learn more about the preceding API call, see the [atlas organizations create](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-organizations-create/#std-label-atlas-organizations-create) API documentation. To get the user IDs and organization IDs, see the following commands: - [atlas organizations list](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-organizations-list.md#std-label-atlas-organizations-list) - [atlas organizations users list](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-organizations-users-list.md#std-label-atlas-organizations-users-list) ### Create the Projects Run the following command for each application and environment pair. Change the IDs and names to use your values: ```text atlas projects create "Customer Portal - Prod" --tag environment=production --orgId 32b6e34b3d91647abb20e7b8 ``` For more configuration options and info about this example, see [atlas projects create.](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-projects-create.md#std-label-atlas-projects-create) To get the project IDs, see the following command: - [atlas projects list](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-projects-list.md#std-label-atlas-projects-list) ### Configure Encryption with Customer Key Management For staging and production environments, we recommend that you enable encryption with customer key management when you provision your clusters. For development and testing, consider skipping encryption with customer key management to save costs, unless you're in a highly-regulated industry or storing sensitive data. To learn more, see [Recommendations for Atlas Orgs, Projects, and Clusters.](https://www.mongodb.com/docs/atlas/architecture/current/hierarchy.md#std-label-arch-center-orgs-projects-clusters-recs) You can't use the the Atlas CLI to manage encryption with customer key management. Instead, use the following methods: - [Atlas UI](https://www.mongodb.com/docs/atlas/security-kms-encryption/) - [Atlas Administration API](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/group/endpoint-encryption-at-rest-using-customer-key-management) ### Create One Cluster Per Project ### Dev and Test Environments To create a single-region cluster for your development and testing environments, run the following command for each project that you created. Change the IDs and names to use your values: **Note:** You can also use the [clusters Atlas Admin API](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/group/endpoint-clusters) to create a cluster. This example doesn't enable auto-scaling to help control costs in development and testing environments. For staging and production environments, [auto-scaling should be enabled.](https://www.mongodb.com/docs/atlas/architecture/current/scalability.md#std-label-arch-center-scalability) ```text atlas clusters create CustomerPortalDev \ --projectId 56fd11f25f23b33ef4c2a331 \ --region EASTERN_US \ --members 3 \ --tier M10 \ --provider GCP \ --mdbVersion 8.0 \ --diskSizeGB 30 \ --tag bu=ConsumerProducts \ --tag teamName=TeamA \ --tag appName=ProductManagementApp \ --tag env=Production \ --tag version=8.0 \ --tag email=marissa@example.com \ --watch ``` To configure a multi-region cluster, create the following `cluster.json` file for each project that you created. Change the IDs and names to use your values. ```json { "name": "CustomerPortalDev", "projectId": "56fd11f25f23b33ef4c2a331", "clusterType": "REPLICASET", "diskSizeGB": 30, "mongoDBMajorVersion": "8.0", "backupEnabled": true, "replicationSpecs": [ { "numShards": 1, "regionConfigs": [ { "providerName": "GCP", "regionName": "EASTERN_US", "members": 3, "priority": 7, "autoScaling": { "compute": { "enabled": true, "scaleDownEnabled": true }, "diskGB": { "enabled": true } } }, { "providerName": "GCP", "regionName": "CENTRAL_US", "members": 2, "priority": 5, "autoScaling": { "compute": { "enabled": true, "scaleDownEnabled": true }, "diskGB": { "enabled": true } } }, { "providerName": "GCP", "regionName": "WESTERN_US", "members": 2, "priority": 4, "autoScaling": { "compute": { "enabled": true, "scaleDownEnabled": true }, "diskGB": { "enabled": true } } } ] } ], "tags": [ { "key": "bu", "value": "ConsumerProducts" }, { "key": "teamName", "value": "TeamA" }, { "key": "appName", "value": "ProductManagementApp" }, { "key": "env", "value": "Production" }, { "key": "version", "value": "8.0" }, { "key": "email", "value": "marissa@example.com" } ] } ``` After you create the preceding configuration file, run the following command to create the cluster: ```text atlas clusters create --file ``` For more configuration options and info about these examples, see [atlas clusters create.](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-clusters-create.md#std-label-atlas-clusters-create) ## Next Steps After you plan the hierarchy and size for your organizations, projects, and clusters, see the following suggested resources or use the left navigation to find features and best practices for each [Well-Architected Framework](https://www.mongodb.com/resources/products/capabilities/well-architected-framework) pillar. - [Guidance for Atlas Monitoring and Alerts](https://www.mongodb.com/docs/atlas/architecture/current/monitoring-alerts.md#std-label-arch-center-monitoring-alerts) - [Guidance for Atlas Network Security](https://www.mongodb.com/docs/atlas/architecture/current/network-security.md#std-label-arch-center-network-security) - [Guidance for Atlas Disaster Recovery](https://www.mongodb.com/docs/atlas/architecture/current/disaster-recovery.md#std-label-arch-center-dr)