******************************** 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) with the access mode type RWX. 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. ================================= 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. ================================================= 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) ================================== ============================================================================================== ===================================== Add a Persistent Data Volume ===================================== .. tabs:: .. tab:: CLI 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 `` 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. .. code-block:: text # robin pdv add --faultdomain --media --rpool --name --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 `` Fault domain for replicas. Valid values include ``disk``, ``host``, or ``rack``. The default value is ``disk`` in Robin CNP v5.4.3 and ``host`` from Robin 5.4.3HF1 onwards. The value ``disk`` for Fault domain is not supported starting from Robin CNP v5.4.3 HF1. **Note:** The Fault domain option is only valid when the replication factor is greater than 1. ``--media `` Specify which type of drives to allocate storage from. Valid values include HDD and SSD. The default media type is HDD ``--rpool `` Name of the resource pool from which to allocate ``--name `` Custom PDV name. The default format is ``pdv-`` ``--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:** .. code-block:: text # 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 .. tab:: API 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: `` - This mandatory field within the payload specifies the name of the namespace which the PDV should be bound to. - ``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: `` - 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: `` - 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``. The default value is ``disk`` in Robin CNP v5.4.3 and ``host`` from Robin 5.4.3HF1 onwards. The value ``disk`` for Fault domain is not supported starting from Robin CNP v5.4.3 HF1. **Note:** The Fault domain option is only valid when the replication factor is greater than 1. - ``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: `` - Utilizing this parameter within the payload results in the storage for the PDV being allocated from the specified resource pool. - ``name: `` - Utilizing this parameter within the payload results in the name of the PDV being set to the string specified. - ``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: `` : 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:** .. raw:: html
Output .. code-block:: text { "jobid":38 } .. raw:: html
============================ List Persistent Data Volumes ============================ .. tabs:: .. tab:: CLI 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: .. code-block:: text # robin pdv list [] --username --namespace --tenant --page_size --page --private --public --all-records ============================= ================================================================================ ``name`` Name of a Physical Data Volume to filter by. Note this parameter is optional. ``--username `` Filter by user. ``--namespace `` Filter by namespace. ``--tenant `` Filter by tenant. ``--page-size `` Displays provided number of PDVs for each 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:** .. code-block:: text # 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 .. tab:: API 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: `` - Utilizing this parameter within the payload results in number of PDVs being returned. - ``page_num: `` - Utilizing this parameter within the payload results in PDVs starting from being returned. - ``tenant: `` - Utilizing this parameter within the payload results in the list of PDVs returned being filtered by the tenant specified. - ``username: `` - Utilizing this parameter within the payload results in the list of PDVs returned being filtered by the user specified. - ``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: `` : 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:** .. raw:: html
Output .. code-block:: text { "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":[ ] } ] } .. raw:: html
================================ Resize a Persistent Data Volume ================================ .. tabs:: .. tab:: CLI To resize a PDV via Robin, issue the following command: .. code-block:: text # robin pdv resize ========== ====================================================================================================================================================== ``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:** .. code-block:: text # robin pdv resize pdv-b8947314-74b9-451b-98dd-7090ea5f368b 2G PersistentDataVolume 'pdv-b8947314-74b9-451b-98dd-7090ea5f368b' was successfully increased in size .. tab:: API Resizes a PDV to the desired size. Note a PDV cannot be decreased in size. **End Point:** /api/v3/robin_server/pdvs/ **Method:** PUT **URL Parameters:** None **Data Parameters:** - ``action: resize`` - This mandatory field within the payload specifies the resize operation is to be performed. - ``name: `` - This mandatory field within the payload specifies the name of the PDV to be resized. - ``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: `` : 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:** .. raw:: html
Output .. code-block:: text { "message":"PersistentDataVolume 'pdv-c2474073-f7b2-4dc7-9f5e-322f7e7dd5e4' was successfully increased in size" } .. raw:: html
====================================== Persistent Data Volume Share Options ====================================== .. tabs:: .. tab:: CLI In order to view the List valid operations that can be specified when sharing a PDV, run the following command: .. code-block:: text # robin pdv share-options --json ====================== ============================================================================================================================ ``--json`` Output in JSON ====================== ============================================================================================================================ **Example:** .. code-block:: text # robin pdv share-options +------------------------+------------+-----------+ | Object Type | Share Type | Operation | +------------------------+------------+-----------+ | PERSISTENT_DATA_VOLUME | USER | view | | PERSISTENT_DATA_VOLUME | USER | update | +------------------------+------------+-----------+ =============================== Share a Persistent Data Volume =============================== .. tabs:: .. tab:: CLI 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. .. code-block:: text # robin pdv share [] --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 `` 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:** .. code-block:: text # robin pdv share pdv-t1-ns1 user1 PersistentDataVolume 'pdv-t1-ns1' has been shared with the following users: user1 ========================================== List Shared Persistent Data Volume Shares ========================================== .. tabs:: .. tab:: CLI 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. .. code-block:: text # robin pdv list-shares [] ============================== =================================================================================================== ``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):** .. code-block:: text # 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):** .. code-block:: text # 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 | ================================ Unshare a Persistent Data Volume ================================ .. tabs:: .. tab:: CLI You can unshare a shared PDV with a single user, list of users, or all users. .. code-block:: text # robin pdv unshare [] --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 `` 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** .. code-block:: text # robin pdv unshare pdv-t1-ns1 user1 PersistentDataVolume 'pdv-t1-ns1' is no longer shared with the following users: user1 ==================================================== Change Ownership of a Shared Persistent Data Volume ==================================================== .. tabs:: .. tab:: CLI 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. .. code-block:: text # robin pdv change-owner --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** .. code-block:: text # 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 ====================================== Delete a Persistent Data Volume ====================================== .. tabs:: .. tab:: CLI 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: .. code-block:: text # robin pdv remove --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** .. code-block:: text # 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 .. tab:: API Deletes a PDV. **End Point:** /api/v3/robin_server/pdvs **Method:** DELETE **URL Parameters:** None **Data Parameters:** - ``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: `` : 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:** .. raw:: html
Output .. code-block:: text { "jobid": 42 } .. raw:: html