> ## Documentation Index
> Fetch the complete documentation index at: https://www.qovery.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MongoDB Atlas Cluster

> Provision a MongoDB Atlas dedicated cluster (advanced_cluster) with a database user and IP access list, via the MongoDB Atlas Terraform provider

Qovery creates it in your account with a third-party provider, using credentials you enter in the form, as a [Blueprint](https://www.qovery.com/docs/configuration/blueprints.md) service in one of your environments.

| | |
| - | - |
| Catalog name | `mongodb-atlas-cluster` |
| Category | Databases & Caches |
| Provider | EXTERNAL |
| Engine | terraform |
| Major versions (latest release) | `default` (1.1.3) |
| Source | [EXTERNAL/mongodb-atlas/default](https://github.com/Qovery/service-catalog/tree/EXTERNAL/mongodb-atlas/default/1.1.3/EXTERNAL/mongodb-atlas/default) |

> [!TIP]
>
> **New to this?** You don't need to know Terraform or Kubernetes. Qovery sets up MongoDB Atlas Cluster in your account with the provider: you fill in a form, or paste the prompt below into your coding agent. The values it publishes, listed under Outputs, reach your other services as environment variables. Qovery tells you when a newer version of the Blueprint is available. Check the requirements in the Reference section before you start, and try it first in a development environment.

## Create it

> [tab] Console
>
> 1. Open the environment, then **New service** › **Blueprint**.
> 2. Find **MongoDB Atlas Cluster** in the catalog and pick the major version.
> 3. Fill in the variables. Required ones are marked; the others use their defaults.
> 4. Create the service, and deploy it now or later.

> [tab] CLI and API
>
> List the catalog to get the latest tag, then create the service from it. `qovery api` signs the requests with your CLI session.
>
> ```bash theme={null}
> ORG_ID="REPLACE_WITH_ORGANIZATION_ID"
> ENV_ID="REPLACE_WITH_ENVIRONMENT_ID"
>
> qovery api "organization/$ORG_ID/blueprint/catalog" | jq '.. | objects | select(.name? == "mongodb-atlas-cluster")'
>
> cat > blueprint.json <<'EOF'
> {
>   "name": "mongodb-atlas-cluster",
>   "tag": "EXTERNAL/mongodb-atlas/default/1.1.3",
>   "icon": "app://qovery-console/mongodb",
>   "variables": [
>     {
>       "name": "atlas_public_key",
>       "value": "REPLACE_WITH_ATLAS_PUBLIC_KEY"
>     },
>     {
>       "name": "atlas_private_key",
>       "value": "REPLACE_WITH_ATLAS_PRIVATE_KEY",
>       "is_secret": true
>     },
>     {
>       "name": "project_id",
>       "value": "REPLACE_WITH_PROJECT_ID"
>     },
>     {
>       "name": "cluster_name",
>       "value": "REPLACE_WITH_CLUSTER_NAME"
>     }
>   ],
>   "spec_overrides": {
>     "engine_version": "1.9.7"
>   }
> }
> EOF
> BLUEPRINT_ID=$(qovery api "environment/$ENV_ID/blueprint" --method POST --input - < blueprint.json | jq -r .id)
> rm blueprint.json   # it can hold secret values
> qovery api "blueprint/$BLUEPRINT_ID/deploy" --method POST
> qovery api "blueprint/$BLUEPRINT_ID"   # status of the latest deployment
> ```
>
> Replace each `REPLACE_WITH_` value. Add optional variables to `variables` the same way.

> [tab] Coding agent
>
> Paste this into Claude Code, Cursor, Codex or another coding agent with the [Qovery agent skills](https://www.qovery.com/docs/getting-started/quickstart/agent-skills.md) installed (`curl -fsSL https://skill.qovery.com/install.sh | bash`).
>
> ```text Prompt wrap theme={null}
> Add the Qovery Blueprint MongoDB Atlas Cluster (mongodb-atlas-cluster) to one of my Qovery environments and deploy it. Ask me for atlas_public_key, atlas_private_key, project_id and cluster_name.
> Ask me before deploying to a production environment.
> Docs: https://www.qovery.com/docs/configuration/blueprints/mongodb-atlas-cluster.md
> ```

You don't add any file to your repository. Qovery creates the Blueprint from the Console or the API.

## Variables and outputs

Generated from `qbm.yml` at `EXTERNAL/mongodb-atlas/default/1.1.3`, the manifest the Console form is built from.

> [accordion] All 12 variables
>
> | Name | Type | Required | Default | Secret | Description |
> | - | - | - | - | - | - |
> | `atlas_public_key` | string | Yes | | | Public half of the Atlas programmatic API key |
> | `atlas_private_key` | string | Yes | | Yes | Private half of the Atlas programmatic API key |
> | `project_id` | string | Yes | | | Existing MongoDB Atlas project ID the cluster is created in |
> | `cluster_name` | string | Yes | | | Letters, digits, hyphens; max 64 chars. |
> | `provider_name` | string | | `AWS` | | Backing cloud provider for the cluster |
> | `region_name` | string | | `US_EAST_1` | | Atlas region name for the backing provider (e.g. US\_EAST\_1 for AWS) |
> | `instance_size` | string | | `M10` | | Dedicated cluster instance size (M10 and up). Shared tiers (M0/M2/M5) are not supported. |
> | `mongo_db_major_version` | string | | `7.0` | | MongoDB major version (e.g. 6.0, 7.0, 8.0) |
> | `backup_enabled` | bool | | `true` | | Enable cloud backup for the cluster |
> | `db_username` | string | | | | Leave empty to use qoveryadmin (SCRAM, readWriteAnyDatabase). A second database in the same Atlas project needs a distinct username. |
> | `db_password` | string | | | Yes | Leave empty and Qovery generates a 32-character alphanumeric password. To set your own: min 8 chars. |
> | `ip_access_list_cidr` | string | | `0.0.0.0/0` | | CIDR allowed to reach the cluster. Defaults to 0.0.0.0/0 (open); restrict in production. |

Outputs become environment variables that other services in the environment can use. By default Qovery also creates an alias for each output, prefixed with the Blueprint's name; see [Aliases Qovery creates for outputs](https://www.qovery.com/docs/configuration/environment-variables.md#aliases-qovery-creates-for-outputs) for the naming rules and the cases where no alias is created.

> [accordion] All 8 outputs
>
> | Name | Secret | Description |
> | - | - | - |
> | `cluster_id` | | Atlas cluster ID |
> | `cluster_name` | | Cluster name |
> | `connection_string_standard` | | Standard connection string (mongodb://) |
> | `connection_string_srv` | | SRV connection string (mongodb+srv://) - insert the db user credentials |
> | `mongo_db_version` | | Running MongoDB version |
> | `db_username` | | Created database username |
> | `db_password` | Yes | Database user password (generated when the input was left empty) |
> | `connection_uri` | Yes | Ready-to-use SRV connection URI with the db user credentials embedded |

> [!WARNING]
>
> Secret variables and outputs are encrypted and masked in Qovery, but Terraform can also keep their values, and values derived from them, in its state. With the Qovery-managed state backend (the default), Qovery stores the state. If you use your own backend, protect it and keep state files out of version control.

## Reference

From the Blueprint's [README](https://github.com/Qovery/service-catalog/blob/EXTERNAL/mongodb-atlas/default/1.1.3/EXTERNAL/mongodb-atlas/default/README.md).

Provisions a [MongoDB Atlas](https://www.mongodb.com/atlas) **dedicated** cluster (`mongodbatlas_advanced_cluster`) in an existing Atlas project, plus a database user (`mongodbatlas_database_user`) and an IP access-list entry (`mongodbatlas_project_ip_access_list`) so it's usable immediately. Uses the `mongodb/mongodbatlas` provider (`~> 1.20`).

### Credentials

A MongoDB Atlas **programmatic API key** (public + private) supplied as variables (`credentials.default: env`). The private key is sensitive. The key must have Project Owner (or cluster + user + access-list write) permission on the target project.

### Variables

#### Required

| Name | Type | Sensitive | Description |
| - | - | - | - |
| `atlas_public_key` | string | | Atlas programmatic API key — public key |
| `atlas_private_key` | string | yes | Atlas programmatic API key — private key |
| `project_id` | string | | Existing Atlas project ID |
| `cluster_name` | string | | Cluster name (`^[a-zA-Z0-9-]{1,64}$`) |

#### Credentials

Both are optional — omit them and Qovery supplies the values, the way native managed
databases did. In the console, leaving the field blank omits it. Through the API or
Terraform, omit the variable rather than sending an empty string: the platform rejects an
empty variable value.

Atlas keys database users by (username, auth database) within a project, so two databases in
the same Atlas project cannot both take the default username — give the second one an
explicit `db_username` or its user creation collides with the first.

| Name | Type | Sensitive | Default | Description |
| - | - | - | - | - |
| `db_username` | string | | `qoveryadmin` | Database user to create (SCRAM auth, readWriteAnyDatabase). Leave empty to use qoveryadmin. Atlas keys users by (username, auth database) per project, so a second database in the same Atlas project needs a distinct username. |
| `db_password` | string | yes | *generated* | Omit and Qovery generates a 32-character alphanumeric password. To set your own: min 8 chars. |

#### Cluster shape

| Name | Type | Default | Description |
| - | - | - | - |
| `provider_name` | string | `AWS` | Backing cloud: `AWS`, `GCP`, `AZURE` |
| `region_name` | string | `US_EAST_1` | Atlas region for the backing provider |
| `instance_size` | string | `M10` | Dedicated tier (M10+). Shared M0/M2/M5 are **not** supported. |
| `mongo_db_major_version` | string | `7.0` | MongoDB major version |
| `backup_enabled` | bool | `true` | Enable cloud backup |
| `ip_access_list_cidr` | string | `0.0.0.0/0` | CIDR allowed to connect (**restrict in production**) |

### Outputs

| Name | Sensitive | Description |
| - | - | - |
| `cluster_id` | | Atlas cluster ID |
| `cluster_name` | | Cluster name |
| `connection_string_standard` | | Standard connection string (`mongodb://`) |
| `connection_string_srv` | | SRV connection string (`mongodb+srv://`) |
| `mongo_db_version` | | Running MongoDB version |
| `db_username` | | Created database username |
| `db_password` | yes | Database user password (generated when the input was left empty) |
| `connection_uri` | yes | Ready-to-use SRV URI with credentials embedded |

### Notes

* This provisions a **dedicated** cluster (M10+), which is billable on Atlas. Shared tiers (M0 free / M2 / M5) use a different `provider_name: TENANT` shape and are intentionally out of scope.
* Uses `mongodbatlas_advanced_cluster` (the `mongodbatlas_cluster` resource is deprecated as of provider 2.0.0). Pinned to `~> 1.20`.
* The cluster is created in an **existing** project (`project_id`); this blueprint does not create the Atlas project or organization.
* Connect with `connection_string_srv`, injecting `db_username` / `db_password`.


## Related topics

- [Blueprints](https://www.qovery.com/docs/configuration/blueprints.md)
- [Migrate to Kubernetes](https://www.qovery.com/docs/getting-started/guides/use-cases/cloud-migration-and-scaling.md)
- [Cluster Advanced Settings](https://www.qovery.com/docs/configuration/cluster-advanced-settings.md)
- [Databases](https://www.qovery.com/docs/configuration/database.md)
- [Install Qovery on AWS](https://www.qovery.com/docs/getting-started/installation/aws.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.