Role

Description

Manage access control roles for Portworx Backup. A role defines which Portworx Backup services and APIs a user can access. Use these commands to create, get (inspect/list), update, and delete roles.

Usage

Create Role

px pxb create role --name <name> [--file </path/to/role-create.json>] \
  [--rules <service=api1,api2:service2=*> | --rules-file </path/to/role-rules.json> | \
   (--services <svc1,svc2> --apis <api1,api2>)] \
  [--labels key1=val1,key2=val2] [--labels-file </path/to/role-labels.json>] \
  [--role-id <external-id>] [--uid <uid>]

Get Role (Inspect)

px pxb get role --name <name> [--uid <uid>] [--include-rules=true|false]

Get Role (List All)

px pxb get role [--max-objects <n>] [--owners user1,user2] \
  [--sort-by Name|CreationTimestamp|LastUpdateTimestamp] \
  [--sort-order Ascending|Descending] \
  [--file </path/to/role-get.json>]

Update Role

px pxb update role --name <name> [--file </path/to/role-update.json>] \
  [--rules <service=api1,api2:service2=*> | --rules-file </path/to/role-rules.json> | \
   (--services <svc1,svc2> --apis <api1,api2>)] \
  [--labels key1=val1,key2=val2] [--labels-file </path/to/role-labels.json>] \
  [--role-id <external-id>]

Delete Role

px pxb delete role --name <name> [--uid <uid>] [--file </path/to/role-delete.json>]

Get Permission

px pxb get permission

Examples

Create role

# From full JSON
px pxb create role --name platform-admin --file /path/to/role-create.json

# Inline services/APIs
px pxb create role --name backup-admin --services "backup,restore" --apis "create,delete,inspect"

# Rules string (multiple rules separated by ':')
px pxb create role --name readonly --rules "backup=inspect:restore=inspect"

# Rules from file and labels from file
px pxb create role --name custom --rules-file /path/to/role-rules.json \
  --labels-file /path/to/role-labels.json

# With external identity mapping (e.g., Keycloak role ID)
px pxb create role --name kc-role --role-id "keycloak-uuid" --services "backup" --apis "*"

Get role

# Inspect by name
px pxb get role --name platform-admin

# Inspect by UID
px pxb get role --uid role-12345

# List all roles
px pxb get role

# List with filtering and sorting
px pxb get role --owners user1,user2 --max-objects 50 \
  --sort-by CreationTimestamp --sort-order Descending

# Do not include rules for faster list
px pxb get role --include-rules=false --max-objects 200

# Load enumerate/inspect configuration from file (API-shaped request)
px pxb get role --file /path/to/role-get.json

Update role

# From file
px pxb update role --name platform-admin --file /path/to/role-update.json

# Update services/APIs
px pxb update role --name backup-admin --services "backup,restore,schedule" --apis "*"

# Update rules via string
px pxb update role --name custom --rules "backup=create,inspect:schedule=inspect"

# Update rules via file + labels inline
px pxb update role --name custom --rules-file /path/to/role-rules.json \
  --labels env=prod,tier=gold

# Update external identity mapping
px pxb update role --name kc-role --role-id "new-keycloak-uuid"

Delete role

# Delete by name
px pxb delete role --name deprecated-role

# Delete by UID
px pxb delete role --uid role-12345

# Delete from configuration file
px pxb delete role --file /path/to/role-delete.json

Get permission

# Get current user's permissions
px pxb get permission

# JSON output
px pxb get permission --output json

Flags for commands and sub-commands

Create Role Flags

Flag	Short	Type	Description
--name	-n	string	Name of the role (required, optional with --file)
--file	-f	string	JSON file with full role specification (mutually exclusive with other content flags)
--rules		string	Colon-separated rules string, e.g., backup=create,inspect:restore=*
--rules-file		string	Path to JSON file containing role rules
--services		string	Comma-separated Portworx Backup services (simple mode)
--apis		string	Comma-separated API operations (simple mode)
--labels		map	Labels for the role (key=value pairs)
--labels-file		string	JSON file with labels
--role-id		string	External identity provider role ID (e.g., Keycloak)
--uid		string	UID for the role (optional; server can generate)

Get Role Flags

Flag	Short	Type	Description
--name	-n	string	Name of the role to inspect (inspect mode)
--uid		string	UID of the role to inspect (inspect mode)
--owners		list	Filter roles by owners (enumerate mode)
--max-objects		uint	Maximum number of roles to return (client-side pagination)
--include-rules		bool	Include detailed rules in output (inspect/list)
--sort-by		string	Sort field: Name, CreationTimestamp, LastUpdateTimestamp
--sort-order		string	Sort order: Ascending or Descending
--file	-f	string	JSON file containing an API-shaped inspect or enumerate request

Update Role Flags

Flag	Short	Type	Description
--name	-n	string	Name of the role to update
--file	-f	string	JSON file with updated role specification (mutually exclusive with other content flags)
--rules		string	Updated rules string, e.g., backup=create,inspect:restore=*
--rules-file		string	Path to JSON file containing updated role rules
--services		string	Updated comma-separated services (simple mode)
--apis		string	Updated comma-separated API operations (simple mode)
--labels		map	Updated labels (key=value pairs)
--labels-file		string	JSON file with labels
--role-id		string	Updated external identity provider role ID

Get Permission Flags

This command has no flags.

Delete Role Flags

Flag	Short	Type	Description
--name	-n	string	Name of the role to delete (optional with --file, required otherwise)
--uid		string	UID of the role to delete (optional)
--file	-f	string	JSON file containing delete configuration

Notes

• Create/Update require role rules. Provide rules using one of: --file, --rules, --rules-file, or the simple --services with --apis.
• File vs CLI precedence: when --file is provided, it supplies the full request; do not combine with other content flags.
• Get automatically selects Inspect vs List mode based on whether --name or --uid is provided.
• Sorting and filtering for list mode are client-side.
• Commands honor global options (e.g., --dry-run) consistent with other resources.

Output Format Support

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

Authentication and Context

• Uses the current organization and auth context from your configuration.
• Ensure you are logged in and have permission to manage roles. See login-logout.md for authentication steps.