Skip to main content
Version: 3.1

Basics operations using pxctl

In this document, we are going to explore the basic operations available through the Portworx command-line tool- pxctl.

By default, the CLI displays the information in human readable form.

pxctl provides the capability to perform fine-grained control of the Portworx resources cluster-wide. Also, it lets the user manage volumes, snapshots, cluster resources, hosts in the cluster and software upgrade in the cluster. Run pxctl --help to learn more about the available commands.

In addition, every command takes in a --json flag which converts the output to a machine-parsable JSON format. You can do something like the following to save the output in JSON format:

pxctl status --json > status.json

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, pxctl has a rich set of cluster-wide management features which are explained in this document.

All operations available through 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.
  • Lets 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 on any node within the cluster, therefore, shows the same global details. But pxctl also identifies details specific to that node.

The current release of pxctl is located in the /opt/pwx/bin/ directory of every worker node and requires that you run it as a privileged user.

Let's look at some simple commands.

Version​

Here's how to find out the current version:

pxctl --version
pxctl version 2.7.0.0-886586d

Status​

This section has been moved to the status page.

pxctl provides access to several upgrade related operations. You can get details on how to use it and of the available flags by running:

pxctl upgrade --help

Running pxctl upgrade​

pxctl upgrade upgrades the Portworx version on a node. Let's suppose you want to upgrade Portworx to version 1.1.16. If so, you would then type the following command:

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. This way, the quorum and the continuity of IOs will be maintained.

Login/Authentication​

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

pxctl secrets can be used to configure authentication credentials and endpoints. Currently, Vault, Amazon KMS, and KVDB are supported.

Vault example​

Here's an example of configuring Portworx with Vault:

pxctl secrets vault login --vault-address http://myvault.myorg.com --vault-token myvaulttoken
Successfully authenticated with Vault.
note

To install and configure Vault, peruse this link

AWS KMS example​

To configure Portworx with Amazon KMS, type the following command:

pxctl secrets aws login

Then, you will be asked a few questions:

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

Finally, a success message will be displayed:

Successfully authenticated with AWS.

EULA​

You can get a link to our EULA by running:

pxctl eula
https://portworx.com/end-user-license-agreement
Last updated on