CZE.DKAction source

DocumentDB · GitHub Actions · AWS CodeBuild

Back up Amazon DocumentDB with mongodump from GitHub Actions

Run an ephemeral CodeBuild runner inside the database VPC, create a compressed BSON archive, and store it in an S3 bucket.

Brian Lund Larsen ·

GitHub ActionsCodeBuild runnerprivate subnetDocumentDB :27017

GitHub-hosted runners cannot reach an Amazon DocumentDB cluster in private subnets so interactiving with it from a workflow requires a runner with access. If you don't want to run a selfhosted runner, AWS CodeBuild can start an ephemeral GitHub Actions runner in the cluster VPC for the duration of the job. CodeBuild removes the runner and build environment after it finishes.

The workflow creates an on-demand archive. It uses Setup MongoDB Database Tools to install mongodump and mongorestore, then sends the compressed archive to S3.

Where the archive fits

Amazon DocumentDB stores continuous backups for point-in-time recovery and supports manual cluster snapshots. Those tools give you the best path for whole-cluster recovery.

A mongodump archive solves a different problem. You can move the portable BSON file between accounts, environments, Amazon DocumentDB clusters, and compatible MongoDB deployments.

Recovery needSnapshot or point-in-time restoreArchive
Recover a complete clusterBest fitPossible, with more work
Restore one database or collectionCreates a new clusterBest fit
Move data to another platform or accountAWS cluster recoveryPortable file
Keep a backup file in your own S3 bucketAWS manages the backup filesYou set encryption and retention
Recover to an exact point in timeBest fitNo single-time guarantee during writes

Keep DocumentDB snapshots and point-in-time recovery enabled. Use the archive for portability, selective restore, and migration. A live mongodump without oplog support does not represent one instant when writes continue during the dump.

Prepare the runner and network

  1. 1. Create a runner project. In CodeBuild, choose the Runner project type, GitHub as the provider, and the repository that contains the workflow. CodeBuild creates the workflow-job webhook.
  2. 2. Attach the VPC. Select the DocumentDB VPC, private subnets, and a security group for the build. Allow that security group to reach the DocumentDB security group on TCP port 27017. The build security group needs no inbound rule.
  3. 3. Provide outbound access. The runner must reach GitHub, MongoDB's download host, the Amazon trust store, and S3. CodeBuild VPC builds need a NAT gateway or NAT instance for public endpoints. An internet gateway cannot assign a public address to the CodeBuild network interface.
  4. 4. Limit AWS access. Give the CodeBuild service role s3:PutObject for the backup prefix. Add the KMS permissions required by the bucket key. Use the runner role in the workflow instead of a long-lived AWS access key.
  5. 5. Store the connection string. Add DOCUMENTDB_URI as a GitHub environment secret and DOCUMENTDB_BACKUP_BUCKET as an environment variable. Use a DocumentDB account with read access to the data in scope.

Run the backup on demand

Save this workflow under .github/workflows. The CodeBuild project name in runs-on must match the project you created.

name: Back up DocumentDB

on:
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: documentdb-backup
  cancel-in-progress: false

jobs:
  backup:
    environment: production
    runs-on: codebuild-documentdb-backup-${{ github.run_id }}-${{ github.run_attempt }}
    timeout-minutes: 60
    env:
      DOCUMENTDB_URI: ${{ secrets.DOCUMENTDB_URI }}
      BACKUP_BUCKET: ${{ vars.DOCUMENTDB_BACKUP_BUCKET }}

    steps:
      - name: Mask the connection string
        shell: bash
        run: echo "::add-mask::$DOCUMENTDB_URI"

      - name: Install MongoDB Database Tools
        uses: brianlund/setup-mongodb-database-tools@9dbac1d63dbdb296f08cc5301a60a7b31d63c320 # v1.0.1
        with:
          version: "100.6.1"

      - name: Download the Amazon RDS CA bundle
        shell: bash
        run: |
          set -euo pipefail
          curl --fail --silent --show-error --location \
            https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem \
            --output "$RUNNER_TEMP/global-bundle.pem"

      - name: Create the archive
        shell: bash
        run: |
          set -euo pipefail
          mongodump \
            --uri="$DOCUMENTDB_URI" \
            --ssl \
            --sslCAFile="$RUNNER_TEMP/global-bundle.pem" \
            --archive="$RUNNER_TEMP/documentdb.archive.gz" \
            --gzip

      - name: Upload the archive to S3
        shell: bash
        run: |
          set -euo pipefail
          backup_key="documentdb/$(date -u +%Y/%m/%d)/${GITHUB_RUN_ID}.archive.gz"
          aws s3 cp \
            "$RUNNER_TEMP/documentdb.archive.gz" \
            "s3://${BACKUP_BUCKET}/${backup_key}" \
            --only-show-errors
          echo "Archive: s3://${BACKUP_BUCKET}/${backup_key}" >> "$GITHUB_STEP_SUMMARY"

The workflow uses workflow_dispatch, a one-hour timeout, and a concurrency group that prevents two backup jobs from running at once. The action reference uses the full v1.0.1 commit SHA. MongoDB Database Tools version 100.6.1 follows the current AWS recommendation for DocumentDB.

MongoDB does not support or test Database Tools against DocumentDB. Follow AWS's compatibility guidance and run a restore test after any DocumentDB engine or Database Tools change.

Configure default SSE-KMS encryption, versioning, and a lifecycle policy on the S3 bucket. The runner writes each archive under a date and GitHub run ID, which gives each object a stable audit link back to the workflow log.

Add --db or --collection to the dump command when you need a narrower export. The connection URI should contain the DocumentDB endpoint, credentials,authSource=admin, replicaSet=rs0, and retryWrites=false.

Prove that the archive restores

A successful dump proves that you created a file. Test the recovery path against an empty disposable cluster with the same Database Tools version:

aws s3 cp \
  "s3://$BACKUP_BUCKET/$BACKUP_KEY" \
  "$RUNNER_TEMP/documentdb.archive.gz" \
  --only-show-errors

mongorestore \
  --uri="$RESTORE_DOCUMENTDB_URI" \
  --ssl \
  --sslCAFile="$RUNNER_TEMP/global-bundle.pem" \
  --archive="$RUNNER_TEMP/documentdb.archive.gz" \
  --gzip

Run restores through a separate workflow and GitHub environment. Give its CodeBuild role s3:GetObject and the KMS decrypt permission for the backup key. Store the target connection string in RESTORE_DOCUMENTDB_URI.

Check collection counts and application queries after the restore. Record the archive key, tool version, duration, and result. The --drop option removes destination collections before restore, so keep it out of the command until you intend to replace the destination data.

Sources