Skip to main content
Version: 3.1

Storage policy using pxctl

Overview​

This feature lets you manage the storage policies of the Portworx cluster. Once defined, a storage policy ensures that the volumes being created on the Portworx cluster follow the same set of specs/rules.

To learn about the available commands, type:

pxctl storage-policy --help
Manage storage policies for creating volumes

Usage:
  pxctl storage-policy [flags]
  pxctl storage-policy [command]

Aliases:
  storage-policy, stp

Examples:
pxctl storage-policy create --replication 2,min --periodic 60,10 devpolicy

Available Commands:
  access        Manage storage policy access by users or groups
  create        Create a storage policy
  delete        Delete a storage policy
  inspect       Inspect a storage policy.
  list          List all storage policies
  set-default   Set storage policy as default policy
  unset-default Remove default storage policy restriction
  update        Update a storage policy

Flags:
  -h, --help   help for storage-policy

Global Flags:
      --ca string            path to root certificate for ssl usage
      --cert string          path to client certificate for ssl usage
      --color                output with color coding
      --config string        config file (default is $HOME/.pxctl.yaml)
      --context string       context name that overrides the current auth context
  -j, --json                 output in json
      --key string           path to client key for ssl usage
      --output-type string   use "wide" to show more details
      --raw                  raw CLI output for instrumentation
      --ssl                  ssl enabled for portworx

Use "pxctl storage-policy [command] --help" for more information about a command.

Create a Storage Policy​

Say we want to create a storage policy named devpol with:

  • a minimum replication level of 2,
  • encryption enabled,
  • sticky bit on, and
  • periodic snapshot scheduled at 60 mins, with 10 keeps.

Then, you should run the following command:

pxctl storage-policy create devpol --replication 2,min --secure --sticky --periodic 60,10
note

To get more details on the available parameters, please refer to the Storage Policy Parameters Section.

Now, let's inspect the storage policy by typing:

pxctl storage-policy list
StoragePolicy   Description
devpol          HA="2,Minimum" Encrypted="true" Sticky="true"...
qapol           HA="2,Minimum" Encrypted="true" Sticky="true"...

Set the Default Storage Policy​

If a storage policy is set as the default one, all volumes created afterward will follow the parameters defined by the said storage policy.

Here is how to set devpol as the default storage policy in your Portworx cluster:

pxctl storage-policy set-default devpol
Storage Policy *devpol* is set to default

Now, let's list the storage policies again:

pxctl storage-policy list
StoragePolicy   Description
*devpol         Encrypted="true" Sticky="true" SnapInterval="periodic 1h0m0s,keep last 10"...
qapol           HA="2,Minimum" Encrypted="true" Sticky="true"...

Notice the * in front of devpol? It means that devpol has been set as the default storage policy.

Let's say you don't remember the settings of the devpol storage policy. If so, pxctl provides an easy way to refresh your memory:

pxctl storage-policy inspect devpol
Storage Policy  :  devpol
    Default                   : Yes
    HA                        : 2,Minimum
    Encrypted                 : true
    Sticky                    : true
    SnapInterval              : periodic 1h0m0s,keep last 10

Now that we've created a storage policy and set it as the default one, let's move forward and try to create a volume with an HA level lower than the one specified in the default storage policy:

pxctl volume create polvol --repl 1 --size 10
Volume successfully created: 745102698654969688

Lastly, we would want to check the settings of the new volume:

pxctl volume inspect polvol
Volume  :  745102698654969688
    Name                 :  polvol
    Size                 :  10 GiB
    Format               :  ext4
    HA                   :  2
    IO Priority          :  LOW
    Creation time        :  Feb 13 16:41:49 UTC 2019
    Snapshot             :  periodic 1h0m0s,keep last 10
    Shared               :  no
    Status               :  up
    State                :  detached
    Attributes           :  encrypted,sticky
    Reads                :  0
    Reads MS             :  0
    Bytes Read           :  0
    Writes               :  0
    Writes MS            :  0
    Bytes Written        :  0
    IOs in progress      :  0
    Bytes used           :  131 MiB
    Replica sets on nodes:
        Set 0
          Node       : X.X.X.116 (Pool 0)
          Node       : X.X.X.114 (Pool 0)
    Replication Status   :  Detached

As expected, the volume was being created with the properties inherited from the devpol policy:

  • HA is equal to 2,
  • periodic snapshots scheduled every 60 mins, with 10 keeps

Remove the Default Storage Policy​

To remove the default storage policy from a Portworx cluster use: pxctl storage-policy unset-default

Let's look at an example.

Suppose devpol was initially set as the default storage policy:

pxctl storage-policy list
StoragePolicy   Description
*devpol         Encrypted="true" Sticky="true" SnapInterval="periodic 1h0m0s,keep last 10"...
qapol           HA="2,Minimum" Encrypted="true" Sticky="true"...

We can remove the default storage policy like so:

pxctl storage-policy unset-default qapol
Default storage policy restriction is removed

To check whether the policy is disabled type:

pxctl storage-policy list
devpol          Encrypted="true" Sticky="true" SnapInterval="periodic 1h0m0s,keep last 10"...
qapol           HA="2,Minimum" Encrypted="true" Sticky="true"...

Can't recall the settings for devpol? Here's how to refresh your memory:

pxctl storage-policy inspect devpol
Storage Policy  :  devpol
    Default                  :  No
    HA                       :  Minimum 2
    Encrypted                :  true
    Sticky                   :  true
    Snapshot             :  periodic 1h0m0s,keep last 10

The following creates a volume with a replication level lower than the one specified in devpol:

pxctl volume create nonpol --size 10 --repl 1
Volume successfully created: 880058853866312532

So, we've created a new volume. Go ahead and inspect its settings:

pxctl volume inspect nonpol
Volume  :  880058853866312532
    Name                 :  nonpol
    Size                 :  10 GiB
    Format               :  ext4
    HA                   :  1
    IO Priority          :  LOW
    Creation time        :  Feb 13 16:51:16 UTC 2019
    Shared               :  no
    Status               :  up
    State                :  detached
    Reads                :  0
    Reads MS             :  0
    Bytes Read           :  0
    Writes               :  0
    Writes MS            :  0
    Bytes Written        :  0
    IOs in progress      :  0
    Bytes used           :  2.6 MiB
    Replica sets on nodes:
        Set 0
          Node       : X.X.X.116 (Pool 0)
    Replication Status   :  Detached

As you can see, the replication level is now set to 1.

Update a Storage Policy​

pxctl lets you update the parameters of an existing storage policy.

Say you want to update qapol and make it so that the current replication parameters (2,Equal) become (1,min).

First, let's list our storage policies:

pxctl storage-policy list
StoragePolicy Description
prodpol       IOProfile="IO_PROFILE_CMS" SnapInterval="policy=snapSched" HA="2,Equal"...
qapol         SnapInterval="policy=weekpol" HA="2,Minimum" Sticky="true"...

Then, here's how to update the replication parameter for qapol:

pxctl storage-policy update qapol --replication 1,min

Lastly, we would want to check if the parameter has been updated:

pxctl storage-policy list
StoragePolicy Description
prodpol       HA="2,Equal" Encrypted="true" Sticky="true"...
qapol         HA="1,Minimum" Sticky="true" SnapInterval="policy=weekpol"...

If the storage policy which is being updated is already set as default , all volumes created thereafter will follow the updated policy specs.

Again, we are going to walk you through an example.

Start by listing existing storage policies:

pxctl storage-policy list
StoragePolicy Description
prodpol       Sticky="true" IOProfile="IO_PROFILE_CMS" SnapInterval="policy=snapSched"...
*qapol        HA="1,Minimum" Sticky="true" SnapInterval="policy=weekpol"...

The above shows that qapol is the default policy. Let's get more details:

pxctl storage-policy inspect qapol
Storage Policy : qapol
    Default         : Yes
    HA              : 1,Minimum
    Sticky          : true
    SnapInterval    : policy=weekpol

Now, we would want to update its parameters:

pxctl storage-policy update qapol --policy snapSched

The following checks if the parameters were successfully updated:

pxctl storage-policy inspect qapol
Storage Policy : qapol
        Default         : Yes
        HA              : 1,Minimum
        Sticky          : true
        SnapInterval    : policy=snapSched

Let's create a new volume. It will have snapSched as snapshot policy attached:

pxctl volume create updatedqapol --size 10
Volume successfully created: 1131539442993682535

Lastly, we would want to inspect the settings of the new volume like so:

pxctl volume inspect updatedqapol
Volume  :  1131539442993682535
    Name                 :  updatedqapol
    Size                 :  10 GiB
    Format               :  ext4
    HA                   :  1
    IO Priority          :  LOW
    Creation time        :  Feb 19 17:06:53 UTC 2019
    Snapshot             :  policy=snapSched
    Shared               :  no
    Status               :  up
    State                :  detached
    Attributes           :  sticky
    Reads                :  0
    Reads MS             :  0
    Bytes Read           :  0
    Writes               :  0
    Writes MS            :  0
    Bytes Written        :  0
    IOs in progress      :  0
    Bytes used           :  2.6 MiB
    Replica sets on nodes:
        Set 0
          Node       : X.X.X.114 (Pool 0)
    Replication Status   :  Detached

Delete a Storage Policy​

Use pxctl storage-policy delete policyname to delete storage policy:

pxctl storage-policy delete  devpol
Storage Policy devpol is deleted

If you need to delete the default policy, then the --force flag is required.

pxctl storage-policy delete qapol --force
Storage Policy qapol is deleted
note

Deleting the default storage policy will remove the volume creation restrictions specified by the policy.

Creating Volumes by Specifying a Storage Policy​

When you create a new volume, pxctl allows you to specify the storage policy that will be applied to the volume.

Let's see how it works.

Create a new policy like this:

pxctl storage-policy create testpol --replication 2,min --sticky --weekly sunday@08:30,8

List storage policies:

pxctl storage-policy list
StoragePolicy   Description
testpol         HA="2,Minimum" Sticky="true" SnapInterval="weekly Sunday@08:30,keep last 8"...

Inspect testpol:

pxctl storage-policy inspect testpol
Storage Policy  :  testpol
    Default                  :  No
    Sticky                    : true
    SnapInterval              : weekly Sunday@08:30,keep last 8
    HA                        : 2,Minimum

Now, let's create a volume named customvol using testpol:

pxctl volume create customvol --size 10 --storagepolicy testpol
Volume successfully created: 492212712402729915

Lastly, let's check customvol's settings:

pxctl volume inspect customvol
Volume  :  492212712402729915
    Name                 :  customvol
    Size                 :  10 GiB
    Format               :  ext4
    HA                   :  2
    IO Priority          :  LOW
    Creation time        :  Feb 19 17:34:08 UTC 2019
    Snapshot             :  weekly Sunday@08:30,keep last 8
    StoragePolicy        :  testpol
    Shared               :  no
    Status               :  up
    State                :  detached
    Attributes           :  sticky
    Reads                :  0
    Reads MS             :  0
    Bytes Read           :  0
    Writes               :  0
    Writes MS            :  0
    Bytes Written        :  0
    IOs in progress      :  0
    Bytes used           :  2.6 MiB
    Replica sets on nodes:
        Set 0
          Node       : X.X.X.114 (Pool 0)
          Node       : X.X.X.110 (Pool 0)
    Replication Status   :  Detached
note
  • Specs such as replication 2 , snapshot policy weekly Sunday@08:30,keep last 8 and sticky are applied to the new volume
  • Specifying a custom policy will override the default storage policy (if any)

Storage Policy Parameters​

Enter the pxctl storage policy create --help command displays the available flags:

pxctl storage policy create --help
Create a storage policy

Usage:
  pxctl storage-policy create [flags]

Aliases:
  create, c

Examples:
pxctl storage-policy create [flags] policy-name

Flags:
  -a, --aggregation_level string   aggregation level (Valid Values: [1 2 3 auto]) (default "1")
  -d, --daily hh:mm,k              daily snapshot at specified hh:mm,k (keeps 7 by default)
      --force                      Force volume creation to fail if storage policy rules not followed by volume
  -h, --help                       help for create
      --io_profile string          IO Profile (Valid Values: [sequential cms db]) (default "sequential")
      --journal                    Journal data for volume
  -m, --monthly day@hh:mm,k        monthly snapshot at specified day@hh:mm,k (keeps 12 by default)
  -p, --periodic mins,k            periodic snapshot interval in mins,k (keeps 5 by default), 0 disables all schedule snapshots
      --policy string              policy names separated by comma
  -r, --replication repl,max/min   replication factor repl,max/min (replication is equal by default)
      --secure                     encrypt volumes using AES-256
      --shared                     make a globally shared namespace volumes
      --sticky                     sticky volumes cannot be deleted until the flag is disabled
      --update                     Allow volume to update without storage policy restriction
  -w, --weekly weekday@hh:mm,k     weekly snapshot at specified weekday@hh:mm,k (keeps 5 by default)

Global Flags:
      --ca string            path to root certificate for ssl usage
      --cert string          path to client certificate for ssl usage
      --color                output with color coding
      --config string        config file (default is $HOME/.pxctl.yaml)
      --context string       context name that overrides the current auth context
  -j, --json                 output in json
      --key string           path to client key for ssl usage
      --output-type string   use "wide" to show more details
      --raw                  raw CLI output for instrumentation
      --ssl                  ssl enabled for portworx

Note that you can specify min, max or equal replication while creating a storage policy.

Example:

1) replication 2,min

If storage policy created with replication 2, min flag. Volume created will be ensured to have replication level at least 2

2) replication 2,max

If storage policy creates with replication 2, flag. Volume created will be ensured to have maximum replication specified 2

3) replication 2

If storage policy is created with replication 2, Volume created will have exact replication level 2

Storage policy access control​

Storage policies also can have restricted access for specific collaborators and groups. The following commands allow you to update groups and collaborators per storage policy:

pxctl storage-policy access add
pxctl storage-policy access remove
pxctl storage-policy access show
pxctl storage-policy access update

Storage policy access types​

When adding or updating storage policy ACLs, you can provide the following access types:

  • Read (default): User or group can use the storage policy
  • Write: User or group can bypass the storage-policy or update it.
  • Admin: Can delete the storage-policy (with RBAC access to the StoragePolicy service APIs)

Let's look at a few simple examples:

pxctl storage-policy access add devpol --group group1:w
pxctl storage-policy access add devpol --collaborator collaborator1:a
pxctl storage-policy access add devpol --collaborator collaborator2:r

Here's what will happen once the above commands get executed:

  • group1 will have Write access
  • collaborator1 will have Admin access
  • collaborator2 will have Read access

Storage policy access update​

The update subcommand for storage policies will set the ACLs for that given storage policy. All previous ACLs will be overwritten.

For example, you can update a storage policy to be owned by a single owner named user1:

pxctl storage-policy access update devpol --owner user1

Or, you can provide a series of collaborators with access to that storage-policy:

pxctl storage-policy access update devpol --collaborators user1,user2,user3

Lastly, you can update a storage-policy to be accessible by a series of groups:

pxctl storage-policy access update devpol --groups group1,group2
note

This command will update all ACLs for a storage-policy. That is if you have given access to a series of groups, but do not provide the same groups the next update, those groups will no longer have access.

To add/remove single groups/collaborators to have access, try using pxctl storage-policy access add/remove.

Storage policy access show​

To see the ACLs for a given storage-policy, you can use pxctl storage-policy access show as follows:

pxctl storage-policy access show devpol
Storage Policy:  devpol
Ownership:
  Owner:  collaborator1
  Acls:
    Groups:
      group1         Read
      group2         Read

Storage policy access add/remove​

To remove or add a single collaborator or group access, you can do so with:

pxctl storage-policy access add devpol --collaborator user:w

or

pxctl storage-policy access remove devpol --group group1
Last updated on
Was this page helpful?