Skip to content

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

GET /1.3/object-storage-2/regions HTTP/1.1

Normal response

HTTP/1.1 200 OK
[
    {
        "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

GET /1.3/object-storage-2/regions/{name} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
    "name": "europe-1",
    "primary_zone": "fi-hel1",
    "zones": [
        {
            "name": "fi-hel1"
        },
        {
            "name": "de-fra1"
        }
    ]
}

Create service

Creates a new object storage service.

Request

POST /1.3/object-storage-2 HTTP/1.1
{
    "name": "example-service",
    "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"
        }
    ]
}

Attributes

Attribute Accepted value Required Description
name 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ yes The name of the service must be unique within customer account.
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 no Attached networks from where object storage can be used. Private networks must reside in object storage region.
labels An array of 0-255 labels objects no Labels used for service filtering, see labels usage

Normal response

HTTP/1.1 201 Created

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

GET /1.3/object-storage-2 HTTP/1.1

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.
sort created_at,-created_at -created_at no Order of returned results.

Normal response

HTTP/1.1 200 OK
[
    {
        "configured_status": "started",
        "created_at": "2023-05-07T15:55:24.655776Z",
        "endpoints": [
            {
                "domain_name": "7mf5k.upbucket.com",
                "iam_url": "https://7mf5k.upbucket.com:4443/iam",
                "sts_url": "https://7mf5k.upbucket.com:4443/sts",
                "type": "public"
            },
            {
                "domain_name": "7mf5k-private.upbucket.com",
                "iam_url": "https://7mf5k-private.upbucket.com:4443/iam",
                "sts_url": "https://7mf5k-private.upbucket.com:4443/sts",
                "type": "private"
            }
        ],
        "name": "example-service",
        "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",
        "uuid": "1200ecde-db95-4d1c-9133-6508f3232567"
    }
]

Notes:

Get service details

Returns object storage service details by given {service_uuid}.

Request

GET /1.3/object-storage-2/{service_uuid} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
    "configured_status": "started",
    "created_at": "2023-05-07T15:55:24.655776Z",
    "endpoints": [
        {
            "domain_name": "7mf5k.upbucket.com",
            "iam_url": "https://7mf5k.upbucket.com:4443/iam",
            "sts_url": "https://7mf5k.upbucket.com:4443/sts",
            "type": "public"
        },
        {
            "domain_name": "7mf5k-private.upbucket.com",
            "iam_url": "https://7mf5k-private.upbucket.com:4443/iam",
            "sts_url": "https://7mf5k-private.upbucket.com:4443/sts",
            "type": "private"
        }
    ],
    "name": "example-service",
    "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",
                    "last_used_at": "2023-05-07T20:52:17Z",
                    "status": "Active"
                }
            ],
            "arn": "urn:ecs:iam::123bbb5c6a4240409e07f7d89fe28891:user/example_user",
            "created_at": "2023-05-07T15:55:24.655776Z",
            "policies": [
              {
                "arn": "urn:ecs:iam:::policy/ECSS3FullAccess",
                "name": "ECSS3FullAccess"
              },
              {
                "arn": "urn:ecs:iam:::policy/IAMFullAccess",
                "name": "IAMFullAccess"
              }
            ],
            "username": "example_user"
        }
    ],
    "uuid": "1200ecde-db95-4d1c-9133-6508f3232567"
}

Notes:

Replace service

Replaces existing object storage service by given {service_uuid}.

Request

PUT /1.3/object-storage-2/{service_uuid} HTTP/1.1
{
    "name": "example-service",  
    "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"
        }
    ],
    "labels": [
        {
            "key": "example-label-key", 
            "value": "example-label-value"
        }
    ]
}

Attributes

Attribute Accepted value Required Description
name 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ yes The name of the service must be unique within customer account.
configured_status started / stopped yes 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.
labels An array of 0-255 labels objects no Labels used for service filtering, see labels usage

Normal response

HTTP/1.1 200 OK

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

PATCH /1.3/object-storage-2/{service_uuid} HTTP/1.1
{
    "name": "example-service",
    "configured_status": "started",
    "networks": [
        {
            "name": "example-private-network",
            "uuid": "03aa7245-2ff9-49c8-9f0e-7ca0270d71a4",
            "type": "private",
            "family": "IPv4"
        }
    ],
    "labels": null
}

Attributes

Attribute Accepted value Required Description
name 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ no The name of the service must be unique within customer account.
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.
labels An array of 0-255 labels objects no Labels used for service filtering, see labels usage

Normal response

HTTP/1.1 200 OK

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}. The deletion of a service is permitted only after all buckets and IAM resource (users, policies) within the service have been successfully deleted.

Request

DELETE /1.3/object-storage-2/{service_uuid} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

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

GET /1.3/object-storage-2/{service_uuid}/metrics HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
    "total_objects": 1287,
    "total_size_bytes": 48277239
}

Attributes

Attribute Description
total_objects Total amount of uploaded objects.
total_size_bytes Total size of uploaded objects in bytes.

List bucket metrics

Request

GET /1.3/object-storage-2/{service_uuid}/buckets HTTP/1.1

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

HTTP/1.1 200 OK
[
    {
        "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

GET /1.3/object-storage-2/{service_uuid}/metrics/series HTTP/1.1

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

HTTP/1.1 200 OK
[
    {
        "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

POST /1.3/object-storage-2/{service_uuid}/networks HTTP/1.1

public network:

{
    "name": "example-public-network",
    "type": "public",
    "family": "IPv4"
}

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

HTTP/1.1 201 Created

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

GET /1.3/object-storage-2/{service_uuid}/networks HTTP/1.1

Normal response

HTTP/1.1 200 OK
[
    {
        "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

GET /1.3/object-storage-2/{service_uuid}/networks/{network_name} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
    "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

DELETE /1.3/object-storage-2/{service_uuid}/networks/{network_name} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Resource not found.

List groups

Returns a list of available service groups by given {service_uuid}.

Request

GET /1.3/object-storage-2/{service_uuid}/groups HTTP/1.1

Normal response

HTTP/1.1 200 Ok
[
  {
    "arn": "urn:ecs:iam::1263b59181cc4841969358b08ed70026:group/test-group",
    "created_at": "2024-04-15T16:28:45Z",
    "name": "test-group"
  }
]

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Get group

Get a single group identified by {group_name}.

Request

POST /1.3/object-storage-2/{service_uuid}/groups/{group_name} HTTP/1.1

Normal response

HTTP/1.1 200 Ok
{
  "arn": "urn:ecs:iam::1263b59181cc4841969358b08ed70026:group/test-data",
  "created_at": "2024-04-15T16:28:45Z",
  "name": "test-data"
}

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Create group

Creates an iam group.

Request

POST /1.3/object-storage-2/{service_uuid}/groups HTTP/1.1
{
  "name": "new-group"
}

Attributes

Attribute AcceptedValue Default value Required Description
name 1-128 characters true A valid string to represent the name of the IAM group.

Normal response

HTTP/1.1 201 Created
{
  "arn": "urn:ecs:iam::1263b59181cc4841969358b08ed70026:group/new-group",
  "created_at": "2024-04-16T13:25:56Z",
  "name": "new-group"
}

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Attach user to group

Attaches an iam user to a group identified by {group_name}, and {username}.

Request

POST /1.3/object-storage-2/{service_uuid}/groups/{group_name}/users/{username} HTTP/1.1

Normal response

HTTP/1.1 204 Ok

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Remove user from group

Removes an iam user from the group identified by {group_name}, and {username}.

Request

DELETE /1.3/object-storage-2/{service_uuid}/groups/{group_name}/users/{username} HTTP/1.1

Normal response

HTTP/1.1 204 Ok

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Delete group

Deletes a group identified by {group_name}.

Request

DELETE /1.3/object-storage-2/{service_uuid}/groups/{group_name} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Create policy

Creates a new service policy by given {service_uuid}.

Request

POST /1.3/object-storage-2/{service_uuid}/policies HTTP/1.1
{
  "name": "example-policy",
  "description": "example-description",
  "document": "%7B%22Version%22%3A%20%222012-10-17%22%2C%20%20%22Statement%22%3A%20%5B%7B%22Action%22%3A%20%5B%22iam%3AGetUser%22%5D%2C%20%22Resource%22%3A%20%22%2A%22%2C%20%22Effect%22%3A%20%22Allow%22%2C%20%22Sid%22%3A%20%22editor%22%7D%5D%7D"
}

Attributes

Attribute Accepted value Required Description
name 1-128 characters, regexp pattern [\\w+=,.@-]+ yes The name of the policy must be unique within the service.
description 1-1000 characters no The policy description.
document 1-6144 characters yes A valid policy document, URL-encoded compliant with RFC 3986.

Normal response

HTTP/1.1 201 Created

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 policies

Returns a list of available service policies by given {service_uuid}.

Request

GET /1.3/object-storage-2/{service_uuid}/policies HTTP/1.1

Normal response

HTTP/1.1 200 OK
[
  {
    "arn": "urn:ecs:iam:::policy/ECSDenyAll",
    "attachment_count": 0,
    "created_at": "2024-02-05T11:06:17Z",
    "default_version_id": "v1",
    "description": "Deny all access.",
    "name": "ECSDenyAll",
    "system": true,
    "updated_at": "2024-02-05T11:06:17Z"
  },
  {
    "arn": "urn:ecs:iam:::policy/ECSS3FullAccess",
    "attachment_count": 1,
    "created_at": "2024-02-05T11:06:16Z",
    "default_version_id": "v1",
    "description": "Provides full access to all buckets.",
    "name": "ECSS3FullAccess",
    "system": true,
    "updated_at": "2024-02-05T11:06:16Z"
  },
  {
    "arn": "urn:ecs:iam:::policy/ECSS3ReadOnlyAccess",
    "attachment_count": 0,
    "created_at": "2024-02-05T11:06:16Z",
    "default_version_id": "v1",
    "description": "Provides read only access to all buckets.",
    "name": "ECSS3ReadOnlyAccess",
    "system": true,
    "updated_at": "2024-02-05T11:06:16Z"
  },
  {
    "arn": "urn:ecs:iam:::policy/IAMFullAccess",
    "attachment_count": 1,
    "created_at": "2024-02-05T11:06:16Z",
    "default_version_id": "v1",
    "description": "Provides full access to IAM.",
    "name": "IAMFullAccess",
    "system": true,
    "updated_at": "2024-02-05T11:06:16Z"
  },
  {
    "arn": "urn:ecs:iam:::policy/IAMReadOnlyAccess",
    "attachment_count": 0,
    "created_at": "2024-02-05T11:06:16Z",
    "default_version_id": "v1",
    "description": "Provides read only access to IAM.",
    "name": "IAMReadOnlyAccess",
    "system": true,
    "updated_at": "2024-02-05T11:06:16Z"
  }
]

Get policy details

Returns service policy details by given {service_uuid} and {policy_name}.

Request

GET /1.3/object-storage-2/{service_uuid}/policies/{policy_name} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
  "arn": "urn:ecs:iam:::policy/ECSS3FullAccess",
  "attachment_count": 0,
  "created_at": "2024-02-05T11:06:16Z",
  "default_version_id": "v1",
  "description": "Provides full access to all buckets.",
  "document": "%7B%0A++++%22Version%22%3A+%222012-10-17%22%2C%0A++++%22Statement%22%3A+%5B%0A++++++++%7B%0A++++++++++++%22Effect%22%3A+%22Allow%22%2C%0A++++++++++++%22Action%22%3A+%22s3%3A*%22%2C%0A++++++++++++%22Resource%22%3A+%22*%22%0A++++++++%7D%0A++++%5D%0A%7D",
  "name": "ECSS3FullAccess",
  "system": true,
  "updated_at": "2024-02-05T11:06:16Z"
}

Note: The policy document, URL-encoded compliant with RFC 3986.

Delete policy

Deletes existing policy by given {service_uuid} and {policy_name}.

Request

DELETE /1.3/object-storage-2/{service_uuid}/policies/{policy_name} HTTP/1.1

List IAM Group Policies

Lists IAM policies attached to a group, identified by {service_uuid}, and {group_name}.

Request

POST /1.3/object-storage-2/{service_uuid}/groups/{group_name}/policies HTTP/1.1
{
  "name": "policy-name"
}

Attributes

Attribute AcceptedValue Default value Required Description
name 1-128 characters true A valid string to represent the name of the IAM group.

Normal response

HTTP/1.1 200 Ok
[
  {
    "arn": "urn:ecs:iam::1263b59181cc4841969358b08ed70026:policy/test-policy",
    "name": "test-policy"
  }
]

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Resource not found.

Attach IAM Group Policy

Attaches a policy to a group, identified by {service_uuid}, and {group_name}.

Request

GET /1.3/object-storage-2/{service_uuid}/groups/{group_name}/policies HTTP/1.1
{
  "name": "policy-name"
}

Attributes

Attribute AcceptedValue Default value Required Description
name 1-128 characters true A valid string to represent the name of the IAM group.

Normal response

HTTP/1.1 204 No Content

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Resource not found.

Detach IAM Group Policy

Detaches a policy from a group, identified by {service_uuid}, and {group_name}.

Request

DELETE /1.3/object-storage-2/{service_uuid}/groups/{group_name}/policies/{policy_name} HTTP/1.1

Attributes

Attribute AcceptedValue Default value Required Description
name 1-128 characters true A valid string to represent the name of the IAM group.

Normal response

HTTP/1.1 204 No Content

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Resource not found.

Create policy version

Creates a policy version by the given {service_uuid}, and {policy_name}.

Request

POST /1.3/object-storage-2/{service_uuid}/policies/{policy_name}/versions HTTP/1.1
{
  "document": "%7B%22Version%22%3A%222012-10-17%22%2C%22Statement%22%3A%5B%7B%22Action%22%3A%5B%22%2A%22%5D%2C%22Effect%22%3A%22Deny%22%2C%22Resource%22%3A%22%2A%22%7D%5D%7D",
  "is_default": true
}
{
  "document": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Action\":[\"*\"],\"Effect\":\"Deny\",\"Resource\":\"*\"}]}",
  "is_default": true
}

Attributes

Attribute AcceptedValue Default value Required Description
document 1-6144 characters true A valid policy document, URL-encoded compliant with RFC 3986.
is_default true / false false false Determines if the newly created policy version will be set as the default.

Normal response

HTTP/1.1 201 Created
{
  "create_date": "2024-03-27T17:24:38.000071+02:00",
  "document": "%7B%22Version%22%3A%222012-10-17%22%2C%22Statement%22%3A%5B%7B%22Action%22%3A%5B%22%2A%22%5D%2C%22Effect%22%3A%22Deny%22%2C%22Resource%22%3A%22%2A%22%7D%5D%7D",
  "is_default": true,
  "version_id": "v2"
}

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

List policy versions

Lists policy versions given by {service_uuid}, and {policy_name}.

Request

GET /1.3/object-storage-2/{service_uuid}/policies/{policy_name}/versions HTTP/1.1

Normal response

HTTP/1.1 200 Ok
[
  {
    "create_date": "2024-03-25T12:47:40Z",
    "document": "%7B%22Version%22%3A%222012-10-17%22%2C%22Statement%22%3A%5B%7B%22Action%22%3A%5B%22*%22%5D%2C%22Resource%22%3A%22*%22%2C%22Effect%22%3A%22Deny%22%7D%5D%7D",
    "is_default": false,
    "version_id": "v4"
  },
  {
    "create_date": "2024-03-25T12:47:38Z",
    "document": "%7B%22Version%22%3A%222012-10-17%22%2C%22Statement%22%3A%5B%7B%22Action%22%3A%5B%22*%22%5D%2C%22Resource%22%3A%22*%22%2C%22Effect%22%3A%22Deny%22%7D%5D%7D",
    "is_default": false,
    "version_id": "v3"
  }
]

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Get policy version

Get a single policy version by the given {service_uuid}, {policy_name}, and {policy_version}.

Request

POST /1.3/object-storage-2/{service_uuid}/policies/{policy_name}/versions/{policy_version} HTTP/1.1

Normal response

HTTP/1.1 200 Ok
{
  "create_date": "2024-03-27T17:24:38.000071+02:00",
  "document": "%7B%22Version%22%3A%222012-10-17%22%2C%22Statement%22%3A%5B%7B%22Action%22%3A%5B%22%2A%22%5D%2C%22Effect%22%3A%22Deny%22%2C%22Resource%22%3A%22%2A%22%7D%5D%7D",
  "is_default": true,
  "version_id": "v2"
}

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Delete a policy version

Deletes a policy version by the given {service_uuid}, {policy_name}, and {policy_version}.

Request

DELETE /1.3/object-storage-2/{service_uuid}/policies/{policy_name}/versions/{policy_version} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

Http status Accepted Values Default AcceptedValue
400 Bad Request INVALID_REQUEST Validation error.

Create user

Creates a new service user by given {service_uuid}.

Request

POST /1.3/object-storage-2/{service_uuid}/users HTTP/1.1
{
    "username": "example_user"
}

Response

{
    "access_keys": [],
    "created_at": "2023-05-07T18:19:16.507681Z",
    "policies": [],
    "username": "example_user"
}

Attributes

Attribute Accepted value Required Description
username 1-64 characters, regexp pattern [\\w+=,.@-]+ yes The name of the user to create.

Normal response

HTTP/1.1 201 Created

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

GET /1.3/object-storage-2/{service_uuid}/users HTTP/1.1

Normal response

HTTP/1.1 200 OK
[
    {
        "access_keys": [
            {
                "access_key_id": "AKIA63F41D01345BB477",
                "created_at": "2023-05-07T20:52:19.705405Z",
                "last_used_at": "2023-05-07T20:52:17Z",
                "status": "Active"
            }
        ],
        "arn": "urn:ecs:iam::123bbb5c6a4240409e07f7d89fe28891:user/example_user",
        "created_at": "2023-05-07T15:55:24.655776Z",
        "policies": [
            {
                "arn": "urn:ecs:iam:::policy/ECSS3FullAccess",
                "name": "ECSS3FullAccess"
            },
            {
                "arn": "urn:ecs:iam:::policy/IAMFullAccess",
                "name": "IAMFullAccess"
            }
        ],
        "username": "example_user"
    }
]

Get user details

Returns service user details by given {service_uuid} and {username}.

Request

GET /1.3/object-storage-2/{service_uuid}/users/{username} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
    "access_keys": [
        {
            "access_key_id": "AKIA63F41D01345BB477",
            "created_at": "2023-05-07T20:52:19.705405Z",
            "last_used_at": "2023-05-07T20:52:17Z",
            "status": "Active"
        }
    ],
    "arn": "urn:ecs:iam::123bbb5c6a4240409e07f7d89fe28891:user/example_user",
    "created_at": "2023-05-07T15:55:24.655776Z",
    "policies": [
        {
            "arn": "urn:ecs:iam:::policy/ECSS3FullAccess",
            "name": "ECSS3FullAccess"
        },
        {
            "arn": "urn:ecs:iam:::policy/IAMFullAccess",
            "name": "IAMFullAccess"
        }
    ],
    "username": "example_user"
}

Delete user

Deletes existing user by given {service_uuid} and {username}.

Request

DELETE /1.3/object-storage-2/{service_uuid}/users/{username} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

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

POST /1.3/object-storage-2/{service_uuid}/users/{username}/access-keys HTTP/1.1

Normal response

HTTP/1.1 201 Created
{
    "access_key_id": "AKIA589142A152F5E423",
    "created_at": "2023-05-07T22:58:26.239729Z",
    "last_used_at": "2023-05-07T22:58:26.239729Z",
    "secret_access_key": "xbINHFALkXjFjmxhAYL8mJnODRDX91OM7cCd2+1Y",
    "status": "Active"
}

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

GET /1.3/object-storage-2/{service_uuid}/users/{username}/access-keys HTTP/1.1

Normal response

HTTP/1.1 200 OK
[
    {
        "access_key_id": "AKIA63F41D01345BB477",
        "created_at": "2023-05-07T20:52:19.705405Z",
        "last_used_at": "2023-05-07T20:52:17Z",
        "status": "Active"
    }
]

Get access key details

Returns access key details by given {service_uuid} and {username} and {access-key-id}.

Request

GET /1.3/object-storage-2/{service_uuid}/users/{username}/access-keys/{access-key-id} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
    "access_key_id": "AKIA63F41D01345BB477",
    "created_at": "2023-05-07T20:52:19.705405Z",
    "last_used_at": "2023-05-07T20:52:17Z",
    "status": "Active"
}

Modify access key details

Modifies access key details by given {service_uuid} and {username} and {access-key-id}.

Request

PATCH /1.3/object-storage-2/{service_uuid}/users/{username}/access-keys/{access-key-id} HTTP/1.1
{
    "status": "Inactive"
}

Attributes

Attribute Accepted value Required Description
status Active/Inactive no Indicates is the key active or inactive.

Normal response

HTTP/1.1 200 OK

Delete access key

Deletes existing access key by given {service_uuid} and {username} and {access-key-id}.

Request

DELETE /1.3/object-storage-2/{service_uuid}/users/{username}/access-keys/{access-key-id} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Resource not found.

List attached user policies

Returns a list of attached user policies by given {service_uuid} or {username}.

Request

GET /1.3/object-storage-2/{service_uuid}/users/{username}/policies HTTP/1.1

Normal response

HTTP/1.1 200 OK
[
  {
    "arn": "urn:ecs:iam:::policy/ECSS3FullAccess",
    "name": "ECSS3FullAccess"
  },
  {
    "arn": "urn:ecs:iam:::policy/IAMFullAccess",
    "name": "IAMFullAccess"
  }
]

Attach user policy

Attach a policy by given {service_uuid} and {username}.

Request

POST /1.3/object-storage-2/{service_uuid}/users/{username}/policies HTTP/1.1
{
  "name": "ECSS3FullAccess"
}

Attributes

Attribute Accepted value Required Description
name Policy name yes A valid policy name.

Normal response

HTTP/1.1 200 Ok

Detach user policy

Detach a policy by given {service_uuid}, {username} and {policy_name}.

Request

DELETE /1.3/object-storage-2/{service_uuid}/users/{username}/policies/{policy_name} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

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
POST /1.3/object-storage-2/{service_uuid}/labels HTTP/1.1
{
    "key": "foo",
    "value": "bar"
}

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

HTTP/1.1 201 Created

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

GET /1.3/object-storage-2/{service_uuid}/labels HTTP/1.1

Normal response

HTTP/1.1 200 OK
[
    {
        "key": "env",
        "value": "staging"
    },
    {
        "key": "foo",
        "value": "bar"
    }
]

Get label details

Returns label details by given {service_uuid} and {key}.

Request

GET /1.3/object-storage-2/{service_uuid}/labels/{key} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
    "key": "env",
    "value": "staging"  
}

Modify label

Modifies existing label by given {service_uuid} and {key}.

Request

PATCH /1.3/object-storage-2/{service_uuid}/labels/{key} HTTP/1.1
{
    "key": "env",
    "value": "production"
}

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

HTTP/1.1 200 OK

Delete label

Deletes existing label by given {service_uuid} and {key}.

Request

DELETE /1.3/object-storage-2/{service_uuid}/labels/{key} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

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-network Configuring network.
setup-tls Configuring TLS certificates.
setup-public-endpoint Configuring public endpoint.
setup-private-endpoint Configuring private endpoint.
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-private-endpoint Removing public endpoint.
delete-public-endpoint Removing private endpoint.
delete-tls Removing TLS certificates.
delete-network Reconfiguring network.
delete-service Deleting the service.