Cluster

Description

The px pxb cluster commands manage clusters registered with Portworx Backup. You can update cluster connectivity and credentials, inspect/list clusters, delete clusters with safety options, share/unshare access to a cluster with users and groups, and manage granular backup sharing permissions for all backups on a cluster.

Usage

Connect Cluster

px pxb connect cluster --name <cluster-name> --kubeconfig </path/to/kubeconfig> [flags]

Update Cluster

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

Get Cluster (Inspect)

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

Get Cluster (List All)

px pxb get cluster [flags]

Delete Cluster

px pxb delete cluster --name <cluster-name> [--uid <uid>] [flags]

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

Get Managed Clusters (Inspect)

px pxb get managed-clusters --name <managed-cluster-name> --provider aws --cloud-credential-name <cred-name> --region <aws-region> [flags]

Get Managed Clusters (List All)

px pxb get managed-clusters --provider aws --cloud-credential-name <cred-name> --region <aws-region> [flags]

Connect Managed Clusters (Bulk Add)

px pxb connect managed-clusters --provider aws --cloud-credential-name <cred-name> --region <aws-region> \
  --cluster-names "<cluster1>,<cluster2>[,<clusterN>]" [flags]

Unshare Cluster

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

px pxb update clusterbackupshare --name <cluster-name> [--uid <uid>] [flags]

Examples

Update kubeconfig

px pxb update cluster \
  --name prod-cluster \
  --kubeconfig /path/to/new/kubeconfig

Update PX token and cloud credentials

px pxb update cluster \
  --name prod-cluster \
  --px-token abc123token \
  --cloud-credential-name aws-prod-cred

Update from file

px pxb update cluster --file /path/to/cluster-update.json

Example /path/to/cluster-update.json:

{
  "createMetadata": { "name": "prod-cluster" },
  "pxConfig": { "accessToken": "abc123token" },
  "cloudCredentialRef": { "name": "aws-prod-cred" }
}

Inspect and list clusters

# Inspect one cluster (with secrets)
px pxb get cluster --name prod-cluster --include-secrets

# List all (JSON output)
px pxb get cluster --output json

# List filtered by cloud credential
px pxb get cluster --cloud-credential-name aws-prod-cred

# Share cluster with users and groups (and include backups)
px pxb share cluster \
  --cluster prod-cluster \
  --users alice-user-123,bob-user-456 \
  --groups devops,platform \
  --share-cluster-backups

# Unshare cluster from specific users/groups
px pxb unshare cluster \
  --cluster prod-cluster \
  --users alice-user-123 \
  --groups devops

# Add groups with different access levels to cluster backups
px pxb update clusterbackupshare \
  --name prod-cluster \
  --add-groups "devops-team=FullAccess,qa-team=View,support-team=Restorable"

# Add collaborators (individual users) with specific access
px pxb update clusterbackupshare \
  --name prod-cluster \
  --add-collaborators "admin-user-123=FullAccess,viewer-user-456=View"

# Remove groups and collaborators from cluster backup access
px pxb update clusterbackupshare \
  --name prod-cluster \
  --remove-groups old-team,deprecated-group \
  --remove-collaborators former-user-789

# Mixed operations: add and remove in single command
px pxb update clusterbackupshare \
  --name prod-cluster \
  --add-groups "new-team=FullAccess" \
  --remove-groups old-team \
  --add-collaborators "new-user=Restorable" \
  --remove-collaborators old-user

# Update from JSON configuration file
px pxb update clusterbackupshare --file cluster-backup-share-config.json

# Dry-run to preview changes
px pxb update clusterbackupshare \
  --name prod-cluster \
  --add-groups "team1=View" \
  --dry-run

Example cluster-backup-share-config.json:

{
  "name": "prod-cluster",
  "uid": "cluster-12345",
  "add_backup_share": {
    "groups": [
      {"id": "devops-team", "access": 3},
      {"id": "qa-team", "access": 1}
    ],
    "collaborators": [
      {"id": "admin-user-123", "access": 3},
      {"id": "viewer-user-456", "access": 1}
    ]
  },
  "del_backup_share": {
    "groups": [
      {"id": "old-team"}
    ],
    "collaborators": [
      {"id": "former-user-789"}
    ]
  }
}

Access Level Mapping: 1=View, 2=Restorable, 3=FullAccess

Delete cluster (with options)

# Basic delete
px pxb delete cluster --name prod-cluster

# Delete cluster and associated restores
px pxb delete cluster --name prod-cluster --delete-restores

# Delete cluster and all associated backups (SuperAdmin only)
px pxb delete cluster --name prod-cluster --delete-all-cluster-backups --force

Connect a cluster

# Connect using kubeconfig and optional provider/credentials
px pxb connect cluster \
  --name prod-cluster \
  --kubeconfig /path/to/kubeconfig \
  --px-token ABCDEF123456 \
  --cloud-credential-name aws-prod-cred \
  --provider aws

# Connect from file (name can be provided in file)
px pxb connect cluster --file /path/to/cluster-connect.json

Get managed clusters

# List all AWS managed clusters in a region
px pxb get managed-clusters --provider aws --cloud-credential-name aws-prod-cred --region us-west-2

# Inspect a specific managed cluster
px pxb get managed-clusters --name eks-team --provider aws --cloud-credential-name aws-prod-cred --region us-west-2

Connect managed clusters (bulk add)

# Add multiple AWS EKS clusters discovered in a region
px pxb connect managed-clusters \
  --provider aws \
  --cloud-credential-name aws-prod-cred \
  --region us-west-2 \
  --cluster-names "eks-team,eks-analytics"

# From file
px pxb connect managed-clusters --file /path/to/managed-clusters-connect.json

Flags for commands and sub-commands

Update Cluster Flags

Required Identification (optional with --file)

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

Update Fields

Flag	Short	Type	Description
`--kubeconfig`	`-k`	string	Path to kubeconfig; file contents are base64-encoded and sent
`--px-token`	`-t`	string	Portworx access token (PX Security Token)
`--cloud-credential-name`		string	Name of cloud credential to associate
`--cloud-credential-uid`		string	UID of cloud credential
`--platform-credential-name`		string	Name of platform credential to associate
`--platform-credential-uid`		string	UID of platform credential

File Input

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

Get Cluster Flags

Resource Identification

Flag	Short	Type	Description
`--name`	`-n`	string	Name of the cluster to inspect (required for inspect; omit to list all)
`--uid`	`-u`	string	UID of the cluster (optional; used with `--name`)

Content and Filters

Flag	Short	Type	Description
`--include-secrets`	`-s`	bool	Include secrets in output
`--cloud-credential-name`		string	Filter by cloud credential name (enumerate mode)
`--cloud-credential-uid`		string	Filter by cloud credential UID (enumerate mode)

Delete Cluster Flags

Required Identification

Flag	Short	Type	Description
`--name`	`-n`	string	Name of the cluster to delete (required)
`--uid`	`-u`	string	UID of the cluster (optional)

Deletion Options

Flag	Type	Description
`--delete-restores`	bool	Delete restores associated with the cluster
`--delete-all-cluster-backups`	bool	Delete all backups on the cluster (SuperAdmin only)
`--force`	bool	Skip confirmation prompt

Required Identification (optional with --file)

Flag	Short	Type	Description
`--cluster`	`-c`	string	Name of the cluster to share (optional with --file, required otherwise)
`--cluster-uid`	`-u`	string	UID of the cluster (optional)

Flag	Type	Description
`--users`	[]string	User IDs to share with (comma-separated)
`--groups`	[]string	Group IDs to share with (comma-separated)
`--share-cluster-backups`	bool	Also share existing backups on this cluster

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

Unshare Cluster Flags

Required Identification (optional with --file)

Flag	Short	Type	Description
`--cluster`	`-c`	string	Name of the cluster to unshare (optional with --file, required otherwise)
`--cluster-uid`	`-u`	string	UID of the cluster (optional)

Unshare Targets

Flag	Short	Type	Description
`--users`		[]string	User IDs to remove access from (comma-separated)
`--groups`		[]string	Group IDs to remove access from (comma-separated)

File Input (unshare)

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

Required Identification

Flag	Short	Type	Description
`--name`	`-n`	string	Name of the cluster (required unless using --file)
`--uid`	`-u`	string	UID of the cluster (optional)

Add Operations

Flag	Short	Type	Description
`--add-groups`		stringToString	Groups to add with access levels (format: "group1=View,group2=FullAccess")
`--add-collaborators`		stringToString	Individual users to add with access levels (format: "user1=Restorable,user2=View")

Remove Operations

Flag	Short	Type	Description
`--remove-groups`		stringSlice	Groups to remove from cluster backup access (comma-separated)
`--remove-collaborators`		stringSlice	Individual users to remove from cluster backup access (comma-separated)

File Input

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

Access Levels

The cluster backup sharing supports three access levels:

Access Level	Description	Permissions
`View`	Read-only access	Can view backup information and status
`Restorable`	View and restore access	Can view backups and perform restore operations
`FullAccess`	Complete administrative access	Can view, restore, delete, and modify backup operations

Connect Cluster Flags

Required Flags

Flag	Short	Type	Description
`--name`	`-n`	string	Name of the cluster to connect (required; may come from `--file`)
`--kubeconfig`	`-k`	string	Path to kubeconfig file (required; file contents are base64-encoded)

Provider and Credentials

Flag	Short	Type	Description
`--px-token`	`-t`	string	Portworx access token (PX Security Token)
`--cloud-credential-name`		string	Name of cloud credential to associate
`--cloud-credential-uid`		string	UID of cloud credential
`--platform-credential-name`		string	Name of platform credential to associate
`--platform-credential-uid`		string	UID of platform credential
`--provider`		string	Cloud provider type (`aws`, `azure`, `google`, `ibm`, `rancher`)

Identification and File Input

Flag	Short	Type	Description
`--uid`		string	UID for the cluster (optional)
`--file`	`-f`	string	YAML/JSON file with complete cluster connection configuration

Get Managed Clusters Flags

Resource Identification

Flag	Short	Type	Description
`--name`	`-n`	string	Name of the managed cluster to inspect (omit to enumerate all)
`--uid`		string	UID of the managed cluster (optional; used with `--name`)

Provider and Credentials (required)

Flag	Short	Type	Description
`--provider`	`-p`	string	Cloud provider type (currently supported: `aws`)
`--cloud-credential-name`		string	Name of cloud credential to use
`--cloud-credential-uid`		string	UID of cloud credential to use

General Content

Flag	Short	Type	Description
`--include-secrets`		bool	Include sensitive information in the response (default: true)

AWS-specific

Flag	Short	Type	Description
`--region`	`-r`	string	AWS region (required for AWS)
`--next-token`		string	AWS pagination token for next set of results
`--max-results`	`-m`	int	Maximum number of results to return (default: 10)

File Input

Flag	Short	Type	Description
`--file`	`-f`	string	JSON configuration file path (supports inspect or enumerate request)

Connect Managed Clusters Flags

Cluster Names

Flag	Short	Type	Description
`--cluster-names`		string	Comma-separated list of cluster names to add
`--cluster-name`		[]string	Specify multiple times to add clusters

Provider and Credentials (required)

Flag	Short	Type	Description
`--provider`	`-p`	string	Cloud provider type (currently supported: `aws`)
`--cloud-credential-name`		string	Name of cloud credential to use
`--cloud-credential-uid`		string	UID of cloud credential to use

AWS-specific

Flag	Short	Type	Description
`--region`	`-r`	string	AWS region where clusters are located (required for AWS)

File Input

Flag	Short	Type	Description
`--file`	`-f`	string	JSON configuration file path

Notes

Connect Cluster: requires --name and --kubeconfig. Provider can be specified as aws|azure|google|ibm|rancher. When combining --file with flags, CLI flags override file values; org and labels come from context.
Get Cluster: dual mode — without --name enumerates; with --name inspects one (optionally add --uid).
Update/Delete Cluster: --name required; --uid optional. With --file, identifiers may come from the file; CLI flags override file values.
Share/Unshare Cluster: require --cluster (name) and at least one of --users or --groups.
Update Cluster Backup Share: requires --name (unless using --file). At least one operation flag must be specified: --add-groups, --add-collaborators, --remove-groups, or --remove-collaborators. Access levels for add operations: View, Restorable, FullAccess. CLI flags override file values when both are provided.
Get Managed Clusters: currently supports provider aws only; requires --cloud-credential-name and --region. --include-secrets defaults to true. With --name, performs inspect; otherwise enumerates. File input supports either request shape.
Connect Managed Clusters (bulk add): requires one or more cluster names via --cluster-names or repeated --cluster-name; currently supports provider aws with required --region. Dry-run is supported; track status using get managed-clusters.
Sorting flags apply only to cluster enumeration (when supported by the CLI build).

Output Format Support

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

Authentication and Context

Organization ID from context
Authentication token from context
Labels from context (used for enumerate filtering)

Description​

Usage​

Connect Cluster​

Update Cluster​

Get Cluster (Inspect)​

Get Cluster (List All)​

Delete Cluster​

Share Cluster​

Get Managed Clusters (Inspect)​

Get Managed Clusters (List All)​

Connect Managed Clusters (Bulk Add)​

Unshare Cluster​

Update Cluster Backup Share​

Examples​

Update kubeconfig​

Update PX token and cloud credentials​

Update from file​

Inspect and list clusters​

Share / Unshare cluster access​

Update cluster backup sharing permissions​

Delete cluster (with options)​

Connect a cluster​

Get managed clusters​

Connect managed clusters (bulk add)​

Flags for commands and sub-commands​

Update Cluster Flags​

Required Identification (optional with --file)​

Update Fields​

File Input​

Get Cluster Flags​

Resource Identification​

Content and Filters​

Delete Cluster Flags​

Required Identification​

Deletion Options​

Share Cluster Flags​

Required Identification (optional with --file)​

Share Targets and Options​

File Input (share)​

Unshare Cluster Flags​

Required Identification (optional with --file)​

Unshare Targets​

File Input (unshare)​

Update Cluster Backup Share Flags​

Required Identification​

Add Operations​

Remove Operations​

File Input​

Access Levels​

Connect Cluster Flags​

Required Flags​

Provider and Credentials​

Identification and File Input​

Get Managed Clusters Flags​

Resource Identification​

Provider and Credentials (required)​

General Content​

AWS-specific​

File Input​

Connect Managed Clusters Flags​

Cluster Names​

Provider and Credentials (required)​

AWS-specific​

File Input​

Notes​

Output Format Support​

Authentication and Context​

Description

Usage

Connect Cluster

Update Cluster

Get Cluster (Inspect)

Get Cluster (List All)

Delete Cluster

Share Cluster

Get Managed Clusters (Inspect)

Get Managed Clusters (List All)

Connect Managed Clusters (Bulk Add)

Unshare Cluster

Update Cluster Backup Share

Examples

Update kubeconfig

Update PX token and cloud credentials

Update from file

Inspect and list clusters

Share / Unshare cluster access

Update cluster backup sharing permissions

Delete cluster (with options)

Connect a cluster

Get managed clusters

Connect managed clusters (bulk add)

Flags for commands and sub-commands

Update Cluster Flags

Required Identification (optional with --file)

Update Fields

File Input

Get Cluster Flags

Resource Identification

Content and Filters

Delete Cluster Flags

Required Identification

Deletion Options

Share Cluster Flags

Required Identification (optional with --file)

Share Targets and Options

File Input (share)

Unshare Cluster Flags

Required Identification (optional with --file)

Unshare Targets

File Input (unshare)

Update Cluster Backup Share Flags

Required Identification

Add Operations

Remove Operations

File Input

Access Levels

Connect Cluster Flags

Required Flags

Provider and Credentials

Identification and File Input

Get Managed Clusters Flags

Resource Identification

Provider and Credentials (required)

General Content

AWS-specific

File Input

Connect Managed Clusters Flags

Cluster Names

Provider and Credentials (required)

AWS-specific

File Input

Notes

Output Format Support

Authentication and Context