Skip to main content

Backups and Snapshots in OpenSearch on FoundryDB

· 4 min read
FoundryDB Team
FoundryDB Team
Engineering @ FoundryDB

OpenSearch has a native snapshot API that writes index data to remote storage. FoundryDB wraps this API so you can trigger, list, and restore backups without configuring S3 credentials, IAM roles, or snapshot repositories manually. This post documents the backup flow using real metadata from a test run against an OpenSearch 2.19.1 cluster.

All commands use YOUR_SERVICE_ID and YOUR_API_TOKEN as placeholders. The FoundryDB API base is https://api.foundrydb.com.

Prerequisites​

  • A FoundryDB OpenSearch cluster in the running state.
  • A FoundryDB API token (available from the dashboard under Account Settings).

Step 1: Trigger a Manual Backup​

Send a POST request to the backups endpoint with backup_type: full.

curl -u admin:YOUR_API_TOKEN \
  -X POST "https://api.foundrydb.com/managed-services/YOUR_SERVICE_ID/backups" \
  -H "Content-Type: application/json" \
  -d '{"backup_type": "full"}'

Response:

{"status": "pending", "backup_type": "manual"}

The backup is queued immediately. FoundryDB creates a native OpenSearch snapshot via the _snapshot API and streams the result to S3.

Step 2: Monitor Backup Progress​

Poll the backups list to track status:

curl -u admin:YOUR_API_TOKEN \
  "https://api.foundrydb.com/managed-services/YOUR_SERVICE_ID/backups" | jq '.backups[-1]'

The backup in the test run started at 18:09:28 UTC and completed at 18:10:51 UTC, a total of 82 seconds. This includes the time to create the OpenSearch snapshot, compress the data, encrypt it, and upload it to S3.

Step 3: Inspect the Completed Backup Record​

The full backup record from the test:

{
  "id": "fe71b367-be08-467b-8f54-4c07a30378a6",
  "backup_type": "manual",
  "backup_method": "opensearch_snapshot",
  "status": "completed",
  "s3_bucket": "managed-database-backups",
  "s3_path_prefix": "opensearch/14869f1e.../fe71b367.../",
  "retention_days": 7,
  "expires_at": "2026-04-21T18:10:51Z",
  "encryption_enabled": true,
  "encryption_algorithm": "AES-256-GCM",
  "encryption_key_id": "bek_d379a3f0"
}

Key fields to note:

  • backup_method: opensearch_snapshot confirms FoundryDB uses the native OpenSearch snapshot mechanism, not a filesystem-level copy. This means the backup is consistent and does not require stopping the cluster.
  • encryption_algorithm: AES-256-GCM with a managed key identifier means the backup data is encrypted at rest. The key is managed by FoundryDB's key management system. You do not need to supply or rotate keys manually.
  • retention_days: 7 is the default. The expires_at field shows when the backup will be automatically deleted from S3.
  • s3_path_prefix includes both a service-level prefix and the backup UUID, so multiple backups for the same service are stored in separate S3 prefixes.

Step 4: List All Backups for the Service​

curl -u admin:YOUR_API_TOKEN \
  "https://api.foundrydb.com/managed-services/YOUR_SERVICE_ID/backups" | \
  jq '.backups[] | {id, status, backup_type, created_at, expires_at}'

This returns both automatic scheduled backups and any manual backups you have triggered. Scheduled backups run on the retention schedule configured for your service tier.

Step 5: Restore from a Backup​

To test the restore flow, we first deleted the restore-test index (3 documents) to simulate data loss:

curl -sk -u YOUR_USER:YOUR_PASSWORD \
  -X DELETE "https://YOUR_OPENSEARCH_HOST:9200/restore-test"

Confirmed deletion (HTTP 404 on the index). Then triggered a restore:

curl -u admin:YOUR_API_TOKEN \
  -X POST "https://api.foundrydb.com/managed-services/YOUR_SERVICE_ID/restore" \
  -H "Content-Type: application/json" \
  -d '{"backup_id": "BACKUP_ID", "restore_type": "full"}'

Response:

{
  "instance_id": "ece2436f-5731-45d9-b505-3c5c5340784b",
  "message": "Restore task has been submitted to the agent",
  "restore_type": "full",
  "status": "restore_initiated",
  "task_id": "f32546fb-a055-484e-b578-83b391e48d1e"
}

After the restore completed, we verified the data was recovered:

curl -sk -u YOUR_USER:YOUR_PASSWORD \
  "https://YOUR_OPENSEARCH_HOST:9200/restore-test/_count"
# {"count": 3}

curl -sk -u YOUR_USER:YOUR_PASSWORD \
  "https://YOUR_OPENSEARCH_HOST:9200/restore-test/_search" | jq '.hits.hits[]._source'

All 3 documents were restored with original values intact:

[
  {"title": "Document One", "value": 100},
  {"title": "Document Two", "value": 200},
  {"title": "Document Three", "value": 300}
]

FoundryDB calls the OpenSearch _snapshot/{repository}/{snapshot}/_restore API on the cluster. The service remains in Running state throughout the restore. For large clusters, restore time scales with data volume.

What FoundryDB Handles for You​

Without FoundryDB, setting up OpenSearch snapshots requires:

  1. Creating an S3 bucket with the right policy.
  2. Configuring an IAM role or access key with s3:PutObject and s3:GetObject.
  3. Registering a snapshot repository via the OpenSearch _snapshot API.
  4. Writing a cron job or Lambda to trigger snapshots on schedule.
  5. Implementing retention logic to delete old snapshots.
  6. Setting up server-side encryption with KMS or SSE-S3.

FoundryDB does all of this during cluster provisioning. The first time you call the backups endpoint, the repository is already registered and the bucket is already configured. Encryption keys are created and rotated automatically.

Backup Frequency and Retention​

Default retention is 7 days. FoundryDB runs automatic backups on a schedule determined by your service tier. Manual backups (as shown above) can be triggered at any time and count against the same retention window.

The expires_at field is authoritative. Once a backup passes its expiry, it is deleted from S3 and no longer available for restore. If you need to keep a backup longer, trigger a new manual backup before the expiry date.

Provision a FoundryDB OpenSearch cluster with automated backups at foundrydb.com. Documentation at docs.foundrydb.com.