Kopia Additional Arguments

The additionalArgs field allows passing custom command-line arguments to Kopia for advanced use cases not directly exposed by VolSync’s API.

When to Use

Use additionalArgs for:

Excluding files/directories from backups
Controlling filesystem boundaries (--one-file-system)
Tuning performance (--parallel, --upload-speed)
Ignoring cache directories (--ignore-cache-dirs)
Handling permission errors during restore

Important

Always prefer VolSync’s native configuration options when available. Only use additionalArgs for features not directly exposed.

Configuration

Add arguments to your ReplicationSource or ReplicationDestination:

apiVersion: volsync.backube/v1alpha1
kind: ReplicationSource
metadata:
  name: backup-source
spec:
  sourcePVC: my-data
  trigger:
    schedule: "*/30 * * * *"
  kopia:
    repository: kopia-secret
    additionalArgs:
      - "--one-file-system"
      - "--ignore-cache-dirs"
      - "--parallel=8"

apiVersion: volsync.backube/v1alpha1
kind: ReplicationDestination
metadata:
  name: restore-dest
spec:
  trigger:
    manual: restore-now
  kopia:
    repository: kopia-secret
    destinationPVC: restored-data
    additionalArgs:
      - "--ignore-permission-errors"
      - "--parallel=4"

Important Notes

All arguments are passed directly to Kopia without validation
Users are responsible for providing valid Kopia flags
Invalid arguments will cause backup/restore failures
Some flags may conflict with VolSync’s configuration - use with caution

Common Use Cases

Exclude Files

additionalArgs:
  - "--exclude=*.tmp"
  - "--exclude=cache/"
  - "--exclude-caches"

Performance Tuning

additionalArgs:
  - "--parallel=16"              # Increase parallel operations
  - "--upload-speed=100"         # Limit upload to 100 MB/s
  - "--compression=s2-parallel-8" # Use parallel compression

Filesystem Boundaries

additionalArgs:
  - "--one-file-system"          # Don't cross filesystem boundaries
  - "--ignore-inode-changes"     # Ignore inode number changes

Restore Options

additionalArgs:
  - "--ignore-permission-errors"  # Continue on permission errors
  - "--no-overwrite-files"       # Don't overwrite existing files
  - "--no-overwrite-directories" # Don't overwrite existing directories

Limitations

Maximum 20 arguments per ReplicationSource/Destination
Arguments are passed as-is to Kopia without validation
Invalid arguments will cause backup/restore failures
Check Kopia logs in the job pod for debugging

Troubleshooting

To verify arguments are being applied:

# Check the job pod logs
kubectl logs -l volsync.backube/replication-name=backup-source

# Look for lines showing the Kopia command being executed
# Additional arguments should appear in the command

If backups/restores fail after adding arguments:

Remove the additionalArgs to verify the issue
Check Kopia documentation for correct argument syntax
Test arguments locally with Kopia CLI if possible
Add arguments one at a time to identify the problematic one