volume_backup

El dominio volume_backup tiene 14 acciones. En la superficie meta se alcanzan todas a través de arcane_volume_backup; en la individual, cada una es una herramienta propia; en la dinámica se ejecutan con arcane_execute_action y el ID canónico.

Resumen

Acción	Título	Tipo
`volume_backup.browse_files`	Browse files in a volume backup	lectura
`volume_backup.create`	Create volume backup	escritura
`volume_backup.delete`	Delete volume backup	destructiva
`volume_backup.discover`	Discover volume backups on an S3 destination	escritura
`volume_backup.download`	Download volume backup	lectura
`volume_backup.files`	List files in a volume backup	lectura
`volume_backup.has_path`	Check if backup contains path	lectura
`volume_backup.list`	List volume backups	lectura
`volume_backup.policy_get`	Get volume backup policies	lectura
`volume_backup.policy_update`	Update volume backup policies	escritura
`volume_backup.restore`	Restore volume backup	destructiva
`volume_backup.restore_files`	Restore specific files from a volume backup	destructiva
`volume_backup.upload`	Upload and restore volume backup	destructiva
`volume_backup.upload_to_s3`	Upload volume backup	escritura

Acciones

`volume_backup.browse_files`

Browse files in a volume backup

Tipo: lectura
Parámetros obligatorios: backupId
Meta-herramienta: arcane_volume_backup con "action": "browse_files"
Herramienta individual: arcane_volume_backup_browse_files
Ruta de Arcane: GET /api/environments/{id}/volumes/backups/{backupId}/files/browse
ID de operación: browse-volume-backup-files
Uso: One directory level of the backup (backupId from volume_backup.list, path relative to the root, default the root, and a failed backup answers 500 as in volume_backup.files) as entries with path and isDirectory, paged with start and limit (default 20). search matches full paths case-insensitively across the whole backup, ignoring path. The paths returned are what volume_backup.restore_files takes.
Acciones relacionadas: volume_backup.list, volume_backup.files, volume_backup.restore_files

`volume_backup.create`

Create volume backup

Tipo: escritura
Parámetros obligatorios: volumeName
Meta-herramienta: arcane_volume_backup con "action": "create"
Herramienta individual: arcane_volume_backup_create
Ruta de Arcane: POST /api/environments/{id}/volumes/{volumeName}/backups
ID de operación: create-volume-backup
Uso: Starts a backup of one volume (volumeName from volume.list) and returns at once with the new entry (id, status running). Poll volume_backup.list until its status is succeeded or failed. With no body it backs up locally. policyId (from volume_backup.policy_get) uses that policy’s local/S3 targets, S3 destination, stopContainers and retention (older backups of the policy beyond retentionCount are deleted), and destination local, s3 or local_s3 overrides the targets. Without policyId, s3 and local_s3 need s3DestinationId from s3_destination.list. With policyId the policy’s S3 destination is used and s3DestinationId is ignored. Fails with 409 while another backup of the volume runs. Needs volumes:backup. Not backup.create, which backs up Arcane itself.
Acciones relacionadas: volume.list, volume_backup.list, volume_backup.policy_get, s3_destination.list, backup.volume_run

`volume_backup.delete`

Delete volume backup

Tipo: destructiva — exige confirm: true
Parámetros obligatorios: backupId
Meta-herramienta: arcane_volume_backup con "action": "delete"
Herramienta individual: arcane_volume_backup_delete
Ruta de Arcane: DELETE /api/environments/{id}/volumes/backups/{backupId}
ID de operación: delete-volume-backup
Uso: Permanently deletes one volume backup (backupId from volume_backup.list): its local snapshot or archive, its S3 copy if it has one, and the record. Needs volumes:backup, fails with 404 for an unknown backupId and fails (does not wait) while a backup, S3 upload or delete of the same volume is running. If the S3 copy cannot be removed the record stays with only that copy.
Acciones relacionadas: volume_backup.list, volume_backup.download

`volume_backup.discover`

Discover volume backups on an S3 destination

Import existing volume backups stored on the destination by this or other Arcane instances

Tipo: escritura
Parámetros obligatorios: s3DestinationId
Meta-herramienta: arcane_volume_backup con "action": "discover"
Herramienta individual: arcane_volume_backup_discover
Ruta de Arcane: POST /api/environments/{id}/volumes/backups/discover
ID de operación: discover-volume-backups
Desde: Arcane v2.12.0
Uso: Imports the volume backups found on an S3 destination (s3DestinationId from s3_destination.list), written by this or another Arcane instance, so volume_backup.list shows them and volume_backup.restore can use them. Needs the recovery key set with backup.recovery_key_set. Returns count of new records and per-instance errors, skipping ones already known. Arcane system backups are discovered with backup.discover.
Acciones relacionadas: s3_destination.list, backup.recovery_key_set, volume_backup.list, volume_backup.restore, backup.discover

`volume_backup.download`

Download volume backup

Tipo: lectura
Parámetros obligatorios: backupId
Meta-herramienta: arcane_volume_backup con "action": "download"
Herramienta individual: arcane_volume_backup_download
Ruta de Arcane: GET /api/environments/{id}/volumes/backups/{backupId}/download
ID de operación: download-volume-backup
Uso: Returns the backup (backupId from volume_backup.list) as a .tar.gz archive blob. Only backups with a local copy can be downloaded, not S3-only ones, and a failed backup (status failed, no snapshot) answers 500 rather than a 4xx. An archive larger than ARCANE_MCP_MAX_DOWNLOAD_BYTES (default 4 MiB) is not returned at all: the result only holds truncated true and a note.
Acciones relacionadas: volume_backup.list, volume_backup.files, volume_backup.upload

`volume_backup.files`

List files in a volume backup

Tipo: lectura
Parámetros obligatorios: backupId
Meta-herramienta: arcane_volume_backup con "action": "files"
Herramienta individual: arcane_volume_backup_files
Ruta de Arcane: GET /api/environments/{id}/volumes/backups/{backupId}/files
ID de operación: list-backup-files
Uso: Flat list of every file path in the backup (backupId from volume_backup.list), relative to the volume root. A failed backup (no snapshot) answers 500 ‘volume backup has no Rustic snapshot’ rather than a 4xx. For one directory level at a time with paging and search use volume_backup.browse_files.
Acciones relacionadas: volume_backup.list, volume_backup.browse_files, volume_backup.restore_files

`volume_backup.has_path`

Check if backup contains path

Tipo: lectura
Parámetros obligatorios: backupId
Meta-herramienta: arcane_volume_backup con "action": "has_path"
Herramienta individual: arcane_volume_backup_has_path
Ruta de Arcane: GET /api/environments/{id}/volumes/backups/{backupId}/has-path
ID de operación: backup-has-path
Uso: Answers exists true or false for one relative file path (e.g. sub/b.txt) in the backup, e.g. before volume_backup.restore_files, with backupId from volume_backup.list. A failed backup answers 500 as in volume_backup.files.
Acciones relacionadas: volume_backup.files, volume_backup.restore_files

`volume_backup.list`

List volume backups

Tipo: lectura
Parámetros obligatorios: volumeName
Meta-herramienta: arcane_volume_backup con "action": "list"
Herramienta individual: arcane_volume_backup_list
Ruta de Arcane: GET /api/environments/{id}/volumes/{volumeName}/backups
ID de operación: list-volume-backups
Uso: Paged backups of one volume (volumeName required, limit defaults to 20) with id, status (running, succeeded, failed), trigger (manual, scheduled, safety), destination, format, size, snapshot IDs and policyId. The id is the backupId the other volume_backup actions take. type=system keeps backups made by the centralized backup.volume_* policies, type=volume the rest. Restores leave trigger=safety backups here. For backups of every volume at once use backup.history.
Acciones relacionadas: volume_backup.create, volume_backup.browse_files, volume_backup.restore, volume_backup.delete, backup.history

`volume_backup.policy_get`

Get volume backup policies

Tipo: lectura
Parámetros obligatorios: volumeName
Meta-herramienta: arcane_volume_backup con "action": "policy_get"
Herramienta individual: arcane_volume_backup_policy_get
Ruta de Arcane: GET /api/environments/{id}/volumes/{volumeName}/backup-policy
ID de operación: get-volume-backup-policy
Uso: Scheduled backup policies of one volume (volumeName from volume.list), each with id, enabled, schedule, retention, targets and its last run. The ids are what volume_backup.policy_update keeps and volume_backup.create takes as policyId. Centralized policies covering many volumes are in backup.volume_config_get.
Acciones relacionadas: volume_backup.policy_update, volume_backup.create, backup.volume_config_get

`volume_backup.policy_update`

Update volume backup policies

Tipo: escritura
Parámetros obligatorios: volumeName, policies
Meta-herramienta: arcane_volume_backup con "action": "policy_update"
Herramienta individual: arcane_volume_backup_policy_update
Ruta de Arcane: PUT /api/environments/{id}/volumes/{volumeName}/backup-policy
ID de operación: update-volume-backup-policy
Uso: Replaces the volume’s whole list of policies: entries with an id from volume_backup.policy_get update that policy, entries without one are created, and omitted policies are deleted ([] removes all). Each needs enabled, schedule (six-field cron with seconds, e.g. 0 0 3 * * ), retentionCount, localEnabled and s3Enabled (with s3DestinationId). stopContainers is optional. An enabled per-volume policy makes the centralized backup.volume_ backups skip this volume.
Acciones relacionadas: volume_backup.policy_get, s3_destination.list, backup.volume_config_update

`volume_backup.restore`

Restore volume backup

Tipo: destructiva — exige confirm: true
Parámetros obligatorios: volumeName, backupId
Meta-herramienta: arcane_volume_backup con "action": "restore"
Herramienta individual: arcane_volume_backup_restore
Ruta de Arcane: POST /api/environments/{id}/volumes/{volumeName}/backups/{backupId}/restore
ID de operación: restore-volume-backup
Uso: Overwrites the whole volume with the backup (volumeName must be the backup’s volume, backupId from volume_backup.list): stops the running containers using the volume, takes a safety backup, restores (files not in the backup are removed) and starts the containers again. A missing volume is created first (no safety backup then). Refused when a running Arcane-managed container mounts the volume. Runs to completion before answering. To put back only some paths use volume_backup.restore_files.
Acciones relacionadas: volume_backup.list, volume_backup.restore_files, volume_backup.browse_files, volume.workspace_get

`volume_backup.restore_files`

Restore specific files from a volume backup

Tipo: destructiva — exige confirm: true
Parámetros obligatorios: volumeName, backupId
Meta-herramienta: arcane_volume_backup con "action": "restore_files"
Herramienta individual: arcane_volume_backup_restore_files
Ruta de Arcane: POST /api/environments/{id}/volumes/{volumeName}/backups/{backupId}/restore-files
ID de operación: restore-volume-backup-files
Uso: Restores only the given paths (relative, from volume_backup.browse_files or volume_backup.files) of the backup into its volume (volumeName must be the backup’s volume). A directory path is restored as a whole, removing files in it that the backup lacks. selectAll with search restores every path containing the search text, selectAll alone restores everything like volume_backup.restore, but paths cannot be combined with selectAll. Like a full restore it stops the containers using the volume, takes a safety backup first and restarts them. Other files stay as they are.
Acciones relacionadas: volume_backup.browse_files, volume_backup.files, volume_backup.has_path, volume_backup.restore, volume.workspace_file_get

`volume_backup.upload`

Upload and restore volume backup

Restore a volume from a complete chunked upload session containing a tar.gz backup archive. multipart/form-data bodies are still accepted for backward compatibility. That form is deprecated and will be removed in a future release.

Tipo: destructiva — exige confirm: true
Parámetros obligatorios: volumeName, uploadId
Meta-herramienta: arcane_volume_backup con "action": "upload"
Herramienta individual: arcane_volume_backup_upload
Ruta de Arcane: POST /api/environments/{id}/volumes/{volumeName}/backups/upload
ID de operación: upload-volume-backup
Uso: Replaces the contents of a volume with a .tar.gz archive uploaded first with upload.session_create (kind volume-backup) and upload.chunk_put. Pass its uploadId. A safety backup is taken first, but containers using the volume are not stopped.
Acciones relacionadas: upload.session_create, upload.chunk_put, volume_backup.download, volume_backup.restore

`volume_backup.upload_to_s3`

Upload volume backup

Upload an existing local volume backup to the selected S3 destination

Tipo: escritura
Parámetros obligatorios: backupId, s3DestinationId
Meta-herramienta: arcane_volume_backup con "action": "upload_to_s3"
Herramienta individual: arcane_volume_backup_upload_to_s3
Ruta de Arcane: POST /api/environments/{id}/volumes/backups/{backupId}/upload
ID de operación: upload-retained-volume-backup-to-s3
Uso: Copies an existing succeeded local backup (backupId from volume_backup.list, a failed one is refused with 500) to an S3 destination (s3DestinationId from s3_destination.list). The returned backup has destination local_s3 and a remoteSnapshotId. A backup already on S3 is refused. To back up straight to S3 use volume_backup.create with destination s3.
Acciones relacionadas: volume_backup.list, s3_destination.list, volume_backup.create