Add incremental backup and restore

[Chyenne8]

Summary

Implements full incremental backup/restore capability using GNU tar's --listed-incremental mechanism. Reduces backup time and storage for large Pulp deployments by only backing up changed files.

Backup Features

Add --incremental CLI parameter:

foremanctl backup /backups --incremental /backups/foreman-backup-TIMESTAMP

Implementation:

• Modified tar commands to use --listed-incremental with .snar snapshot files
• .config.snar tracks foremanctl state changes
• .pulp.snar tracks Pulp content changes
• Replaced community.general.archive with raw tar for --listed-incremental support
• Copy .snar files from previous backup before tar runs
• Validate previous backup exists and contains .snar files
• Enhanced error messages suggest alternative backups when .snar missing
• Metadata records: is_incremental, base_backup_dir, base_backup_timestamp

Error handling automation:

• Scans parent directory for backups with .snar support
• Lists available alternatives with type and timestamp
• Provides ready-to-use command with suggested backup

Restore Features

Auto-detect incremental backups from metadata:

• Parse metadata.yml to identify backup type
• Display full vs incremental in validation output

Backup chain validation:

• Verify base backup directory exists
• Confirm base backup metadata matches expected timestamp
• Check if base backup already restored via .last_restore_timestamp
• Fail with clear instructions if chain incomplete

Add --chain for automatic chain restore:

foremanctl restore /backups/foreman-backup-TIMESTAMP --chain

Chain restore automation:

• Recursively walks metadata to build full dependency chain
• Restores backups in chronological order (full -> inc1 -> inc2)
• Databases restored only from full backup
• Incrementals apply file changes using --listed-incremental=/dev/null
• Eliminates manual multi-step restore process

Handle .snar files during restore:

• Detect .snar presence to identify incremental archives
• Use tar --listed-incremental=/dev/null for extraction
• Fall back to unarchive module for full backups

Usage Examples

Create full backup (generates .snar files):

foremanctl backup /backups

Create incremental backup:

foremanctl backup /backups --incremental /backups/foreman-backup-20260629T120000

Restore with auto-chain (recommended):

foremanctl restore /backups/foreman-backup-20260701T080000 --chain

Manual chain restore:

foremanctl restore /backups/foreman-backup-20260629T120000
foremanctl restore /backups/foreman-backup-20260630T080000 --force
foremanctl restore /backups/foreman-backup-20260701T080000 --force

Validate incremental backup:

foremanctl restore /backups/foreman-backup-TIMESTAMP --validate

Testing

Backup:

• ✅ Full backup creates .config.snar and .pulp.snar files
• ✅ Incremental backup significantly smaller than full
• ✅ Error with suggestions when .snar files missing
• ✅ Metadata correctly tracks incremental status

Restore:

• ✅ Incremental detected from metadata
• ✅ Chain validation prevents incomplete restores
• ✅ --chain automatically handles dependencies
• ✅ Clear errors for missing base backups

Files Modified

Backup:

• src/playbooks/backup/metadata.obsah.yaml
• src/roles/backup/tasks/main.yaml
• src/roles/backup/tasks/pulp_content.yaml
• src/roles/backup/tasks/metadata.yaml
• docs/user/backup.md

Restore:

• src/playbooks/restore/metadata.obsah.yaml
• src/roles/restore/tasks/validate.yaml
• src/roles/restore/tasks/main.yaml
• src/roles/restore/tasks/restore_pulp_content.yaml
• src/roles/restore/tasks/restore_foremanctl_state.yaml
• src/roles/restore/tasks/restore_databases.yaml
• src/roles/restore/tasks/restore_chain.yaml (new)
• src/roles/restore/tasks/restore_chain_walk.yaml (new)
• src/roles/restore/tasks/restore_single.yaml (new)
• docs/user/restore.md

Stats

• 15 files changed
• 550 insertions
• 24 deletions