Managing persistent volume instances with the Volumes API

Create and manage persistent volume instances on your existing IBM® Cloud Pak for Data storage devices with the Volumes REST API.

Introduction

Many enterprise applications use a mounted file system to work with data sets. For example, many Spark jobs process CSV, PARQUET, and AVRO files that are stored on a POSIX-compliant shared file system that can be accessed by all of the executors. However, you might need to store source code for Spark jobs or additional packages that can be used by your Spark jobs. In some cases, these additional files need to be stored on a mountable, shared file system. You can use a volume instance to store these files by using the Volumes API.

You can perform the following tasks:

Work directly with the files on the file system.
You can use the managed volume instances to host files. You can give Cloud Pak for Data users access to the volume instance, and the volume instance can be accessed by services that are running on Cloud Pak for Data.
With the Volumes API, you can create persistent volumes without direct access to Kubernetes or in-depth knowledge of Kubernetes storage principles. However, you should have a basic understanding of Kubernetes storage concepts.
Store and access files that are generated by other services in your ecosystem.
The volume instance is created through a Red Hat® OpenShift® storage account in the Cloud Pak for Data project (namespace) on behalf of the users who creates the volume instance.
After a volume instance is created, you can associate (mount) the volume in the appropriate pods in your Cloud Pak for Data deployment.
Enable access management for specific volumes.
You can specify which users have access to the volume instance to ensure that only authorized users have access to the volume.
Important: A user with direct access to Kubernetes and sufficient privileges on the storage device can potentially still access a volume instance that was created by using the Volumes API.
Allow authorized users to use the Volume API to upload files into their volumes.
Authorized users can upload, view, or delete files on the volume by using the Volumes API and its utilities.

What types of storage can you use to create a storage volume?

You can use the following types of storage to create a storage volume in IBM Cloud Pak for Data:

Storage Requirements
External NFS To connect to an exported path on a remote NFS server, the server must be accessible from the OpenShift worker nodes through a low latency network. The NFS server should also be resilient and highly available.
Existing PVC To use an existing persistent volume claim (PVC) on the cluster, a cluster administrator must create the persistent volume claims that point to the storage that you want to use.
Restriction: Use persistent volume claims that point to file storage rather than block storage.
New PVC To use a new persistent volume claim (PVC) on the cluster, a cluster administrator must set up dynamic storage on the cluster.
Restriction: Use file storage rather than block storage to create storage volumes.

What permissions do you need to create storage volumes?

To use this API, you must have the Create service instances permission in Cloud Pak for Data. You can check which permissions you have from your profile.

The Volumes API

You can use the Volumes API to complete the following tasks:
Authorization
  • Generate an authorization token

    To use the Volumes API, you must authenticate to Cloud Pak for Data. See also Get authorization token in the Cloud Pak for Data Platform API.

    Required role
    You must have the Create service instances permission in Cloud Pak for Data.
    Endpoint
    /icp4d-api/v1/authorize
    Method
    POST
    Command syntax

    Replace the variables with the correct values for your environment.

    curl -kiv -X POST \
  https://<my-deployment-url>/icp4d-api/v1/authorize \
  -H 'Content-Type: application/json' \
  -d '{
 "username":<username>,
 "password":<password>
}'

    This returns a response that contains the access token.

    Example response
    {
    "_messageCode_": "200",
    "message": "Success",
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6ImFkbWluIiwic3ViIjoiYWRtaW4iLCJpc3MiOiJLTk9YU1NPIiwiYXVkIjoiRFNYIiwicm9sZSI6IkFkbWluIiwicGVybWlzc2lvbnMiOlsiYWRtaW5pc3RyYXRvciIsImNhbl9wcm92aXNpb24iXSwidWlkIjoiMTAwMDMzMDk5OSIsImF1dGhlbnRpY2F0b3IiOiJkZWZhdWx0IiwiZGlzcGxheV9uYW1lIjoiYWRtaW4iLCJpYXQiOjE1NzQzMTcyNTIsImV4cCI6MTU3NDM2MDQ1Mn0.ggJotn2ktiWErtoy1Jm_Nv6yWYJH4ebRmXKiMtYIhLJ9nHjMeJqKu4bTl8ZL0feOZpCzuee6nbFe0Y3rL2PdS2BZODBuQCNcsQRCE5ab38q9d0KTbcYZMBRkGbMNlWna2OecBqlGE7KoC4V_XHzdQX2EJaP4I6gMC1R0kjDmYIGAqBMRrps4w87HtIQJttMZpa13stAr2Qdq3m0aS3y-1g4Nl3oW3g0ubI52SAm8AMm5ioXs0ZFtWmjcxq64cYPptK4bnnn5cnm2HsP_LD6v8oFbU6XKRdECJPrk4yZMbyt6-_ipsAqWzJAAL80Bid_59RAEZ-Fdn7TDn6ve3EVaYw"
}

    The authorization token is used in subsequent API calls.

  • Generate an access token for a volume instance

    Generates a JSON Web Token (JWT) token for the volume instance. You must include the volume instance ID as a JSON string in the HTTP request body. You can get the volume instance ID by using /zen-data/v3/service_instances. This token is authorized to access the instance and has the same role as the user who generated the token. You can use the token to interact with the volume instance. For example, you can use the token to:

    Action Required access level
    Start a file server on the volume Admin
    Upload files to or delete files on the volume Editor or higher
    Download files from the volume Viewer or higher
    The instance token for the volume is more secure than your user authorization token. Your user authorization token gives you the appropriate level of access to the entire Cloud Pak for Data deployment. Your instance token gives you only the appropriate level of access to the volume instance.
    Required role
    You must have Viewer access to the specified volume.
    Endpoint

    /zen-data/v2/serviceInstance/token

    Method
    POST
    Command syntax

    Replace the variables with the correct values for your environment.

    curl -k -X POST \
  https://<my-deployment-url>/zen-data/v2/serviceInstance/token \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
  -d '{
   "serviceInstanceID":"<volume-instance-id>"
}'
    Sample response
    {
    "AccessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b20iOnsiTW9kdWxlTmFtZSI6InZvbHVtZXMiLCJSb2xlIjoiQWRtaW4iLCJTZXJ2aWNlSW5zdGFuY2VEaXNwbGF5TmFtZSI6InZvbHVtZS1zYW1wbGUtMSIsIlNlcnZpY2VJbnN0YW5jZUlEIjoiMTU3NDM2MjQ4OTAwNSIsIlNlcnZpY2VJbnN0YW5jZVVzZXJOYW1lIjoiYWRtaW4iLCJaZW5EaXNwbGF5TmFtZSI6ImFkbWluIiwiWmVuVUlEIjoiMTAwMDMzMDk5OSIsIlplblVzZXJuYW1lIjoiYWRtaW4ifSwiZXhwIjoxNTc0MzY2ODkxLCJpYXQiOjE1NzQzNjU2OTEsImlzcyI6IklDUEQiLCJzdWIiOiJhZG1pbiIsInVpZCI6IjEwMDAzMzA5OTkifQ.kU_-x5eSS7Ky9xJCmvfzQ25y8wBsrTghVFy1SxkVWOTlIas5GfW2qM1afDwqxcmFQnnLjPIVU2vn4t-iRyeUp7SSDAxVv6UOxSRP5z6xGOhRvD25KyYqqQemIwHtWUkE95gZ1JCIjFjaHcLdmCkQui_zZXc58sZgA4952ItPFlEr1HzjVs6tAsx2bD7yBVi_kQBT43PSPcL22v8KlNH5qUuoMkNzrek4ZTTo0uptAPJsrM0SBXx8m6QFtk9UroJG7UKRVUEuiAXLycXrvh9XKaigMqqlGbATwlqRxrPENb5TSdW8_mFPt7hzoMJ-KMkDfptqdnJyVMu4lc_Fux3Esg",
    "TokenPayload": {
        "ModuleName": "volumes",
        "Role": "Admin",
        "ServiceInstanceDisplayName": "volume-sample-1",
        "ServiceInstanceID": "1574362489005",
        "ServiceInstanceUserName": "admin",
        "ZenDisplayName": "admin",
        "ZenUID": "1000330999",
        "ZenUsername": "admin"
    }
}
    Tip: Alternatively, you can complete this action from the web client:
    1. Log in to the Cloud Pak for Data web client.
    2. From the menu, select My instances > Provisioned instances.
    3. Locate the volume for which you want to generate a token.
    4. From the action menu, select View details.
    5. On the Details page, copy the access token.

Create a volume instance
  • Create a volume

    Creates a volume instance in a new persistent volume claim (PVC) that can be used to host data files, manage access to Cloud Pak for Data users, and be consumed by other services. You must include the volume instance definition as a JSON string in the HTTP request body. The definition specifies the following information about the volume:

    Parameters Type Description
    display_name String

    The name to display for the volume in the web client.

    The string should be 150 characters or less and contain only lowercase alphanumeric characters.

    This display_name is used to derive the new PVC name. It will be volumes-display_name-pvc.
    namespace String

    The Red Hat OpenShift project (namespace) where the Cloud Pak for Data control plane is installed.
    storageClass String

    The storage class to use for the storage volume. You must specify an existing storage class.

    Ensure that you select a storage class that has the appropriate access mode for your needs:
    • A volume with ReadWriteOnce access means that the volume can be mounted as read/write by a single node.
    • A volume with ReadOnlyMany access means that the volume can be mounted as read-only by multiple nodes.
    • A volume with ReadWriteMany access means that the volume can be mounted as read/write by multiple nodes.
    storageSize String

    The maximum amount of storage to allocate to the storage volume.

    Specify the amount of storage as an integer with one of the following units:
    • For megabytes, use M.
    • For mebibytes, use Mi.
    • For gigabytes, use G.
    • For gibibytes, use Gi
    For example, to specify a 25 GB volume, enter:
     "storageSize":"25G"
    Required role
    You must have the Create service instances permission in Cloud Pak for Data.
    Endpoint

    /zen-data/v3/service_instances

    Method
    POST
    Command syntax

    Replace the variables with the correct values for your environment.

    curl -k -X POST \
  https://<my-deployment-url>/zen-data/v3/service_instances \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
  -d '{
   "addon_type": "volumes",
   "addon_version": "-",
   "create_arguments": {
    "metadata": {
      "storageClass": "<storage-class>",
      "storageSize": "<space-allocated-to-volume>"
    }
  },
   "namespace": "<control-plane-namespace>",
   "display_name": "<my-display-name>"
}'
    Sample response
    {
    "id": "1585361220129"
}
    Tip: To confirm that the volume was successfully created:
    1. Log in to the Cloud Pak for Data web client.
    2. From the menu, select My instances > Provisioned instances.
    If the volume was created successfully, it is included in the list of provisioned instances.

  • Create a volume in an existing persistent volume claim

    Creates a volume instance for an existing persistent volume claim (PVC). You must include the volume instance definition as a JSON string in the HTTP request body. The definition specifies the following information about the volume. For more information, see Create a volume. You must also specify an existing persistent volume claim to add a volume instance to. You can get the persistent volume claim by using /zen-data/v3/service_instances.

    Parameters Type Description
    display_name String

    The name to display for the volume in the web client.

    The string should be 150 characters or less and contain only lowercase alphanumeric characters.

    This display_name is used to derive the new PVC name. It will be volumes-display_name-pvc.
    namespace String

    The Red Hat OpenShift project (namespace) where the Cloud Pak for Data control plane is installed.
    existing_pvc_name String

    The name of the existing persistent volume claim that should be used for the provisioned volume.
    Required role
    You must have the Create service instances permission in Cloud Pak for Data.
    Endpoint

    /zen-data/v3/service_instances

    Method
    POST
    Command syntax

    Replace the variables with the correct values for your environment.

    curl -k -X POST \
  https://<my-deployment-url>/zen-data/v3/service_instances \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
  -d '{
   "addon_type": "volumes",
   "addon_version": "-",
   "create_arguments": {
    "metadata": {
      "existing_pvc_name": "<my-pvc-name>"
    }
   },
   "namespace": "<control-plane-namespace>",
   "display_name": "<my-display-name>",
}'
    Sample response
    {
    "id": "1585361257806"
}

  • Prerequisites for setting up your NFS server

    1. Set up the NFS server. For more information, see Storage considerations.
    2. Install the cpd-meta-operator. For more information, see Installing Operators from OperatorHub and Setting up the Cloud Pak for Data Operator.
    3. Install Cloud Pak for Data.
      1. Create a Cloud Pak for Data instance namespace, for example cpd-tenant.
        oc new-project cpd-tenant
      2. Install Cloud Pak for Data.
      3. Update custom resource definitions (CRD) with the storage class that you are using for Cloud Pak for Data.
        oc apply -f deploy/crds/metaoperator.cpd.ibm.com_v1_service_cr_ceph.yaml
    4. If Cloud Pak for Data is already installed with the cpd binary, you can configure it to point to the cpd-meta-operator installation.
      1. Point to your Cloud Pak for Data project.
        oc project <cpd-namespace>
        .
      2. Edit the product configmap to point META_OPERATOR_NAMESPACE to cpd-meta-operator namespace.
        oc  patch configmap product-configmap --type merge  -p
    '{"data":
        {"META_OPERATOR_NAMESPACE":"<cpd-meta-operator-namespace>"}
    }'
      3. Replace <cpd-meta-operator-namespace> with meta-operator's namespace from step 2.

  • Create a volume on an external NFS server

    Creates a volume instance on an existing NFS server. You must complete the Prerequisites for setting up your NFS server. You must include the volume instance definition as a JSON string in the HTTP request body. The definition specifies the following information about the volume. For more information, see Create a volume.

    Parameters Type Description
    display_name String

    The name to display for the volume in the web client.

    The string should be 150 characters or less and contain only lowercase alphanumeric characters.

    This display_name is used to derive the new PVC name. It will be volumes-display_name-pvc.
    namespace String

    The Red Hat OpenShift project (namespace) where the Cloud Pak for Data control plane is installed.
    nfs_server_address String

    The IP address or fully qualified domain of the NFS server.

    nfs_export_path String

    The export directory path in the NFS server.
    mount_path String

    The directory that the NFS server exported path should be mounted in.

    This path is prefixed with /mnts/ and you specify a path in this directory.
    Required role
    You must have the Create service instances permission in Cloud Pak for Data.
    Endpoint

    /zen-data/v3/service_instances

    Method
    POST
    Command syntax

    Replace the variables with the correct values for your environment.

    curl -k -X POST \
  https://<my-deployment-url>/zen-data/v3/service_instances \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
  -d '{
   "addon_type": "volumes",
   "addon_version": "-",
   "create_arguments": {
    "metadata": {
      "nfs_server_address": "<nfs-server-address>",
      "nfs_export_path": "<nfs-export-path>>",
      "mount_path": "<mount-path>"
    }
   },
   "namespace": "<control-plane-namespace>",
   "display_name": "<display-name>"
}'
    Sample request
    curl -k -X POST \
  https://<my-deployment-url>/zen-data/v3/service_instances \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "addon_type": "volumes",
   "addon_version": "-",
   "create_arguments": {
     "metadata": {
       "nfs_server_address": "9.30.10.10",
       "nfs_export_path": "/mnt/nfs_shares/",
       "mount_path": "/mnts/data/"
     }
    },
   "namespace": "<control-plane-namespace>",
   "display_name": "<display-name>"
}'
    Sample response
    {
    "id": "1585361257809"
}

Volume management
  • Accessing a volume from a service

    After you create a volume, services can reference the volume from their Kubernetes deployments. For more information, see Create a Pod in the Kubernetes documentation.

  • Get a list of volume instances

    Retrieves the list of volumes that you have access to.

    Note: If you use `` as the name, the PVC name of the newly created PVC will be: volumes-<volume-display-name>-pvc.

    If the volume was created by using an existing PVC, then metadata.existing_pvc_name stores the PVC from which volume is created.

    Required role
    You must have Viewer access to at least one volume.
    Endpoint

    /zen-data/v3/service_instances

    Method
    GET
    Command syntax

    Replace the variables with the correct values for your environment.

    curl -k -X GET \
  'https://<my-deployment-url>/zen-data/v3/service_instances?addon_type=volumes' \
  -H 'Authorization: Bearer <authorization-token>'
    Sample response
    {
    "limit": 20,
    "offset": 0,
    "service_instances": [
        {
            "addon_type": "volumes",
            "addon_version": "-",
            "created_at": "2020-03-28T02:07:37.847338Z",
            "display_name": "existing-pv-sample-1",
            "id": "1585361257806",
            "instance_identifiers": null,
            "metadata": {
                "IMAGE_TAG": "v3.0.0.0",
                "docker_registry_prefix": "docker-registry.default.svc:5000/zen",
                "existing_pvc_name": "user-home-pvc",
                "name": "volumes-existing-pv-sample-1",
                "zenControlPlaneNamespace": "zen",
                "zenServiceInstanceId": 1585361257806,
                "zenServiceInstanceNamespace": "zen"
            },
            "misc_data": {},
            "namespace": "zen",
            "owner_uid": "1000330999",
            "owner_username": "admin",
            "parameters": {},
            "provision_status": "PROVISIONED",
            "resources": {},
            "role": "Admin",
            "total_users": 1,
            "updated_at": "2020-03-28T02:10:30.113654Z",
            "zen_service_instance_info": {
                "docker_registry_prefix": "docker-registry.default.svc:5000/zen"
            }
        },
        {
            "addon_type": "volumes",
            "addon_version": "-",
            "created_at": "2020-03-28T02:07:00.349084Z",
            "display_name": "volumes-sample-1",
            "id": "1585361220129",
            "instance_identifiers": null,
            "metadata": {
                "IMAGE_TAG": "v3.0.0.0",
                "docker_registry_prefix": "docker-registry.default.svc:5000/zen",
                "name": "volumes-volumes-sample-1",
                "storageClass": "nfs-client",
                "storageSize": "1Gi",
                "zenControlPlaneNamespace": "zen",
                "zenServiceInstanceId": 1585361220129,
                "zenServiceInstanceNamespace": "zen"
            },
            "misc_data": {},
            "namespace": "zen",
            "owner_uid": "1000330999",
            "owner_username": "admin",
            "parameters": {},
            "provision_status": "PROVISIONED",
            "resources": {},
            "role": "Admin",
            "total_users": 1,
            "updated_at": "2020-03-28T02:10:30.084494Z",
            "zen_service_instance_info": {
                "docker_registry_prefix": "docker-registry.default.svc:5000/zen"
            }
        }
    ],
    "total_count": 2
}

  • Get a list of volumes and associated metadata

    Retrieves the list of volumes that you have access to with additional metadata information such as the PVC name that is associated with the volume and the mount path.

    Parameters Type Description
    display_name String

    The name of the existing volume to query.
    fetch_all_instances Boolean

    If set to true returns all volume instances. This parameter can be used by an Administrator only.
    id String

    The ID of the existing volume to query.
    limit Integer

    The number of volumes to return.
    offset Integer

    The number of volumes to skip before starting to collect the list of volumes.
    Required role
    You must have Viewer access to at least one volume.
    Endpoint

    /zen-data/v1/volumes

    Method
    GET
    Command syntax

    Replace the variables with the correct values for your environment.

    curl -k -X GET \
  'https://<my-deployment-url>//zen-data/v1/volumes' \
  -H 'Authorization: Bearer <authorization-token>'
    Sample response
    {
    "limit": 20,
    "offset": 0,
    "service_instances": [
        {
            "addon_type": "volumes",
            "addon_version": "-",
            "created_at": "2020-03-28T02:07:37.847338Z",
            "display_name": "existing-pv-sample-1",
            "id": "1585361257806",
            "instance_identifiers": null,
            "metadata": {
                "IMAGE_TAG": "v3.0.0.0",
                "docker_registry_prefix": "docker-registry.default.svc:5000/zen",
                "pvc_name": "user-home-pvc",
                "mount_path": "/mnt/data",
                "name": "volumes-existing-pv-sample-1",
                "zenControlPlaneNamespace": "zen",
                "zenServiceInstanceId": 1585361257806,
                "zenServiceInstanceNamespace": "zen"
            },
            "misc_data": {},
            "namespace": "zen",
            "owner_uid": "1000330999",
            "owner_username": "admin",
            "parameters": {},
            "provision_status": "PROVISIONED",
            "resources": {},
            "role": "Admin",
            "total_users": 1,
            "updated_at": "2020-03-28T02:10:30.113654Z",
            "zen_service_instance_info": {
                "docker_registry_prefix": "docker-registry.default.svc:5000/zen"
            }
        },
        {
            "addon_type": "volumes",
            "addon_version": "-",
            "created_at": "2020-03-28T02:07:00.349084Z",
            "display_name": "volumes-sample-1",
            "id": "1585361220129",
            "instance_identifiers": null,
            "metadata": {
                "IMAGE_TAG": "v3.0.0.0",
                "docker_registry_prefix": "docker-registry.default.svc:5000/zen",
                "name": "volumes-volumes-sample-1",
                "pvc_name": "volumes-volumes-sample-1-pvc",
                "mount_path": "/mnt/data",
                "storageClass": "nfs-client",
                "storageSize": "1Gi",
                "zenControlPlaneNamespace": "zen",
                "zenServiceInstanceId": 1585361220129,
                "zenServiceInstanceNamespace": "zen"
            },
            "misc_data": {},
            "namespace": "zen",
            "owner_uid": "1000330999",
            "owner_username": "admin",
            "parameters": {},
            "provision_status": "PROVISIONED",
            "resources": {},
            "role": "Admin",
            "total_users": 1,
            "updated_at": "2020-03-28T02:10:30.084494Z",
            "zen_service_instance_info": {
                "docker_registry_prefix": "docker-registry.default.svc:5000/zen"
            }
        }
    ],
    "total_count": 2
}

    In the previous example, pvc_name points to the associated Kubernetes PVC with the respective volume and mount_path points to the path that the volume should be mounted if a container wants to mount the volume.

    Sample request that queries a specific volume

    Volumes can also be queried directly by providing the display_name query parameter.

    curl -k -X GET \
  'https://<my-deployment-url>/zen-data/v1/volumes?display_name=<insert-volume-name>' \
  -H 'Authorization: Bearer <authorization-token>'

    Replace <insert-volume-name> with display name you chose when you provisioned the volume. This returns volume details for the volume with the specified display name.

    Sample request that queries all volume instances

    An administrator can retrieve all volume instances present even if they don't have access to it by specifying the fetch_all_instances parameter set to true.

    curl -k -X GET \
  'https://<my-deployment-url>/zen-data/v1/volumes?fetch_all_instances=true' \
  -H 'Authorization: Bearer <authorization-token>'

  • Delete a volume

    Deletes a volume instance and removes users' access to the volume.

    Important: The data inside of the volume is not deleted and services can continue to use the volume until a Red Hat OpenShift project administrator removes the persistent volume claim to reclaim the storage. The reclaim policy that is specified in the storage class determines what happens when the persistent volume claim is deleted.
    You must include the volume instance ID in the HTTP request. You can get the volume instance ID by using /zen-data/v3/service_instances.
    Required role
    You must have Admin access to the specified volume.
    Endpoint

    /zen-data/v3/service_instances/<ID>

    Method
    DELETE
    Command syntax

    Replace the variables with the correct values for your environment.

    curl -k -X DELETE \
  https://<my-deployment-url>/zen-data/v3/service_instances/<ID> \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json'
    Sample response
    {
    "id": "1585593738565"
}
    Tip: Alternatively, you can complete this action from the web client:
    1. Log in to the Cloud Pak for Data web client.
    2. From the menu, select My instances > Provisioned instances.
    3. Locate the volume that you want to delete.
    4. From the action menu, select Delete.

User access management
  • Give access to a volume

    Gives one or more users access to a volume instance. By default, only the user who created the volume instance is an administrator. You must include the volume instance ID as a JSON string in the HTTP request body. You can get the volume instance ID by using /zen-data/v3/service_instances. The JSON string must also include information about the user and the type of access that you want to give the user:

    Required role
    You must have Admin access to the specified volume.
    Required information about the user

    To give a user access to the volume, you must have the following information about the user:

    Parameters Type Description
    display_name String

    The user's display name in Cloud Pak for Data.
    uid String

    The user's ID in Cloud Pak for Data.
    username String

    The user's username in Cloud Pak for Data.

    An individual user can gather this information by logging in to the web client. The user's display_name is shown on the home page. The user's name and UID are displayed on the profile page.

    Alternatively, a Cloud Pak for Data administrator can provide this information by:
    • Logging in to the web client and going to the Manage users page
    • Using the Get all users method in the Cloud Pak for Data
    User access levels

    When you give the user access to the volume, you must specify the access level that the user has:

    Parameter Type Description
    role String

    The access level that the user has.

    Valid values are:

    • Viewer: A user with this role can download files or list the files in a directory.
    • Editor: A user with this role has viewer permissions and can also start and stop the file server on the volume or upload and delete files on the volume.
    • Admin: A user with this role has editor permissions and can also manage access to the volume or delete the volume.
    Endpoint

    /zen-data/v2/serviceInstance/users

    Method
    POST
    Command syntax

    Replace the variables with the correct values for your environment.

    curl -k -X POST \
  https://<my-deployment-url>/zen-data/v2/serviceInstance/users/ \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
  -d '{
   "serviceInstanceID":"<volume-instance-ID>",
   "users":[
      {
         "display_name":"<display-name-of-user>",
         "role":"<access-level>",
         "uid":"<uid-of-user>",
         "username":"<username-of-user>"
      }
   ]
}'
    Tip: Alternatively, you can complete this action from the web client:
    1. Log in to the Cloud Pak for Data web client.
    2. From the menu, select My instances > Provisioned instances.
    3. Locate the volume that you want to give users access to.
    4. From the action menu, select Manage access.
    5. Click Add users.
    6. Select the users to give access to the volume and the role that each user has on the volume.
    7. Click Add.

  • Get a list of users with access to a volume

    Retrieves the list of users who have access to the specified volume. The role of each user is also returned.

    Required role
    You must have Admin access to the specified volume.
    Endpoint

    /zen-data/v2/serviceInstance/users?sID={volume_instance_id}

    Method
    GET
    Path parameters
    Parameter Type Description
    ID String

    The ID of the volume instance.

    You can get the volume instance ID by using /zen-data/v3/service_instances.
    Command syntax

    Replace the variables with the correct values for your environment.

    curl -k -X GET \
  'https://<my-deployment-url>/zen-data/v2/serviceInstance/users?sID=<volume_instance_id>' \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json'
    Sample response
    {
    "_messageCode_": "success",
    "message": "Success in getting requests",
    "requestObj": [
        {
            "ID": "1574362489005/1000330999",
            "SID": 1574362489005,
            "Role": "Admin",
            "Password": "",
            "UID": "1000330999",
            "UserName": "admin",
            "DisplayName": "admin",
            "ServiceInstanceUserName": "admin",
            "Exists": true,
            "DeletedAt": null
        },
        {
            "ID": "1574362489005/1000331001",
            "SID": 1574362489005,
            "Role": "Editor",
            "Password": "",
            "UID": "1000331001",
            "UserName": "mike",
            "DisplayName": "mike",
            "ServiceInstanceUserName": "mike",
            "Exists": true,
            "DeletedAt": null
        }
    ]
}

  • Change a user's role on a volume

    Changes the user's role (access level) on the specified volume. You must include the volume instance ID as a JSON string in the HTTP request body. You can get the volume instance ID by using /zen-data/v3/service_instances. The JSON string must also include information about the user and the type of access that you want to give the user:

    Required role
    You must have Admin access to the specified volume.
    Required information about the user

    To change a user's role on the volume, you must have the following information about the user:

    Parameters Type Description
    uid String

    The user's ID in Cloud Pak for Data.

    To get a list of the users who have access to the volume and each user's UID, see Get a list of users with access to a volume.

    User access levels

    You must specify the new access level that the user has:

    Parameters Type Description
    newRole String

    The access level that the user has.

    Valid values are:

    • Viewer: A user with this role can download files or list the files in a directory.
    • Editor: A user with this role has viewer permissions and can also start and stop the file server on the volume or upload and delete files on the volume.
    • Admin: A user with this role has editor permissions and can also manage access to the volume or delete the volume.
    Endpoint

    /zen-data/v2/serviceInstance/users/role

    Method
    PATCH
    Command syntax

    Replace the variables with the correct values for your environment.

    curl -k -X PATCH \
  https://<my-deployment-url>/zen-data/v2/serviceInstance/users/role \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
  -d '{
   "serviceInstanceID":"<volume-instance-ID>",
   "roles":[
      {
         "uid":"<uid-of-user>",
         "newRole":"<new-access-level>"
      }
   ]
}'
    Sample response
    {
    "_messageCode_": "200",
    "message": "Successfully updated roles"
}
    Tip: Alternatively, you can complete this action from the web client:
    1. Log in to the Cloud Pak for Data web client.
    2. From the menu, select My instances > Provisioned instances.
    3. Locate the volume that the user has access to.
    4. From the action menu, select Manage access.
    5. From the action menu for the user, select Edit role.
    6. Select the new role for the user and click Save.

  • Revoke access to a volume

    Revoke a user's access to the specified volume instance. You must include the volume instance ID as a JSON string in the HTTP request body. You can get the volume instance ID by using /zen-data/v3/service_instances. The JSON string must also include information about the user:

    Required role
    You must have Admin access to the specified volume.
    Required information about the user

    To revoke a user's access to the volume, you must specify the following information about the user:

    Parameter Type Description
    users Array

    An array that contains one or more strings that specify the users IDs for which you want to revoke access.

    To get a list of the users who have access to the volume and each user's UID, see Get a list of users with access to a volume.

    Endpoint

    /zen-data/v2/serviceInstance/users

    Method
    DELETE
    Command syntax

    Replace the variables with the correct values for your environment.

    curl -k -X DELETE \
  https://<my-deployment-url>/zen-data/v2/serviceInstance/users/ \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
  -d '{
   "serviceInstanceID":"<volume-instance-ID>",
   "users":[
      "<uid-of-user>"
   ]
}'
    Sample response
    {
    "_messageCode_": "200",
    "message": "Successfully deleted users "
}
    Tip: Alternatively, you can complete this action from the web client:
    1. Log in to the Cloud Pak for Data web client.
    2. From the menu, select My instances > Provisioned instances.
    3. Locate the volume for which you want to revoke a user's access.
    4. From the action menu, select Manage access.
    5. From the action menu for the user, select Remove.

File server management
  • Start a file server on a volume

    Starts the Volume File Server REST service on the specified volume instance. The Volume File Server service enables users to work with files that reside in the specified volume through API calls:

    Action Required access level
    Create directories Editor or higher
    Upload files Editor or higher
    Delete files Editor or higher
    List files Viewer or higher
    Download files Viewer or higher
    Required role
    You must have Editor or Admin access to the specified volume.
    Endpoint

    /zen-data/v1/volumes/volume_services/{display_name}

    Method
    POST
    Path parameters
    Parameter Type Description
    display_name String

    The display name of the volume instance.

    You can get the volume instance display name by using /zen-data/v3/service_instances.
    Command syntax

    Replace the variables with the correct values for your environment.

    curl -k -X POST \
  https://<my-deployment-url>/zen-data/v1/volumes/volume_services/<display_name> \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
  -d '{}'
    Sample response
    {
    "_messageCode_": "200",
    "message": "Successfully stopped volume service"
}

  • Configuring the user (UID) that file server starts as

    Starts the file server on the specified volume instance for a user, which is specified by the uid parameter. For more information, see Start a file server on a volume. The UID of the user can be configured in the request body. The files uploaded to the file server will be owned by that UID.

    Required role
    You must have Editor or Admin access to the specified volume.
    Endpoint

    /zen-data/v1/volumes/volume_services/{display_name}

    Method
    POST
    Path parameters
    Parameter Type Description
    display_name String

    The display name of the volume instance.

    You can get the volume instance display name by using /zen-data/v3/service_instances.
    run_as_user UID in the range 1000320900-1000361000

    The default UID is 1000320999. The range is 1000320900 - 1000361000.

    Note: UIDs that starting from 1000330990 are reserved for users in user-management within Cloud Pak for Data.
    Command syntax

    Replace the variables with the correct values for your environment.

    curl -k -X POST \
  https://<my-deployment-url>/zen-data/v1/volumes/volume_services/<display_name> \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "run_as_user": <uid-of-user>
  }'
    Sample response
    {
    "_messageCode_": "200",
    "message": "Successfully started volume service"
}

  • Automatically start a file server

    When you create a volume, you can starts the Volume File Server REST service on the specified volume instance automatically instead of by using the Start a file server on a volume API.

    Parameters Type Description
    display_name String

    The name to display for the volume in the web client.

    The string should be 150 characters or less and contain only lowercase alphanumeric characters.

    This display_name is used to derive the new PVC name. It will be volumes-display_name-pvc.
    namespace String

    The Red Hat OpenShift project (namespace) where the Cloud Pak for Data control plane is installed.
    storageClass String

    The storage class to use for the storage volume. You must specify an existing storage class.

    Ensure that you select a storage class that has the appropriate access mode for your needs:
    • A volume with ReadWriteOnce access means that the volume can be mounted as read/write by a single node.
    • A volume with ReadOnlyMany access means that the volume can be mounted as read-only by multiple nodes.
    • A volume with ReadWriteMany access means that the volume can be mounted as read/write by multiple nodes.
    create_arguments.metadata.file_server.start Boolean

    Set to True to automatically start the file server.
    resources.limits.cpu (Optional) String

    The maximum CPU that can be consumed. When a limit is reached, if quotas are enforced, you cannot create a new pod and existing pods cannot use more CPU.

    If not specified. the default value is 1.
    resources.limits.memory (Optional) String

    The maximum memory that can be consumed (in GB). When a limit is reached, if quotas are enforced, you cannot create a new pod and existing pods cannot use more memory.

    The default value is 1Gi.
    resources.requests.cpu (Optional) String

    The minimum CPU that can be consumed before monitors indicate that this CPU usage has been reached. If quotas are enforced, when a request is reached you cannot create a new pod; however, existing pods can consume more resources up to the maximum set by the limits.

    If not specified, the default value is 0.1.
    resources.requests.memory (Optional) String

    The minimum memory required before monitors indicate that this memory usage has been reached (in GB). If quotas are enforced, when a request is reached you cannot create a new pod; however, existing pods can consume more resources up to the maximum set by the limits.

    The default value is 100Mi.
    Required role
    You must have Editor or Admin access to the specified volume.
    Endpoint

    /zen-data/v3/service_instances

    Method
    POST
    Command syntax

    Replace the variables with the correct values for your environment.

    curl -k -X POST \
  https://<my-deployment-url>/zen-data/v3/service_instances \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
  -d '{
   "addon_type": "volumes",
   "addon_version": "-",
   "create_arguments": {
    "metadata": {
      "storageClass": "<storage-class>",
      "storageSize": "<space-allocated-to-volume>",
      "file_server": {
        "start": true,
        "resources": {
          "limits": {
            "cpu": "<cpu-limits>",
            "memory": "<memory-limits>"
          },
          "requests": {
            "cpu": "<cpu-requests>",
            "memory": "<memory-requests>"
          }
        }
      }
    }
  },
   "namespace": "<control-plane-namespace>",
   "display_name": "<display-name>"
}'
    Sample response
    {
    "id": "1585361257809"
}

  • Stop a file server on a volume

    Stops the Volume File Server REST service on the specified volume instance.

    Important: The data in the volume is not deleted.
    You can stop the file server to suspend unnecessary processing when the file server is not needed. Stopping the file server releases the compute resources that are used by the file server.
    Required role
    You must have Editor or Admin access to the specified volume.
    Endpoint

    /zen-data/v1/volumes/volume_services/{display_name}

    Method
    DELETE
    Path parameters
    Parameter Type Description
    display_name String

    The display name of the volume instance.

    You can get the display name from the web client or by using /zen-data/v3/service_instances.
    Command syntax

    Replace the variables with the correct values for your environment.

    curl -k -X DELETE \
  https://<my-deployment-url>/zen-data/v1/volumes/volume_services/<display_name> \
  -H 'Authorization: Bearer <authorization-token>'
    Sample response
    {
   "_messageCode_":"200",
   "message":"Successfully stopped volume service"
}

File and directory management
  • Create a directory inside a volume

    Creates a directory or a nested directory structure on the specified volume instance. You can use directories to organize the files on the volume. Keep the following rules in mind when you create directories:

    • Directories are created at the root level inside of the volume directory.
    • If a directory in the requested path exists, it is skipped during traversal.
    • To create nested directories, use URL encoding on the {directory_path} parameter.
    Required role
    You must have Editor or Admin access to the specified volume.
    Endpoint

    /zen-volumes/{display_name}/v1/volumes/files/{directory_path}

    Method
    PUT
    Path parameters
    Parameter Type Description
    display_name String

    The display name of the volume instance.

    You can get the display name from the web client or by using /zen-data/v3/service_instances.
    directory_path String

    The directory structure to create.

    If you are creating a nested directory, use URL encoding. For example, to create a directory called Shared files/analytics projects, enter:

    Shared%20files%2Fanalytics%20projects
    make_executable (Optional) Boolean

    Set the make_executable parameter to true to ensure that the directory you created has executable permissions. This operation sets the +x bit across owner, group, and other (world) attributes of the directory. If you are requesting to create a sequence of nested directories, setting the make_executable parameter to true ensures that only the final directory in the path has executable permissions.
    Command syntax

    Replace the variables with the correct values for your environment.

    curl -k -X PUT \
  https://<my-deployment-url>/zen-volumes/<display_name>/v1/volumes/files/<directory_path>?make_executable=true \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: multipart/form-data' \
  -F upFile=''
    Sample response
    {
    "_messageCode_": "Success",
    "message": "Successfully uploaded file and created the necessary directory structure"
}

  • Get a list of the directories and files on a volume

    Retrieves the list of all directories and files on the specified volume. You can use the recursive parameter to list contents from the <directory_path> recursively. You can also optionally use the include_details query parameter to list the contents of the <directory_path> as an array of objects and their metadata.

    Required role
    Any user with access to the volume.
    Endpoint

    /zen-volumes/{display_name}/v1/volumes/directories/{directory_path}

    Method
    GET
    Path parameters
    Parameter Type Description
    display_name String

    The display name of the volume instance.

    You can get the display name from the web client or by using /zen-data/v3/service_instances.
    directory_path String

    The directory for which you want to display the contents.

    If you are referring to a nested directory, use URL encoding. For example, to create a reference to a directory called Shared files/analytics projects, enter:

    Shared%20files%2Fanalytics%20projects
    include_details (Optional) Boolean

    If set to true, the API lists the contents from the directory_path as an array of objects with each object containing certain metadata information about the entity (file/directory) encountered at that location.

    The default is false.

    The information includes:

    • content_length, in bytes
    • last_modified, in RFC 1123 format
    recursive (Optional) Boolean

    The default value is false.

    Set the parameter to true to list the contents of the specified directory path recursively.
    Command syntax

    Replace the variables with the correct values for your environment.

    curl -k -X GET \
  https://<my-deployment-url>/zen-volumes/<display_name>/v1/volumes/directories/<directory_path> \
  -H 'Authorization: Bearer <authorization-token>'
    To recursively list the directories in the specified <directory_path>, use:
    curl -k -X GET \
  https://<my-deployment-url>/zen-volumes/<display_name>/v1/volumes/directories/<directory_path>?recursive=true \
  -H 'Authorization: Bearer <authorization-token>'
    To list the details of the contents of the files in the specified <directory_path>, use:
    curl -k -X GET \
  https://my-deployment-url/zen-volumes/display_name/v1/volumes/directories/directory_path?include_details=true \
  -H 'Authorization: Bearer authorization-token'
    Sample response with recursion but no details
    {
    "_messageCode_": "Success",
    "message": "Successfully read contents of the directory",
    "responseObject": {
        "directoryContents": [
            "bar/add-ons.json",
            "bar/baz",
            "bar/baz/banking.json",
            "bar/baz/qux"
        ]
    },
    "status": "200"
}
    Sample response with no recursion but details
    {
    "_messageCode_": "Success",
    "message": "Successfully read contents of the directory",
    "responseObject": {
        "directoryContents": [
            {
                "path": "dsxl_version.txt",
                "type": "file",
                "content_length": 21,
                "last_modified": "Fri, 11 Sep 2020 20:37:17 GMT"
            },
            {
                "path": "i18n",
                "type": "directory",
                "content_length": 32,
                "last_modified": "Fri, 11 Sep 2020 22:33:11 GMT"
            },
            {
                "path": "version.txt",
                "type": "file",
                "content_length": 25,
                "last_modified": "Fri, 11 Sep 2020 23:22:21 GMT"
            }
        ]
    },
    "status": "200"
}

  • Upload a file to a volume

    Uploads a file to the specified directory on the specified volume. You must specify:

    • The target directory for the file on the volume
    • The path to the source file on the local file system:
      -F upFile='@<fully-qualified-file-path>'
      For example:
      -F upFile='@/Users/some-user/sample-data/filename.csv'
    Required role
    You must have Editor or Admin access to the specified volume.
    Endpoint

    /zen-volumes/{display_name}/v1/volumes/files/{target_file_path}

    Method
    PUT
    Path parameters
    Parameter Type Description
    display_name String

    The display name of the volume instance.

    You can get the display name from the web client or by using /zen-data/v3/service_instances.
    target_file_path String

    The fully qualified path of the file on the volume.

    If you are referring to a nested directory, use URL encoding. For example, to add a file called filename.csv to the Shared files/analytics projects directory, enter:

    Shared%20files%2Fanalytics%20projects%Ffilename.csv

    To get the list of existing directories, see Get a list of the directories and files on a volume.
    extract (Optional) Boolean

    The default value is false.

    Set the parameter to true to extract the contents of .zip, .tar, .tar.gz, or .tgz files to the specified directory. You can also upload binary-like files, that is, files that don't have a file extension.

    Important: If you specify this parameter, do not include the file name in the target_file_path parameter.
    make_executable (Optional) Boolean

    Set the make_executable parameter to true to ensure that the file that you uploaded has executable permissions. This operation sets the +x bit across owner, group, and other (world) attributes of the directory. The make_executable parameter operates only on singleton files and has no effect on archived file uploads. When you uploaded an archive, the extracted files inherit the permissions from the source from where they were archived.
    Command syntax

    Replace the variables with the correct values for your environment.

    curl -k -X PUT \
  https://<my-deployment-url>/zen-volumes/<display_name>/v1/volumes/files/<target_file_path> \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: multipart/form-data' \
  -F upFile='@<fully-qualified-file-path>'

    To extract the contents of a TAR.GZ file to the specified directory, use:

    curl -k -X PUT \
  https://<my-deployment-url>/zen-volumes/<display_name>/v1/volumes/files/<target_file_path>?extract=true \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: multipart/form-data' \
  -F upFile='@<fully-qualified-file-path>'

    To upload a file to a specified directory and make it executable, use:

    curl -k -X PUT \
  https://<my-deployment-url>/zen-volumes/<display_name>/v1/volumes/files/<target_file_path>?make_executable=true \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: multipart/form-data' \
  -F upFile='@<fully-qualified-file-path>'
    Sample response
    {
    "_messageCode_": "Success",
    "message": "Successfully uploaded file and created the necessary directory structure"
}

  • Download a file from a volume

    Downloads the specified file from the specified volume. You can download a file or an archived directory in the name of your choice. Pass the file name of your choice in the optional override_file_name parameter. You can use the dry_run parameter to check if the asset at the target_file_path exists and return some useful metadata in the response header about the asset. You can also download an entire directory as an archive. Pass the archive type in as the value for the compress parameter in the request. If you issue this command from a web browser, the download prompt is displayed.

    Required role
    Any user with access to the volume.
    Endpoint

    /zen-volumes/{display_name}/v1/volumes/files/{target_file_path}

    Method
    GET
    Path parameters
    Parameter Type Description
    display_name String

    The display name of the volume instance.

    You can get the display name from the web client or by using /zen-data/v3/service_instances.
    compress (Optional) String
    Supported archive types are:
    • zip
    • tar
    • tar.gz
    dry_run (Optional) Boolean

    If set to true, the API checks the asset at the target_file_path for existence and returns metadata about the asset or entity in the response header . The default is false.

    This information includes:
    • Content-Length in bytes
    • Resource-Type, which identifies the entity as a file or directory
    • Last-Modified, which is RFC 1123 date formatted
    override_file_name (Optional) String

    The new name for the uploaded file. This file name does not have to be the fully qualified path of the file.
    target_file_path String

    The fully qualified path of the file on the volume.

    If you are referring to a nested directory, use URL encoding. For example, to download a file called filename.csv from the Shared files/analytics projects directory, enter:

    Shared%20files%2Fanalytics%20projects%Ffilename.csv
    Command syntax

    Replace the variables with the correct values for your environment.

    curl -k -X GET \
  https://<my-deployment-url>/zen-volumes/<display_name>/v1/volumes/files/<target_file_path>?override_file_name=<renamed_target_file_path>&compress=tar \
  -H 'Authorization: Bearer <authorization-token>'
    Sample request to download a file with dry_run=true
    curl -k -X GET \
  https://<my-deployment-url>/zen-volumes/<display_name>/v1/volumes/files/<target_file_path>?dry_run=true \
  -H 'Authorization: Bearer <authorization-token>'
    Sample response
    HTTP 206 Partial Content

Response headers:
< Content-Length: 145
< Last-Modified: Fri, 11 Sep 2020 23:33:11 GMT
< Resource-Type: file
    Sample request to download a directory with dry_run=true
    curl -k -X GET \
  https://<my-deployment-url>/zen-volumes/<display_name>/v1/volumes/files/<target_file_path>?dry_run=true \
  -H 'Authorization: Bearer <authorization-token>'
    Sample response
    HTTP 206 Partial Content

Response headers:
< Content-Length: 170
< Last-Modified: Fri, 11 Sep 2020 23:33:11 GMT
< Resource-Type: directory

  • Delete a directory or file on a volume

    Deletes the specified file or directory on the specified volume.

    Required role
    You must have Editor or Admin access to the specified volume.
    Endpoint

    /zen-volumes/{display_name}/v1/volumes/files/{target_path}

    Method
    DELETE
    Path parameters
    Parameter Type Description
    display_name String

    The display name of the volume instance.

    You can get the display name from the web client or by using /zen-data/v3/service_instances.
    target_path String

    The fully qualified path of the file or directory on the volume.

    If you are referring to a nested directory, use URL encoding.

    For example,:
    • To delete the file called filename.csv from the Shared files/analytics projects directory, enter:
      Shared%20files%2Fanalytics%20projects%Ffilename.csv
    • To delete the Shared files/analytics projects directory, enter:
      Shared%20files%2Fanalytics%20projects
    Command syntax

    Replace the variables with the correct values for your environment.

    curl -k -X DELETE \
  https://<my-deployment-url>/zen-volumes/<display_name>/v1/volumes/files/<target_path> \
  -H 'Authorization: Bearer <authorization-token>'
    Sample response
    {
    "_messageCode_": "Success",
    "message": "Successfully deleted file"
}

  • Copy, move, or rename a file or directory in a volume

    Copies, moves, or renames files and directories within a volume. It consumes a request JSON body parameter.

    Required role
    You must have Editor or Admin access to the specified volume.
    Endpoint

    /zen-volumes/<volume_name>/v1/volumes/objects/copy

    Method
    PUT
    Path parameters
    Parameter Type Description
    display_name String

    The display name of the volume instance.

    You can get the display name from the web client or by using /zen-data/v3/service_instances.
    source_path String

    The fully qualified path of the file or directory on the volume.

    If you are referring to a nested directory, use URL encoding.

    You can compose the source_path by using /zen-data/v3/service_instances.
    destination_path String

    The fully qualified path of the destination for the file or directory on the volume.

    If you are referring to a nested directory, use URL encoding.
    overwrite_destination (Optional) Boolean

    Set to true if you want to force replace a conflicting object at the destination_path. This value defaults to false. That is, if there are conflicts during the copy, move, or rename it is reported back to the user in the API response.
    keep_source (Optional) Boolean

    Set to false if you do not want to retain a copy of the object at the source_path (equivalent to a mv in UNIX). This value defaults to true, which keeps the object at the source_path.
    destination_in_path (Optional) Boolean

    Set to true if destination_path in the request body includes the name the object is to be copied as. This value defaults to false. That is, the object will be copied to the destination_path with the same name as in the source_path, creating any directories specified in the destination_path.
    Command syntax

    Replace the variables with the correct values for your environment.

    curl -k -X PUT \
  https://<my-deployment-url>/zen-volumes/<volume_name>/v1/volumes/objects/copy \
  -H 'Authorization: Bearer <authorization-token>' \
  -H 'Content-Type: application/json' \
  -d '{
	"source_path": "foo/bar",
	"destination_path": "baz"
  }
    Sample response
    {
    "_messageCode_": "Success",
    "message": "Successfully copied object from source to destination"
}