Merge pull request #137 from mongodb/release

Release

Author: sarahsimpers

snooty.toml

@@ -48,6 +48,8 @@ atlas-go-to = "Atlas Goto"
 atlas-sp = "Atlas Stream Processing"
 atlas-ui = "Atlas UI"
 aws = ":abbr:`AWS (Amazon Web Services)`"
+aws-cdk = ":abbr:`AWS (Amazon Web Services)` :abbr:`CDK (Cloud Development Kit)`"
+aws-cf = ":abbr:`AWS (Amazon Web Services)` CloudFormation"
 avs = "Atlas Vector Search"
 aws-pl = "AWS PrivateLink"
 asql = "Atlas SQL"
@@ -173,6 +175,7 @@ vnet = "VNet"
 waf = "`Well-Architected Framework <https://www.mongodb.com/resources/products/capabilities/well-architected-framework>`__"
 wif = "Workforce Identity Federation"
 workload = "Workload Identity Federation"
+iac = ":abbr:`IaC (Infrastructure as Code)`"
 
 [substitutions]
 service-register = ":mdbacct:`MongoDB Atlas registration page </register?tck=docs_atlas>`"

source/automation.txt

@@ -19,27 +19,35 @@ Guidance for {+service+} Automated Infrastructure Provisioning
    :depth: 3
    :class: onecol
 
-|service-fullname| provides an easy way to host and manage your data in
-the cloud. It includes tools that enable programmatic management of the
-deployment, scaling, and maintenance of your {+service+} {+clusters+} to
-streamline operations, reduce manual interventions, and ensure
-consistent, policy-compliant deployments. These tools offer you the
-flexibility to work with {+service+} through direct scripting (such as
-scripts that use the GoSDK Client or call the {+atlas-admin-api+}
-directly), or Infrastructure as Code (IaC) tooling that uses declarative
-configuration, like our Kubernetes Operator, Terraform, Cloud Formation
-or AWS CDK.
+|service-fullname| provides tools that enable programmatic management of the deployment, 
+scaling, and maintenance of your Atlas {+clusters+}. 
+{+service+} provides the flexibility to implement Infrastructure as Code (IaC) using either imperative or declarative programming.
+For example, developers can write imperative scripts that call functions from our {+atlas-go-sdk+} client, 
+or manage {+service+} resources using declarative {+iac+} tools like the {+ak8so+}, Terraform, {+aws-cf+}, or the {+aws-cdk+}. 
+
+{+service+}'s {+iac+} tools are especially useful at the enterprise scale. 
+We recommend that our enterprise customers use {+iac+} tools for the following benefits: 
+
+- **Consistency**: {+iac+} tools enable repeatability across environments, so that deployments
+  generate consistent results. 
+- **Scalability**: {+iac+} tools enable :ref:`auto-scaling <arch-center-scalability>` to automatically adjust 
+  the tier or storage capacity of {+clusters+} in response to real-time use. 
+- **Reduced Human Error**: {+iac+} tools automate operational overhead, reducing manual interventions 
+  that produce common human errors.
+- **Faster Development**: {+iac+} tools streamline operations to promote more efficient development. 
+- **Improved Change Management**: {+iac+} tools support reviews and standardization of infrastructure,
+  allowing for better change management practices and compliance. 
 
 Features for Atlas Automation
 -----------------------------
 
-You can automate the management, provisioning, and configuration of
-|service| building blocks like database users and roles, |service|
-{+clusters+}, projects and organizations. Additionally, you can automate
-setting up and managing additional {+clusters+} resources, including
+You can automate the configuration, provisioning, and management of
+|service| building blocks like database users and roles, and |service|
+{+clusters+}, projects, and organizations. You can also automate
+various configuration and management tasks for {+cluster+} resources, including 
 enabling auto-scaling compute and storage, creating and updating
 multi-cloud {+clusters+}, monitoring {+cluster+} performance and health,
-automating backups and restores, defining backup policies, and many more.
+automating backups and restores, defining backup policies, and more.
 
 You can align your choice of tools with your preferred workflow to
 ensure seamless integration of |service-fullname| into your existing
@@ -58,6 +66,22 @@ programming language or bash script.
 
 To learn more, see :ref:`atlas-admin-api-access`.
 
+{+atlas-cli+} 
+~~~~~~~~~~~~~
+
+Enables you to manually or programmatically create, manage, and automate
+tasks related to |service| resources from a unified command line tool.
+
+To learn more, see the following resources:
+
+- :ref:`Atlas CLI <atlascli>`
+- :ref:`Quick Start <atlas-cli-quick-start>`
+- :ref:`atlas-cli-ephemeral-cluster`
+
+You can also use the {+atlas-cli+}
+examples in the {+atlas-arch-center+} such as the :ref:`Org, Project,
+and Cluster<arch-center-hierarchy>` examples to get started.
+
 .. _arch-center-iac:
 
 HashiCorp Terraform MongoDB Atlas Provider
@@ -79,10 +103,10 @@ Cluster<arch-center-hierarchy>` examples to get started.
 
 .. include:: /includes/complete-examples.rst
 
-GoSDK Client 
-````````````
+{+atlas-go-sdk+} Client
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The {+service+} Go SDK client simplifies interaction with the
+The {+atlas-go-sdk+} client simplifies interaction with the
 {+atlas-admin-api+} by providing pre-built functions and full |api|
 endpoint coverage. The SDK provides platform-specific and GoLang
 language-specific tools, libraries, and documentation to help build
@@ -104,22 +128,6 @@ Resources to manage |service| include:
   JavaScript, TypeScript, Python, Java, C#, and Go. 
 
 To learn more, see `Deploy MongoDB Atlas with AWS CloudFormation <https://www.mongodb.com/developer/products/atlas/deploy-mongodb-atlas-aws-cloudformation/>`__.
-   
-{+atlas-cli+} 
-~~~~~~~~~~~~~
-
-Enables you to manually or programmatically create, manage, and automate
-tasks related to |service| resources from a unified command line tool.
-
-To learn more, see the following resources:
-
-- :ref:`Atlas CLI <atlascli>`
-- :ref:`Quick Start <atlas-cli-quick-start>`
-- :ref:`atlas-cli-ephemeral-cluster`
-
-You can also use the {+atlas-cli+}
-examples in the {+atlas-arch-center+} such as the :ref:`Org, Project,
-and Cluster<arch-center-hierarchy>` examples to get started.
 
 |ak8so| 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -148,9 +156,9 @@ development workflow, we recommend an :ref:`IaC tool <arch-center-iac>`
 because they provide more robust options for infrastructure provisioning
 and state management.
 
-You can also use a combination of multiple tools. For example, use IaC
-tool for provisioning and state management, and leverage the
-{+atlas-admin-api+}, GoSDK, and {+atlas-cli+} for quick administrative
+You can also use a combination of multiple tools. For example, use {+iac+}
+tools for provisioning and state management, and leverage the
+{+atlas-admin-api+}, {+atlas-go-sdk+}, and {+atlas-cli+} for quick administrative
 tasks that are ephemeral in nature. The {+atlas-cli+} is great for
 local development as well as integration into a suite of tests as part
 of your CI/CD pipeline for application development because it improves

source/hierarchy.txt

@@ -130,12 +130,17 @@ projects and {+clusters+}:
 Local {+service+} Deployments
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-For your dev and test environments, you can also develop {+service+}
-{+clusters+} locally with the {+atlas-cli+}. This can enable developers
-to work locally from their machine and cut down on costs for
-development and test environments. To learn more, see 
-:atlascli:`Create a Local {+service+} Deployment
-</atlas-cli-deploy-local>`.
+For development and testing purposes, developers can use the {+atlas-cli+} to 
+:atlascli:`create a local {+service+} deployment</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 :atlascli:`run {+atlas-cli+} commands with Docker </atlas-cli-docker>`
+to build, run, and manage local {+service+} deployments using containers.
+Containers are standardized units that contain all of the software 
+needed to run an application. Containerization allows developers to build
+local {+service+} deployments in secure, reliable, and portable test 
+environments. To learn more, see :atlascli:`Create a Local {+service+} Deployment with Docker </atlas-cli-deploy-docker>`.
 
 Org and Project Hierarchies
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -193,29 +198,39 @@ this hierarchy.
 ~~~~~~~~~~~~~~~~~~~~~
 
 To maintain isolation between environments, we recommend that you deploy 
-{+cluster+}s that belong to the same application and are administered 
-by the same team in the same project, as shown in the following diagram:
+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.
+
+However, this hierarchy may make it more complicated to share project-level configurations such as private endpoints and |cmk|\s across clusters.
+To learn more, see :ref:`hierarchy-multiple-clusters`. 
 
 .. figure:: /includes/images/deployment-hierarchy.svg
    :alt: An image showing one deployment per project in each organization.
    :align: center
    :lightbox:
 
-Grouping multiple {+clusters+} and therefore applications into one
-project by environment as shown in the following diagram simplifies
-administration when 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, since 
-all {+clusters+} in the same project share this configuration. However,
-this {+cluster+} hierarchy may violate the least-privilege rule.
+.. _hierarchy-multiple-clusters: 
+
+When to Consider Multiple {+Clusters+} Per Project 
+``````````````````````````````````````````````````
+
+The following diagram shows an organization whose projects each contain multiple {+service+} {+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.
 
-You should use this hierarchy only if both of the following are true:
+However, this {+cluster+} hierarchy may violate the principle of least privilege.
 
-- Every team member with access to the project is working on all other
+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 lower environments. Production
-  {+clusters+} should belong to the same application and be administered 
-  by the same team in the same 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.
 
 .. figure:: /includes/images/alt-deployment-by-environment.svg
    :alt: An image showing deployments grouped by environment.
@@ -247,42 +262,39 @@ To learn more about parsing billing data using tags, see
 
 In a dedicated deployment ({+cluster+} size ``M10``\+), {+service+}
 allocates resources exclusively. We recommend dedicated deployments
-because they provide higher security and performance than shared
+for production use cases because they provide higher security and performance than shared
 clusters.
 
-Use the following {+cluster+} size guide to select a {+cluster+} tier that ensures performance without over-provisioning. The {+cluster+} size guide also provides recommendations on which {+cluster+} tiers
-are suitable for development and testing environments, and which are
-suitable for staging and production environments.
-
-The {+cluster+}
-size guide uses "t-shirt sizing," a common analogy used in software
+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. You should consider t-shirt sizes as approximate
-starting points. Sizing a {+cluster+} is an iterative process based on
+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 mission-critical
-   applications, high-memory workloads, and high-CPU workloads, contact
-   |mdb-support| for customized guidance.
+   workloads, and high-CPU workloads. For these use cases,
+   contact |mdb-support| for customized guidance.
 
-You can estimate 
-the {+cluster+} resources required by using your organization's approximate data size and workload:
+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 database writes per
+- **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. 
+
 .. list-table::
    :header-rows: 1
-   :widths: 10 10 20 20 10 10 10 20
+   :widths: 10 10 20 20 10 10 10 10
 
    * - T-Shirt Size
      - Cluster Tier
@@ -291,7 +303,7 @@ the {+cluster+} resources required by using your organization's approximate data
      - CPUs (#)
      - Default RAM
      - Default IOPS
-     - Recommended For
+     - Suitable For
 
    * - Small
      - ``M10`` [1]_