21. Managed Object Storage
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. Managed 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. All customers data is encrypted by default using encryption at rest.
Managed Object Storage API commands allow creation, management and deletion of Object Storage devices as well as viewing Object Storage network data usage. Managed Object Storage is fully S3-compliant allowing file and bucket management using existing S3 clients.
API follows JSON Merge Patch semantics. Note when modifying nested structures payload should contain entire array, which in a sense is PUT within PATCH for them.
JSON Merge Patch uses null to explicitly indicate property deletion while absent properties are ignored, i.e. not modified.
List regions
Returns a list of available managed object storage regions.
Request
Normal response
[
{
"name": "europe-1",
"primary_zone": "fi-hel1",
"zones": [
{
"name": "fi-hel1"
},
{
"name": "de-fra1"
}
]
}
]
Get region details
Returns object storage region details by given {name}.
Request
Normal response
{
"name": "europe-1",
"primary_zone": "fi-hel1",
"zones": [
{
"name": "fi-hel1"
},
{
"name": "de-fra1"
}
]
}
Create service
Creates a new object storage service.
Request
{
"region": "example",
"configured_status": "started",
"networks": [
{
"name": "example-public-network",
"type": "public",
"family": "IPv4"
},
{
"name": "example-private-network",
"uuid": "03aa7245-2ff9-49c8-9f0e-7ca0270d71a4",
"type": "private",
"family": "IPv4"
}
],
"users": [
{
"username": "example_user"
}
]
}
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| region | A valid region identifier, e.g. europe-1 |
yes | Region in which the service will be hosted, see regions. |
| configured_status | started / stopped |
yes | Service status managed by the customer. |
| networks | An array of 0-8 network objects | yes | Attached networks from where object storage can be used. Private networks must reside in object storage region. |
| users | An array of 0-50 user objects | yes | List of cloud Users allowed to use object storage. |
| labels | An array of 0-255 labels objects | no | Labels used for service filtering, see labels usage |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
List services
Returns a list of object storage services.
Request
Query parameters
| Attribute | Accepted value | Default value | Required | Description |
|---|---|---|---|---|
| limit | 0-100 | 10 | no | Number of entries to receive at most. |
| offset | >= 0 | 0 | no | Offset for retrieved results. |
Normal response
[
{
"configured_status": "started",
"created_at": "2023-05-07T15:55:24.655776Z",
"endpoints": [
{
"domain_name": "7mf5k.upbucket.com",
"type": "public"
},
{
"domain_name": "7mf5k-private.upbucket.com",
"type": "private"
}
],
"networks": [
{
"family": "IPv4",
"name": "example-public-network",
"type": "public"
},
{
"family": "IPv4",
"name": "example-private-network",
"type": "private",
"uuid": "03aa7245-2ff9-49c8-9f0e-7ca0270d71a4"
}
],
"operational_state": "running",
"region": "europe-1",
"updated_at": "2023-05-07T21:38:15.757405Z",
"users": [
{
"access_keys": [
{
"access_key_id": "AKIA63F41D01345BB477",
"created_at": "2023-05-07T20:52:19.705405Z",
"enabled": true,
"last_used_at": "2023-05-07T20:52:17Z",
"name": "example-access-key",
"updated_at": "2023-05-07T21:06:18.81511Z"
}
],
"created_at": "2023-05-07T15:55:24.655776Z",
"operational_state": "ready",
"updated_at": "2023-05-07T16:48:14.744079Z",
"username": "example_user"
}
],
"uuid": "1200ecde-db95-4d1c-9133-6508f3232567"
}
]
Notes:
- Please see service configured statuses and operational states description.
Get service details
Returns object storage service details by given {service_uuid}.
Request
Normal response
{
"configured_status": "started",
"created_at": "2023-05-07T15:55:24.655776Z",
"endpoints": [
{
"domain_name": "7mf5k.upbucket.com",
"type": "public"
},
{
"domain_name": "7mf5k-private.upbucket.com",
"type": "private"
}
],
"networks": [
{
"family": "IPv4",
"name": "example-public-network",
"type": "public"
},
{
"family": "IPv4",
"name": "example-private-network",
"type": "private",
"uuid": "03aa7245-2ff9-49c8-9f0e-7ca0270d71a4"
}
],
"operational_state": "running",
"region": "europe-1",
"updated_at": "2023-05-07T21:38:15.757405Z",
"users": [
{
"access_keys": [
{
"access_key_id": "AKIA63F41D01345BB477",
"created_at": "2023-05-07T20:52:19.705405Z",
"enabled": true,
"last_used_at": "2023-05-07T20:52:17Z",
"name": "example-access-key",
"updated_at": "2023-05-07T21:06:18.81511Z"
}
],
"created_at": "2023-05-07T15:55:24.655776Z",
"operational_state": "ready",
"updated_at": "2023-05-07T16:48:14.744079Z",
"username": "example_user"
}
],
"uuid": "1200ecde-db95-4d1c-9133-6508f3232567"
}
Notes:
- Please see service configured statuses and operational states description.
Replace service
Replaces existing object storage service by given {service_uuid}.
Request
{
"configured_status": "started",
"networks": [
{
"name": "example-public-network",
"type": "public",
"family": "IPv4"
},
{
"name": "example-private-network",
"uuid": "03aa7245-2ff9-49c8-9f0e-7ca0270d71a4",
"type": "private",
"family": "IPv4"
}
],
"users": [
{
"username": "example_user"
}
],
"labels": [
{
"key": "example-label-key",
"value": "example-label-value"
}
]
}
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| configured_status | started / stopped |
yes | Service status managed by the customer. |
| networks | An array of 0-8 network objects | yes | Attached networks from where object storage can be used. Private networks must reside in object storage region. |
| users | An array of 0-50 user objects | yes | List of cloud Users allowed to use object storage. |
| labels | An array of 0-255 labels objects | no | Labels used for service filtering, see labels usage |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
| 404 Not Found | RESOURCE_NOT_FOUND | Service with provided UUID not found. |
Modify service
Modifies existing object storage service by given {service_uuid}.
Request
{
"configured_status": "started",
"networks": [
{
"name": "example-private-network",
"uuid": "03aa7245-2ff9-49c8-9f0e-7ca0270d71a4",
"type": "private",
"family": "IPv4"
}
],
"users": [
{
"username": "example_user_1"
},
{
"username": "example_user_2"
}
],
"labels": null
}
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| configured_status | started / stopped |
no | Service status managed by the customer. |
| networks | An array of 0-8 network objects | no | Attached networks from where object storage can be used. Private networks must reside in object storage region. |
| users | An array of 0-50 user objects | no | List of cloud Users allowed to use object storage. |
| labels | An array of 0-255 labels objects | no | Labels used for service filtering, see labels usage |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
| 404 Not Found | RESOURCE_NOT_FOUND | Service with provided UUID not found. |
Delete service
Deletes existing object storage service by given {service_uuid}.
Request
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 404 Not Found | RESOURCE_NOT_FOUND | Service with provided UUID not found. |
Get service metrics
Returns object storage metrics by given {service_uuid}.
Request
Normal response
Attributes
| Attribute | Description |
|---|---|
| total_objects | Total amount of uploaded objects. |
| total_size_bytes | Total size of uploaded objects in bytes. |
List bucket metrics
Request
Query parameters
| Attribute | Accepted value | Default value | Required | Description |
|---|---|---|---|---|
| limit | 0-100 | 10 | no | Number of entries to receive at most. |
| offset | >= 0 | 0 | no | Offset for retrieved results. |
Normal response
[
{
"name": "example-bucket-1",
"total_objects": 157,
"total_size_bytes": 5293771
},
{
"name": "example-bucket-2",
"total_objects": 12,
"total_size_bytes": 832226
}
]
List service metrics series
Returns Object Storage instance metrics series by a given {service_uuid}.
Request
Query parameters
| Attribute | Accepted value | Default value | Required | Description |
|---|---|---|---|---|
| from | RFC 3339 timestamp | 24 hours ago | no | Beginning of the time range for which to return metrics. |
| to | RFC 3339 timestamp | Current time | no | End of the time range for which to return metrics. |
| interval | 1h-24h string |
1h |
no | Metrics aggregation interval. |
| sort | start_at,-start_at |
-start_at |
no | Order of returned results. |
| limit | 0-100 | 10 |
no | Number of entries to receive at most. |
| offset | >=0 | 0 |
no | Offset for retrieved results. |
Normal response
[
{
"bytes_created": 530000,
"bytes_deleted": 244000,
"bytes_received": 530000,
"bytes_total": 7502000,
"bytes_transmitted": 0,
"end_at": "2023-10-31T12:00:00Z",
"objects_created": 79,
"objects_deleted": 40,
"objects_total": 1237,
"start_at": "2023-10-31T11:00:00Z"
},
{
"bytes_created": 490000,
"bytes_deleted": 248000,
"bytes_received": 490000,
"bytes_total": 7216000,
"bytes_transmitted": 0,
"end_at": "2023-10-31T11:00:00Z",
"objects_created": 79,
"objects_deleted": 40,
"objects_total": 1198,
"start_at": "2023-10-31T10:00:00Z"
},
{
"bytes_created": 494000,
"bytes_deleted": 190000,
"bytes_received": 494000,
"bytes_total": 6974000,
"bytes_transmitted": 0,
"end_at": "2023-10-31T10:00:00Z",
"objects_created": 82,
"objects_deleted": 36,
"objects_total": 1159,
"start_at": "2023-10-31T09:00:00Z"
}
]
Attributes
| Attribute | Description |
|---|---|
| bytes_total | Total size of data stored as of end_at, in bytes. |
| bytes_created | Bytes created within the time interval marked by start_at and end_at. |
| bytes_deleted | Bytes deleted within the time interval marked by start_at and end_at. |
| bytes_received | Bytes received within the time interval marked by start_at and end_at. |
| bytes_transmitted | Bytes transmitted within the time interval marked by start_at and end_at. |
| objects_total | Total number of objects as of end_at. |
| objects_created | Number of objects created within the time interval marked by start_at and end_at. |
| objects_deleted | Number of objects deleted within the time interval marked by start_at and end_at. |
| start_at | The timestamp marking the start of the data aggregation interval, inclusive. |
| end_at | The timestamp marking the end of the data aggregation interval, exclusive. |
Create network
Creates a new service network by given {service_uuid}.
Request
public network:
or private network:
{
"name": "example-private-network",
"uuid": "03bec0ad-85c3-459e-824d-710f8f24f740",
"type": "private",
"family": "IPv4"
}
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ |
yes | The name of the network must be unique within the service. |
| uuid | A valid network uuid | yes | Private network uuid. For public networks the field should be omitted. |
| type | public / private |
yes | The type of the network. |
| family | IPv4 |
yes | Network family. IPv6 currently not supported. |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
List networks
Returns a list of available service networks by given {service_uuid}.
Request
Normal response
[
{
"family": "IPv4",
"name": "example-public-network",
"type": "public"
},
{
"family": "IPv4",
"name": "example-private-network",
"type": "private",
"uuid": "03aa7245-2ff9-49c8-9f0e-7ca0270d71a4"
}
]
Get network details
Returns service network details by given {service_uuid} and {network_name}.
Request
Normal response
{
"family": "IPv4",
"name": "example-private-network",
"type": "private",
"uuid": "03bec0ad-85c3-459e-824d-710f8f24f740"
}
Delete network
Deletes existing network by given {service_uuid} and {network_name}.
Request
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 404 Not Found | RESOURCE_NOT_FOUND | Resource not found. |
Create user
Creates a new service user by given {service_uuid}.
Request
Response
{
"access_keys": [],
"created_at": "2023-05-07T18:19:16.507681Z",
"operational_state": "pending",
"updated_at": "2023-05-07T18:19:16.507681Z",
"username": "example_user"
}
Note: check out list of User operational states.
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| username | Valid cloud user username | yes | The username of cloud main or sub account user. |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
List users
Returns a list of available service users by given {service_uuid}.
Request
Normal response
[
{
"access_keys": [
{
"access_key_id": "AKIA63F41D01345BB477",
"created_at": "2023-05-07T20:52:19.705405Z",
"enabled": true,
"last_used_at": "2023-05-07T20:52:17Z",
"name": "example-access-key",
"updated_at": "2023-05-07T21:06:18.81511Z"
}
],
"created_at": "2023-05-07T15:55:24.655776Z",
"operational_state": "ready",
"updated_at": "2023-05-07T16:48:14.744079Z",
"username": "example_user"
}
]
Get user details
Returns service user details by given {service_uuid} and {username}.
Request
Normal response
{
"access_keys": [
{
"access_key_id": "AKIA63F41D01345BB477",
"created_at": "2023-05-07T20:52:19.705405Z",
"enabled": true,
"last_used_at": "2023-05-07T20:52:17Z",
"name": "example-access-key",
"updated_at": "2023-05-07T21:06:18.81511Z"
}
],
"created_at": "2023-05-07T15:55:24.655776Z",
"operational_state": "ready",
"updated_at": "2023-05-07T16:48:14.744079Z",
"username": "example_user"
}
Delete user
Deletes existing user by given {service_uuid} and {username}.
Request
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 404 Not Found | RESOURCE_NOT_FOUND | Resource not found. |
Create access key
Creates a new access key by given {service_uuid} and {username}.
Request
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ |
yes | The name of the access key must be unique within the user. |
| enabled | true/false |
no | Indicates is the key active or inactive. |
Normal response
{
"access_key_id": "AKIA589142A152F5E423",
"created_at": "2023-05-07T22:58:26.239729Z",
"enabled": true,
"last_used_at": "2023-05-07T22:58:26.239729Z",
"name": "example-access-key",
"secret_access_key": "xbINHFALkXjFjmxhAYL8mJnODRDX91OM7cCd2+1Y",
"updated_at": "2023-05-07T22:58:26.239729Z"
}
Note: customer can get secret_access_key only once on access key creation. UpCloud doesn't store customers secret keys.
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
List access keys
Returns a list of available access keys by given {service_uuid} or {username}.
Request
Normal response
[
{
"access_key_id": "AKIA63F41D01345BB477",
"created_at": "2023-05-07T20:52:19.705405Z",
"enabled": true,
"last_used_at": "2023-05-07T20:52:17Z",
"name": "main1",
"updated_at": "2023-05-07T20:52:27.675144Z"
}
]
Get access key details
Returns access key details by given {service_uuid} and {username} and {access-key-name}.
Request
Normal response
{
"access_key_id": "AKIA63F41D01345BB477",
"created_at": "2023-05-07T20:52:19.705405Z",
"enabled": true,
"last_used_at": "2023-05-07T20:52:17Z",
"name": "example-access-key",
"updated_at": "2023-05-07T20:52:27.675144Z"
}
Modify access key details
Modifies access key details by given {service_uuid} and {username} and {access-key-name}.
Request
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ |
no | The name of the access key must be unique within the user. |
| enabled | true/false |
no | Indicates is the key active or inactive. |
Normal response
Delete access key
Deletes existing access key by given {service_uuid} and {username} and {access-key-name}.
Request
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 404 Not Found | RESOURCE_NOT_FOUND | Resource not found. |
Create label
Creates a new label by given {service_uuid}.
Labels used for service filtering.
Labels usage examples
Below are some examples of what certain GET requests might look like.
- exact match:
GET /1.3/object-storage-2?label=env%3Dstaging - existence:
GET /1.3/object-storage-2?label=env - multiple:
GET /1.3/object-storage-2?label=env&label=foo%3Dbar
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| key | 2-32 characters, regexp pattern ^([a-zA-Z0-9])+([a-zA-Z0-9_-])*$ |
yes | Represents the label identifier. The key is unique within a service. |
| value | 0-255 characters, regexp pattern \A[\p{L}\p{N}\p{P}\p{S}\p{M}\p{Z}]*\z |
yes | Represents the label value. |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
List labels
Returns a list of available service labels by given {service_uuid}.
Request
Normal response
Get label details
Returns label details by given {service_uuid} and {key}.
Request
Normal response
Modify label
Modifies existing label by given {service_uuid} and {key}.
Request
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| key | 2-32 characters, regexp pattern ^([a-zA-Z0-9])+([a-zA-Z0-9_-])*$ |
no | Represents the label identifier. The key is unique within a service. |
| value | 0-255 characters, regexp pattern \A[\p{L}\p{N}\p{P}\p{S}\p{M}\p{Z}]*\z / null |
no | Represents the label value. |
Normal response
Delete label
Deletes existing label by given {service_uuid} and {key}.
Request
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 404 Not Found | RESOURCE_NOT_FOUND | Resource not found. |
Service configured status
The service configured status indicates the service's current intended status. Managed by the customer.
| Status | Description |
|---|---|
| started | The service is running. |
| stopped | The service is stopped. |
Service operational state
The service operational state indicates the service's current operational, effective state. Managed by the system.
| State | Description |
|---|---|
| pending | Indicates newly created service or started reconfiguration. |
| setup-service | Configuring service. |
| setup-user | Configuring object storage users. |
| setup-network | Configuring network. |
| setup-dns | Updating DNS records. |
| setup-checkup | Verifying object storage correctly configured and running. |
| running | Indicates service up and running. |
| stopped | Indicates service is down. |
| delete-dns | Removing DNS records. |
| delete-network | Reconfiguring network. |
| delete-user | Deleting object storage users. |
| delete-service | Deleting the service. |
User operational state
The user operational state indicates the user's current operational, effective state. Managed by the system.
| State | Description |
|---|---|
| pending | Indicates newly attached user. |
| ready | The user configured and ready access keys issuing. |