15. Object Storage (EOL)
Object Storage is a computer data storage architecture that manages data as objects as opposed to block storage which manages data as blocks within sectors and tracks. Object storage is commonly used to manage large amounts of unstructured data for example storing large datasets like photos, music, or files in online collaboration services.
Object Storage API commands allow creation, management and deletion of Object Storage devices as well as viewing Object Storage network data usage. Object Storage is fully S3-compliant allowing file and bucket management using existing S3 clients.
Get Object Storages
List all Object Storage devices on the account or those which the subaccount has permissions.
Request
Normal response
{
"object_storages": {
"object_storage": [
{
"created": "2020-07-23T05:06:35Z",
"description": "Example object storage",
"name": "example-object-storage",
"size": 250,
"state": "started",
"url": "https://example-object-storage.nl-ams1.upcloudobjects.com/",
"uuid": "06832a75-be7b-4d23-be05-130dc3dfd9e7",
"zone": "uk-lon1"
},
{
"created": "2020-07-23T05:06:35Z",
"description": "App object storage",
"name": "app-object-storage",
"size": 500,
"state": "started",
"url": "https://app-data-storage.nl-ams1.upcloudobjects.com/",
"uuid": "06636a75-ae9b-4d23-be06-260dc3ded8e0",
"zone": "nl-ams1"
}
]
}
}
Create Object Storage
Used to create a new Object Storage device with a given name, size and location.
Request
{
"object_storage": {
"name": "app-object-storage",
"description": "App object storage",
"zone": "nl-ams1",
"access_key": "UCOBTMRABUTKMC2WF6BD",
"secret_key": "NCAtWEblflr7HhimErIgRVNo48+x546VLm0azVcO",
"size": 500
}
}
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 3-32 characters | no | Object Storage name, default is a generated UUID |
| description | 1-255 characters | no | Short description for the Object Storage |
| zone | A valid zone identifier | yes | The zone in which the server will be hosted, e.g. fi-hel1. See Zones. |
| access_key | yes | Access key used to identify user | |
| secret_key | yes | Secret key used to authenticate user | |
| size | 250, 500, 1000 | yes | Object Storage size in gigabytes |
Normal response
{
"object_storage": {
"name": "app-object-storage",
"description": "App object storage",
"zone": "nl-ams1",
"size": 500
}
}
Error responses
| HTTP status | Error code | Description |
|---|---|---|
| 400 Bad Request | SIZE_INVALID | The attribute size has an invalid value |
| 400 Bad Request | SIZE_MISSING | The required attribute size is missing |
| 400 Bad Request | ACCESS_KEY_INVALID | The attribute access_key has an invalid value |
| 400 Bad Request | ACCESS_KEY_MISSING | The required attribute access_key is missing |
| 400 Bad Request | SECRET_KEY_INVALID | The attribute secret_key has an invalid value |
| 400 Bad Request | SECRET_KEY_MISSING | The required attribute secret_key is missing |
| 400 Bad Request | DESCRIPTION_INVALID | The attribute description has an invalid value |
| 400 Bad Request | ZONE_MISSING | The required attribute zone is missing |
| 403 Forbidden | OBJECT_STORAGE_FORBIDDEN | No permission to access details of the specified Object Storage |
| 404 Not Found | OBJECT_STORAGE_NOT_FOUND | Object Storage {uuid} does not exist |
| 404 Not Found | ZONE_NOT_FOUND | The zone {zone} does not exist |
| 409 Conflict | NAME_INVALID | The attribute name has an invalid value |
Get Object Storage details
A request to get details about a specific Object Storage device by the given {uuid}.
Request
Normal response
{
"object_storage": {
"uuid": "063881d4-edc5-4102-8214-9b7e11edb9cb",
"name": "app-object-storage",
"description": "app-object-storage",
"zone": "nl-ams1",
"url": "https://063881d4-edc5-4102-8214-9b7e11edb9cb.os.upcloud.host/",
"size": 500,
"used_space": 0,
"state": "started",
"created": "2020-07-23T05:06:35Z"
}
}
Modify Object Storage
Modify requests can be used to update the details of an Object Storage including description, access_key and secret_key.
Request
{
"object_storage": {
"description": "Example object storage",
"access_key": "JT9WE882AZ548P5F1OZ2",
"secret_key": "nYuuz2hp+T+T8OdnX8ZefKcN8+VpyoT23IDrVjzP"
}
}
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| description | 1-255 characters | no | Short description for the Object Storage |
| access_key | 4-255 characters | yes if secret_key given | Access key used to identify user |
| secret_key | 8-255 characters | yes if access_key given | Secret key used to authenticate user |
| size | 250, 500, 1000 | no | Size of Object Storage in gigabytes, can be increased but cannot be decreased |
Normal response
{
"object_storage": {
"uuid": "063881d4-edc5-4102-8214-9b7e11edb9cb",
"name": "Example object storage",
"zone": "fi-hel1",
"url": "https://063881d4-edc5-4102-8214-9b7e11edb9cb.os.upcloud.host/",
"size": 500,
"used_space": 42,
"state": "started",
"created": "2020-07-23T05:06:35Z"
}
}
Error responses
| HTTP status | Error code | Description |
|---|---|---|
| 400 Bad Request | SIZE_INVALID | The attribute size has an invalid value |
| 400 Bad Request | SIZE_INVALID | Size can not be decreased |
| 400 Bad Request | ACCESS_KEY_INVALID | The attribute access_key has an invalid value |
| 400 Bad Request | SECRET_KEY_INVALID | The attribute secret_key has an invalid value |
| 400 Bad Request | DESCRIPTION_INVALID | The attribute description has an invalid value |
| 403 Forbidden | OBJECT_STORAGE_FORBIDDEN | No permission to access details of the specified Object Storage |
| 404 Not Found | OBJECT_STORAGE_NOT_FOUND | Object Storage {uuid} does not exist |
Delete Object Storage
Object Storage devices can be deleted using the following API request. Note that deleting the storage will permanently delete any data on the device and which cannot be reverted.
Request
Normal response
Error responses
| HTTP status | Error code | Description |
|---|---|---|
| 403 Forbidden | OBJECT_STORAGE_FORBIDDEN | No permission to access details of the specified Object Storage |
| 404 Not Found | OBJECT_STORAGE_NOT_FOUND | Object Storage {uuid} does not exist |
Get Object Storage network statistics
The network usage of an Object Storage device is metered and can be reviewed using the statistics request.
Request
Parameters
Statistics queries can be filtered and arranged using a number of query parameters.
| Key | Value | Required | Description |
|---|---|---|---|
| from | {date-time} 2020-01-01T00%3A00%3A00Z | yes | Beginning of time range; RFC 3339 timestamp or negative integer noting hours from current time |
| to | {date-time} 2020-12-31T00%3A00%3A00Z | End of time range, default is current time, format as in from |
|
| interval | {integer} >= 1, <= time range hours | Grouping results by number of hours, default: 1 | |
| bucket | array[string] | Filter results by bucket name | |
| filename | array[string] | Filter results by filename | |
| method | array[string] GET, POST, PATCH, PUT, DELETE | Filter results by HTTP method | |
| status | array[integer] HTTP status codes | Filter results by HTTP status | |
| group_by | array[string] bucket, filename, method, status | Group results by specified properties | |
| order_by | array[string] timestamp, bytes_received, bytes_transmitted, requests, bucket, filename, method, status | Order results by specified properties, default ascending timestamp, descending with - prefix | |
| limit | {integer} | Limit to specified number of results |
Normal response
{
"stats": {
"stat": [
{
"timestamp": "2020-07-21T09:20:25.988Z",
"bucket": "string",
"filename": "string",
"method": "GET",
"status": 0,
"bytes_received": 0,
"bytes_transmitted": 0,
"requests": 0
}
]
}
}
Error responses
| HTTP status | Error code | Description |
|---|---|---|
| 403 Forbidden | OBJECT_STORAGE_FORBIDDEN | No permission to access details of the specified Object Storage |
| 404 Not Found | OBJECT_STORAGE_NOT_FOUND | Object Storage {uuid} does not exist |
Manage buckets and files
Managing an object storage's buckets and file objects is done via the S3 compliant API. The endpoint URL can be found in the API response. Use they access key & secret key that you set when creating the object storage.
You can create your own S3 client or use any of the S3-compliant libraries/software available online. For example, s3cmd is a good command-line client for getting started with S3.