Skip to main content
Version: 3.1

Install on Docker Standalone

Deprecation notice

Support for Portworx on the following orchestrators will be deprecated:

  • Docker Swarm and Docker Standalone
  • Nomad

For installation instructions on other platforms, refer to the Platform guides section.

note

This document presents the Docker (or podman) method of installing a Portworx cluster using runC containers. Please refer to the Portworx on Kubernetes page if you want to install Portworx on Kubernetes.

Why OCI​

Running Portworx as a runC container eliminates any cyclical dependencies between the Docker container consuming storage from the Portworx container. It also enables you to run your Linux containers without a Docker daemon completely, while still getting all of the advantages of a Linux container and a cloud-native storage solution provided by Portworx.

Install​

To install and setup the Portworx OCI bundle, perform the following steps:

  1. Install the Portworx OCI bundle
  2. Configure the Portworx OCI bundle
  3. Enable and start the Portworx service

Prerequisites​

  • Systemd: The installation procedure assumes that the systemd package is installed on your system. You can check if systemd is installed by entering the following command:

    systemctl

    If you are running Ubuntu 16.04, CentOS 7 or CoreOS v94 or newer, systemd is already installed, and no actions are required.

  • Firewall: Ensure ports 9001-9022 are open on the cluster nodes that run Portworx.

  • NTP: Ensure all nodes running Portworx are time-synchronized by installing and running the NTP service.

  • KVDB: Portworx requires a key-value database like etcd. Portworx by Pure Storage recommends a highly available etcd cluster with persistent storage. See the etcd installation page for more details.

  • Storage: At least one Portworx node should have extra storage available, either as an unformatted partition or as a disk-drive. Note that Portworx automatically formats any storage devices you pass as parameters to the px-runc installer. The following example command passes the /dev/sdb and /dev/sdc3 storage devices as parameters:

    px-runc install -name portworx -c doc-cluster -k etcd:http://127.0.0.1:4001 -s /dev/sdb -s /dev/sdc3 -v /mnt:/mnt:shared

Step 1: Install the Portworx OCI bundle​

Portworx provides a Docker-based installation utility to help deploy the Portworx OCI bundle. You can install this bundle by running the following Docker container on your host system:

REL="/3.0"  # Portworx v3.0 release

latest_stable=$(curl -fsSL "https://install.portworx.com$REL/?type=dock&stork=false&aut=false" | awk '/image: / {print $2}' | head -1)

# Download OCI bits (reminder, you will still need to run `px-runc install ..` after this step)
sudo docker run --entrypoint /runc-entry-point.sh \
    --rm -i --privileged=true \
    -v /opt/pwx:/opt/pwx -v /etc/pwx:/etc/pwx \
    $latest_stable

Step 2: Configure Portworx under runC​

Now that you have downloaded and installed the Portworx OCI bundle, you can use the px-runc install command from the bundle to configure your installation.

The px-runc command is a helper tool that configures and runs the Portworx runC container.

The following example shows how you can use px-runc to install Portworx::

sudo /opt/pwx/bin/px-runc install -c MY_CLUSTER_ID \
    -k etcd://myetc.company.com:2379 \
    -s /dev/xvdb -s /dev/xvdc

Command-line arguments​

Below is the list of arguments you can pass to px-runc:

General options​
-c <id>                   [REQUIRED] Specifies the cluster ID that this PX instance is to join
-k <kvdb://host:port>     [REQUIRED] Points to your key value database, such as an etcd cluster
-b                        Use in-built kvdb. Provide the kvdb endpoints required for bootstrap with -k option.
-s <device path>          [REQUIRED unless -a/-A are used] Specify storage devices that PX should use for storing the data
-xs <omit device path>    Specify storage devices that PX should NOT use for storing the data (useful with -a/-A)
-T <type>                 Specify backend storage type (<type> is mdraid or lvm)
-cache [<device path>]    Specify storage devices that PX should use for caching
-dedicated_cache          Constrain cache drive assignment from given -cache drives only
-j <device path>          Specify storage device that PX should use for storing the journal data
-metadata <device path>   Specify storage device that PX should use for storing the system meta data
-kvdb_dev <device path>   Specify storage device that PX should use for storing internal kvdb data
-oci <dir>                Specify OCI directory (dfl: /opt/pwx/oci)
-sysd <file>              Specify SystemD service file (dfl: /etc/systemd/system/portworx.service)
-e key=value              Specify extra environment variables
-v <dir:dir[:shared,ro]>  Specify extra mounts
-d <ethX>                 Specify the data network interface
-m <ethX>                 Specify the management network interface
-z                        Instructs PX to run in zero storage mode
-f                        Instructs PX to use an unmounted drive even if it has a filesystem on it
-a                        Instructs PX to use any available, unused and unmounted drives
-A                        Instructs PX to use any available, unused and unmounted drives or partitions
-x <swarm|kubernetes>     Specify scheduler type (if PX running in scheduler environment)
-r <startport>            Start of the portrange Portworx will use for communication (dfl: 9001)
-marketplace_name         [OPTIONAL] pass in the marketplace name if installing via a 3rd party marketplace
KVDB options​
-userpwd <user:passwd>    Username and password for ETCD authentication
-ca <file>                Specify location of CA file for ETCD authentication
-cert <file>              Specify location of certificate for ETCD authentication
-key <file>               Specify location of certificate key for ETCD authentication
+internal-kvdb-options:
-kvdb_cluster_size <#>    Size of the internal kvdb cluster (dfl: 3)
-kvdb_recovery            Starts the nodes in kvdb recovery mode
Cluster domain options​
-cluster_domain <name>    Cluster Domain Name for this cluster
PX-API options​
# px-api-ssl-options:
-apirootca <file>         Specify self-signed root CA certificate file
-apicert <file>           Specify node certificate file
-apikey <file>            Specify node certificate key file
-apidisclientauth         Disable api client authentication
# px-authentication-options:
-oidc_issuer   <URL>          Location of OIDC service (e.g. https://accounts.google.com)
-oidc_client_id <id>          Client id provided by the OIDC
-oidc_custom_claim_namespace  OIDC namespace for custom claims
-jwt_issuer <val>             JSON Web Token issuer (e.g. openstorage.io)
-jwt_rsa_pubkey_file <file>   JSON Web Token RSA Public file path
-jwt_ecds_pubkey_file <file>  JSON Web Token ECDS Public file path
-username_claim <claim>       Claim key from the token to use as the unique id of the user (<claim> is sub, email or name; dfl: sub)
Volume options​
-disable-sharedv4         Disable sharedv4 volume support. When set, NFS dependencies will not be installed.
CSI options​
-csiversion <ver>         Specify which CSI version to use (<ver> is 1.0 or 0.3; dfl: 1.0)
secrets options​
-secret_type <type>       Specify the secrets type (<type> is aws-kms, dcos, docker, ibm-kp, k8s, kvdb, vault, gcloud-kms or azure-kv)
-cluster_secret_key <id>  Specify cluster-wide secret ID
Auto-scaling group options​
-max_drive_set_count <#>         Specify maximum number of drive sets PX can create
-max_storage_nodes_per_zone <#>  Specify the maximum number of storage nodes per zone in PX cluster
-node_pool_label <key>           Specify the scheduler node label key with which nodes are grouped into node pools
Resource control options​
--cpus <#.#>                  Specify maximum number of CPUs Portworx can use (e.g. --cpus=1.5)
--cpu-shares <#>              Specify CPU shares (relative weight)
--cpuset-cpus <val>           Specify CPUs in which to allow execution (<val> is range <#-#>, or sequence <#,#>)
--memory <bytes>              Specify maximum amount of memory Portworx can use
--memory-reservation <bytes>  Specify memory reservation soft limit (must be smaller than '--memory')
--memory-swap <bytes>         Specify maximum amount of RAM+SWAP memory Portworx can use
--memory-swappiness <0-100>   Specify percentage of container's anonymous pages host can swap out
Environment variables​
PX_HTTP_PROXY          If running behind an HTTP proxy, set the PX_HTTP_PROXY variables to your HTTP proxy.
PX_HTTPS_PROXY         If running behind an HTTPS proxy, set the PX_HTTPS_PROXY variables to your HTTPS proxy.
PX_ENABLE_CACHE_FLUSH  To enable cache flush daemon, set PX_ENABLE_CACHE_FLUSH=true.
note

You can set the environment variables using the -e option.

For example, to set the PX_ENABLE_CACHE_FLUSH environment variable to true, run the following command:

sudo /opt/pwx/bin/px-runc install -e PX_ENABLE_CACHE_FLUSH=yes \
    -c MY_CLUSTER_ID -k etcd://myetc.company.com:2379 -s /dev/xvdb

Examples​

Install Portworx using etcd:

px-runc install -k etcd://my.company.com:2379 -c MY_CLUSTER_ID -s /dev/sdc -s /dev/sdb2 {{ include.sched-flags }}
px-runc install -k etcd://X.X.X.65:2379 -c MY_CLUSTER_ID -s /dev/sdc -m eth1 -d eth2 {{ include.sched-flags }}

Modify the Portworx configuration​

After the initial installation, you can modify the Portworx configuration file at /etc/pwx/config.json. See the schema definition page for more details. Once you're done making changes to the Portworx configuration file, restart Portworx by running:

systemctl restart portworx

Step 3: Start Portworx runC​

Once you install the Portworx OCI bundle and systemd configuration from the steps above, you can control Portworx directly via systemd.

Below commands reload systemd configurations, enable and start the Portworx service.

sudo systemctl daemon-reload
sudo systemctl enable portworx
sudo systemctl start portworx

Upgrade the Portworx OCI bundle​

To upgrade the Portworx OCI bundle, simply re-run the first step from the installation process and pass the --upgrade flag to the docker run command.

The following commands upgrade your Portworx OCI bundle to the latest stable:

latest_stable=$(curl -fsSL "https://install.portworx.com?type=dock&stork=false&aut=false" | awk '/image: / {print $2}' | head -1)
sudo docker run --entrypoint /runc-entry-point.sh \
    --rm -i --privileged=true \
    -v /opt/pwx:/opt/pwx -v /etc/pwx:/etc/pwx \
    $latest_stable --upgrade
sudo systemctl restart portworx

Once the update process is finished, you must restart the Portworx service.

note

If you are installing Portworx on RedHat Linux or RedHat CoreOS with CRI-O container runtime, you don't have to install Docker in order to install Portworx. Instead, simply replace docker command with podman (e.g. sudo podman run --entrypoint...).

Uninstall the Portworx OCI bundle​

Run the following commands to uninstall the Portworx OCI bundle:

# 1: Remove systemd service (if any)
sudo systemctl stop portworx
sudo systemctl disable portworx
sudo rm -f /etc/systemd/system/portworx*

# NOTE: if the steps below fail, please reboot the node, and repeat the steps 2..5

# 2: Unmount oci (if required)
grep -q '/opt/pwx/oci /opt/pwx/oci' /proc/self/mountinfo && sudo umount /opt/pwx/oci

# 3: Remove binary files
sudo rm -fr /opt/pwx

# 4: [OPTIONAL] Remove configuration files. Doing this means UNRECOVERABLE DATA LOSS.
sudo chattr -ie /etc/pwx/.private.json
sudo rm -fr /etc/pwx

Logging and Log files​

The systemd software uses a flexible logging mechanism, where logs can be viewed using the journalctl command.

For example, the following commands fetch the logs starting from 09:00 until 1 hour ago:

# Monitor the Portworx logs
sudo journalctl -f -u portworx

# Get a slice of Portworx logs
sudo journalctl -u portworx --since 09:00 --until "1 hour ago"

If you prefer to capture Portworx service logs in a separate log file, you need to modify your host system as follows:

# Create a rsyslogd(8) rule to separate out the PX logs:
sudo cat > /etc/rsyslog.d/23-px-runc.conf << _EOF
:programname, isequal, "px-runc" /var/log/portworx.log
& stop
_EOF

# Create logrotate(8) configuration to periodically rotate the logs:
sudo cat > /etc/logrotate.d/portworx << _EOF
/var/log/portworx.log {
    daily
    rotate 7
    compress
    notifempty
    missingok
    postrotate
        /usr/bin/pkill -HUP syslogd 2> /dev/null || true
    endscript
}
_EOF

# Signal syslogd to reload the configurations:
sudo pkill -HUP syslogd
Last updated on