Skip to main content

​
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
  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:
monk secrets add -g mongodb-atlas-token="mdb_xxx"
monk secrets add -g mongodb-user-password="strong-password"
  1. 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
  1. 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.
ActionDescription
get-backup-infoView backup configuration and status
create-snapshotCreate an on-demand backup snapshot
list-snapshotsList available snapshots
describe-snapshotGet detailed info about a specific snapshot
delete-snapshotDelete a backup snapshot
restoreRestore from snapshot or point-in-time
get-restore-statusCheck restore job progress
list-restore-jobsView 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"