6. Managing Persistent Data Volumes

A Persistent Data Volume (PDV) in Robin is a volume that persists even after an application is deleted from the cluster. A PDV is derived from the persistent storage volume(PV).

A PDV provides tenant users a private volume just like a personal home folder in a file server environment. If a tenant user deletes an app, the PDV still persists. Users can access the PDV from different apps and save data of different apps in the PDV. By default, A tenant user can have a single PDV. However, if required, a particular user can create more than one PDV. Users can increase the size of the PDV when required.

A tenant administrator can allocate a PDV for each tenant user. A PDV consists of a file system with directories and data files required for application deployment.

The PDVs can be mounted to multiple applications as read-only or read/write volumes. However, the PDV is not bound to any specific application.

A PDV persists until it is manually deleted.

Note

The PDV cannot be used across multiple namespaces.

6.1. Types of Persistent Data Volumes

Robin provides two types of persistent Data Volumes:

  • Private - PDVs are intended for exclusive use by the PDVs owner.Tenant users can only see the PDVs owned by them.

  • Public - Cluster or tenant admins can only create a Public PDV and the admins can share Public PDVs with specific tenant users or all tenant users.

6.2. Considerations for Using Persistent Data Volumes

  • Each PDV is bound to a single tenant and tenant user (the PDVs owner).

  • A PDV can only be bound to a single namespace.

  • For tenant users to access a shared PDV, the users must be provided access to the namespace the PDV is bound to.

  • A Private PDV ownership can be assigned or reassigned to any other users in the tenant that it is bound to.

  • A Public PDV ownership can be assigned or reassigned to a user with the tenant administrator rights.

  • Tenant users can only view PDVs they own or that have been shared with them.

  • By default, users with shared access to PDVs have the view permission. Additional permissions can be provided as needed.

  • Tenant admins can view all PDVs that are bound to their tenant.Cluster admins can view all PDVs allocated in the cluster.

Topics covered in this chapter:

robin pdv add

Add a Public or Private Persistent Data Volume (PDV)

robin pdv list

Displays list Persistent Data Volumes (PDV)

robin pdv resize

Resize a Persistent Data Volume (PDV)

robin pdv share

Share a Persistent Data Volume (PDV) with one or more users

robin pdv share-options

List valid operations when sharing a Persistent Data Volume (PDV) with one or more tenant users

robin pdv list-shares

List Persistent Data Volume (PDV) shares showing which users have been extended access to specific PDVs for particular operations

robin pdv unshare

Stop sharing a Persistent Data Volume (PDV) with one or more users

robin pdv change-owner

Change the owner of a Persistent Data Volume (PDV)

robin pdv remove

Remove a Persistent Data Volume (PDV)

6.3. Add a Persistent Data Volume

Robin enables to create a Public and Private PDV types. Only a cluster or tenant admins can create the Public PDV and the admins can share it with multiple tenant users or specific users. Tenant users can create the Private PDV. Tenant users can only see the PDVs owned by them. Robin automatically assigns a name for the PDV. The PDV name is prefixed with the word pdv followed by a UID. You can also provide a custom name by using the --name <name> option. The name of PDVs is uniqe within the cluster.

When you provide a custom name, Robin does not allow you to create a PDV with the same name that might exists in a different namespace.

Note

By default, you can add only one private PDV for a user in a given tenant. Use the --force flag to override this restriction and create more PDVs.

The default media type is HDD. If you have SSDs, you must explicitly speficy media type as SSD when adding PDVs.

Note

All tenant users can create Private PDVs and tenant admins can create both.

To create a Private or Public PDV, run the following command:

Prerequisites:

  • A namespace is already created.

# robin pdv add <namespace> <size> <replication>
                                   --faultdomain <faultdomain>
                                   --media <media>
                                   --rpool <rpool>
                                   --name <name>
                                   --users <users>
                                   --force
                                   --public
                                   --all-tenant-users

namespace

Name of the namespace to bound with the underlying PVC

size

Size of the PDV to be created. Can be specified as total bytes or a human readable format, such as ‘1GB’. Note it must be divisible by 1GB

replication

The replication factor for the PDV. Valid values include 1, 2 or 3. The default is 1.

--faultdomain <faultdomain>

Fault domain for replicas. Valid values include disk, host or rack. Note this option is only valid when the replication factor is greater than 1

--media <media>

Specify which type of drives to allocate storage from. Valid values include HDD and SSD. The default media type is HDD

--rpool <rpool>

Name of the resource pool from which to allocate

--name <name>

Custom PDV name. The default format is pdv-<UUID>

--users <users>

Comma separated list of usernames to create a PDV for

--force

Override any operation restrictions

--public

Make the PDV public, so it can be shared with other tenant users. The default is to make the PDV private for a given user

--all-tenant-users

Add a PDV for all tenant users for specified namespace

Example:

# robin pdv add t001-u000004 1GB 1 --wait
Job:  331 Name: PersistentDataVolumeAdd  State: VALIDATED       Error: 0
Job:  331 Name: PersistentDataVolumeAdd  State: WAITING         Error: 0
Job:  331 Name: PersistentDataVolumeAdd  State: COMPLETED       Error: 0

Creates a public or private PDV such that it can be used by application pods.

End Point: /api/v3/robin_server/pdvs

Method: POST

URL Parameters: None

Data Parameters:

  • namespace: <namespace> - This mandatory field within the payload specifies the name of the namespace which the PDV should be bound to.

  • size: <size> - This mandatory field within the payload specifies the size of the PDV to be created. It should be specified either as integer representing the total number of bytes or as a string in a human readable format such as ‘1GB’. Note the size must be divisible by 1GB.

  • replication: <replication> - This mandatory field within the payload specifies the replication factor of the PDV and results in the specified number of replicas being spawned. Valid values include 1, 2 or 3.

  • faultdomain: <faultdomain> - Utilizing this parameter within the payload results in the replicas of the PDV being distributed over the specified faultdomain. Valid values include disk, host or rack. Note this field is only valid when the replication factor is greater than 1.

  • media: <media> - Utilizing this parameter within the payload results in the storage for the PDV being allocated from the drives of the specified type. Valid values include HDD and SSD.

  • rpool: <rpool> - Utilizing this parameter within the payload results in the storage for the PDV being allocated from the specified resource pool.

  • name: <name> - Utilizing this parameter within the payload results in the name of the PDV being set to the string specified.

  • user_list: <user_list> - Utilizing this parameter within the payload, by specifiying a comma seperated list of usernames, results in the PDV being associated with the respective users.

  • all_tenant_users: true - Utilizing this parameter within the payload results in the PDV being associated with tenant all users of the specified namespace. The default value is false. Note this field overrides any users passed via the user_list parameter.

  • private: false - Utilizing this parameter within the payload results in a public PDV being created. The default value is true.

  • force: true - Utilizing this parameter within the payload results in all operation restrictions being overriden. The default value is false.

Port: RCM Port (default value is 29442)

Headers:

  • Authorization: <auth_token> : Authorization token to identify which user is sending the request. The token can be acquired from the login API.

Success Response Code: 202

Error Response Code: 500 (Internal Server Error), 401 (Unauthorized Error), 400 (Invalid API Usage Error), 409 (Duplicate Resource Error)

Example Response:

Output
{
   "jobid":38
}

6.4. List Persistent Data Volumes

The PDV list displays the following details:

  • Name of the PDV

  • Owner and tenant of the PDV

  • Type of the PDV - Private or Public

  • Size of PDVs

  • Media on which the PDV exists

  • Mapped PV and PVC

You can use different filtering options to view desired details. The list command displays only the PDVs owned a tenant user shared

To view list of PDVs, run the following command:

# robin pdv list [<name>]
                 --username <username>
                 --namespace <namespace>
                 --tenant <tenant>
                 --page_size <size>
                 --page <page>
                 --private
                 --public
                 --all-records

name

Name of a Physical Data Volume to filter by. Note this parameter is optional.

`--username <username>

Filter by user.

--namespace <namespace>

Filter by namespace.

--tenant <tenant>

Filter by tenant.

--page-size <size>

Displays provided number of PDVs for each page.

--page <page>

Displays page number (starting index 1).

--all-records

List all PDVs without pagination.

--private

Display only user private PDVs.

--public

Display only user public PDVs.

Example:

# robin pdv list

Name                                     | Owner/Tenant         | Access  | Size | Media | PV                                       | PVC
-----------------------------------------+----------------------+---------+------+-------+------------------------------------------+-------------------------------------
pdv-t1-ns1                               | admin1/t1            | Public  | 10G  | HDD   | pvc-92fb0e2f-e8f3-4818-9fcf-675f84957c98 | t1-ns1/pvc-2-11-16323303197922
pdv-t1-ns1-16323314360136                | user1/t1             | Private | 1G   | HDD   | pvc-32875a1e-23e6-4bdf-80d0-525f65ae8dbf | t1-ns1/pvc-2-11-16323314360593
pdv-t1-ns1-16323314361605                | user2/t1             | Private | 1G   | HDD   | pvc-8ae9f1de-0fe3-451c-b571-937fe9a74394 | t1-ns1/pvc-2-11-16323314362139
pdv-t1-ns1-16323314358497                | admin1/t1            | Private | 1G   | HDD   | pvc-3c44bdf0-4ab0-4d96-8bd0-94182e91d8bc | t1-ns1/pvc-2-11-16323314359163
pdv-t1-ns2-16324486391571                | t1u1/t1              | Private | 1G   | HDD   | pvc-08de738e-acd8-4761-a3c7-fa9358720d72 | t1-ns2/pvc-2-13-16324486392167
pdv-t1-ns2-16324486386595                | admin1/t1            | Private | 1G   | HDD   | pvc-b097b653-0091-4774-95a3-35de4bf408f0 | t1-ns2/pvc-2-13-16324486387381
pdv-t1-ns2-16324486388421                | user1/t1             | Private | 1G   | HDD   | pvc-194d5ceb-f528-4a14-af3a-f3fc2e5033db | t1-ns2/pvc-2-13-16324486389026
pdv-t1-ns2-16324486389915                | user2/t1             | Private | 1G   | HDD   | pvc-86316408-77f6-4436-8a35-12fb4479484a | t1-ns2/pvc-2-13-16324486390637
pdv-t1-ns2-16324487358204                | user1/t1             | Private | 1G   | HDD   | pvc-a78d4f3f-d8be-4f5a-88f3-5e7357ade992 | t1-ns2/pvc-2-13-16324487358844
pdv-t1-ns2-16324487359761                | user2/t1             | Private | 1G   | HDD   | pvc-8ee97e30-374d-4fbe-bd8f-140e7d887b35 | t1-ns2/pvc-2-13-16324487360418
pdv-t1-ns2-16324487361146                | t1u1/t1              | Private | 1G   | HDD   | pvc-9dcd16ba-28f7-4f60-8eea-e802a81fc937 | t1-ns2/pvc-2-13-16324487361904
pdv-t1-ns2-16324487356366                | admin1/t1            | Private | 1G   | HDD   | pvc-bdd5ee1e-f7f5-4e3e-9fd2-fa513e4f4d34 | t1-ns2/pvc-2-13-16324487357133
pdv-t1-ns2                               | admin1/t1            | Public  | 1G   | HDD   | pvc-6ad4aafc-1e0f-4c06-93ab-4084e9201820 | t1-ns2/pvc-2-13-16324488710927
t1-ns1                                   | user2/t1             | Private | 1G   | HDD   | pvc-896277c2-e826-4b2f-a398-37c5f5f1a5b6 | t1-ns1/pvc-2-11-16330168070648
t1-ns1-b                                 | user2/t1             | Private | 1G   | HDD   | pvc-aa67ea36-ca5e-4904-a945-75c180126b11 | t1-ns1/pvc-2-11-16330177827135
pdv1-test                                | admin1/t1            | Public  | 1G   | HDD   | pvc-d19ba495-1c89-442d-b0cd-2c0b0a45231d | t002-u000005/pvc-2-5-16330498622676
pdv-b8947314-74b9-451b-98dd-7090ea5f368b | robin/Administrators | Private | 1G   | HDD   | pvc-e22afeb8-ea11-4e8b-b519-1a5ed78d8286 | t001-u000004/pvc-1-4-16331264021687

Returns information on all PDVs managed by the Robin cluster including details on the owner (and associated tenant), size, type and the respective PVC.

End Point: /api/v3/robin_server/pdvs

Method: GET

URL Parameters: None

Data Parameters:

  • private: [true|false] - Utilizing this parameter within the payload results in the list of PDVs returned being filtered by their type. The default value is None and results in PDVs being returned regardless of their type.

  • page_size: <size> - Utilizing this parameter within the payload results in <size> number of PDVs being returned.

  • page_num: <index> - Utilizing this parameter within the payload results in PDVs starting from <index> being returned.

  • tenant: <tenant> - Utilizing this parameter within the payload results in the list of PDVs returned being filtered by the tenant specified.

  • username: <username> - Utilizing this parameter within the payload results in the list of PDVs returned being filtered by the user specified.

  • namespace: <namespace> - Utilizing this parameter within the payload results in the list of PDVs returned being filtered by the namespace specified.

Port: RCM Port (default value is 29442)

Headers:

  • Authorization: <auth_token> : Authorization token to identify which user is sending the request. The token can be acquired from the login API.

Success Response Code: 200

Error Response Code: 500 (Internal Server Error), 401 (Unauthorized Error), 400 (Invalid API Usage Error)

Example Response:

Output
{
   "object_type":"PersistentDataVolume",
   "start":1,
   "count":20,
   "total":1,
   "page_size":20,
   "page_num":1,
   "items":[
      {
         "id":1,
         "name":"pdv-c2474073-f7b2-4dc7-9f5e-322f7e7dd5e4",
         "private":true,
         "user_id":4,
         "username":"robin",
         "tenant_id":1,
         "tenant":"Administrators",
         "volume_id":1,
         "volume":"pvc-427e79bc-ab2d-4a7b-99cf-83fc45e2f6ef",
         "volume_size":5368709120,
         "volume_media":"HDD",
         "pdv_volumes":[
            {
               "pv_name":"pvc-427e79bc-ab2d-4a7b-99cf-83fc45e2f6ef",
               "pvc_name":"pvc-1-4-16335381444801",
               "namespace":"t001-u000004"
            }
         ],
         "instances":[

         ]
      }
   ]
}

6.5. Resize a Persistent Data Volume

To resize a PDV via Robin, issue the following command:

# robin pdv resize <name> <size>

name

Name of the PDV

size

The new size of the PDV. Can be specified as total bytes or a human readable format, such as ‘1GB’. Note the size specified must be divisible by 1GB

Note

A PDV cannot be descreased in size.

Example:

# robin pdv resize pdv-b8947314-74b9-451b-98dd-7090ea5f368b 2G
PersistentDataVolume 'pdv-b8947314-74b9-451b-98dd-7090ea5f368b' was successfully increased in size

Resizes a PDV to the desired size. Note a PDV cannot be decreased in size.

End Point: /api/v3/robin_server/pdvs/<name>

Method: PUT

URL Parameters: None

Data Parameters:

  • action: resize - This mandatory field within the payload specifies the resize operation is to be performed.

  • name: <name> - This mandatory field within the payload specifies the name of the PDV to be resized.

  • size: <size> - This mandatory field within the payload specifies the new size of the PDV. It should be specified either as integer representing the total number of bytes or as a string in a human readable format such as ‘1GB’. Note the size must be divisible by 1GB.

Port: RCM Port (default value is 29442)

Headers:

  • Authorization: <auth_token> : Authorization token to identify which user is sending the request. The token can be acquired from the login API.

Success Response Code: 200

Error Response Code: 500 (Internal Server Error), 401 (Unauthorized Error), 400 (Invalid API Usage Error), 404 (Not Found Error)

Example Response:

Output
{
   "message":"PersistentDataVolume 'pdv-c2474073-f7b2-4dc7-9f5e-322f7e7dd5e4' was successfully increased in size"
}

6.6. Persistent Data Volume Share Options

In order to view the List valid operations that can be specified when sharing a PDV, run the following command:

# robin pdv share-options --json

--json

Output in JSON

Example:

# robin pdv share-options
+------------------------+------------+-----------+
| Object Type            | Share Type | Operation |
+------------------------+------------+-----------+
| PERSISTENT_DATA_VOLUME | USER       | view      |
| PERSISTENT_DATA_VOLUME | USER       | update    |
+------------------------+------------+-----------+

6.7. Share a Persistent Data Volume

PDV access can be shared among users. You can only share a public type PDV. You can share the PDV only with users within the tenant.

Note

When you share a PDV with users within a tenant, the same users must also have access to the namespace in which the PDV exists.

# robin pdv share <pdv_name> [<user_list>]
                             --operations <operations>
                             --all-tenant-users
                             --force

pdv_name

Name of the PDV to share.

user_list

An optional comma separated list of users to share the PDV with. If the PDV has already been share and the all_tenant_users flag has been set, then no action will be taken.

--operations <operations>

Comma separated list of operations the users will be allowed to perform on the shared PDV. To allow all valid operations to be performed, enter ‘ALL_OPERATIONS’ on the command line (default value is ‘view’)

--all-tenant-users

Set the all_tenant_users flag to share the PDV with all tenant users.

--force

Allow a user’s primary PDV to be shared.

Example:

# robin pdv share pdv-t1-ns1 user1
PersistentDataVolume 'pdv-t1-ns1' has been shared with the following users: user1

6.8. List Shared Persistent Data Volume Shares

You can view the list of shared PDVs within a tenant. You can view the list of shared PDVs for all users and for a single or a list of users.

# robin pdv list-shares [<username>]

username

The username of the user to show PDV shares for. If username is not provided, then shows PDV shares for all users.

Example 1 (Display list of PDV shares for one user):

# robin pdv list-shares user1
PDV Id | PDV Name   | Operation | Users
-------+------------+-----------+------------------
1      | pdv-t1-ns1 | view      | user1,user2,t1u1
13     | pdv-t1-ns2 | view      | user1

Example 2 (Display all PDV shares):

# robin pdv list-shares
PDV Id | PDV Name   | Operation | Users
-------+------------+-----------+------------------
1      | pdv-t1-ns1 | view      | user1,user2,t1u1
13     | pdv-t1-ns2 | view      | user1
17     | pdv1-test  | view      |
17     | pdv1-test  | update    |

6.9. Unshare a Persistent Data Volume

You can unshare a shared PDV with a single user, list of users, or all users.

# robin pdv unshare <pdv_name> [<user_list>]
                               --operations <operations>
                               --all-tenant-users

pdv_name

Persistent Data Volume (PDV) name.

user_list

Optional comma separated list of users to stop sharing a PDV with.

--operations <operations>

Comma separated list of operations users will no longer be allowed toperform on the shared PDV. If no operations are specified, then sharing of the PDV with the specified users will be stopped.

--all-tenant-users

Stop sharing the PDV with all tenant users.

Example

robin pdv unshare pdv-t1-ns1 user1
PersistentDataVolume 'pdv-t1-ns1' is no longer shared with the following users: user1

6.10. Change Ownership of a Shared Persistent Data Volume

You can change the ownership of a Private PDV from one user to a different user. You cannot change the ownership of a Public PDV.

# robin pdv change-owner <pdv_name> <username>
                                    --force

pdv_name

Name of the PDV.

username

The username of the new user

--force

Allow ownership change of a user’s primary PDV

Example

# robin pdv change-owner t1-ns1 demo-user --wait
Job:  331 Name: PDVChangeOwner  State: VALIDATED       Error: 0
Job:  331 Name: PDVChangeOwner  State: WAITING         Error: 0
Job:  331 Name: PDVChangeOwner  State: COMPLETED       Error: 0

6.11. Delete a Persistent Data Volume

You can run the command robin pdv list to view the PDVs and select the desired PDVs to delete. There might be a need for you to delete PDVs when deleting users. You can delete multiple PDVs at a time by providing a comma-separated list.

To delete a PDV, run the following command:

# robin pdv remove <names>
                   --force
                   --yes

names

A comma seperated list of PDVs to remove.

--force

Force removal of any user shares.

--yes

Do not prompt the user for confirmation.

Example

# robin pdv remove t1-ns1 --yes --wait
Job:  337 Name: PersistentDataVolumeRemove  State: VALIDATED       Error: 0
Job:  337 Name: PersistentDataVolumeRemove  State: WAITING         Error: 0
Job:  337 Name: PersistentDataVolumeRemove  State: COMPLETED       Error: 0

Deletes a PDV.

End Point: /api/v3/robin_server/pdvs

Method: DELETE

URL Parameters: None

Data Parameters:

  • name: <name> - This mandatory field within the payload specifies the name of the PDV to be deleted.

  • force: true - Utilizing this parameter within the payload results in all user shares of the PDV being forcibly removed too. The default value is false.

Port: RCM Port (default value is 29442)

Headers:

  • Authorization: <auth_token> : Authorization token to identify which user is sending the request. The token can be acquired from the login API.

Success Response Code: 202

Error Response Code: 500 (Internal Server Error), 401 (Unauthorized Error), 400 (Invalid API Usage Error), 404 (Not Found Error)

Example Response:

Output
{
   "jobid": 42
}