Managed Service Backups
Codesphere allows you to enable automated backups for your managed services to prevent data loss. This page covers the general backup concepts that apply to all managed services. Provider-specific configuration examples and limitations are documented on the respective provider pages.
Key Concepts
- Backup Store: The external storage location where your backups are saved. This can be an external S3-compatible service (like AWS S3) or a Codesphere S3 Managed Service.
- Retention Period: The number of days a backup is kept before it is automatically deleted by Codesphere (
deleteRetentionDays). - Interval: How often a new backup is created, measured in hours (
intervalH). Codesphere handles the scheduling automatically. - Recovery: Creating a new managed service in the exact state of a previous backup or point in time.
Checking Provider Capabilities
Not all managed services support backups or point-in-time recovery. To see if a provider supports it, you can check the /managed-services/providers API endpoint. The capabilities object will list two specific features:
backups: The provider supports taking automated backups and recovering a service to the exact state at the moment a specific backup was taken.pointInTimeRecovery: In addition to standard backups, the provider supports recovering a service to an arbitrary point in time (e.g., a specific minute) between two backups.
If pointInTimeRecovery is true, the backups capability will also be true.
You can also check the capabilities in the UI: the provider details page, which opens when you click Start setup on a provider card in the catalog, lists them as well.
Backups are currently supported for PostgreSQL, Babelfish, DocumentDB, and Object Storage, and can be saved to any S3-compatible backup store.
Enabling Backups
You can enable backups when creating a new managed service or by updating an existing one, either in the UI or via the API.
Via the UI
If the provider supports backups, the managed service's settings have a Backups tab. It's there for standalone managed services in your Resource Group and for managed services in the Landscape Config Editor, both when you create a service and when you edit one. In this tab you turn on automatic backups and set the backup frequency (in hours), the retention period (in days), and the S3-compatible backup store.
Via the API
Provide the backups block in the request body with enabled: true, your intervalH, deleteRetentionDays, and your storage config and secrets. This works both when creating a new service (POST) and when updating an existing one (PATCH).
The values you provide for config and secrets (both in the backups block and the recoverFrom block below) can vary between providers. Codesphere validates them against the backups.configSchema and backups.secretsSchema defined by the provider. You can inspect these schemas in the response of the /managed-services/providers API endpoint, and find concrete examples in the provider documentation. When you restore from a backup ID, config and secrets in recoverFrom are optional. See Restore using only the backup ID.
Via ci.yml
If you define your managed services in a ci.yml file, you can specify backup configuration directly there. Add a backups block to the managed service entry:
managedServices:
my-postgres:
provider:
name: postgres
schemaVersion: v1
plan:
id: 1
parameters: {}
config: {}
secrets: {}
backups:
enabled: true
deleteRetentionDays: 7
intervalH: 24
config:
type: s3
endpointUrl: https://s3.eu-central-1.amazonaws.com
bucket: ${{ workspace.env.BACKUP_BUCKET }}
prefix: my-prefix
accessKeyId: ${{ workspace.env.BACKUP_ACCESS_KEY_ID }}
secrets:
secretKey: ${{ vault.backup_secret_key }}
Setting enabled: false disables backups and requires no other fields. See Disabling and Re-enabling Backups for what this means for your service. When enabled: true, the following fields are required:
| Field | Description |
|---|---|
deleteRetentionDays | Days to keep each backup before automatic deletion. Must be between 1 and 365. |
intervalH | Backup frequency in hours. Must be between 1 and 744. |
config | Provider-specific storage configuration. Supports environment variable references. |
secrets | Provider-specific storage credentials. Supports vault references. |
The config and secrets values must match the backups.configSchema and backups.secretsSchema defined by the provider. See the provider documentation for concrete examples.
Viewing Backup History
Via the UI
The Restore section in the Backups tab displays a list of all completed backups with:
- Backup ID: Unique identifier for the backup
- Start Time: When the backup was initiated
- Finish Time: When the backup completed successfully
- Restore: A button to restore the service from this backup. See Restoring from a Backup.
Via the API
List your managed services and check the backups.entries array of the service you are interested in:
curl "https://api.codesphere.com/managed-services?resourceGroup=YOUR_RESOURCE_GROUP_ID" \
-H "Authorization: Bearer YOUR_API_TOKEN"
{
"id": "8316ee2f-87f8-424e-b925-7382dc50d662",
"name": "my-postgres",
"backups": {
"enabled": true,
"intervalH": 12,
"deleteRetentionDays": 30,
"entries": [
{
"id": "0d95627e-2adf-4f04-9b3d-08d258f978c6",
"scheduledAt": "2026-07-12T19:38:49.410Z",
"initiatedAt": "2026-07-12T19:38:49.410Z",
"confirmedAt": "2026-07-12T19:38:49.410Z"
}
]
}
}
Each backup entry contains the backup id (which you can pass as the backup ID in recoverFrom when restoring), when it was scheduled and initiated, and confirmedAt — the time the backup was confirmed in the backup store.
Restoring from a Backup (Recovery)
Restoring a backup in Codesphere always creates a new managed service, rather than replacing the data in-place. The existing managed service remains untouched and completely independent.
Via the UI
Open the managed service, go to the Backups tab, and click Restore next to a finished backup. This opens the Create Service From Backup dialog, prefilled with the settings of the source service.
The UI restores from a specific backup ID only. Point-in-time recovery is available through the API. The requirements listed in Restore using only the backup ID also apply to restores started from the UI.
Via the API
To restore a backup, you create a new managed service and use the recoverFrom property to either specify a specific backup ID or — if the provider supports point-in-time recovery — a previous managed service ID with a recovery timestamp.
When recovering, the backups block is not strictly required.
It only controls if the recovered service is taking backups of itself.
Restore using only the backup ID
When you restore from a specific backup ID, you can omit config and secrets from the recoverFrom block and pass only the backup id:
"recoverFrom": {
"id": "BACKUP_UUID_HERE"
}
Codesphere then looks up the managed service the backup was taken from and reuses its current backup store config and secrets. This only works if:
- You have permission to manage the managed service the backup was taken from.
- The new service uses the same provider and provider schema version as the service the backup was taken from.
- The backup has been confirmed.
- The source service still has a backup store configured.
For concrete recovery examples, see the provider documentation.
Via ci.yml
To restore a managed service of your landscape, add a recoverFrom block to its entry in ci.yml:
run:
my-postgres:
provider:
name: postgres
schemaVersion: v1
plan:
id: 1
parameters: {}
config: {}
secrets: {}
recoverFrom:
id: BACKUP_UUID_HERE
recoverFrom is only applied when the landscape sync creates the service. Adding or changing it for a service that already exists has no effect.
recoverFrom reference
recoverFrom accepts the same three shapes in the API and in ci.yml. Pick exactly one.
| Shape | Restores | Backup store |
|---|---|---|
id | The given backup. | Codesphere finds the service the backup belongs to and uses the backup store settings saved for it. |
id, config, secrets | The given backup. | The store you provide. |
msId, time, config, secrets | The service with ID msId at the point in time time. Requires pointInTimeRecovery. | The store you provide. It is required because msId does not need to refer to an existing service, so Codesphere cannot look it up. |
Codesphere rejects a recoverFrom block that does not match one of these shapes. For example, it rejects an id that is not a UUID, and it rejects id together with only one of config or secrets.
| Field | Description |
|---|---|
id | UUID of the backup, as shown in the Backup ID column of the Backups tab or in backups.entries[].id of the API response. |
msId | UUID of the managed service to recover from. The service does not need to exist anymore. |
time | ISO 8601 timestamp to recover from, for example 2026-04-10T12:00:00Z. The new service gets the latest state at or before this time. If the exact moment is not available, for example because recent changes have not reached the backup store yet, it gets the closest earlier state. A completed backup must exist before time. |
config | Backup store location, see Backup store config. |
secrets | Backup store credentials, see Backup store secrets. |
Backup store config
config describes where the backups are currently stored. Unknown fields are rejected. In ci.yml, values support environment variable references (for example ${{ workspace.env.BACKUP_BUCKET }}) and vault references (for example ${{ vault.backup_bucket }}). Vault references are not resolved in confidential workspaces, so use environment variable references there.
| Field | Required | Description |
|---|---|---|
type | Yes | Always s3. |
endpointUrl | Yes | Regional endpoint of your S3-compatible store, for example https://s3.eu-central-1.amazonaws.com. |
bucket | Yes | Name of the bucket, without s3://. |
prefix | No | Path inside the bucket, without leading or trailing /, for example team-a/backups. |
accessKeyId | Yes | Access key ID for the store. |
Older configurations that use destinationPath: s3://bucket/prefix instead of bucket and prefix are still accepted and converted. Use bucket and prefix for new configurations.
Backup store secrets
In ci.yml, values support vault references (for example ${{ vault.backup_secret_key }}) and environment variable references (for example ${{ workspace.env.BACKUP_SECRET_KEY }}). Vault references are not resolved in confidential workspaces, so use environment variable references there.
| Field | Required | Description |
|---|---|---|
secretKey | Yes | Secret access key for the store. |
Examples
Use this table to choose a shape:
| Example | Use it when | Do not use it when |
|---|---|---|
| Backup ID only | The service the backup was taken from still exists, still has the same backup store settings, and you have permission to manage it. | The backup store settings changed after the backup was taken, the source service is gone, or the backup belongs to another resource group in a landscape. |
| Backup ID with a backup store | You know where the backup is stored and want to restore it independent of the source service. Examples are restoring into a different Codesphere environment, recovering after a disaster where Codesphere's own data is lost, or restoring after the store settings or the source service changed. | You are not sure about the exact bucket and prefix the backup is written to. A wrong location makes the restore fail. |
| Point in time | You need the state at a moment between two backups, for example right before data was deleted by mistake. The provider must support point-in-time recovery. | You want one specific backup (use its id), or the provider does not support point-in-time recovery. |
Backup ID only
recoverFrom:
id: 0d95627e-2adf-4f04-9b3d-08d258f978c6
Backup ID with a backup store
recoverFrom:
id: 0d95627e-2adf-4f04-9b3d-08d258f978c6
config:
type: s3
endpointUrl: https://s3.eu-central-1.amazonaws.com
bucket: my-codesphere-backups
prefix: team-a/backups
accessKeyId: ${{ workspace.env.BACKUP_ACCESS_KEY_ID }}
secrets:
secretKey: ${{ vault.backup_secret_key }}
Point in time
recoverFrom:
msId: 8316ee2f-87f8-424e-b925-7382dc50d662
time: "2026-04-10T12:00:00Z"
config:
type: s3
endpointUrl: https://s3.eu-central-1.amazonaws.com
bucket: my-codesphere-backups
prefix: team-a/backups
accessKeyId: ${{ workspace.env.BACKUP_ACCESS_KEY_ID }}
secrets:
secretKey: ${{ vault.backup_secret_key }}
When a landscape restores from id only, the backup must belong to a managed service in the same resource group as the landscape.
Triggering a Manual Backup
You can schedule an immediate on-demand backup for a service that has automatic backups enabled. Manual backups are created outside the regular schedule and do not affect your configured backup frequency.
Via the UI
In the Backups tab of your service details, click the Backup Now button. The button is disabled until automatic backups have been enabled and saved.
Via the API
Use the POST endpoint to schedule a backup:
curl -X POST "https://api.codesphere.com/managed-services/YOUR_SERVICE_ID/backups" \
-H "Authorization: Bearer YOUR_API_TOKEN"
As with enabling backups, the provider-specific config and secrets for your backup store must be provided in the request body. They are validated against the provider's backups.configSchema and backups.secretsSchema — check the provider documentation for concrete examples.
Disabling and Re-enabling Backups
You can turn automatic backups off at any time. Switch off Automatic Backups in the Backups tab, send backups: { "enabled": false } in a PATCH request, or set enabled: false in your ci.yml. No other backups fields are needed.
What Happens When You Disable Backups
- No new backups are created. This includes scheduled backups that have not initiated yet and manual backups.
- Your service stops using the backup store. A full or unreachable backup store can no longer affect it. It can take a short while until this applies.
- Existing backups are kept. They are not deleted automatically while backups are disabled. You can remove them from your backup store yourself.
- Your backup settings are kept. The backup store, frequency and retention period stay saved.
What Happens When You Re-enable Backups
Switch Automatic Backups back on and save, or send backups: { "enabled": true }. Your saved backup settings are used again. You only need to provide the other backups fields if you want to change them.
- Backups continue on your configured schedule.
- Backups that were scheduled but had not started when you disabled backups may be skipped.
- If your provider supports point-in-time recovery, you cannot recover to a point in time within the period when backups were disabled. Restoring from a backup taken before is not affected.
Disclaimers and Limitations
When using managed service backups, please keep the following in mind:
- User Responsibility for S3 Storage: Encryption and redundancy of backups are the responsibility of the user. You must ensure that the S3 storage you configure satisfies your organization's security and redundancy requirements.
- Bucket Capacity: It is your responsibility to make sure the backup store has enough free space. If the target bucket runs out of space or hits a quota, backups will fail.
- Backup Timing: There is no guarantee on the exact time that a scheduled backup will occur. The actual backup creation could be delayed by a couple of minutes depending on system load and network conditions.