Jump to: navigation, search

Manila/API

< Manila
Revision as of 17:28, 30 May 2014 by Vponomaryov (talk | contribs) (List Snapshots with Details)

OpenStack Shared Filesystem Management Service API v1 specification

This document describes how to develop applications that use Manila Service API v1 for authentication. This document also describes how to integrate services with Manila Service API v1.

Glossary

To use the Shared Filesystem Managenent service API effectively, you should understand several key concepts:

Share

A remote mountable filesystem. It can only be attached to several instances at a time.

Share type

Share protocol (NFS, CIFS)

Snapshot

A point in time copy of the data contained in a share.

Share Network

stores network information that will be used by share servers, where shares are hosted.

Security Service

stores information for configuring clients for LDAP, Kerberos or Active Directory on 'share server'. It should be attached to share-network, if assumed to be used.

Share Server

is created by multitenant backend drivers, where shares are hosted. Using 'generic' driver, it is Nova's VMs, using 'cluster_mode' driver from NetApp it is 'vserver's...

Volume type

designed for filtering/choosing 'backends' before creation of share. Behaviour same as in 'Cinder' project.

High-Level Task Flow

The high-level task flow for Manila is as follows:

The tenant creates a share. For example, the tenant creates a 30G NFS share called share1 in network, specified by share-network with id '%some-share-network-id%' and on backend 'netapp' using volume-type.

$ manila create nfs 30 --name share1 --description "Description of share" --share-network-id %some-share-network-id% --volume-type netapp

Authentication

You can use cURL to try the authentication process in two steps: get a token; send the token to a service. Get an authentication token by providing your user name and either your API key or your password. Here are examples of both approaches: You can request a token by providing your user name and your password.


$ curl -X POST https://localhost:5000/v2.0/tokens -d '{"auth":{"passwordCredentials":{"username": "joecool", "password":"coolword"}, "tenantId":"5"}}' -H 'Content-type: application/json'

Successful authentication returns a token which you can use as evidence that your identity has already been authenticated. To use the token, pass it to other services as an X-Auth-Token header. Authentication also returns a service catalog, listing the endpoints you can use for Cloud services. Use the authentication token to send a GET to a service you would like to use. Authentication tokens are typically valid for 24 hours. Applications should be designed to re-authenticate after receiving a 401 (Unauthorized) response from a service endpoint.


Request/Response Types

Manila API supports both the JSON and XML data serialization formats. The request format is specified using the Content-Type header and is required for calls that have a request body. The response format can be specified in requests either by using the Accept header or by adding an .xml or .json extension to the request URI. Note that it is possible for a response to be serialized using a format different from the request. If no response format is specified, JSON is the default. If conflicting formats are specified using both an Accept header and a query extension, the query extension takes precedence.

NOTE: manila supports XML container type for the moment, after implementation of bp for nova: https://blueprints.launchpad.net/nova/+spec/remove-v3-xml-api were decided to stop support and test this container type in manila.

Table 2.1. Response Formats

Format Acceptt Header Query Extension Default
JSON application/json .json Yes
XML application/xml .xml No

API Operations

Shares

Create Share

POST /v1/<tenant_id>/shares

Content-Type: application/json

Accept: application/json


JSON Request

{
   "share": {
       "volume_type": "%volume_type%",
       "name": "test",
       "snapshot_id": null,
       "description": "test description",
       "metadata": {
           "key1": "value1",
           "key2": "value2",
       },
       "share_proto": "nfs",
       "share_network_id": "%share_network_id%",
       "size": 1
   }
}

JSON Response

{
   "share": {
       "id": %share_id%", 
       "links": [
           {"href": "http://%ip%:8786/v1/%tenant_id%/shares/%share_id%", "rel": "self"},
           {"href": "http://%ip%:8786/%tenant_id%/shares/%share_id%", "rel": "bookmark"}
       ],
       "name": "test"
   }
}
List shares with details

GET /v1/<tenant_id>/shares/details

Accept: application/json


JSON Response

{
   "shares": [
       {
            "status": "available",
            "export_location": %ip%:/opt/stack/data/manila/mnt/share-%share_id%,
            "name": "test",
            "links": [
                {"href": "http://%ip%:8786/v1/%tenant_id%/shares/%share_id%", "rel": "self"},
                {"href": "http://%ip%:8786/%tenant_id%/shares/%share_id%", "rel": "bookmark"}
            ],
            "availability_zone": "nova",
            "created_at": "2014-05-30T12:14:31.000000",
            "description": null,
            "share_proto": "NFS",
            "share_network_id": "%share_network_id%",
            "metadata": {
                "key1": "value1",
                "key2": "value2",
            },
            "host": "hostname@backendname",
            "volume_type": "%volume_type%",
            "snapshot_id": null,
            "project_id": "%project_id(tenant_id)%",
            "id": "%share_id%",
            "size": 1
       },
       {
            "status": "available",
            "export_location": null, 
            "name": "somename",
            "links": [
                {"href": "http://%ip%:8786/v1/%tenant_id%/shares/%share_id%", "rel": "self"},
                {"href": "http://%ip%:8786/%tenant_id%/shares/%share_id%", "rel": "bookmark"}
            ], 
            "availability_zone": "nova", 
            "created_at": "2014-05-30T12:12:55.000000", 
            "description": "somedescription", 
            "share_proto": "NFS", 
            "share_network_id": "%share_network_id%", 
            "metadata": {},
             "host": "hostname2@backendname2", 
            "volume_type": "%volume_type%",
             "snapshot_id": "%snapshot_id%",
            "project_id": "%project_id(tenant_id)%",
             "id": "%share_id%",
             "size": 1
       }
   ]
}
Show Share

GET /v1/<tenant_id>/shares/<share_id>

Accept: application/json

JSON Response

{
   "share": {
       "status": "available",
       "export_location": "%ip%:/opt/stack/data/manila/mnt/share-%share_id%",
       "name": "name_of_cifs_share",
       "links": [
           {"href": "http://%ip%:8786/v1/%tenant_id%/shares/%share_id%", "rel": "self"},
           {"href": "http://%ip%:8786/%tenant_id%/shares/%share_id%", "rel": "bookmark"}
       ],
       "availability_zone": "nova",
       "created_at": "2014-05-30T11:31:13.000000",
       "description": "some description",
       "share_proto": "CIFS",
       "share_network_id": "%share_network_id%",
       "metadata": {
           "key1": "value1", 
           "key2": "value2"
       },
       "host": "hostname@backendname",
       "volume_type": "%volume_type%",
       "snapshot_id": null,
       "project_id": "%project_id%",
       "id": "%share_id%",
       "size": 5
   }
}
Update Share

PUT /v1/<tenant_id>/shares/<share_id>

Accept: application/json

JSON Request

{
    "share": {
       "display_description": "New description",
       "display_name": "newname"
   }
}

JSON Response

{
   "share": {
       "availability_zone": "nova",
       "created_at": "2013-10-02T09:58:12.000000",
       "description": "New description",
       "share_network_id": "%share_network_id%",
       "export_location": "localhost:/opt/stack/data/manila/mnt/share-%share_id%",
       "id": "%share_id%",
       "links": [
           {
               "href": "http://localhost:8786/v1/%tenant_id%/shares/%share_id%",
               "rel": "self"
           },
           {
               "href": "http://localhost:8786/%tenant_id%/shares/%share_id%",
               "rel": "bookmark"
           }
       ],
       "name": "newname",
       "volume_type": "%volume_type%",
       "share_proto": "NFS",
       "size": 2,
       "snapshot_id": null,
       "status": "available",
       "project_id": "%project_id%",
       "host": "hostname@backendname",
       "metadata": {
                    "key1": "value1", 
                    "key2": "value2"
       }
   }
}
Delete Share

DELETE /v1/<tenant_id>/shares/<share_id>

Show Share Metadata

GET /v1/<tenant_id>/shares/<share_id>/metadata

Accept: application/json

JSON Response

{
    "metadata": {
       "key1": "value1",
       "key2": "value2"
   }
}
Update Share Metadata

PUT /v1/<tenant_id>/shares/<share_id>/metadata

Accept: application/json

JSON Request

{
    "metadata": {
       "key1": "value1"
   }
}

JSON Response

{
    "metadata": {
       "key1": "value1"
   }
}
Set Share Metadata

POST /v1/<tenant_id>/shares/<share_id>/metadata

Accept: application/json

JSON Request

{
    "metadata": {
       "key1": "value1"
   }
}

JSON Response

{
    "metadata": {
       "key1": "value1", 
       "key2": "value2"
   }
}
Unset Share Metadata

DELETE /v1/<tenant_id>/shares/<share_id>/metadata/<key>

Snapshots

Create Snapshot

POST /v1/<tenant_id>/snapshots

Accept: application/json

JSON Request

{
    "snapshot": {
       "description": null,
       "force": false,
       "name": null,
       "share_id": "%share_id%"
   }
}

JSON Response

{
    "snapshot": {
       "id": "%snapshot_id%",
       "links": [
           {
               "href": "http://localhost:8786/v1/%tenant_id%/snapshots/%snapshot_id%",
               "rel": "self"
           },
           {
               "href": "http://localhost:8786/%tenant_id%/snapshots/%snapshot_id%",
               "rel": "bookmark"
           }
       ],
       "name": null
   }
}
List Snapshots with Details

GET /v1/<tenant_id>/snapshots/detail

Accept: application/json

JSON Response

{
    "snapshots": [
        {
            "status": "available",
            "share_id": "%share_id%",
            "description": "test-desc",
            "links": [
                {"href": "http://%ip%:8786/v1/%tenant_id%/snapshots/%snapshot_id%", "rel": "self"},
                {"href": "http://%ip%:8786/%tenant_id%/snapshots/%snapshot_id%", "rel": "bookmark"}
            ],
            "id": "%snapshot_id%",
            "size": 1,
            "name": "snap-test",
            "created_at": "2014-05-30T17:20:37.000000",
            "export_location": "10.254.0.3:/shares/share-%share_id%",
            "share_proto": "NFS",
            "share_size": 1
        },
        {
            "status": "available",
            "share_id": "%share_id%",
            "description": "test-desc",
            "links": [
                {"href": "http://%ip%:8786/v1/%tenant_id%/snapshots/%snapshot_id%", "rel": "self"},
                {"href": "http://%ip%:8786/%tenant_id%/snapshots/%snapshot_id%", "rel": "bookmark"}
            ], 
            "id": "%snapshot_id%",
            "size": 1, 
            "name": "snap-test",
            "created_at": "2014-05-30T17:20:24.000000",
            "export_location": "10.254.0.3:/shares/share-%share_id%",
            "share_proto": "NFS",
            "share_size": 1
        }
    ]
}
Show Snapshot

GET /v1/<tenant_id>/snapshots/<snapshot_id>

Accept: application/json

JSON Response

{
    "snapshot": {
       "created_at": "2013-10-02T10:04:59.000000",
       "description": null,
       "export_location": "localhost:/opt/stack/data/manila/mnt/share-e1f9c138-f614-43a6-8a0c-51c39f3b169c",
       "id": "3c5b3b68-75c4-412f-8a9c-7ced9df2ac6c",
       "links": [
           {
               "href": "http://localhost:8786/v1/23ccb90954c149ee8cb7de08521914be/snapshots/3c5b3b68-75c4-412f-8a9c-7ced9df2ac6c",
               "rel": "self"
           },
           {
               "href": "http://localhost:8786/23ccb90954c149ee8cb7de08521914be/snapshots/3c5b3b68-75c4-412f-8a9c-7ced9df2ac6c",
               "rel": "bookmark"
           }
       ],
       "name": null,
       "share_id": "e1f9c138-f614-43a6-8a0c-51c39f3b169c",
       "share_proto": "NFS",
       "share_size": 1,
       "size": 1,
       "status": "available"
   }
}
Update Snapshot

PUT /v1/<tenant_id>/snapshots/<snapshot_id>

Accept: application/json

JSON Request

{
   "snapshot": {
       "display_description": "New description",
       "display_name": "newname"
   }
}

JSON Response

{
    "snapshot": {
       "created_at": "2013-10-02T10:04:59.000000",
       "description": "New description",
       "export_location": "localhost:/opt/stack/data/manila/mnt/share-e1f9c138-f614-43a6-8a0c-51c39f3b169c",
       "id": "3c5b3b68-75c4-412f-8a9c-7ced9df2ac6c",
       "links": [
           {
               "href": "http://localhost:8786/v1/%tenant_id%/snapshots/%snapshot_id%",
               "rel": "self"
           },
           {
               "href": "http://localhost:8786/%tenant_id%/snapshots/%snapshot_id%",
               "rel": "bookmark"
           }
       ],
       "name": "newname",
       "share_id": "%share_id%",
       "share_proto": "NFS",
       "share_size": 1,
       "size": 1,
       "status": "available"
   }
}
Delete Snapshot

DELETE /v1/<tenant_id>/snapshots/<snapshot_id>

Accept: application/json

Share Networks

Create Share Network

POST /v1/<tenant_id>/share-networks

Content-Type: application/json

Accept: application/json


JSON Request

{
   "share_network": {
       "name": "test_name",
       "description": "test_description",
       "neutron_net_id": "some_neutron_net_id",
       "neutron_subnet_id": "some_neutron_subnet_id",
   }
}

JSON Response

{
    "share_network": {
       "id": "%share_network_id%",
       "name": "test_name",
       "description": "test_description",
       "neutron_net_id": "%some_neutron_net_id%",
       "neutron_subnet_id": "%some_neutron_subnet_id%",
       "segmentation_id": null,
       "network_type": null,
       "status": null,
       "created_at": "2009-10-11T12:13:14.000000",
       "updated_at": null,
       "ip_version": null,
       "cidr": null,
       "project_id": "%project_id%",
   }
}
List share-networks

GET /v1/<tenant_id>/share-networks

Accept: application/json


JSON Response

{
    "share_networks": [
       {
           "id": "%share_network_id%",
           "name": "test_name",
           "status": null
       },
       {
           "id": "%share_network_id_2%",
           "name": "test_name_2",
           "status": null
       },
   ]
}

Extensions

Share Actions

Allow access

POST /v1/<tenant_id>/shares/<share_id>/action

Accept: application/json

JSON Request

{
    "os-allow_access": {
       "access_to": "1.1.1.1",
       "access_type": "ip"
   }
}

JSON Response

{
    "access": {
       "access_to": "1.1.1.1",
       "access_type": "ip",
       "created_at": "2013-10-02T10:29:36.539532",
       "deleted": false,
       "deleted_at": null,
       "id": "%access_rule_id%",
       "share_id": "%share_id%",
       "state": "new",
       "updated_at": null
   }
}
Deny Access

POST /v1/<tenant_id>/shares/<share_id>/action

Accept: application/json

JSON Request

{
     "os-deny_access": {
       "access_id": "%access_rule_id%"
   }
}
List Access Rules

POST /v1/<tenant_id>/shares/<share_id>/action

Accept: application/json

JSON Request

{
    "os-access_list": null
}

JSON Response

{
    "access_list": [
       {
           "access_to": "1.1.1.1",
           "access_type": "ip",
           "id": "%access_rule_id%",
           "state": "active"
       }
   ]
}