ViPR Controller REST API for Object Control

Table of Contents

Back to Top

Introduction

This article provides an overview of the methods provided by the ViPR Controller REST API for configuring the ViPR object store. Once the object store is configured, subsequent object create, read, update, and delete operations are performed using the supported S3, EMC Atmos, or OpenStack Swift object protocols.

This article applies to EMC ViPR 2.0.

You can refer to the following articles to get an understanding of how to access the REST API and how to authenticate:

In addition, an API Reference is provided in:

The EMC ViPR REST API Reference is auto-generated from the source code and provides a reference for each of the available methods.

The following topics provide a summary of the object storage methods provided by the Controller REST API and describe the steps required to configure ViPR object storage using the API:

The ViPR UI implements many of the API calls to provide a graphical environment for configuring Data Services. You can access the ViPR UI at:

https://<ViPR_IP_Address>/

Back to Top

Controller REST API for Object Control summary

The Controller REST API for Object Control provides API methods that enable object storage to be configured.

The following table summarizes the API.

Back to Top

Step-by-step: configure ViPR object storage

This topic summarizes the steps involved in using the ViPR REST API to configure ViPR object storage and links to the more detailed instructions for performing each step.

Before you begin

  • When using commodity storage to support the object store, refer to the ViPR Installation and Configuration Roadmap for details of the commodity install and configuration.

  • You must ensure that you have configured storage that can be used for the object store. When using object on file systems, storage to support the object store is provided by file systems created from file virtual pools and you must ensure that a suitable pool exists. Creating a file virtual pool is described in the following article: Create Virtual Pools for File Storage in ViPR.

Procedure

  1. Create one or more data stores that will provide the underlying storage.
    An example is provided in: Create an object data store on a file systeml
  2. Create an object virtual pool.
    An example is provided in Create an object virtual pool.
  3. Configure the tenant to use object storage by assigning a namespace.
  4. Create buckets.
    In general buckets within object storage are created using the supported object API (S3, Atmos, OpenStack Swift). However, the controller REST API provides the ability to create buckets to support operations such as ingestion, or to use HDFS storage in simple (non-Kerberos) mode.
  5. Create secret keys.
    To use the ViPR object store you will need to create secret keys for ViPR authenticated users.
    An example is provided in: Create a secret key
Back to Top

Create an object data store on a file system

At least one data store must be created before an object virtual pool can be created and before data services tenant settings can be configured.

Before you begin

  • The SYSTEM_ADMIN or RESTRICTED_SYSTEM_ADMIN role is required to execute this method.
  • A file virtual pool must have been created and must be associated with the virtual array that you intend to use to support object storage - that is, the virtual array you will specify when creating an object virtual pool.

Procedure

  1. You can get a list of the available file virtual pools using:

    GET https://<ViPR_IP_address>:4443/file/vpools

    In the example response below, a single file virtual pool exists.

    <vpool_list> <virtualpool> <id> urn:storageos:VirtualPool:9805606e-320b-485a-9b8e-48d81ddc4dc3:vdc1 </id> <link rel="self" href="/file/vpools/urn:storageos:VirtualPool:9805606e-320b-485a-9b8e-48d81ddc4dc3:vdc1"/> <name>IsilonVPool</name> <vpool_type>file</vpool_type> </virtualpool> </vpool_list>

  2. You also need to know the identity of the virtual array that will be used to provide storage. You can do this using:

    GET https://<ViPR_IP_address>:4443/vdc/varrays

    In the example response below, a single virtual array, VA-1, exists.

    <varrays> <varray> <id>urn:storageos:VirtualArray:793757ab-ad51-4038-b80a-682e124eb25e:vdc1</id> <link rel="self" href="/vdc/varrays/urn:storageos:VirtualArray:793757ab-ad51-4038-b80a-682e124eb25e:vdc1"/> <name>VA-1</name> </varray> </varrays>

  3. To create an object store you can use:

    POST /vdc/data-stores/filesystems

    The body of the request supplies the size of the data store, the name of the data store, and the virtual array and file virtual pool from which the data store file system should be created, as shown below.

    <filesystems_data_store_create> <size>50000000000</size> <file_data_services_vpool> urn:storageos:VirtualPool:9805606e-320b-485a-9b8e-48d81ddc4dc3:vdc1 </file_data_services_vpool> <name>DS1-on-Isilon</name> <description>Data store on Isilon</description> <virtual_array> urn:storageos:VirtualArray:793757ab-ad51-4038-b80a-682e124eb25e:vdc1 </virtual_array> </filesystems_data_store_create>

    The method is asynchronous and returns a task that can then be queried to determine its state. The task looks like this:

    <task> <associated_resources/> <name>CREATE</name> <op_id>CREATE</op_id> <resource> <id>urn:storageos:HostingDeviceInfo:746f4c10-4eb2-4bbe-ba36-9ceade52cd08:vdc1</id> <link rel="self" href="/vdc/object-pools/urn:storageos:HostingDeviceInfo:746f4c10-4eb2-4bbe-ba36-9ceade52cd08:vdc1"/> <name>urn:storageos:HostingDeviceInfo:746f4c10-4eb2-4bbe-ba36-9ceade52cd08:vdc1</name> </resource> <link rel="self" href="/vdc/data-stores/urn:storageos:HostingDeviceInfo:746f4c10-4eb2-4bbe-ba36-9ceade52cd08:vdc1/tasks/CREATE"/> <state>pending</state> </task>

    The task can be queried using: GET /vdc/data-stores/{id}/tasks

Back to Top

Create an object virtual pool

You must create at least one object virtual pool. A virtual pool comprises all of the data stores in one or more selected virtual arrays.

Before you begin

  • A virtual array must exist and must have a data store associated with it before you can create a virtual pool.

Procedure

  1. You can create an object virtual pool using:

    POST /vdc/data-services/vpools

    The body of the request identifies one or more virtual arrays (GET /vdc/varrays) that will contribute data stores to the object virtual pool. An object virtual pool can span ViPR sites, so the <zone_mapping> can specify multiple vdc/varray pairs.

    <data_service_vpool_create> <name>varray123</name> <description>Vpool with single varray mapping</description> <zone_mappings> <name> urn:storageos:VirtualDataCenter:1de0bbc2-907c-4ede-b133-f5331e03e6fa:vdc1 </name> <value> urn:storageos:VirtualArray:465a3ef1-5ac5-46fc-8e1a-6fb4aefce7fd:vdc1 </value> </zone_mappings> </data_service_vpool_create>

    The response provides the identity of the data services virtual pool. In this example:

    <data_service_vpool> <id> urn:storageos:ReplicationGroupInfo:0f360f6b-98ca-40b6-8b84-bac0f9934c0e:global </id> <tags/> <description>Vpool with single varray mapping</description> <name>varray123</name> <varrayMappings> <name> urn:storageos:VirtualDataCenter:1de0bbc2-907c-4ede-b133-f5331e03e6fa:vdc1 </name> <value> urn:storageos:VirtualArray:465a3ef1-5ac5-46fc-8e1a-6fb4aefce7fd:vdc1 </value> </varrayMappings> </data_service_vpool>

Back to Top

Configuring a tenant to use the object store

A namespace must be assigned for each tenant in order to use Data Services.

Before you begin

Procedure

  1. You can create the namespace for the tenant using:

    POST /object/namespaces/namespace

    The body of the request must specify the tenant identity, as shown below:

    <namespace_create> <namespace>rootnamespace</namespace> <tenant> urn:storageos:TenantOrg:2786ebfb-f495-4d28-9b8f-83382d6881ca:global </tenant> </namespace_create>

    You can also optionally specify a default virtual pool and a default project for the tenant, as below:

    <namespace_create> <namespace>rootnamespace</namespace> <tenant> urn:storageos:TenantOrg:2786ebfb-f495-4d28-9b8f-83382d6881ca:global </tenant> <default_object_project> urn:storageos:Project:489e8831-2a9b-4a59-9dc6-1f9660a07f5f:global </default_object_project> <default_data_services_vpool> urn:storageos:ReplicationGroupInfo:8fc8e19b-edf0-4e81-bee8-79accc867f64:global </default_data_services_vpool> </namespace_create>

    The response from the previous command is as below:

    <namespace> <id>rootnamespace</id> <inactive>false</inactive> <link rel="self" href="/object/namespaces/namespace/rootnamespace"/> <name>rootnamespace</name> <tags/> <tenant> urn:storageos:TenantOrg:2786ebfb-f495-4d28-9b8f-83382d6881ca:global </tenant> <default_object_project> urn:storageos:Project:489e8831-2a9b-4a59-9dc6-1f9660a07f5f:global </default_object_project> <default_data_services_vpool> urn:storageos:ReplicationGroupInfo:8fc8e19b-edf0-4e81-bee8-79accc867f64:global </default_data_services_vpool> </namespace>

Back to Top

Create a bucket using the ViPR Controller REST API

The ViPR Controller REST API provides methods for performing object storage configuration, including creating buckets.

Before you begin

  • ViPR object storage must have been configured using data services nodes or commodity nodes.
  • Object storage must have at least one object virtual pool which is backed by one or more virtual arrays.

A bucket must be created in an object virtual pool and must be associated with a project.

Procedure

  1. Get the UID for the project with which the bucket will be associated.
    The UIDs for all projects can be obtained using GET /projects/bulk. For example:

    GET https://<ViPR IP address>:4443/projects/bulk

    Returns the identity of any projects. In this case there is only one.

    <ids> <id>urn:storageos:Project:489e8831-2a9b-4a59-9dc6-1f9660a07f5f:global </id> </ids>

    You can then obtain the details of each project using GET /projects/{id}.
  2. Get the UID of the object virtual pool in which you want to create the bucket.
    The UIDs for all projects can be obtained using GET /object/data-services-vpools. For example:

    GET https://<ViPR IP address>:4443/vdc/data-service/vpools

    In this example, one pool is returned which has a single varrayMapping and so will have the data stores contributed by the single virtual array specified in that mapping:

    <data_service_vpools> <data_service_vpool> <creation_time>1403531485559</creation_time> <id>urn:storageos:ReplicationGroupInfo:0f360f6b-98ca-40b6-8b84-bac0f9934c0e:global</id> <inactive>false</inactive> <tags/> <description>Vpool with single varray mapping</description> <name>varray567</name> <varrayMappings> <name> urn:storageos:VirtualDataCenter:1de0bbc2-907c-4ede-b133-f5331e03e6fa:vdc1 </name> <value> urn:storageos:VirtualArray:465a3ef1-5ac5-46fc-8e1a-6fb4aefce7fd:vdc1 </value> </varrayMappings> <data_service_vpool> </data_service_vpools>

  3. Create the bucket using POST /object/bucket and specify the protocol that will be allowed to access the bucket: S3, ATMOS, SWIFT, or CAS.
    In addition to the virtual pool and the project, you also need to specify whether you want the bucket to be capable of supporting HDFS operation. To support HDFS operation, <filesystem_enabled> must be set to true. For example:

    POST https://<ViPR IP address>:4443/object/bucket

    with the following payload:

    <object_bucket_create> <name>MyBucket</name> <project>urn:storageos:Project:489e8831-2a9b-4a59-9dc6-1f9660a07f5f:global </project> <vpool> urn:storageos:ReplicationGroupInfo:0f360f6b-98ca-40b6-8b84-bac0f9934c0e:global</vpool> <filesystem_enabled>true</filesystem_enabled> <head_type>S3</head_type> <namespace>rootnamespace</namespace> </object_bucket_create>

    If you omit the namespace, the namespace of the tenant with which the user making the create bucket request is associated will be used.

    The response is of the form shown below.

    <object_bucket> <id>rootnamespace.MyBucket</id> <inactive>false</inactive> <name>MyBucket</name> <tags/> </object_bucket>

Back to Top

Create a secret key

To authenticate with object services, a user will normally need to be assigned a secret key.

Before you begin

Procedure

  1. Create a secret key.

    POST /object/secret-keys

    You will get a response in the form:

    <user_secret_key> <link href="/object/user-secret-keys/root" rel="self"/> <secret_key>SwVjQT/p6/guLWj46TeVEE6vSWYWTUiwhExqFoHt</secret_key> <key_timestamp>2013-11-27 10:43:57.582</key_timestamp> </user_secret_key>