Restore from Backup

Restore feature flag configurations from backup files within the same environment

Restore Overview

FlagFlow's restore functionality allows you to recover your feature flag configuration from previously created backup files within the same environment. Unlike cross-environment migration, restore operations work within a single environment to recover from data loss, configuration errors, or to roll back changes.

Same-Environment Restore: Restore operations are designed for disaster recovery within the same environment. For transferring configurations between different environments, use the Migration functionality instead.

Restore vs Migration

Understanding the difference between restore and migration operations is crucial for using the right tool for your needs:

Restore Operation

  • Works within the same environment
  • Used for disaster recovery and rollbacks
  • Replaces current configuration completely
  • Source and target environment must match
  • Simpler validation and fewer safety checks

Migration Operation

  • Works between different environments
  • Used for promoting changes across stages
  • Analyzes differences and creates specific steps
  • Source and target environments must be different
  • Comprehensive validation and dependency checking

When to Use Restore

Common Restore Scenarios

  • Data Loss Recovery: Restore after etcd data corruption or accidental deletion
  • Configuration Rollback: Return to a known good configuration after problematic changes
  • Environment Recovery: Rebuild flag configuration after system failures
  • Testing Cleanup: Reset development environment to baseline state
  • Hotfix Reversal: Quickly undo emergency changes that caused issues

Before Restoring: Always create a current backup before performing a restore operation. Restore operations completely replace your existing configuration.

Restore Process

Step 1: Verify Backup File

Before restoring, ensure your backup file is valid and matches the current environment:

Backup Verification
# Verify backup file integrity
jq empty backup.json && echo "✅ Valid JSON" || echo "❌ Invalid JSON"

# Check environment match
BACKUP_ENV=$(jq -r '.environment' backup.json)
CURRENT_ENV={ENVIRONMENT:-development}

if [ "$BACKUP_ENV" = "$CURRENT_ENV" ]; then
    echo "✅ Environment matches: $BACKUP_ENV"
else
    echo "❌ Environment mismatch: $BACKUP_ENV != $CURRENT_ENV"
fi

# Check backup contents
echo "📊 Backup contains $(jq '.flags | length' backup.json) flags"

Step 2: Create Pre-Restore Backup

Always create a backup of the current state before restoring:

Pre-Restore Backup
# Create pre-restore backup
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
curl -o "pre-restore-backup-$TIMESTAMP.json"      "http://localhost:3000/migration/export"

echo "📦 Pre-restore backup saved: pre-restore-backup-$TIMESTAMP.json"

Step 3: Perform Restore via Web Interface

Use the FlagFlow web interface to perform the restore:

  1. Navigate to the Migration page in your FlagFlow instance
  2. Locate the File-based Migration section
  3. Click Choose File and select your backup file
  4. Click Analyze Migration - the system will detect this is a restore
  5. Review the restore steps and click Execute Migration

Automatic Detection: FlagFlow automatically detects when you're uploading a backup from the same environment and treats it as a restore operation rather than a migration.

Restore Validation

Environment Verification

FlagFlow performs specific validations for restore operations to ensure safety:

  • Environment Match: Backup environment must match current environment
  • File Integrity: JSON structure and required fields validation
  • Schema Validation: All flag types and constraints must be valid
  • Value Validation: Backup values must comply with their schema definitions

Restore Step Generation

During restore, FlagFlow analyzes the differences between current state and backup to generate restoration steps:

Restore Step Analysis
Example restore steps for production environment:

1. DELETE current_only_flag (exists in current, not in backup)
2. CREATE_DEFAULTVALUE backup_flag (exists in backup, not current)
3. SET_VALUE backup_flag = true (restore backed up value)
4. UPDATE_SCHEMA_DEFAULTVALUE changed_flag (schema changed)
5. SET_VALUE changed_flag = "restored_value" (restore backed up value)

✅ All steps will be selected by default for complete restoration

Restore Strategies

Complete Restore (Recommended)

The default and recommended approach for disaster recovery:

  • Restores all flags exactly as they were in the backup
  • Removes any flags created after the backup
  • Updates all values to match the backup state
  • Ensures complete consistency with the backup point-in-time

Selective Restore

For more granular control over what gets restored:

  • Uncheck specific restoration steps you don't want to execute
  • Useful when you want to keep some recent changes
  • Restore only specific flags or flag groups
  • Requires careful consideration of dependencies

Caution with Selective Restore: Selective restoration may result in an inconsistent state. Only use this approach if you fully understand the implications.

Common Restore Scenarios

Disaster Recovery

Complete Disaster Recovery
# Scenario: Complete data loss in production
# Situation: etcd cluster failure, all flag data lost

1. Identify most recent backup file
   - flagflow_migration_production_20240810-020000.json (daily backup)
   
2. Verify backup integrity and environment match
   - Environment: production ✓
   - 47 flags in backup ✓
   - JSON structure valid ✓

3. Restore steps generated:
   - CREATE_DEFAULTVALUE for all 47 flags
   - SET_VALUE for all flags with non-default values
   
4. Execute complete restore to rebuild entire configuration

Configuration Rollback

Configuration Rollback
# Scenario: Recent changes caused issues, need to rollback
# Situation: Bad deployment 2 hours ago, rollback to pre-deploy state

1. Use pre-deployment backup
   - flagflow_migration_production_20240810-140000.json
   
2. Restore will generate steps to:
   - DELETE new flags created during deployment
   - UPDATE_SCHEMA_DEFAULTVALUE for modified flags
   - SET_VALUE to restore previous values
   
3. Execute to return to known good state

Development Environment Reset

Development Reset
# Scenario: Reset development environment to baseline
# Situation: Development environment cluttered with test flags

1. Use baseline configuration backup
   - flagflow_migration_development_baseline.json
   
2. Restore will clean up:
   - DELETE all experimental flags
   - Reset all values to baseline state
   - Restore original flag schemas
   
3. Development environment returns to clean state

Automated Restore Scripts

Emergency Restore Script

Emergency Restore Script
#!/bin/bash
# emergency-restore.sh - Quick restore for disaster recovery

BACKUP_FILE=$1
FLAGFLOW_URL="http://localhost:3000"

if [ -z "$BACKUP_FILE" ]; then
    echo "Usage: $0 <backup-file.json>"
    exit 1
fi

echo "🚨 Emergency Restore Starting..."
echo "📁 Backup file: $BACKUP_FILE"

# Verify backup file
if [ ! -f "$BACKUP_FILE" ]; then
    echo "❌ Backup file not found: $BACKUP_FILE"
    exit 1
fi

# Validate JSON
if ! jq empty "$BACKUP_FILE" 2>/dev/null; then
    echo "❌ Invalid JSON in backup file"
    exit 1
fi

# Check environment match
BACKUP_ENV=$(jq -r '.environment' "$BACKUP_FILE")
CURRENT_ENV={ENVIRONMENT:-development}

if [ "$BACKUP_ENV" != "$CURRENT_ENV" ]; then
    echo "❌ Environment mismatch: $BACKUP_ENV != $CURRENT_ENV"
    echo "   Use migration instead of restore for cross-environment operations"
    exit 1
fi

echo "✅ Environment verified: $CURRENT_ENV"
echo "📊 Backup contains $(jq '.flags | length' "$BACKUP_FILE") flags"

# Create pre-restore backup
echo "📦 Creating pre-restore backup..."
PRE_RESTORE_BACKUP="pre-restore-backup-$(date +%Y%m%d-%H%M%S).json"
curl -s "$FLAGFLOW_URL/migration/export" -o "$PRE_RESTORE_BACKUP"

if [ $? -eq 0 ]; then
    echo "✅ Pre-restore backup created: $PRE_RESTORE_BACKUP"
else
    echo "❌ Failed to create pre-restore backup"
    exit 1
fi

echo "🎯 Ready for restore. Upload $BACKUP_FILE to FlagFlow migration interface."
echo "🔄 Pre-restore backup available at: $PRE_RESTORE_BACKUP"
echo ""
echo "Manual steps:"
echo "1. Open $FLAGFLOW_URL/ui/migration"
echo "2. Upload $BACKUP_FILE"
echo "3. Click 'Analyze Migration'"
echo "4. Review restore steps and execute"

Scheduled Restore Validation

Restore Validation Test
#!/bin/bash
# validate-restore-readiness.sh - Test restore capability regularly

BACKUP_DIR="/path/to/backups"
FLAGFLOW_URL="http://localhost:3000"
TEST_BACKUP=""

# Find most recent backup
TEST_BACKUP=$(ls -t "$BACKUP_DIR"/flagflow_migration_*.json | head -1)

if [ -z "$TEST_BACKUP" ]; then
    echo "❌ No backup files found in $BACKUP_DIR"
    exit 1
fi

echo "🧪 Testing restore readiness with: $(basename "$TEST_BACKUP")"

# Verify backup can be loaded by migration system
# Note: This would require API endpoint to validate without executing
curl -s -X POST "$FLAGFLOW_URL/migration/validate"      -F "file=@$TEST_BACKUP" | jq .

echo "✅ Restore validation completed"

Best Practices

Before Restore

  • Create Backup: Always backup current state before restoring
  • Verify Environment: Confirm backup matches current environment
  • Check Backup Age: Ensure backup is from the desired point in time
  • Plan Downtime: Notify users of potential service disruption
  • Test First: If possible, test restore in staging environment

During Restore

  • Complete Restore: Use complete restore for disaster recovery
  • Monitor Progress: Watch for any errors during restore execution
  • Avoid Interruption: Don't modify flags while restore is running
  • Document Actions: Record what backup was restored and why

After Restore

  • Verify Completion: Check that all expected flags are present
  • Test Applications: Ensure applications work with restored configuration
  • Monitor Behavior: Watch for any unexpected application behavior
  • Update Documentation: Record the restore operation in logs
  • Resume Backups: Ensure backup schedule continues normally

Troubleshooting

Environment Mismatch Error

  • Verify backup environment matches ENVIRONMENT variable
  • Check backup file was created from the correct environment
  • Use migration instead of restore for cross-environment operations
  • Confirm backup file hasn't been modified or corrupted

Restore Execution Failures

  • Check etcd connectivity and storage availability
  • Verify user has 'migration' permission for restore operations
  • Look for disk space issues that prevent flag creation
  • Review server logs for detailed error messages

Incomplete Restore Results

  • Check if some restore steps were unselected or failed
  • Verify backup file contains all expected flags
  • Look for validation errors that prevented some flag creation
  • Consider re-running restore with missing steps selected

Application Issues After Restore

  • Check if applications expect flags created after the backup
  • Verify restored flag values are appropriate for current application version
  • Look for new application features that depend on missing flags
  • Consider selective restore to preserve some current flags

Advanced Recovery Scenarios

Partial Data Loss

When only some flags are lost or corrupted:

Selective Recovery
# Scenario: Specific flags corrupted, others intact
# Strategy: Selective restore to recover only affected flags

1. Identify affected flags through application errors or monitoring
2. Load backup file and analyze which flags need restoration
3. Use selective restore:
   - Uncheck CREATE/DELETE steps for unaffected flags
   - Include only UPDATE and SET_VALUE steps for corrupted flags
4. Execute selective restore to fix specific issues

Schema Corruption Recovery

Schema-Only Recovery
# Scenario: Flag schemas corrupted but values intact
# Strategy: Restore schemas while preserving current values

1. Load backup with correct schemas
2. Use migration analysis to identify schema differences
3. Execute only UPDATE_SCHEMA_DEFAULTVALUE steps
4. Skip SET_VALUE steps to preserve current values
5. Manually verify and adjust values if needed

Next Steps

After completing a restore operation, consider these follow-up actions:

  • Monitor Applications: Ensure all applications work correctly with restored flags
  • Update Team: Notify team members of the restore operation and its scope
  • Resume Normal Operations: Re-enable any monitoring or automated processes
  • Document Incident: Record the restore operation for future reference
  • Review Backup Strategy: Assess if backup frequency needs adjustment

For creating backups, see the Export and Backup documentation. For cross-environment operations, see the Migration documentation.

© 2025 FlagFlow All Rights Reserved. llms.txt