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

# MongoDB Atlas

> Managed MongoDB clusters, projects, and users.

## What is this integration?

Manage MongoDB Atlas projects, clusters, and users with Monk.

## What Monk manages

* Project, Cluster, User

## Obtaining Atlas Credentials

Before using MongoDB Atlas with Monk, you'll need to create an Organization API Key in MongoDB Atlas.

### What You'll Need

* **Organization Name** - Your MongoDB Atlas organization name or ID
* **Service Account Client ID** - Atlas API Public Key
* **Service Account Client Secret** - Atlas API Private Key

### Step-by-Step

1. **Log into MongoDB Atlas** at [https://cloud.mongodb.com](https://cloud.mongodb.com)
2. Click your **organization name** in the top left
3. Go to **Organization Settings** (gear icon)
4. Navigate to **Access Manager** → **API Keys** tab
5. Click **Create API Key**
6. Enter description: "Monk Deployment"
7. **Set Organization Permissions:**
   * `Organization Project Creator`
   * `Project Cluster Manager`
   * `Project User Admin`
8. Click **Next**
9. **Copy the Public Key** (Client ID) - save this
10. **Copy the Private Key** (Client Secret) - **shown only once, save it now!**
11. Click **Done**
12. **Note your Organization Name** from Organization Settings main page

### Required Access Scope

Monk needs these specific permissions:

* **Organization Project Creator** - To create Atlas projects for your deployments
* **Project Cluster Manager** - To provision and manage database clusters
* **Project User Admin** - To create database users for your applications

**Monk cannot:**

* Access existing projects or data outside what it creates
* Modify organization-level settings
* Access billing information

This is the minimal scope required for Monk to manage Atlas resources.

### Security Best Practices

✅ **Rotate keys periodically** - Update API keys every 90 days
✅ **Use project-specific keys when possible** - If you only deploy to one project
✅ **Monitor API key usage** - Check Atlas Access Tracking logs
✅ **Revoke unused keys** - Remove old keys when no longer needed

## Auth

* Uses a Monk secret for API token (e.g., mongodb-atlas-token) and password secret for users

## Getting Started

1. Set secrets:

```bash theme={null}
monk secrets add -g mongodb-atlas-token="mdb_xxx"
monk secrets add -g mongodb-user-password="strong-password"
```

2. Define resources (save as mongodb-atlas.yaml):

```yaml theme={null}
namespace: my-mongodb

my-project:
  defines: mongodb-atlas/project
  name: my-application-project
  organization: my-organization
  secret_ref: mongodb-atlas-token
  permitted-secrets:
    mongodb-atlas-token: true

my-cluster:
  defines: mongodb-atlas/cluster
  name: my-application-cluster
  project_id: \<- connection-target("project") entity-state get-member("id")
  provider: AWS
  region: US_EAST_1
  instance_size: M0
  secret_ref: mongodb-atlas-token
  connections:
    project:
      runnable: my-mongodb/my-project
      service: data
  depends:
    wait-for:
      runnables:
        - my-mongodb/my-project
      timeout: 120

my-user:
  defines: mongodb-atlas/user
  name: app-user
  role: readWrite
  project_id: \<- connection-target("project") entity-state get-member("id")
  secret_ref: mongodb-atlas-token
  password_secret_ref: mongodb-user-password
  connections:
    project:
      runnable: my-mongodb/my-project
      service: data
  depends:
    wait-for:
      runnables:
        - my-mongodb/my-project
      timeout: 120
```

3. Create/update:

```bash theme={null}
monk update my-mongodb/my-project
monk update my-mongodb/my-cluster
monk update my-mongodb/my-user
```

## Backup & Snapshot Actions (M10+ Clusters)

MongoDB Atlas provides comprehensive backup and restore capabilities for **M10 and higher dedicated clusters**.

<Note type="warning">
  **M0 free tier does not support backup API.** M2 and M5 shared tiers also
  lack backup support. For production deployments requiring backups, use M10+
  dedicated clusters which include automated daily backups and point-in-time
  restore capabilities.
</Note>

| Action               | Description                                 |
| -------------------- | ------------------------------------------- |
| `get-backup-info`    | View backup configuration and status        |
| `create-snapshot`    | Create an on-demand backup snapshot         |
| `list-snapshots`     | List available snapshots                    |
| `describe-snapshot`  | Get detailed info about a specific snapshot |
| `delete-snapshot`    | Delete a backup snapshot                    |
| `restore`            | Restore from snapshot or point-in-time      |
| `get-restore-status` | Check restore job progress                  |
| `list-restore-jobs`  | View all restore jobs                       |

### Using Backups with Monk

**Ask Monk to manage backups:**

```
back up my MongoDB database
```

```
show me available backups
```

```
restore from latest backup
```

Monk translates these natural language requests to the appropriate Atlas API calls.

### CLI Reference (Advanced)

For direct CLI usage:

```bash theme={null}
# View backup configuration
monk do my-mongodb/my-cluster/get-backup-info

# Create a snapshot before migration
monk do my-mongodb/my-cluster/create-snapshot description="Pre-migration"

# List available snapshots
monk do my-mongodb/my-cluster/list-snapshots

# Restore from snapshot (WARNING: overwrites data!)
monk do my-mongodb/my-cluster/restore snapshot_id="xxx"

# Point-in-time restore
monk do my-mongodb/my-cluster/restore restore_timestamp="2024-12-01T10:00:00Z"

# Check restore progress
monk do my-mongodb/my-cluster/get-restore-status job_id="xxx"

# Get details about a specific snapshot
monk do my-mongodb/my-cluster/describe-snapshot snapshot_id="xxx"

# Delete a snapshot
monk do my-mongodb/my-cluster/delete-snapshot snapshot_id="xxx"
```