Backup

Description

The px pxb backup command provides comprehensive backup management capabilities for Kubernetes resources and persistent volumes. It supports creating, retrieving, updating, deleting, and retrying backups across different backup object types including namespace backups and virtual machine backups.

The backup command integrates with Portworx Backup to create point-in-time snapshots of applications, including their persistent data, configuration, and metadata. Backups can be stored in various cloud storage locations and support advanced features like pre/post execution rules, namespace and resource filters, VM-aware backups, direct KDMP data movement, and Normal or Generic modes for storage-class snapshotting. When both include and exclude filters are provided, explicit include lists take precedence over broad type-based filters; advanced label selectors allow fine-grained targeting.

Usage

Create Backup

px pxb create backup --name <backup-name> --cluster <cluster-name> \
  --backup-location-name <location-name> [flags]

Get Backup (Inspect)

px pxb get backup --name <backup-name> [--uid <uid>] [flags]

Get Backup (List All)

px pxb get backup [flags]

Update Backup

px pxb update backup --name <backup-name> [--uid <uid>] [flags]

Delete Backup

px pxb delete backup --name <backup-name> [flags]

Retry Backup

px pxb retry backup --name <backup-name> [flags]

px pxb share backup --name <backup-name> [--uid <uid>] [flags]

Unshare Backup

px pxb unshare backup --name <backup-name> [--uid <uid>] [flags]

px pxb get backupshare --name <backup-name> [--uid <uid>] [flags]

Examples

Basic Backup Operations

Simple Namespace Backup

# Create a basic backup of specific namespaces
px pxb create backup \
  --name daily-app-backup \
  --cluster production-cluster \
  --namespaces "frontend,backend,database" \
  --backup-location-name s3-primary

Full Cluster Backup

# Backup all namespaces in a cluster
px pxb create backup \
  --name full-cluster-backup \
  --cluster production-cluster \
  --backup-location-name s3-primary \
  --parallel-backup

Virtual Machine Backup

# Create a VM backup with specific resources
px pxb create backup \
  --name vm-backup \
  --cluster vm-cluster \
  --backup-object-type VirtualMachine \
  --namespaces "vms" \
  --include-resources "vm1:default:kubevirt.io:v1:VirtualMachine" \
  --backup-location-name vm-storage

Advanced Backup Scenarios

Backup with Resource Filtering

# Backup with specific resource types and label selectors
px pxb create backup \
  --name filtered-backup \
  --cluster production-cluster \
  --namespaces "app" \
  --resource-types "deployments,services,configmaps" \
  --exclude-resource-types "events,replicasets" \
  --label-selectors "tier=frontend,env=prod" \
  --backup-location-name s3-backup

Backup with Execution Rules

# Create backup with pre and post execution rules
px pxb create backup \
  --name rule-backup \
  --cluster production-cluster \
  --namespaces "database" \
  --pre-exec-rule-name db-quiesce \
  --post-exec-rule-name db-resume \
  --backup-location-name s3-backup

Generic Backup with CSI Snapshots

# Create a generic backup with volume snapshot class mapping
px pxb create backup \
  --name csi-backup \
  --cluster production-cluster \
  --namespaces "default" \
  --backup-type Generic \
  --volume-snapshot-class-mapping "kubernetes.io/aws-ebs=ebs-snapshot-class" \
  --backup-location-name s3-backup

Backup from Configuration File

# Create backup using a JSON/YAML configuration file
px pxb create backup --file /path/to/backup-config.json

# Example backup-config.json:
{
  "name": "complex-backup",
  "cluster_ref": { "name": "production-cluster" },
  "backup_location_ref": { "name": "s3-primary" },
  "namespaces": ["app1", "app2"],
  "label_selectors": { "app": "web", "tier": "production" },
  "backup_object_type": { "type": "All" },
  "backup_type": "Normal",
  "direct_kdmp": true
}

Backup Retrieval Operations

List All Backups

# Table output
px pxb get backup

# JSON output
px pxb get backup --output json

# Filtering
px pxb get backup \
  --cluster-name-filter production \
  --status "Success,InProgress" \
  --max-objects 50

Inspect Specific Backup

# Get detailed information about a specific backup
px pxb get backup --name daily-app-backup

# Include detailed resource information
px pxb get backup --name daily-app-backup --include-detailed-resources

# Get backup by UID (name is required; UID helps disambiguate)
px pxb get backup --name daily-app-backup --uid backup-12345-abcde

Filter Backups by Time Range

px pxb get backup \
  --start-time "2024-01-01T00:00:00Z" \
  --end-time "2024-01-31T23:59:59Z" \
  --sort-by "creation_time" \
  --sort-order "desc"

Filter Backups by Schedule References

# List backups created by a specific backup schedule
px pxb get backup --backup-schedule-refs "daily-backup:schedule-123"

# List backups from multiple backup schedules (use multiple flags)
px pxb get backup \
  --backup-schedule-refs "daily-backup:schedule-123" \
  --backup-schedule-refs "weekly-backup:schedule-456" \
  --backup-schedule-refs "monthly-backup:schedule-789"

# List backups from schedule by name only (when UID is not known)
px pxb get backup --backup-schedule-refs "daily-backup"

# Combine schedule filtering with other filters
px pxb get backup \
  --backup-schedule-refs "daily-backup:schedule-123" \
  --status "Success,PartialSuccess" \
  --start-time "2024-01-01T00:00:00Z"

# Filter by schedule policy references
px pxb get backup --schedule-policy-refs "daily-policy:policy-123"

Important: For multiple schedule references, use multiple --backup-schedule-refs flags. Do NOT use comma-separated values in a single flag (e.g., "schedule1,schedule2") as this will be parsed incorrectly.

Backup Management Operations

Update Backup

# Update backup metadata
px pxb update backup --name daily-app-backup --uid backup-12345-abcde

# Update backup from file
px pxb update backup --file /path/to/backup-update.json

Delete Backup

# Delete a specific backup
px pxb delete backup --name daily-app-backup --uid backup-12345-abcde

# Delete backup from specific cluster
px pxb delete backup --name daily-app-backup --cluster production-cluster

Retry Failed Backup

# Retry a failed backup
px pxb retry backup --name failed-backup

# Retry backup with specific resources
px pxb retry backup \
  --name failed-backup \
  --include-resources "web-app:frontend:apps/v1:Deployment" \
  --skip-auto-exec-rules

Advanced Configuration Examples

Backup with Namespace Label Selectors

px pxb create backup \
  --name label-based-backup \
  --cluster production-cluster \
  --ns-label-selectors "environment=production,team=platform" \
  --backup-location-name s3-backup

Backup with Advanced Resource Selection

px pxb create backup \
  --name advanced-backup \
  --cluster production-cluster \
  --namespaces "app" \
  --advanced-resource-label-selector "tier in (frontend,backend), !env=test" \
  --include-resources "web-app:app:apps/v1:Deployment,db-service:app:v1:Service" \
  --backup-location-name s3-backup

Direct KDMP Backup

px pxb create backup \
  --name kdmp-backup \
  --cluster production-cluster \
  --namespaces "data" \
  --direct-kdmp \
  --keep-cr-status \
  --backup-location-name s3-backup

Update Backup Metadata (Labels)

# Set or replace labels on a backup (key=value pairs)
px pxb update backup --name daily-app-backup --labels env=prod,team=platform

# Update labels again (e.g., change environment)
px pxb update backup --name daily-app-backup --labels env=staging

# Update labels using a JSON/YAML file
px pxb update backup --name daily-app-backup --file /path/to/update-labels.json

# Grant groups different access levels
px pxb share backup --name daily-app-backup \
  --add-groups "team1=View,team2=Restorable,admins=FullAccess"

# Grant collaborators (users) access
px pxb share backup --name daily-app-backup \
  --add-collaborators "alice-user-123=View,bob-user-456=FullAccess"

# Mix add/remove in one update
px pxb share backup --name daily-app-backup \
  --add-groups "devops=FullAccess" \
  --remove-groups team1 \
  --remove-collaborators alice-user-123

# From file (name can be provided in the file)
px pxb share backup --file /path/to/backup-share-config.json

Unshare a backup (revoke access)

# Remove specific groups
px pxb unshare backup --name daily-app-backup --remove-groups team2,old-team

# Remove specific collaborators
px pxb unshare backup --name daily-app-backup --remove-collaborators bob-user-456

# Remove all group and collaborator access
px pxb unshare backup --name daily-app-backup --remove-all-groups --remove-all-collaborators

# From file (mutually exclusive with flags)
px pxb unshare backup --file /path/to/backup-share-delete.json

# Inspect current sharing settings
px pxb get backupshare --name daily-app-backup --detailed

# JSON output
px pxb get backupshare --name daily-app-backup --output json

# From file (file must include name)
px pxb get backupshare --file /path/to/backup-share-inspect.json

Note:

For share/unshare/get backupshare: --name is required; --uid is optional. When using --file, the required name can be provided by the file payload.
For unshare, --file is mutually exclusive with removal flags; include removals in the file when using --file.

Example JSON file (/path/to/update-labels.json):

{
  "labels": {
    "env": "prod",
    "team": "platform"
  }
}

Note: Updating labels replaces the label map on the backup with the provided values. If you need to preserve existing labels, include them in the update payload as well.

Flags for commands and sub-commands

Create Backup Flags

Required Flags (optional with --file)

Flag	Short	Type	Description
`--name`	`-n`	string	Name of the backup (required, optional with --file)
`--cluster`	`-c`	string	Name of the cluster where backup should be run (required, optional with --file)
`--backup-location-name`		string	Name of backup location to be used (required, optional with --file)

Optional Identification

Flag	Short	Type	Description
`--uid`		string	UID of the backup
`--cluster-uid`	`-u`	string	UID of the cluster
`--backup-location-uid`		string	UID of the backup location

Backup Scope Configuration

Flag	Short	Type	Description
`--namespaces`		[]string	Namespaces to be backed up (comma-separated)
`--namespaces-file`		string	YAML/JSON file containing namespaces array
`--ns-label-selectors`		string	Label selectors to choose namespaces
`--backup-object-type`	`-b`	string	`All` (default) or `VirtualMachine`

Resource Selection

Flag	Type	Description
`--label-selectors`	map	Label selectors `key=value,key2=value2`
`--label-selectors-file`	string	YAML/JSON file with label selectors
`--advanced-resource-label-selector`	string	Advanced label selector (supports operators)
`--resource-types`	[]string	Specific resource types to backup
`--resource-types-file`	string	YAML/JSON file with resource types
`--exclude-resource-types`	[]string	Resource types to exclude
`--exclude-resource-types-file`	string	YAML/JSON file with excluded types
`--include-resources`	string	`name:namespace:group:version:kind` list
`--include-resources-file`	string	YAML/JSON file with include list

Backup Type and Behavior

Flag	Short	Type	Description
`--backup-type`	`-t`	string	`Normal` (default) or `Generic`
`--direct-kdmp`		bool	Use direct KDMP for data movement
`--keep-cr-status`		bool	Include custom resource status in backup

Execution Rules

Flag	Type	Description
`--pre-exec-rule-name`	string	Pre-execution rule name
`--pre-exec-rule-uid`	string	Pre-execution rule UID
`--post-exec-rule-name`	string	Post-execution rule name
`--post-exec-rule-uid`	string	Post-execution rule UID
`--skip-vm-auto-exec-rules`	bool	Skip automatic execution rules for VM backups

Storage and Snapshots

Flag	Type	Description
`--volume-snapshot-class-mapping`	map	`provisioner=snapshotclass` mapping
`--volume-snapshot-class-mapping-file`	string	JSON file with mapping
`--volume-resource-only-policy-name`	string	Name of volume resource only policy
`--volume-resource-only-policy-uid`	string	UID of volume resource only policy

File Input

Flag	Short	Type	Description
`--file`	`-f`	string	YAML/JSON file with complete configuration

Get Backup Flags

Resource Identification (optional with --file)

Flag	Short	Type	Description
`--name`		string	Name of backup to inspect (optional with --file, required for inspect mode otherwise)
`--uid`		string	UID of backup to inspect (optional; used with --name)

Enumeration Control

Flag	Short	Type	Description
`--max-objects`		uint64	Maximum number of backups to return
`--include-detailed-resources`		bool	Include detailed resource information

Filtering Options

Flag	Type	Description
`--owners`	[]string	Filter by backup owners
`--status`	[]string	Filter by status (Success, Failed, InProgress, …)
`--backup-object-type`	string	Filter by object type
`--name-filter`	string	Name substring/pattern filter
`--cluster-name-filter`	string	Filter by cluster name
`--cluster-uid-filter`	string	Filter by cluster UID

Time-based Filtering

Flag	Short	Type	Description
`--start-time`		string	RFC3339 start time
`--end-time`		string	RFC3339 end time

Label-based Filtering

Flag	Short	Type	Description
`--labels`		map	`key=value,key2=value2`

Schedule-based Filtering

Flag	Short	Type	Description
`--schedule-policy-refs`		[]string	Filter by schedule policy refs (name or name:uid). Use multiple flags for multiple policies
`--backup-schedule-refs`		[]string	Filter by backup schedule refs (name or name:uid). Use multiple flags for multiple schedules

Sorting Options

Flag	Short	Type	Description
`--sort-by`		string	`name`, `creation_time`, `status`,
`--sort-order`		string	`asc` or `desc`

File Input

Flag	Short	Type	Description
`--file`		string	YAML/JSON file for get/enumerate configuration

Update Backup Flags

Required Identification (optional with --file)

Flag	Short	Type	Description
`--name`		string	Name of the backup to update (optional with --file, required otherwise)
`--uid`		string	UID of the backup to update (optional)

File Input

Flag	Short	Type	Description
`--file`		string	YAML/JSON file with update configuration

Note: When using --file, the required backup name may come from the file payload. If neither the file nor the CLI provides a name, the command fails validation.

Metadata

Flag	Short	Type	Description
`--labels`		map	Labels to set on the backup (key=value,key2=value2)

Delete Backup Flags

Required Identification (optional with --file)

Flag	Short	Type	Description
`--name`		string	Name of the backup to delete (optional with --file, required otherwise)

Optional Identification

Flag	Type	Description
`--uid`	string	UID of the backup to delete
`--cluster`	string	Name of the cluster
`--cluster-name`	string	Alternative cluster name
`--cluster-uid`	string	UID of the cluster

File Input

Flag	Short	Type	Description
`--file`		string	YAML/JSON file with delete configuration

Required Identification

Flag	Short	Type	Description
`--name`	`-n`	string	Name of the backup to share (required, optional with --file)
`--uid`	`-u`	string	UID of the backup to share (optional)

Access Management

Flag	Short	Type	Description
`--add-groups`		map	Add groups with access levels (e.g., `team1=View,team2=Restorable,admins=FullAccess`)
`--add-collaborators`		map	Add collaborators with access levels (e.g., `user-123=View,admin-user-456=FullAccess`)

Removal Options

Flag	Short	Type	Description
`--remove-groups`		[]string	Remove groups from backup access (comma-separated list of group IDs)
`--remove-collaborators`		[]string	Remove collaborators from backup access (comma-separated list of user IDs)

File Input

Flag	Short	Type	Description
`--file`		string	YAML/JSON file containing backup share configuration

Note: For share, file input can be combined with flags; CLI flags override file values.

Unshare Backup Flags

Required Identification

Flag	Short	Type	Description
`--name`	`-n`	string	Name of the backup to unshare (required, optional with --file)
`--uid`	`-u`	string	UID of the backup to unshare (optional)

Removal Options

Flag	Type	Description
`--remove-groups`	[]string	Remove specific groups (comma-separated list of group IDs)
`--remove-collaborators`	[]string	Remove specific collaborators (comma-separated list of user IDs)
`--remove-all-groups`	bool	Remove all group access
`--remove-all-collaborators`	bool	Remove all collaborator access

File Input

Flag	Short	Type	Description
`--file`		string	YAML/JSON file with unshare configuration

Note: For unshare, --file is mutually exclusive with --name/--uid and all removal flags.

Required Identification

Flag	Short	Type	Description
`--name`	`-n`	string	Name of the backup (required, optional with --file)
`--uid`	`-u`	string	UID of the backup (optional)

Display

Flag	Short	Type	Description
`--detailed`		bool	Show detailed sharing information

File Input

Flag	Short	Type	Description
`--file`		string	YAML/JSON file with backupshare inspect configuration

Note: For get backupshare, --file is mutually exclusive with --name/--uid. When using --file, the file must include the required name.

Backup Retry Flags

Required Identification

Flag	Short	Type	Description
`--name`		string	Name of the backup to retry

Optional Identification

Flag	Short	Type	Description
`--uid`		string	UID of the backup to retry

Retry Configuration

Flag	Type	Description
`--include-resources`	string	`name:namespace:group:version:kind` list
`--include-resources-file`	string	YAML/JSON file with include list
`--skip-auto-exec-rules`	bool	Skip automatic execution rules during retry

File Input

Flag	Short	Type	Description
`--file`		string	YAML/JSON file with retry configuration

Notes

File vs CLI Flag Precedence

When both --file and CLI flags are provided, CLI flags take precedence over file values.
The organization ID is always taken from the current context.
File parsing supports both YAML and JSON formats.

Dual Mode Operations

px pxb get backup without --name triggers enumerate mode (lists backups).
px pxb get backup with --name triggers inspect mode (optionally add --uid to disambiguate if multiple backups share the name across contexts).

Required Flag Validation

Get (inspect mode) requires: --name (UID is optional)
Create requires: --name, --cluster, --backup-location-name.
Update requires: --name
Delete requires: --name
Retry requires: --name

Resource Format Specifications

Include/Exclude Resources: name:namespace:group:version:kind.
Label Selectors: key=value,key2=value2.
Advanced Label Selectors: operators like in, notin, exists, !exists.
Time filters: RFC3339 (e.g., 2024-01-01T00:00:00Z).

Output Format Support

All commands support:

--output table (default)
--output json
--output yaml
--output name (for get)

Authentication and Context

All commands automatically include:

Organization ID from context
Authentication token from context
Labels from context

Description​

Usage​

Create Backup​

Get Backup (Inspect)​

Get Backup (List All)​

Update Backup​

Delete Backup​

Retry Backup​

Share Backup​

Unshare Backup​

Get Backup Share​

Examples​

Basic Backup Operations​

Simple Namespace Backup​

Full Cluster Backup​

Virtual Machine Backup​

Advanced Backup Scenarios​

Backup with Resource Filtering​

Backup with Execution Rules​

Generic Backup with CSI Snapshots​

Backup from Configuration File​

Backup Retrieval Operations​

List All Backups​

Inspect Specific Backup​

Filter Backups by Time Range​

Filter Backups by Schedule References​

Backup Management Operations​

Update Backup​

Delete Backup​

Retry Failed Backup​

Advanced Configuration Examples​

Backup with Namespace Label Selectors​

Backup with Advanced Resource Selection​

Direct KDMP Backup​

Update Backup Metadata (Labels)​

Backup Sharing Operations​

Share a backup with groups and collaborators​

Unshare a backup (revoke access)​

Get backup share details​

Flags for commands and sub-commands​

Create Backup Flags​

Required Flags (optional with --file)​

Optional Identification​

Backup Scope Configuration​

Resource Selection​

Backup Type and Behavior​

Execution Rules​

Storage and Snapshots​

File Input​

Get Backup Flags​

Resource Identification (optional with --file)​

Enumeration Control​

Filtering Options​

Time-based Filtering​

Label-based Filtering​

Schedule-based Filtering​

Sorting Options​

File Input​

Update Backup Flags​

Required Identification (optional with --file)​

File Input​

Metadata​

Delete Backup Flags​

Required Identification (optional with --file)​

Optional Identification​

File Input​

Share Backup Flags​

Required Identification​

Access Management​

Removal Options​

File Input​

Unshare Backup Flags​

Required Identification​

Removal Options​

File Input​

Get Backup Share Flags​

Required Identification​

Display​

File Input​

Backup Retry Flags​

Description

Usage

Create Backup

Get Backup (Inspect)

Get Backup (List All)

Update Backup

Delete Backup

Retry Backup

Share Backup

Unshare Backup

Get Backup Share

Examples

Basic Backup Operations

Simple Namespace Backup

Full Cluster Backup

Virtual Machine Backup

Advanced Backup Scenarios

Backup with Resource Filtering

Backup with Execution Rules

Generic Backup with CSI Snapshots

Backup from Configuration File

Backup Retrieval Operations

List All Backups

Inspect Specific Backup

Filter Backups by Time Range

Filter Backups by Schedule References

Backup Management Operations

Update Backup

Delete Backup

Retry Failed Backup

Advanced Configuration Examples

Backup with Namespace Label Selectors

Backup with Advanced Resource Selection

Direct KDMP Backup

Update Backup Metadata (Labels)

Backup Sharing Operations

Share a backup with groups and collaborators

Unshare a backup (revoke access)

Get backup share details

Flags for commands and sub-commands

Create Backup Flags

Required Flags (optional with --file)

Optional Identification

Backup Scope Configuration

Resource Selection

Backup Type and Behavior

Execution Rules

Storage and Snapshots

File Input

Get Backup Flags

Resource Identification (optional with --file)

Enumeration Control

Filtering Options

Time-based Filtering

Label-based Filtering

Schedule-based Filtering

Sorting Options

File Input

Update Backup Flags

Required Identification (optional with --file)

File Input

Metadata

Delete Backup Flags

Required Identification (optional with --file)

Optional Identification

File Input

Share Backup Flags

Required Identification

Access Management

Removal Options

File Input

Unshare Backup Flags

Required Identification

Removal Options

File Input

Get Backup Share Flags

Required Identification

Display

File Input

Backup Retry Flags