Restore Configuration

Data from a backup can be restored using the ReplicationDestination CR. In most cases, it is desirable to perform a single restore into an empty PersistentVolume.

Note

Simplified Identity Configuration for Kopia ReplicationDestination

Identity configuration is now OPTIONAL! When not provided, VolSync automatically determines the appropriate identity, making simple same-namespace restores easier.

Automatic Identity (when no identity fields are provided):

  • Username: <destination-name>

  • Hostname: <namespace>

This works perfectly when the ReplicationDestination has the same name as the ReplicationSource and both are in the same namespace.

For more complex scenarios, you can still use:

  1. sourceIdentity: For cross-namespace restores or different names

  2. Explicit identity: Provide both username AND hostname for custom control

Simple Same-Namespace Restore (No Configuration Needed)

The simplest way to restore data is to create a ReplicationDestination with the same name as your ReplicationSource. No identity configuration is needed!

apiVersion: volsync.backube/v1alpha1
kind: ReplicationDestination
metadata:
  name: my-backup  # Same name as the ReplicationSource
  namespace: production
spec:
  kopia:
    destinationPVC: restored-data
    repository: kopia-config
    # No identity configuration needed!
    # Automatically uses:
    # - username: my-backup-production
    # - hostname: production

Advanced: Restoring from a Specific ReplicationSource (sourceIdentity)

For cross-namespace restores or when the destination has a different name than the source, use the sourceIdentity field. This provides automatic discovery of the source configuration.

Understanding the Multi-Tenancy Challenge

Kopia repositories support multiple clients backing up to the same repository. Each client is identified by a unique combination of username and hostname. When you want to restore data, you need to specify the exact identity to restore from.

Without sourceIdentity, you would need to:

  1. Determine the exact username and hostname used by the ReplicationSource

  2. Manually configure these values in your ReplicationDestination

  3. Handle the complexity of VolSync’s automatic identity generation rules

The sourceIdentity field simplifies this by allowing you to specify just the ReplicationSource’s name and namespace, and VolSync automatically generates the matching username and hostname.

How Identity Generation Works with sourceIdentity

When you use sourceIdentity, VolSync generates the identity as follows:

Username Generation:

The username is generated from the sourceName field using the same logic as the ReplicationSource would use:

  • If the source has a custom username, that would need to be specified explicitly

  • Otherwise, uses the sanitized source name

Hostname Generation:

The hostname is generated simply from the namespace:

  1. Standard behavior:

    sourceIdentity:
  sourceName: webapp-backup
  sourceNamespace: production
  sourcePVCName: webapp-data  # Optional - doesn't affect hostname

    Generates hostname: production (always just the namespace)

  2. With auto-discovery (sourcePVCName not provided):

    sourceIdentity:
  sourceName: webapp-backup
  sourceNamespace: production
  # sourcePVCName will be fetched from the ReplicationSource for reference

    VolSync will: - Query the ReplicationSource webapp-backup in namespace production - Read its spec.sourcePVC field for reference (e.g., webapp-data) - Generate hostname: production (always just namespace, PVC name not used)

  3. Key point:

    The hostname is ALWAYS just the namespace name. All PVCs in a namespace share the same hostname.

Complete Identity Example:

For a ReplicationSource with: - Name: webapp-backup - Namespace: production - sourcePVC: webapp-data

The generated identity would be: webapp-backup-production@production (username includes namespace suffix, hostname is just namespace)

Using sourceIdentity

The sourceIdentity field accepts three parameters:

  • sourceName (required): The name of the ReplicationSource that created the backups

  • sourceNamespace (required): The namespace where the ReplicationSource exists

  • sourcePVCName (optional): The name of the source PVC - auto-discovered if not provided

Example: Basic sourceIdentity usage

apiVersion: volsync.backube/v1alpha1
kind: ReplicationDestination
metadata:
  name: restore-webapp
  namespace: production
spec:
  trigger:
    manual: restore-once
  kopia:
    repository: kopia-config
    destinationPVC: webapp-data-restored
    copyMethod: Direct
    # Specify which ReplicationSource's snapshots to restore
    sourceIdentity:
      sourceName: webapp-backup
      sourceNamespace: production

In this example, VolSync will automatically:

  1. Fetch the ReplicationSource configuration from webapp-backup in the production namespace

  2. Auto-discover the sourcePVC name from the ReplicationSource (if sourcePVCName not provided)

  3. Generate the username based on the source name (webapp-backup)

  4. Generate the hostname using just the namespace (PVC name not included)

  5. Connect to the repository using these generated credentials

  6. Restore from the snapshots created by that specific ReplicationSource

Example: Cross-namespace restore with auto-discovery

You can restore snapshots created in a different namespace. For comprehensive guidance on cross-namespace restore scenarios including disaster recovery, environment cloning, and namespace migration, see Cross-Namespace Restore Guide.

Basic cross-namespace restore example:

apiVersion: volsync.backube/v1alpha1
kind: ReplicationDestination
metadata:
  name: restore-from-staging
  namespace: production
spec:
  trigger:
    manual: restore-once
  kopia:
    repository: kopia-config
    destinationPVC: restored-data
    copyMethod: Direct
    # Restore staging data to production
    sourceIdentity:
      sourceName: app-backup
      sourceNamespace: staging
      # sourcePVCName automatically discovered from staging/app-backup ReplicationSource

Example: Explicit PVC name (bypassing auto-discovery)

You can explicitly specify the source PVC name if needed:

apiVersion: volsync.backube/v1alpha1
kind: ReplicationDestination
metadata:
  name: restore-specific-pvc
  namespace: production
spec:
  trigger:
    manual: restore-once
  kopia:
    repository: kopia-config
    destinationPVC: restored-data
    copyMethod: Direct
    sourceIdentity:
      sourceName: multi-pvc-backup
      sourceNamespace: production
      sourcePVCName: specific-data-pvc  # Explicitly specify which PVC's snapshots to restore

Example: Combining sourceIdentity with previous parameter

You can use sourceIdentity together with the previous parameter to restore older snapshots from a specific source:

apiVersion: volsync.backube/v1alpha1
kind: ReplicationDestination
metadata:
  name: restore-previous-version
  namespace: production
spec:
  trigger:
    manual: restore-once
  kopia:
    repository: kopia-config
    destinationPVC: restored-data
    copyMethod: Direct
    # Identify the source
    sourceIdentity:
      sourceName: database-backup
      sourceNamespace: production
      # Auto-discovery will fetch the PVC name from the source
    # Skip the latest snapshot, use the previous one
    previous: 1

Auto-Discovery Feature Details

The auto-discovery feature simplifies configuration by automatically fetching the source PVC name from the ReplicationSource. This is particularly useful when:

  1. You don’t remember the exact PVC name: No need to look up the source configuration

  2. PVC names might change: Auto-discovery always gets the current value

  3. Reducing configuration errors: Eliminates typos in PVC names

  4. Simplifying documentation: Restore procedures don’t need to specify PVC names

How Auto-Discovery Works

When sourcePVCName is not provided in sourceIdentity:

  1. VolSync queries the Kubernetes API for the specified ReplicationSource

  2. It reads the spec.sourcePVC field from the ReplicationSource

  3. This value is used to generate the hostname for identity matching

  4. If the ReplicationSource cannot be found or accessed, an error is reported

Auto-Discovery Requirements

  • The ReplicationSource must exist in the specified namespace

  • The operator must have permission to read ReplicationSource resources

  • The ReplicationSource must have a spec.sourcePVC field defined

When to Use Explicit sourcePVCName

While auto-discovery is convenient, you might want to specify sourcePVCName explicitly when:

  1. Cross-cluster restores: The source cluster/ReplicationSource is not accessible

  2. Performance optimization: Avoid the API call to fetch the ReplicationSource

  3. Historical restores: Restoring from a source that no longer exists

  4. Custom scenarios: When you need to override the discovered value

Repository Auto-Discovery

VolSync can automatically discover and use the repository configuration from the ReplicationSource when using sourceIdentity. This feature reduces manual configuration overhead by automatically fetching the repository secret name from the source backup configuration.

How Repository Auto-Discovery Works

When using sourceIdentity, VolSync can automatically discover the repository configuration:

  1. Query the ReplicationSource: VolSync fetches the ReplicationSource specified in sourceIdentity

  2. Extract Repository: If the ReplicationSource has spec.kopia.repository configured, VolSync automatically uses this value for the restore operation

  3. Apply to Restore: The discovered repository is used to connect to the backup repository

Priority Order for Repository Configuration

VolSync resolves the repository with the following priority:

  1. Explicit repository in ReplicationDestination: Highest priority (manual override)

  2. Auto-discovered from ReplicationSource: Automatic discovery when destination repository is empty

  3. Empty repository: If neither explicit nor discovered repository is available, results in configuration error

Example: Repository Auto-Discovery in Action

Consider this ReplicationSource with a repository configuration:

# Original ReplicationSource that created the backup
apiVersion: volsync.backube/v1alpha1
kind: ReplicationSource
metadata:
  name: webapp-backup
  namespace: production
spec:
  sourcePVC: webapp-data
  kopia:
    repository: production-kopia-config  # Repository secret name

When restoring with sourceIdentity, the repository is automatically discovered:

apiVersion: volsync.backube/v1alpha1
kind: ReplicationDestination
metadata:
  name: webapp-restore
  namespace: production
spec:
  trigger:
    manual: restore-once
  kopia:
    # No repository specified - will be auto-discovered!
    destinationPVC: webapp-data-restored
    copyMethod: Direct
    sourceIdentity:
      sourceName: webapp-backup
      sourceNamespace: production

VolSync will automatically:

  1. Fetch the webapp-backup ReplicationSource from the production namespace

  2. Discover that it uses repository: production-kopia-config

  3. Use this repository configuration for the restore operation

  4. Connect to the same backup repository that the source used

Manual Override of Auto-Discovery

You can override the auto-discovered repository by specifying it explicitly:

apiVersion: volsync.backube/v1alpha1
kind: ReplicationDestination
metadata:
  name: webapp-restore-custom
spec:
  kopia:
    # Explicit repository overrides auto-discovery
    repository: different-repo-config
    destinationPVC: webapp-data-restored
    copyMethod: Direct
    sourceIdentity:
      sourceName: webapp-backup
      sourceNamespace: production

Cross-Environment Restore Example

Repository auto-discovery simplifies cross-environment restores when the same repository is shared:

# Restore production data to staging using auto-discovered repository
apiVersion: volsync.backube/v1alpha1
kind: ReplicationDestination
metadata:
  name: restore-prod-to-staging
  namespace: staging
spec:
  trigger:
    manual: restore-once
  kopia:
    # Repository will be auto-discovered from production source
    destinationPVC: staging-data
    copyMethod: Direct
    sourceIdentity:
      sourceName: webapp-backup
      sourceNamespace: production  # Cross-namespace restore

This restore operation will:

  1. Discover the repository configuration from production/webapp-backup

  2. Use the same repository that production uses for its backups

  3. Restore the production snapshots to the staging environment

Before and After: Configuration Simplification

Repository auto-discovery significantly reduces the configuration overhead when setting up restore operations.

Before (Manual Configuration):

# You had to manually specify all details
apiVersion: volsync.backube/v1alpha1
kind: ReplicationDestination
metadata:
  name: webapp-restore
spec:
  trigger:
    manual: restore-once
  kopia:
    repository: production-kopia-config  # Must manually specify
    destinationPVC: webapp-data-restored
    copyMethod: Direct
    # Manual identity configuration (old format for compatibility)
    username: webapp-backup-production
    hostname: production  # Now always just namespace

After (Auto-Discovery):

# VolSync handles all the discovery automatically
apiVersion: volsync.backube/v1alpha1
kind: ReplicationDestination
metadata:
  name: webapp-restore
spec:
  trigger:
    manual: restore-once
  kopia:
    # Repository auto-discovered - no manual configuration needed!
    destinationPVC: webapp-data-restored
    copyMethod: Direct
    sourceIdentity:
      sourceName: webapp-backup      # Just specify the source
      sourceNamespace: production    # And its namespace

With auto-discovery, VolSync automatically:

  • Discovers repository: production-kopia-config from the ReplicationSource

  • Generates username: webapp-backup from the source name

  • Generates hostname: production (always just the namespace, PVC name not included)

  • Discovers any sourcePathOverride settings from the source

sourcePathOverride Auto-Discovery

In addition to auto-discovering the source PVC name and repository, VolSync can also automatically discover and use the sourcePathOverride setting from the ReplicationSource. This ensures that restore operations use the correct snapshot path when the source used a path override.

How sourcePathOverride Auto-Discovery Works

When using sourceIdentity, VolSync can automatically discover the sourcePathOverride from the ReplicationSource configuration:

  1. Query the ReplicationSource: VolSync fetches the ReplicationSource specified in sourceIdentity

  2. Extract sourcePathOverride: If the ReplicationSource has spec.kopia.sourcePathOverride configured, VolSync automatically uses this value for the restore operation

  3. Apply to restore: The discovered sourcePathOverride is used to restore from the correct snapshot path

Priority Order for sourcePathOverride

VolSync resolves sourcePathOverride with the following priority:

  1. Explicit sourcePathOverride in sourceIdentity: Highest priority (manual override)

  2. Auto-discovered from ReplicationSource: Automatic discovery when not explicitly provided

  3. No sourcePathOverride: Standard restore without path override

Example: Auto-Discovery in Action

Consider this ReplicationSource with a path override:

# Original ReplicationSource that created the backup
apiVersion: volsync.backube/v1alpha1
kind: ReplicationSource
metadata:
  name: webapp-backup
  namespace: production
spec:
  sourcePVC: webapp-data
  kopia:
    repository: kopia-config
    # This path override was used during backup
    sourcePathOverride: "/var/lib/webapp/data"

When restoring with sourceIdentity, the sourcePathOverride is automatically discovered:

apiVersion: volsync.backube/v1alpha1
kind: ReplicationDestination
metadata:
  name: webapp-restore
  namespace: production
spec:
  trigger:
    manual: restore-once
  kopia:
    repository: kopia-config
    destinationPVC: webapp-data-restored
    copyMethod: Direct
    sourceIdentity:
      sourceName: webapp-backup
      sourceNamespace: production
      # No need to specify sourcePathOverride - it's auto-discovered!

VolSync will automatically:

  1. Fetch the webapp-backup ReplicationSource from the production namespace

  2. Discover that it uses sourcePathOverride: "/var/lib/webapp/data"

  3. Apply this path override during the restore operation

  4. Restore the data from the correct snapshot path

Manual Override of Auto-Discovery

You can override the auto-discovered sourcePathOverride by specifying it explicitly:

apiVersion: volsync.backube/v1alpha1
kind: ReplicationDestination
metadata:
  name: webapp-restore-override
spec:
  kopia:
    repository: kopia-config
    destinationPVC: webapp-data-restored
    copyMethod: Direct
    sourceIdentity:
      sourceName: webapp-backup
      sourceNamespace: production
      # Explicitly override the auto-discovered value
      sourcePathOverride: "/custom/restore/path"

Cross-Environment Restore Example

Auto-discovery makes cross-environment restores seamless:

# Restore production data to staging, preserving the path override
apiVersion: volsync.backube/v1alpha1
kind: ReplicationDestination
metadata:
  name: restore-prod-to-staging
  namespace: staging
spec:
  trigger:
    manual: restore-once
  kopia:
    repository: kopia-config
    destinationPVC: staging-data
    copyMethod: Direct
    sourceIdentity:
      sourceName: webapp-backup
      sourceNamespace: production  # Cross-namespace restore
      # Both PVC name and sourcePathOverride are auto-discovered

This restore operation will:

  1. Discover the source PVC name from production/webapp-backup

  2. Discover the sourcePathOverride from the same ReplicationSource

  3. Generate the correct identity: webapp-backup-production@production

  4. Restore using the correct snapshot path override

Benefits of sourcePathOverride Auto-Discovery

  1. Simplified Configuration: No need to manually specify path overrides

  2. Error Reduction: Eliminates mismatches between backup and restore path settings

  3. Cross-Environment Compatibility: Automatic path override preservation across environments

  4. Maintenance Reduction: Changes to source path overrides don’t require destination updates

Fallback to Manual Username/Hostname

If you need more control, you can still manually specify username and hostname fields. When these are explicitly set, they take precedence over sourceIdentity:

apiVersion: volsync.backube/v1alpha1
kind: ReplicationDestination
metadata:
  name: restore-manual-identity
spec:
  kopia:
    repository: kopia-config
    # Manual identity configuration (overrides sourceIdentity if both are present)
    username: "custom-user"
    hostname: "custom-host"
    # sourceIdentity would be ignored if present

Priority order for identity resolution:

  1. Explicit username/hostname: If specified, these are used exactly as provided

  2. sourceIdentity with explicit sourcePVCName: Uses provided PVC name for hostname generation

  3. sourceIdentity with auto-discovery: Fetches PVC name from ReplicationSource

  4. Default generation: If none specified, generates based on ReplicationDestination name and namespace

Enhanced Error Reporting and Discovery

VolSync provides comprehensive error reporting and snapshot discovery features to help you quickly identify and resolve restore issues. When a restore operation encounters problems, the system automatically provides detailed diagnostic information.

Status Fields for Debugging

VolSync exposes several status fields that provide critical information about the restore operation and available snapshots:

RequestedIdentity

Shows the exact username@hostname that VolSync is attempting to restore from. This helps verify that identity resolution is working as expected:

kubectl get replicationdestination restore-webapp -o jsonpath='{.status.kopia.requestedIdentity}'
# Output: webapp-backup-production@production

SnapshotsFound

Indicates how many snapshots were found for the requested identity. A value of 0 indicates that no matching snapshots were found:

kubectl get replicationdestination restore-webapp -o jsonpath='{.status.kopia.snapshotsFound}'
# Output: 15

AvailableIdentities

Lists all identities available in the repository with detailed information about each. This is particularly helpful when snapshots aren’t found for the requested identity:

# View available identities in formatted output
kubectl get replicationdestination restore-webapp -o json | jq '.status.kopia.availableIdentities'

# Alternative: using grep
kubectl get replicationdestination restore-webapp -o yaml | grep -A 50 availableIdentities

Error Reporting Examples

When snapshots are not found, the enhanced error reporting provides clear feedback:

Example: No snapshots found

status:
  conditions:
  - type: Synchronizing
    status: "False"
    reason: SnapshotsNotFound
    message: "No snapshots found for identity 'webapp-backup-production@production'.
             Available identities in repository:
             database-backup-production@production (30 snapshots, latest: 2024-01-20T11:00:00Z),
             app-backup-staging@staging (7 snapshots, latest: 2024-01-19T22:00:00Z)"
  kopia:
    requestedIdentity: "webapp-backup-production@production"
    snapshotsFound: 0
    availableIdentities:
    - identity: "database-backup-production@production"
      snapshotCount: 30
      latestSnapshot: "2024-01-20T11:00:00Z"
    - identity: "app-backup-staging@staging"
      snapshotCount: 7
      latestSnapshot: "2024-01-19T22:00:00Z"

Example: Successful discovery

status:
  conditions:
  - type: Synchronizing
    status: "True"
    reason: SynchronizingData
    message: "Restoring from snapshot 2024-01-20T10:30:00Z"
  kopia:
    requestedIdentity: "webapp-backup-production@production"
    snapshotsFound: 15
    availableIdentities:
    - identity: "webapp-backup-production@production"
      snapshotCount: 15
      latestSnapshot: "2024-01-20T10:30:00Z"
    - identity: "database-backup-production@production"
      snapshotCount: 30
      latestSnapshot: "2024-01-20T11:00:00Z"
    - identity: "app-backup@staging-app-data"
      snapshotCount: 7
      latestSnapshot: "2024-01-19T22:00:00Z"

Using Discovery Information for Debugging

The discovery features help you:

  1. Identify available backup sources: See all identities in the repository

  2. Verify snapshot availability: Check snapshot counts and latest timestamps

  3. Debug configuration issues: Compare requested vs. available identities

  4. Choose the correct source: Select from available identities when multiple exist

Error Reporting and Troubleshooting

VolSync’s enhanced error reporting provides detailed information when restore operations encounter issues. This section covers common error scenarios and their solutions.

Common Error Scenarios

Scenario 1: No snapshots found

Error Message: “No snapshots found for identity ‘<username>@<hostname>’”

Symptoms: - snapshotsFound shows 0 - Restore operation fails - Error message lists available identities

Resolution Steps:

  1. Review available identities

    The error message and availableIdentities field show what’s in the repository:

    kubectl get replicationdestination restore-webapp -o json | jq '.status.kopia.availableIdentities'

  2. Verify source configuration

    Check the ReplicationSource that created the backups:

    # Find the source
kubectl get replicationsource -A | grep webapp-backup

# Check its configuration
kubectl get replicationsource webapp-backup -n production -o yaml | grep -A 10 "kopia:"

  3. Common fixes:

    • Incorrect sourceIdentity: Verify sourceName and sourceNamespace match exactly

    • Custom identity: If source uses custom username/hostname, use those instead

    • No backups created: Check if the ReplicationSource has run successfully

Scenario 2: Identity mismatch

Symptoms: - Data restored from wrong source - requestedIdentity doesn’t match expectations

Debugging Process:

  1. Check the requested identity:

    kubectl get replicationdestination restore-webapp -o jsonpath='{.status.kopia.requestedIdentity}'

  2. Compare with available identities to find the correct one:

    kubectl get replicationdestination restore-webapp -o yaml | grep -A 50 availableIdentities

  3. Update configuration to use the correct identity

Scenario 3: Insufficient snapshots for previous parameter

Error Message: “Requested snapshot index X but only Y snapshots found”

Symptoms: - Using previous parameter - snapshotsFound is less than or equal to previous value

Solution:

# Check available snapshot count
status:
  kopia:
    snapshotsFound: 2  # Only 2 snapshots available

# Adjust previous parameter
spec:
  kopia:
    previous: 1  # Maximum value is snapshotsFound - 1

Step-by-Step Debugging Process

When encountering restore issues, follow this systematic approach:

  1. Check the error message

    kubectl describe replicationdestination <name> | grep -A 10 "Conditions:"

  2. Review discovery information

    # Check requested identity
kubectl get replicationdestination <name> -o jsonpath='{.status.kopia.requestedIdentity}'

# Check snapshot count
kubectl get replicationdestination <name> -o jsonpath='{.status.kopia.snapshotsFound}'

# List available identities
kubectl get replicationdestination <name> -o json | jq '.status.kopia.availableIdentities'

  3. Verify source configuration

    # Find the ReplicationSource
kubectl get replicationsource -A

# Check its configuration
kubectl get replicationsource <name> -n <namespace> -o yaml

  4. Check mover pod logs

    # Find the mover pod
kubectl get pods -l "volsync.backube/mover-job" -n <namespace>

# View logs
kubectl logs <pod-name> -n <namespace>

  5. Adjust configuration based on findings

    Based on the discovery information, update your ReplicationDestination:

    • Use correct sourceIdentity values

    • Or switch to explicit username/hostname

    • Adjust previous parameter if needed

Best Practices for Error Prevention

  1. Use discovery features proactively

    Before configuring a restore, create a temporary ReplicationDestination to discover available identities:

    apiVersion: volsync.backube/v1alpha1
kind: ReplicationDestination
metadata:
  name: identity-discovery
spec:
  trigger:
    manual: discover
  kopia:
    repository: kopia-config
    destinationPVC: temp-pvc
    copyMethod: Direct

    Then check the status for available identities before configuring your actual restore.

  2. Document identity configuration

    Maintain documentation of:

    • Custom username/hostname configurations in ReplicationSources

    • Identity mappings between sources and their generated identities

    • Repository organization for multi-tenant setups

  3. Monitor backup success

    Regularly verify that backups are being created successfully:

    # Check last successful backup
kubectl get replicationsource <name> -o jsonpath='{.status.lastSyncTime}'

  4. Test restore procedures

    Regularly test restore operations in non-production environments:

    • Verify identity configuration works correctly

    • Test point-in-time recovery with previous parameter

    • Validate restored data integrity

  5. Use consistent naming conventions

    Maintain consistent ReplicationSource names across environments to simplify:

    • Disaster recovery procedures

    • Cross-environment restores

    • Identity management

  6. Leverage error messages

    The enhanced error reporting provides actionable information:

    • Lists available identities when snapshots aren’t found

    • Shows exact identity being requested

    • Provides snapshot counts and timestamps

    Use this information to quickly identify and fix configuration issues.

Basic Restore Example

For example, create a PVC to hold the restored data:

---
kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: datavol
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 3Gi

Restore the data into datavol:

---
apiVersion: volsync.backube/v1alpha1
kind: ReplicationDestination
metadata:
  name: datavol-dest
spec:
  trigger:
    manual: restore-once
  kopia:
    repository: kopia-config
    # Use an existing PVC, don't provision a new one
    destinationPVC: datavol
    copyMethod: Direct

In the above example, the data will be written directly into the new PVC since it is specified via destinationPVC, and no snapshot will be created since a copyMethod of Direct is used.

The restore operation only needs to be performed once, so instead of using a cronspec-based schedule, a manual trigger is used. After the restore completes, the ReplicationDestination object can be deleted.

Practical Auto-Discovery Example

This example demonstrates how auto-discovery simplifies restore configuration:

Step 1: Create a ReplicationSource for backup

apiVersion: volsync.backube/v1alpha1
kind: ReplicationSource
metadata:
  name: webapp-backup
  namespace: production
spec:
  sourcePVC: webapp-persistent-data
  trigger:
    schedule: "0 */6 * * *"
  kopia:
    repository: kopia-config

Step 2: Restore using sourceIdentity with auto-discovery

apiVersion: volsync.backube/v1alpha1
kind: ReplicationDestination
metadata:
  name: webapp-restore
  namespace: production
spec:
  trigger:
    manual: restore-once
  kopia:
    repository: kopia-config
    destinationPVC: webapp-data-restored
    copyMethod: Direct
    sourceIdentity:
      sourceName: webapp-backup
      sourceNamespace: production
      # Note: sourcePVCName not specified - will be auto-discovered

Step 3: Verify the auto-discovery worked

# Check the requested identity
kubectl get replicationdestination webapp-restore -o jsonpath='{.status.kopia.requestedIdentity}'
# Output: webapp-backup@production-webapp-persistent-data
#         The PVC name "webapp-persistent-data" was auto-discovered

Benefits of this approach:

  1. No need to remember or look up the PVC name

  2. Configuration remains valid even if the source PVC name changes

  3. Reduces configuration errors from typos

  4. Simplifies restore documentation and procedures

Practical Debugging Example

This example demonstrates how to use the enhanced error reporting to debug a failed restore:

Scenario: Attempting to restore data but getting “No snapshots found” error.

Step 1: Check the error details

kubectl describe replicationdestination webapp-restore

Output shows:

Status:
  Conditions:
    Type:     Synchronizing
    Status:   False
    Reason:   SnapshotsNotFound
    Message:  No snapshots found for identity 'webapp-backup@production-webapp-data'.
             Available identities in repository:
             webapp-backup@staging-webapp-data (15 snapshots),
             database-backup@production-postgres-data (30 snapshots)

Step 2: Review available identities

kubectl get replicationdestination webapp-restore -o json | jq '.status.kopia.availableIdentities'

Output:

[
  {
    "identity": "webapp-backup@staging-webapp-data",
    "snapshotCount": 15,
    "latestSnapshot": "2024-01-20T10:30:00Z"
  },
  {
    "identity": "database-backup@production-postgres-data",
    "snapshotCount": 30,
    "latestSnapshot": "2024-01-20T11:00:00Z"
  }
]

Step 3: Identify the issue

The error shows that: - We’re looking for webapp-backup@production-webapp-data - But the repository has webapp-backup@staging-webapp-data - The namespace is different (staging vs production)

Step 4: Fix the configuration

apiVersion: volsync.backube/v1alpha1
kind: ReplicationDestination
metadata:
  name: webapp-restore
  namespace: production
spec:
  trigger:
    manual: restore-once
  kopia:
    repository: kopia-config
    destinationPVC: webapp-data-restored
    copyMethod: Direct
    # Fix: Use the correct namespace
    sourceIdentity:
      sourceName: webapp-backup
      sourceNamespace: staging  # Changed from production to staging

Step 5: Verify the fix

After applying the corrected configuration:

kubectl get replicationdestination webapp-restore -o jsonpath='{.status.kopia.snapshotsFound}'
# Output: 15

kubectl get replicationdestination webapp-restore -o jsonpath='{.status.kopia.requestedIdentity}'
# Output: webapp-backup@staging-webapp-data

The restore now proceeds successfully with 15 snapshots available.

Point-in-Time and Previous Snapshot Restores

The example, shown above, will restore the data from the most recent backup. To restore an older version of the data, the previous, shallow and restoreAsOf fields can be used. See below for more information on their meaning.

Example: Restoring from a previous snapshot

To restore from the second-most-recent snapshot (skipping the latest backup):

---
apiVersion: volsync.backube/v1alpha1
kind: ReplicationDestination
metadata:
  name: datavol-dest-previous
spec:
  trigger:
    manual: restore-previous
  kopia:
    repository: kopia-config
    destinationPVC: datavol
    copyMethod: Direct
    # Skip 1 snapshot to get the previous one
    previous: 1

Example: Combining previous with restoreAsOf

To restore from 2 snapshots before a specific point in time:

---
apiVersion: volsync.backube/v1alpha1
kind: ReplicationDestination
metadata:
  name: datavol-dest-timepoint
spec:
  trigger:
    manual: restore-timepoint
  kopia:
    repository: kopia-config
    destinationPVC: datavol
    copyMethod: Direct
    # Find snapshots before this time, then skip 2 to get the 3rd oldest
    restoreAsOf: "2024-01-15T14:30:00Z"
    previous: 2

Restore options

There are a number of additional configuration options not shown in the above example.

accessModes

When VolSync creates the destination volume, this specifies the accessModes for the PVC. The value should be ReadWriteOnce or ReadWriteMany.

capacity

When VolSync creates the destination volume, this value is used to determine its size. This need not match the size of the source volume, but it must be large enough to hold the incoming data.

copyMethod

This specifies how the data should be preserved at the end of each synchronization iteration. Valid values are:

  • Direct - Do not create a point-in-time copy of the data.

  • Snapshot - Create a VolumeSnapshot at the end of each iteration

destinationPVC

Instead of having VolSync automatically provision the destination volume (using capacity, accessModes, etc.), the name of a pre-existing PVC may be specified here.

cleanupTempPVC

This optional boolean specifies whether a destination PVC dynamically provisioned by VolSync should be deleted at the end of a successful sync iteration. If destinationPVC is specified, then this setting will have no effect, VolSync will only cleanup PVCs that it deployed. If this is set to true, every sync this ReplicationDestination makes will re-provision a new temp destination PVC and all data will need to be sent again during the sync. Dynamically provisioned destination PVCs will always be deleted if the owning ReplicationDestination is removed, even if this setting is false. The default is false.

storageClassName

When VolSync creates the destination volume, this specifies the name of the StorageClass to use. If omitted, the system default StorageClass will be used.

volumeSnapshotClassName

When using a copyMethod of Snapshot, this value specifies the name of the VolumeSnapshotClass to use when creating a snapshot. If omitted, the system default VolumeSnapshotClass will be used.

cacheCapacity

This determines the size of the Kopia metadata cache volume. This volume contains cached metadata from the backup repository. It must be large enough to hold the repository metadata. The default is 1 Gi.

Cache Volume Behavior:

  • When specified: A PersistentVolumeClaim is created with the specified capacity

  • When not specified: An EmptyDir volume is used as fallback, providing temporary cache storage

Important

With EmptyDir fallback, cache contents are lost when the pod restarts, which may impact performance for subsequent restore operations as the cache needs to be rebuilt.

cacheStorageClassName

This is the name of the StorageClass that should be used when provisioning the cache volume. It defaults to .spec.storageClassName, then to the name of the StorageClass used by the source PVC.

Note

This setting only applies when cacheCapacity is specified. EmptyDir volumes do not use StorageClasses.

cacheAccessModes

This is the access mode(s) that should be used to provision the cache volume. It defaults to .spec.accessModes, then to the access modes used by the source PVC.

Note

This setting only applies when cacheCapacity is specified. EmptyDir volumes do not use access modes.

cleanupCachePVC

This optional boolean determines if the cache PVC should be cleaned up at the end of the restore. Cache PVCs will always be deleted if the owning ReplicationDestination is removed, even if this setting is false. Defaults to false.

customCA

This option allows a custom certificate authority to be used when making TLS (https) connections to the remote repository.

key

This is the name of the field within the Secret that holds the CA certificate

secretName

This is the name of a Secret containing the CA certificate

configMapName

This is the name of a ConfigMap containing the CA certificate

enableFileDeletion

A boolean field that controls whether the destination directory should be cleaned before restore operations. When set to true, all files and directories in the destination (except lost+found) are removed before the restore begins, ensuring the restored data exactly matches the snapshot content. When false (the default), Kopia’s standard behavior applies: existing files are overwritten, new files are created, but extra files not in the snapshot remain untouched.

Use Cases:

  • Disaster recovery: Ensuring exact state restoration without leftover files

  • Test environment refresh: Cleaning test data before restoring production snapshots

  • Clean slate restores: Removing orphaned or accumulated files from previous restores

  • Compliance requirements: Ensuring no unauthorized data remains after restore

Important Considerations:

  • This operation is destructive - all existing data in the destination will be deleted

  • The lost+found directory (if present) is preserved for filesystem integrity

  • Ensure you have backups if the destination contains important data

  • The cleaning happens before each restore operation when enabled

Example Usage:

apiVersion: volsync.backube/v1alpha1
kind: ReplicationDestination
metadata:
  name: clean-restore
spec:
  kopia:
    enableFileDeletion: true  # Clean destination before restore
    destinationPVC: restored-data
    repository: kopia-config
    sourceIdentity:
      sourceName: webapp-backup
      sourceNamespace: production

Default Behavior (when false or not specified):

Without this flag, Kopia follows its standard restore behavior:

  • Existing files with the same name are overwritten

  • New files from the snapshot are created

  • Extra files not in the snapshot remain untouched

  • This can lead to a mix of old and new data

When to Use:

  • Enable when you need the destination to exactly match the snapshot

  • Enable for disaster recovery scenarios

  • Enable when refreshing test/staging environments from production

  • Disable when you want to preserve existing files not in the backup

  • Disable when doing partial restores or merging data

repository

This is the name of the Secret (in the same Namespace) that holds the connection information for the backup repository. When empty and using sourceIdentity, the repository will be automatically discovered from the specified ReplicationSource, eliminating the need for manual configuration.

sourceIdentity

This optional field provides a simplified way to specify which ReplicationSource’s snapshots to restore. It automatically generates the correct username and hostname based on the source configuration, with auto-discovery of the source PVC name, sourcePathOverride, and repository configuration.

sourceName

The name of the ReplicationSource that created the snapshots to restore (required)

sourceNamespace

The namespace where the ReplicationSource exists (required)

sourcePVCName

The name of the source PVC (optional). If not provided, VolSync will automatically fetch the ReplicationSource configuration and discover the PVC name from the spec.sourcePVC field. This auto-discovery simplifies configuration and reduces errors.

sourcePathOverride

The path override to use for snapshot restoration (optional). If not provided, VolSync will automatically fetch the ReplicationSource configuration and discover the sourcePathOverride from the spec.kopia.sourcePathOverride field. When specified, this value overrides any auto-discovered path override. This ensures that restore operations use the correct snapshot path when the source used a path override.

When sourceIdentity is specified, it takes precedence over default identity generation but is overridden by explicit username and hostname fields.

previous

Non-negative integer that specifies how many snapshots to skip before selecting one to restore from. When set to 0 (the default), the latest snapshot is used. When set to 1, the second newest snapshot is used (skipping 1 snapshot), and so on. This parameter can be combined with restoreAsOf to skip snapshots from a specific point in time.

Examples:

  • previous: 0 or omitted: Use the latest snapshot

  • previous: 1: Skip the latest snapshot, use the previous one

  • previous: 2: Skip 2 snapshots, use the 3rd newest

When used with restoreAsOf, the behavior is the same, but counting starts from the first snapshot taken before the restoreAsOf timestamp.

restoreAsOf

An RFC-3339 timestamp which specifies an upper-limit on the snapshots that we should be looking through when preparing to restore. Snapshots made after this timestamp will not be considered. Note: though this is an RFC-3339 timestamp, Kubernetes will only accept ones with the day and hour fields separated by a T. E.g, 2022-08-10T20:01:03-04:00 will work but 2022-08-10 20:01:03-04:00 will fail.

shallow

Non-negative integer which specifies how many recent snapshots to consider for restore. When restoreAsOf is provided, the behavior is the same, however the starting snapshot considered will be the first one taken before restoreAsOf. This is similar to Restic’s previous option but uses Kopia’s shallow clone concept.

policyConfig

This optional field allows applying external policy files during restore operations. While restore operations typically don’t need policy configuration (policies mainly affect backup creation), this can be useful for:

  • Setting download speed limits during restore

  • Configuring restore-specific actions

  • Applying custom repository settings for restore operations

The same configuration options as ReplicationSource are available:

configMapName

Name of a ConfigMap containing policy files (mutually exclusive with secretName)

secretName

Name of a Secret containing policy files (mutually exclusive with configMapName)

globalPolicyFilename

Filename for global policy (defaults to “global-policy.json”)

repositoryConfigFilename

Filename for repository config (defaults to “repository.config”)

repositoryConfig

Inline JSON configuration for advanced repository settings

Using External Policies with Restore

While restore operations typically don’t require policy configuration (since policies primarily affect how backups are created), there are scenarios where applying policies during restore can be beneficial.

Example: Restore with Download Speed Limits

Limit download speed to prevent network saturation during restore:

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: restore-policies
data:
  repository.config: |
    {
      "downloadSpeed": 52428800,
      "downloadParallelism": 2,
      "enableActions": true
    }
---
apiVersion: volsync.backube/v1alpha1
kind: ReplicationDestination
metadata:
  name: throttled-restore
spec:
  trigger:
    manual: restore-now
  kopia:
    repository: kopia-config
    destinationPVC: restored-data
    copyMethod: Direct

    # Apply policies during restore
    policyConfig:
      configMapName: restore-policies

    sourceIdentity:
      sourceName: production-backup
      sourceNamespace: production

Example: Restore with Pre/Post Actions

Execute commands before and after restore operations:

---
apiVersion: v1
kind: Secret
metadata:
  name: restore-actions
type: Opaque
stringData:
  repository.config: |
    {
      "enableActions": true,
      "actionCommandTimeout": "10m"
    }
---
apiVersion: volsync.backube/v1alpha1
kind: ReplicationDestination
metadata:
  name: restore-with-actions
spec:
  trigger:
    manual: restore-once
  kopia:
    repository: kopia-config
    destinationPVC: database-restored

    policyConfig:
      secretName: restore-actions

    # Actions to prepare and verify restore
    actions:
      beforeSnapshot: |
        echo "Starting restore at $(date)" >> /tmp/restore.log
        # Stop services that might access the volume
        pkill -f myapp || true
      afterSnapshot: |
        echo "Restore completed at $(date)" >> /tmp/restore.log
        # Verify restored data
        test -f /data/critical-file.db || exit 1
        # Restart services
        /usr/local/bin/start-app.sh

    sourceIdentity:
      sourceName: database-backup
      sourceNamespace: production

Example: Advanced Restore with Structured Config

Use inline JSON configuration for complex restore scenarios:

---
apiVersion: volsync.backube/v1alpha1
kind: ReplicationDestination
metadata:
  name: advanced-restore
spec:
  trigger:
    manual: restore-now
  kopia:
    destinationPVC: restored-app
    copyMethod: Direct

    # Inline repository configuration for restore
    policyConfig:
      repositoryConfig: |
        {
          "caching": {
            "cacheDirectory": "/tmp/restore-cache",
            "maxCacheSize": 5368709120,
            "metadataCacheSize": 1073741824
          },
          "performance": {
            "downloadParallelism": 8,
            "downloadSpeed": 209715200,
            "bufferSize": 33554432
          },
          "verification": {
            "verifyData": true,
            "verifyChecksums": true
          }
        }

    # Restore from specific point in time
    restoreAsOf: "2024-01-15T10:30:00Z"

    sourceIdentity:
      sourceName: app-backup
      sourceNamespace: production

Best Practices for Restore Policies

  1. Performance Tuning: - Use download speed limits to prevent network congestion - Adjust parallelism based on available resources - Configure caching for large restores

  2. Action Scripts: - Stop services before restore to prevent data corruption - Verify critical files after restore - Send notifications on completion

  3. Security: - Use Secrets for sensitive configuration - Validate JSON syntax before applying - Keep policy files under 1MB

  4. Testing: - Test restore policies in non-production first - Monitor restore performance with different settings - Document optimal configurations for different scenarios

Troubleshooting Restore Policies

Policy Not Applied During Restore

Check if the policy ConfigMap/Secret exists:

kubectl get configmap restore-policies -o yaml
kubectl get secret restore-actions -o yaml

Download Speed Not Limited

Verify the repository.config is being applied:

# Check mover pod logs
kubectl logs <restore-pod> | grep -i "download.*speed"

Actions Not Executing

Ensure enableActions is set to true:

# Check the repository config
kubectl get configmap restore-policies -o jsonpath='{.data.repository\.config}' | jq .

JSON Validation Errors

Validate JSON syntax:

# Extract and validate JSON
kubectl get configmap restore-policies -o jsonpath='{.data.repository\.config}' | jq .

Complete Restore Example with All Features

Here’s a comprehensive example combining all restore features with external policies:

# Comprehensive restore policies
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: full-restore-policies
data:
  repository.config: |
    {
      "enableActions": true,
      "actionCommandTimeout": "15m",
      "downloadSpeed": 104857600,
      "downloadParallelism": 4,
      "verifyData": true
    }

# Complete restore configuration
---
apiVersion: volsync.backube/v1alpha1
kind: ReplicationDestination
metadata:
  name: full-featured-restore
spec:
  trigger:
    manual: restore-now

  kopia:
    # Repository auto-discovered from sourceIdentity
    destinationPVC: production-data-restored
    copyMethod: Snapshot

    # Apply external policies
    policyConfig:
      configMapName: full-restore-policies

    # Source identification with auto-discovery
    sourceIdentity:
      sourceName: production-backup
      sourceNamespace: production
      # sourcePVCName auto-discovered
      # sourcePathOverride auto-discovered
      # repository auto-discovered

    # Point-in-time restore
    restoreAsOf: "2024-01-15T00:00:00Z"
    previous: 1  # Use second-newest from that time

    # Clean destination before restore
    enableFileDeletion: true

    # Custom CA if needed
    customCA:
      configMapName: custom-ca-bundle
      key: ca-bundle.pem

    # Cache configuration
    cacheCapacity: 5Gi
    cacheStorageClassName: fast-ssd

    # Performance settings
    parallelism: 4

    # Pre/post restore actions
    actions:
      beforeSnapshot: |
        echo "=== Pre-restore checks ==="
        df -h /data
        # Stop application
        systemctl stop myapp || true
        # Backup current state
        tar czf /tmp/pre-restore-backup.tar.gz /data 2>/dev/null || true
      afterSnapshot: |
        echo "=== Post-restore validation ==="
        # Verify critical files
        test -f /data/app.conf || exit 1
        test -d /data/database || exit 1
        # Set permissions
        chown -R app:app /data
        # Start application
        systemctl start myapp
        echo "Restore completed successfully"

    # Security context
    moverSecurityContext:
      runAsUser: 1000
      runAsGroup: 1000
      fsGroup: 1000

status:
  # Status will show:
  kopia:
    requestedIdentity: "production-backup-production@production"
    snapshotsFound: 42

Additional Command-Line Arguments for Restore

Similar to backup operations, you can pass additional command-line arguments to Kopia during restore operations using the additionalArgs field. This provides flexibility for advanced restore scenarios.

Warning

Use additionalArgs with caution during restores. Invalid arguments can cause restore failures or data corruption. Always test in a non-production environment first.

Basic Usage

Add custom Kopia arguments to your ReplicationDestination:

apiVersion: volsync.backube/v1alpha1
kind: ReplicationDestination
metadata:
  name: restore-with-args
spec:
  kopia:
    repository: kopia-config
    destinationPVC: restored-data
    additionalArgs:
      - "--parallel=8"            # Parallel downloads
      - "--override-uid=1000"     # Set file owner UID
      - "--override-gid=1000"     # Set file owner GID
      - "--progress-interval=100" # Progress reporting

Common Restore Use Cases

Performance Optimization:

additionalArgs:
  - "--parallel=16"           # More parallel downloads
  - "--skip-verification"     # Skip file verification (faster but less safe)

Ownership and Permissions:

additionalArgs:
  - "--override-uid=1000"     # Set all files to UID 1000
  - "--override-gid=1000"     # Set all files to GID 1000
  - "--ignore-permission-errors" # Continue on permission errors

Progress Monitoring:

additionalArgs:
  - "--progress-interval=50"  # Report every 50 files
  - "--verbose"               # More detailed output

Example: Complete Restore with Additional Args

apiVersion: volsync.backube/v1alpha1
kind: ReplicationDestination
metadata:
  name: optimized-restore
spec:
  trigger:
    manual: "restore-now"
  kopia:
    repository: kopia-config
    destinationPVC: app-data-restored

    # Standard configuration
    restoreAsOf: "2024-01-15T12:00:00Z"
    enableFileDeletion: true

    # Performance and ownership tuning
    additionalArgs:
      - "--parallel=12"
      - "--override-uid=1000"
      - "--override-gid=1000"
      - "--progress-interval=100"
      - "--ignore-permission-errors"

Security Considerations

The same security restrictions apply as for backup operations. Forbidden flags include:

  • Credential and authentication flags

  • Repository configuration overrides

  • Cache and log directory overrides

  • Username/hostname overrides (use identity fields instead)

For comprehensive documentation on additional arguments, see Kopia Additional Arguments.

latestSnapshotTime: “2024-01-15T12:00:00Z”