Introducing our new CEO Don Johnson - Read More

purestorage/docker-plugin

Verified Publisher

By Pure Storage

Updated over 4 years ago

See certified image at https://store.docker.com/plugins/pure-docker-volume-plugin

Plugin
Developer Tools
8

10K+

Docker Volume Plugin for Pure Storage FlashArray and FlashBlade.

Seamless integration of Docker containers and All Flash Storage. Run stateful applications using industry leading FlashArray and FlashBlade storage products.

Platform and Software Dependencies
  • Operating Systems Supported*:

    • CentOS 7
    • RedHat RHEL7
    • Ubuntu (Trusty 14.04 LTS, Xenial 16.04 LTS)
  • Environments Supported*:

    • Docker (v17.06 and above, newer version is recommended)
    • Swarm
    • Mesos 1.8 and above
  • Other software dependencies:

    • Latest linux multipath software package for your operating system (Required)
    • Latest iSCSI initiator software for your operating system (Optional, required for iSCSI connectivity)
    • Latest NFS software package for your operating system (Optional, required for NFS connectivity)
    • Latest FC initiator software for your operating system (Optional, requied for FC connectivity)
    • Latest Filesystem utilities/drivers (XFS by default, Required)
  • Supported Hardware:

    • Pure Storage FlashArray (minimum Purity code version 4.8)
    • Pure Storage FlashBlade (minimum Purity version 2.2.0)

* Please see release notes for details

Installation instructions

  • Pure.json and Backend management
    • The plugin manages all Pure backends that are advertised in a pure.json. A fleet of backends (more than one backend) can be managed by the plugin. The following is an example of a pure.json file that advertises two FlashArrays and a FlashBlade:

      (substitute values for the MgmtEndPoint, NFSEndPoint and APIToken fields with values specific to your FlashArray/FlashBlade installation)

        {
            "FlashArrays":[
                {
                    "MgmtEndPoint":"1.2.3.4",
                    "APIToken":"661f9687-0b1e-7b0d-e07d-1e776d50f9eb",
                    "Labels":{
                        "env": "production",
                        "rack": "1b"
                    }
                },
                {
                    "MgmtEndPoint":"5.6.7.8",
                    "APIToken":"661f9687-0b1e-7b0d-e07d-1e776d50f9eb",
                    "Labels":{
                        "env": "staging",
                        "rack": "2a"
                    }
                }
            ],
            "FlashBlades":[
                {
                    "MgmtEndPoint":"1.2.3.4",
                    "NFSEndPoint":"1.2.3.5",
                    "APIToken":"T-661f9687-0b1e-7b0d-e07d-1e776d50f9eb"
                }
            ]
        }
      
      • When provisioning a volume, a backend is automatically chosen based on the following criteria:

        • Capacity
        • Health
      • Labels can be used to filter the list of backends. Labels are arbitrary (key, value) pairs that can be added to any backend as seen in the example above. More than one backend can have the same (key, value) pair. When creating a new volume, label (key = value) pairs can be specified to filter the list of backends to a given set. The plugin also provides the following well known labels that can be used:

        • "purestorage.com/backend": Holds the value "file" for FlashBlades and "block" for FlashArrays.
        • "purestorage.com/hostname": Holds the host name of the backend.
        • "purestorage.com/id": Holds the ID of the backend.
        • "purestorage.com/family": Holds either "FlashArray" or "FlashBlade".

      See below for an example of how to use labels.

  • Manual install
    • Create and populate a configuration file /etc/pure-docker-plugin/pure.json as described above

    • Install the plugin by running this command :

      docker plugin install purestorage/docker-plugin:v3.10 --alias pure

    • Review (and grant access) to the permissions requested.

  • Automated install
    • Arrange to have /etc/pure-docker-plugin/pure.json to be created and deployed on all your docker nodes. The content of pure.json is as described above.

    • For a scripted install, you can agree to grant all permissions on the command line, like this

      docker plugin install purestorage/docker-plugin:v3.10 --alias pure --grant-all-permissions

Upgrades

Upgrading Managed Plugin Versions

Follow the instructions to upgrade here: https://docs.docker.com/engine/reference/commandline/plugin_upgrade/

Upgrading PURE's Docker Volume plugin from legacy mode to managed mode.

Starting with Docker v1.13, Docker supports enhanced plugin infrastructure. Details about this new managed plugin mode are here : https://docs.docker.com/engine/extend/ Docker versions 1.12 and below runs volume plugins in "legacy mode". If you are upgrading Docker in your environment, you might want to switch PURE's volume plugin from legacy mode to the new managed plugin mode.

Upgrade steps

Here are steps to do this upgrade :

  1. Shutdown docker
  2. Uninstall legacy plugin (run uninstall.sh from the PURE Docker volume plugin release package)
  3. Delete /run/docker/plugins/pure.sock socket file
  4. Upgrade docker (if needed) to ensure managed plugin support is available in docker
  5. Start docker
  6. Install managed plugin (see above)

Usage

A docker volume driver called “pure” is now available for use with all docker commands involving volumes. Examples :

  1. Create a volume

    docker volume create -—driver=pure -o size=32GB testvol1

  2. Create a volume filtering backends using labels (see the pure.json example above):

    • Using custom labels

      docker volume create --driver=pure -o size=32GB -o volume_label_selector='env=staging' stagingvol1
      
      docker volume create --driver=pure -o size=32GB -o volume_label_selector='rack=2a' rackvol1
      
    • Using well known lables

      docker volume create --driver=pure -o size=32GB -o volume_label_selector='purestorage.com/backend=file' bladevol1
      
      docker volume create --driver=pure -o size=32GB -o volume_label_selector='purestorage.com/hostname=hostname' testvol1
      
  3. Create a volume, import an existing volume (not created by the pure plugin) volume

    docker volume create --driver=pure --name testvol3 -o import_from_src=<original-volume-name>

  4. Create a volume, clone an existing pure volume

    docker volume create --driver=pure --name testvol3 -o source=<original-volume-name>

  5. Run a container and attach a volume

    docker run -ti -v testvol1:/data ubuntu:16.04 /bin/bash -i

  6. Run a container, create and attach a volume

    docker run -ti --volume-driver=pure -v testvol2:/data ubuntu:16.04 /bin/bash -i

Using the plugin in a container cluster (Mesos / Swarm)

In a cluster, it is required for all docker plugin installations to see all the cluster shared volumes from FlashArray and FlashBlade filesystems, so that the clustering software can mount any volume (FlashArray) or any filesystem (FlashBlade) on any node in the cluster. To get this behavior, set an environment variable for the plugin using the “docker plugin set” command.

docker plugin set pure PURE_DOCKER_NAMESPACE=<clusterid>

Here <clusterid> is a cluster-wide unique string that identifies your cluster from the rest of your infrastructure. To see the current value of this variable, you can run

docker plugin inspect --format "{{ .Settings.Env }}" pure

Configuration Options

NameDefaultDescription
PURE_DOCKER_NAMESPACECluster namespace to use for the plugin to operate in.
PURE_DEFAULT_SIZE32Value (in GiB) for volumes to be created if no size option is specified.
PURE_DISCOVERY_LOCAL_CONF/etc/pure-docker-plugin/pure.jsonPath to discovery config file.
PURE_FLASHARRAY_SAN_TYPEISCSIChange the FlashArray configuration for an initiator between ISCSI and FC
PURE_DEFAULT_BLOCK_FS_TYPExfsOverride the default filesystem for block devices provisioned. It is not recommended to change this
PURE_DEFAULT_BLOCK_FS_OPT-qOverride the default filesystem creation options (opts for mkfs). It is not recommended to change this
PURE_DEFAULT_BLOCK_MNT_OPTAdd custom mount options beyond defaults for the storage device. It is not recommended to change this
PURE_DEFAULT_ENABLE_FB_NFS_SNAPSHOTfalseSetting for enabling/disabling FlashBlade NFS snapshot feature
PURE_ISCSI_LOGIN_TIMEOUT20The iscsi login timeout in seconds
PURE_ISCSI_ALLOWED_CIDRS""The list of CIDR blocks allowed as the iscsi targets, e.g. 10.0.0.0/24,10.1.0.0/16. Use comma (,) as the separator, and empty string means allowing all addresses.
PURE_LOG_LEVEL"debug"The log level of the plugin. Can be one of debug, info, warn, error, fatal, or panic.

Other notes

  1. FlashArray volumes are limited to 64 characters. In clustered installations, due to the use of clusterid, volume names are limited to less than 64 characters.
  2. If your FlashArray or FlashBlade configuration changes, you can edit (or deploy) pure.json, the plugin will pick up any changes without requiring a plugin restart.
  3. If you want to use this docker plugin in a mesos environment, please refer to https://mesos.apache.org/documentation/latest/isolators/docker-volume. Use the right driver name (“pure”) when using the examples from this article. If using DVDI you will potentially need to use the "legacy" plugin installation. See README.legacy.md in the plugin package available in pure-docker-plugin-3.3.tar.gz
  4. The host running the plugin will need to have the correct mkfs.<type> utilities that correspond to the value of PURE_DEFAULT_BLOCK_FS_TYPE.
  5. For installation on DC/OS, please refer to https://docs.d2iq.com/mesosphere/dcos/2.0/storage/external-storage/#using-3rd-party-docker-volume-driver to set up the plugin socket properly by writing unix:///run/docker/plugins/<plugin-id>/pure.sock to file /etc/docker/plugins/pure.spec

Release Notes

v3.10

  • Fixed a bug that too many entries in findmnt result on hosts would cause docker log parsing failure and buffer overflow, which would cause docker plugin not starting properly.

3.9

  1. Added an argument to change the log level using docker plugin set [plugin name or ID] PURE_LOG_LEVEL=[level], where level is one of debug, info, warn, error, fatal, or panic.

3.8

  1. Fix deadlock issue in the logrus fireHook

3.7

  1. Fix the deadlock issue introduced by the third party logging package.
  2. Fixed an issue that crash the docker when docker tries to rm a volume.

3.6

  1. Reduced the call volume to REST APIs on FA and FB, especially when there is only one appliance in the fleet.
  2. Fixed an issue where the flexvol driver cleans up not-in-use multipath devices that are not managed by the driver.

3.5

Mitigated the known CVEs by removing the dependency on Alpine image.

3.4

Added the following configuration environment variables.

  • PURE_DEFAULT_ENABLE_FB_NFS_SNAPSHOT
  • PURE_ISCSI_LOGIN_TIMEOUT
  • PURE_ISCSI_ALLOWED_CIDRS

For example, to adjust the iscsi target login timeout to 10 seconds, you may run:

docker plugin set pure PURE_ISCSI_LOGIN_TIMEOUT=10

To only allow the docker plugin to use iscsi targets in particular subnets, you could run:

docker plugin set pure PURE_ISCSI_ALLOWED_CIDRS=10.1.2.0/24,10.2.0.0/16

See Configuration Options for details.

Known Vulnerabilities

3.3

Bug Fixes
  • Added FlashArray attachment sync step before Mount() to prevent issues with LUNs changing in the event of a preempted attachment previously.
  • Added delay before preempting attachments to help with close races
  • Added check to enforce safe attachments or fail the Mount() call
Known Issues
  • The plugin cannot go above 255 LUN's per initiator.

3.2

Features
  • Added ability to disable RWO volume attach preemption. The new setting will instead fail any additional mounts.
Bug Fixes
  • Fixed issue with "in use" multipath devices more gracefully, and attempt to flush the devices early in detach workflow.
Known Issues
  • Intermittent failures mounting XFS volumes on Ubuntu 16.04 using fibre channel

3.1

Features
  • Added ability to override default filesystem type and mount options. XFS is still the default and supported choice.
Known Issues
  • Intermittent failures mounting XFS volumes on Ubuntu 16.04 using fibre channel

3.0

Features
  • GA support for FlashBlade
  • Added "Fleet" management via Pure Service Orchestrator
    • Support multiple FlashArray, FlashBlade, or mixed environments
  • New options for volume creation
    • volume_label_selector -- Label selector for use with fleet of storage backends
    • source -- Source volume to clone from
  • Automatic XFS repair on mount
Bug Fixes
  • Fixed issue with invalid initiatorname.iscsi file format causing a crash
  • Fixed issue with XFS UUID conflicts on cloned volumes
  • Fixed issue with Docker version >=18.03.1 where volume mount fails when run as managed plugin
Known Issues
  • Intermittent failures mounting XFS volumes on Ubuntu 16.04 using fibre channel

Docker Pull Command

docker plugin install purestorage/docker-plugin