The Portworx command-line tool, pxctl, is available on every node where PX is running. It is available at the host at /opt/pwx/bin/pxctl. The CLI is designed to accept and display human readable input and output by default. In addition, every command takes in a -j option such that the output is in machine parsable json format.

In most production deployments, you will provision volumes directly using Docker or your scheduler (such as a Kubernetes pod spec). However, pxctl also lets you directly provision and manage storage. In addition, the pxctl has a rich set of cluster wide management features which are explained in this document.

All operations from pxctl are reflected back into the containers that use Portworx storage. In addition to what is exposed in Docker volumes, pxctl:

  • Gives access to Portworx storage-specific features, such as cloning a running container’s storage.
  • Shows the connection between containers and their storage volumes.
  • Let you control the Portworx storage cluster, such as adding nodes to the cluster. (The Portworx tools refer to servers managed by Portworx storage as nodes.)

The scope of the pxctl command is global to the cluster. Running pxctl from any node within the cluster therefore shows the same global details. pxctl also identifies details specific to that node.

This current release of pxctl requires that you run as a privileged user. The pxctl tool is available in the /opt/pwx/bin/ directory. To run pxctl without typing the full directory path each time, add pxctl to your PATH as follows:

# sudo su
# export PATH=/opt/pwx/bin:$PATH

pxctl provides capabilities to perform much more fine-grained control of the PX resources cluster-wide and as seen above offers capabilties to manage volumes, snapshots, cluster resources, hosts in the cluster and software upgrade in the cluster.

Now you can just type pxctl and you’re ready to start.

Version

# sudo /opt/pwx/bin/pxctl -v
pxctl version 2.2.0-555ffff

Help

To view all the commands offered by pxctl, type ‘pxctl help’

# sudo /opt/pwx/bin/pxctl help  
NAME:
   pxctl - px cli

USAGE:
   pxctl [global options] command [command options] [arguments...]
   
VERSION:
   1.2.0-75d0dbb
   
COMMANDS:
     status         Show status summary
     volume, v      Manage volumes
     snap, s        Manage volume snapshots
     cluster, c     Manage the cluster
     service, sv    Service mode utilities
     host           Attach volumes to the host
     secrets        Manage Secrets
     upgrade        Upgrade PX
     eula           Show license agreement
     cloudsnap, cs  Backup and restore snapshots to/from cloud
     objectstore    Manage the object store
     help, h        Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --json, -j     output in json
   --color        output with color coding
   --raw, -r      raw CLI output for instrumentation
   --help, -h     show help
   --version, -v  print the version
sudo /opt/pwx/bin/pxctl upgrade --help
NAME:
   pxctl upgrade - Upgrade PX

USAGE:
   pxctl upgrade [command options] [arguments...]

OPTIONS:
   --tag value, -l value  Specify a PX Docker image tag (default: "latest")
   

pxctl upgrade

pxctl upgrade upgrades the PX version on a node. Note: the container name also needs to be specified in the CLI.

sudo /opt/pwx/bin/pxctl upgrade --tag 1.1.6 my-px-enterprise
Upgrading my-px-enterprise to version: portworx/px-enterprise:1.1.6
Downloading PX portworx/px-enterprise:1.1.6 layers...
<Output truncated>

It is recommended to upgrade the nodes in a staggered manner so as to maintain quorum and continuity of IOs.

Login/Authentication

You must make PX login to the secrets endpoint when using encrypted volumes and ACLs.

pxctl secrets can be used to configure authentication credentials and endpoints - Vault, Amazon KMS, KVDB are currently supported. Vault example (Note: To install and configure Vault, peruse this link)

# sudo /opt/pwx/bin/pxctl secrets vault login
Enter VAULT_ADDRESS: http://myvault.myorg.com
Enter VAULT_TOKEN: ***
Successfully authenticated with Vault.

AWS KMS example

# sudo /opt/pwx/bin/pxctl secrets aws login
Enter AWS_ACCESS_KEY_ID [Hit Enter to ignore]: ***
Enter AWS_SECRET_ACCESS_KEY [Hit Enter to ignore]: ***
Enter AWS_SECRET_TOKEN_KEY [Hit Enter to ignore]: ***
Enter AWS_CMK [Hit Enter to ignore]: mykey
Enter AWS_REGION [Hit Enter to ignore]: us-east-1b
Successfully authenticated with AWS.
Edit this page