MongoDB Atlas - Monk Docs

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

Log into MongoDB Atlas at https://cloud.mongodb.com
Click your organization name in the top left
Go to Organization Settings (gear icon)
Navigate to Access Manager → API Keys tab
Click Create API Key
Enter description: “Monk Deployment”
Set Organization Permissions:
- Organization Project Creator
- Project Cluster Manager
- Project User Admin
Click Next
Copy the Public Key (Client ID) - save this
Copy the Private Key (Client Secret) - shown only once, save it now!
Click Done
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

Set secrets:

monk secrets add -g mongodb-atlas-token="mdb_xxx"
monk secrets add -g mongodb-user-password="strong-password"

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

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

Create/update:

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.

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.

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:

# 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"

​What is this integration?

​What Monk manages

​Obtaining Atlas Credentials

​What You’ll Need

​Step-by-Step

​Required Access Scope

​Security Best Practices

​Auth

​Getting Started

​Backup & Snapshot Actions (M10+ Clusters)

​Using Backups with Monk

​CLI Reference (Advanced)

What is this integration?

What Monk manages

Obtaining Atlas Credentials

What You’ll Need

Step-by-Step

Required Access Scope

Security Best Practices

Auth

Getting Started

Backup & Snapshot Actions (M10+ Clusters)

Using Backups with Monk

CLI Reference (Advanced)