Merge bf83ed2 into 8d3d644

openapi-spec/swagger.yaml

@@ -732,9 +732,9 @@ definitions:
             type: string
   Pool:
     description: >-
-      A backend is initialized by specific driver configuration. Each backend
-      can be regarded as a docking service between SDS controller and storage
-      service.
+      A pool is discoveried and updated by a dock service. Each pool can be regarded
+      as a physical storage pool or a virtual storage pool. It's a logical and 
+      atomic pool and can be abstracted from any storage platform.
     allOf:
       - $ref: '#/definitions/BaseModel'
       - type: object

pkg/model/base.go

@@ -24,11 +24,20 @@ import (
 )
 
 type BaseModel struct {
-	// +readOnly:true
+	// The uuid of the object, it's unique in the context and generated by system
+	// on successful creation of the object. It's not allowed to be modified by
+	// the user.
+	// +readOnly
 	Id string `json:"id"`
-	// +readOnly:true
+
+	// CreateAt representing the server time when the object was created successfully.
+	// Now, it's represented as a time string in RFC8601 format.
+	// +readOnly
 	CreatedAt string `json:"createdAt"`
-	// +readOnly:true
+
+	// UpdatedAt representing the server time when the object was updated successfully.
+	// Now, it's represented as a time string in RFC8601 format.
+	// +readOnly
 	UpdatedAt string `json:"updatedAt"`
 }
 

pkg/model/dock.go

@@ -24,11 +24,26 @@ package model
 // service.
 type DockSpec struct {
 	*BaseModel
-	Name        string `json:"name,omitempty"`
+
+	// The name of the dock.
+	Name string `json:"name,omitempty"`
+
+	// The description of the dock.
+	// +optional
 	Description string `json:"description,omitempty"`
-	// +readOnly:true
-	Status      string `json:"status,omitempty"`
+
+	// The status of the dock.
+	// One of: "available" or "unavailable".
+	Status string `json:"status,omitempty"`
+
+	// The storage type of the dock.
+	// One of: "block", "file" or "object".
 	StorageType string `json:"storageType,omitempty"`
-	Endpoint    string `json:"endpoint,omitempty"`
-	DriverName  string `json:"driverName,omitempty"`
+
+	// Endpoint represents the dock server's access address.
+	Endpoint string `json:"endpoint,omitempty"`
+
+	// DriverName represents the dock provider.
+	// Currently One of: "cinder", "ceph", "lvm", "default".
+	DriverName string `json:"driverName,omitempty"`
 }

pkg/model/pool.go

@@ -19,22 +19,42 @@ This module implements the common data structure.
 
 package model
 
-// A backend is initialized by specific driver configuration. Each backend
-// can be regarded as a docking service between SDS controller and storage
-// service.
+// A pool is discoveried and updated by a dock service. Each pool can be regarded
+// as a physical storage pool or a virtual storage pool. It's a logical and
+// atomic pool and can be abstracted from any storage platform.
 type StoragePoolSpec struct {
 	*BaseModel
-	Name        string `json:"name,omitempty"`
+	// The name of the pool.
+	Name string `json:"name,omitempty"`
+
+	// The description of the pool.
+	// +optional
 	Description string `json:"description,omitempty"`
-	// +readOnly:true
-	Status           string `json:"status,omitempty"`
-	DockId           string `json:"dockId,omitempty"`
+
+	// The status of the pool.
+	// One of: "available" or "unavailable".
+	Status string `json:"status,omitempty"`
+
+	// The uuid of the dock which the pool belongs to.
+	DockId string `json:"dockId,omitempty"`
+
+	// The locality that pool belongs to.
 	AvailabilityZone string `json:"availabilityZone,omitempty"`
+
+	// The total capacity of the pool.
 	// Default unit of TotalCapacity is GB.
 	TotalCapacity int64 `json:"totalCapacity,omitempty"`
+
+	// The free capaicty of the pool.
 	// Default unit of FreeCapacity is GB.
-	FreeCapacity int64  `json:"freeCapacity,omitempty"`
-	StorageType  string `json:"storageType,omitempty"`
+	FreeCapacity int64 `json:"freeCapacity,omitempty"`
+
+	// The storage type of the dock.
+	// One of: "block", "file" or "object".
+	StorageType string `json:"storageType,omitempty"`
+
+	// Map of keys and json object that represents the extra epecs
+	// of the pool, such as supported capabilities.
 	// +optional
 	Extras ExtraSpec `json:"extras,omitempty"`
 }

pkg/model/profile.go

@@ -24,8 +24,20 @@ package model
 // capabilities which are desirable features for a class of applications.
 type ProfileSpec struct {
 	*BaseModel
-	Name        string    `json:"name,omitempty"`
-	Description string    `json:"description,omitempty"`
-	StorageType string    `json:"storageType,omitempty"`
-	Extras      ExtraSpec `json:"extras,omitempty"`
+
+	// The name of the profile.
+	Name string `json:"name,omitempty"`
+
+	// The description of the profile.
+	// +optional
+	Description string `json:"description,omitempty"`
+
+	// The storage type of the profile.
+	// One of: "block", "file" or "object".
+	StorageType string `json:"storageType,omitempty"`
+
+	// Map of keys and json object that represents the extra epecs
+	// of the profile, such as requested capabilities.
+	// +optional
+	Extras ExtraSpec `json:"extras,omitempty"`
 }

pkg/model/version.go

@@ -26,13 +26,22 @@ const (
 	deprecated = "DEPRECATED"
 )
 
-// Lists information for all SDS controller API versions. An API version is
-// a string that consists of a ‘v’ + number, or ‘v’ + number + ‘alpha’ or
-// ‘beta’ + number.
+// An API version is a string that consists of a ‘v’ + number,
+// or ‘v’ + number + ‘alpha’ or ‘beta’ + number.
 type VersionSpec struct {
+	// Name is an API version string that consists of a ‘v’ + number,
+	// or ‘v’ + number + ‘alpha’ or ‘beta’ + number.
+	// +readOnly
 	Name string `json:"name,omitempty"`
+
+	// The status of the api version.
+	// One of: "CURRENT", "SUPPORTED", "DEPRECATED".
 	// +readOnly:true
-	Status    string `json:"status,omitempty"`
+	Status string `json:"status,omitempty"`
+
+	// UpdatedAt representing the server time when the api version was updated
+	// successfully. Now, it's represented as a time string in RFC8601 format.
+	// +readOnly
 	UpdatedAt string `json:"updatedAt,omitempty"`
 }
 

pkg/model/volume.go

@@ -27,17 +27,39 @@ import (
 // to physical machine or virtual machine instance.
 type VolumeSpec struct {
 	*BaseModel
-	ProjectId   string `json:"projectId,omitempty"`
-	UserId      string `json:"userId,omitempty"`
-	Name        string `json:"name,omitempty"`
+
+	// The uuid of the project that the volume belongs to.
+	ProjectId string `json:"projectId,omitempty"`
+
+	// The uuid of the user that the volume belongs to.
+	// +optional
+	UserId string `json:"userId,omitempty"`
+
+	// The name of the volume.
+	Name string `json:"name,omitempty"`
+
+	// The description of the volume.
+	// +optional
 	Description string `json:"description,omitempty"`
+
+	// The size of the volume requested by the user.
 	// Default unit of volume Size is GB.
-	Size             int64  `json:"size,omitempty"`
+	Size int64 `json:"size,omitempty"`
+
+	// The locality that volume belongs to.
 	AvailabilityZone string `json:"availabilityZone,omitempty"`
-	// +readOnly:true
-	Status    string `json:"status,omitempty"`
-	PoolId    string `json:"poolId,omitempty"`
+
+	// The status of the volume.
+	// One of: "available", "error", "in-use", etc.
+	Status string `json:"status,omitempty"`
+
+	// The uuid of the pool which the volume belongs to.
+	// +readOnly
+	PoolId string `json:"poolId,omitempty"`
+
+	// The uuid of the profile which the volume belongs to.
 	ProfileId string `json:"profileId,omitempty"`
+
 	// Metadata should be kept until the scemantics between opensds volume
 	// and backend storage resouce description are clear.
 	// +optional
@@ -46,17 +68,32 @@ type VolumeSpec struct {
 
 type VolumeAttachmentSpec struct {
 	*BaseModel
-	ProjectId  string `json:"projectId,omitempty"`
-	UserId     string `json:"userId,omitempty"`
-	VolumeId   string `json:"volumeId,omitempty"`
+	// The uuid of the project that the volume belongs to.
+	ProjectId string `json:"projectId,omitempty"`
+
+	// The uuid of the user that the volume belongs to.
+	// +optional
+	UserId string `json:"userId,omitempty"`
+
+	// The uuid of the volume which the attachment belongs to.
+	VolumeId string `json:"volumeId,omitempty"`
+
+	// The locaility when the volume was attached to a host.
 	Mountpoint string `json:"mountpoint,omitempty"`
-	// +readOnly:true
+
+	// The status of the attachment.
+	// One of: "attaching", "attached", "error", etc.
 	Status string `json:"status,omitempty"`
+
 	// Metadata should be kept until the scemantics between opensds volume
 	// attachment and backend attached storage resouce description are clear.
 	// +optional
-	Metadata       map[string]string `json:"metadata,omitempty"`
-	HostInfo       `json:"hostInfo,omitempty"`
+	Metadata map[string]string `json:"metadata,omitempty"`
+
+	// See details in `HostInfo`
+	HostInfo `json:"hostInfo,omitempty"`
+
+	// See details in `ConnectionInfo`
 	ConnectionInfo `json:"connectionInfo,omitempty"`
 }
 
@@ -85,14 +122,32 @@ func (con *ConnectionInfo) EncodeConnectionData() []byte {
 
 type VolumeSnapshotSpec struct {
 	*BaseModel
-	ProjectId   string `json:"projectId,omitempty"`
-	UserId      string `json:"userId,omitempty"`
-	Name        string `json:"name,omitempty"`
+
+	// The uuid of the project that the volume snapshot belongs to.
+	ProjectId string `json:"projectId,omitempty"`
+
+	// The uuid of the user that the volume snapshot belongs to.
+	// +optional
+	UserId string `json:"userId,omitempty"`
+
+	// The name of the volume snapshot.
+	Name string `json:"name,omitempty"`
+
+	// The description of the volume snapshot.
+	// +optional
 	Description string `json:"description,omitempty"`
-	// Default unit of snapshot Size is GB.
-	Size     int64  `json:"size,omitempty"`
-	Status   string `json:"status,omitempty"`
+
+	// The size of the volume which the snapshot belongs to.
+	// Default unit of volume Size is GB.
+	Size int64 `json:"size,omitempty"`
+
+	// The status of the volume snapshot.
+	// One of: "available", "error", etc.
+	Status string `json:"status,omitempty"`
+
+	// The uuid of the volume which the snapshot belongs to.
 	VolumeId string `json:"volumeId,omitempty"`
+
 	// Metadata should be kept until the scemantics between opensds volume
 	// snapshot and backend storage resouce snapshot description are clear.
 	// +optional