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:

• Please see service configured statuses and operational states description.

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:

• Please see service configured statuses and operational states description.

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.

Create bucket

Creates a new service bucket by the given {service_uuid}.

Request

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

{
  "name": "my-bucket-1"
}

Attributes

Attribute	AcceptedValue	Default value	Required	Description
name	1-254 characters		true	A valid string to represent the name of the bucket.

Normal response

HTTP/1.1 201 Created

{
  "name": "my-bucket-1", 
  "total_objects": 0, 
  "total_size_bytes": 0
}

Error response

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

Delete bucket

Deletes an existing bucket by given {service_uuid} and {bucket_name}. This API call will remove all objects from the bucket permanently and cannot be reversed.

Request

DELETE /1.3/object-storage-2/{service_uuid}/buckets/{bucket_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.

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 printable ASCII characters (range 0x20-0x7E), must not start with _	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 printable ASCII characters (range 0x20-0x7E), must not start with _	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.

Attach custom domain

Attaches a new custom domain to the service identified by {service_uuid}.

A maximum of 5 custom domains can be added per service.

DNS records setup

To attach a custom domain, public access to the service must be enabled and DNS records must contain the following CNAME records. Assume the service has public endpoint zzzzz.upcloudobjects.com and custom domain to be attached is objects.example.com, these are the expected records under example.com domain:

Type	Host	Target
CNAME	objects	zzzzz.upcloudobjects.com
CNAME	*.objects	zzzzz.upcloudobjects.com
CNAME	_acme-challenge.objects	Domain obtained from DNS challenge request e.g. _acme-challenge.xxxxx.upcloudlb.com or such

Request

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

{
    "domain_name": "objects.example.com",
    "type": "public"
}

Attributes

Attribute	Accepted value	Required	Description
domain_name	Must be a subdomain and consist of 3 to 5 parts such as objects.example.com. Cannot be root-level domain e.g. example.com.	yes	Custom domain to be added.
type	At the moment only public is accepted.	yes	Type of the custom domain.

Normal response

HTTP/1.1 201 Created

Error response

HTTP status	Error code	Description
400 Bad Request	INVALID_REQUEST	Validation error.

Get custom domain details

Returns custom domain details by given {service_uuid} and {domain_name}.

Request

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

Normal response

HTTP/1.1 200 OK

{
    "domain_name": "objects.example.com",
    "type": "public"
}

Error response

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

List custom domains

Returns a list of custom domains attached to a service by given {service_uuid}.

Request

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

Normal response

HTTP/1.1 200 OK

[
   {
        "domain_name": "objects.example.com",
        "type": "public"
    },
    {
        "domain_name": "object2.example.com",
        "type": "public"
    }
]

Error response

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

Delete custom domain

Deletes existing custom domain by given {service_uuid} and {domain_name}.

Request

DELETE /1.3/object-storage-2/{service_uuid}/custom-domains/{domain_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.

Modify custom domain

Modifies existing custom domain by given {service_uuid} and {domain_name}.

Request

PATCH /1.3/object-storage-2/{service_uuid}/custom-domains/{domain_name} HTTP/1.1

{
    "domain_name": "objects.example.com",
    "type": "public"
}

Attributes

Attribute	Accepted value	Required	Description
domain_name	Must be a subdomain and consist of 3 to 5 parts such as objects.example.com. Cannot be root-level domain e.g. example.com.	yes	New modified custom domain.
type	At the moment only public is accepted.	yes	Type of the custom domain.

Normal response

HTTP/1.1 200 OK

{
    "domain_name": "objects.example.com",
    "type": "public"
}

Error response

HTTP status	Error code	Description
400 Bad Request	INVALID_REQUEST	Validation error.
404 Not Found	RESOURCE_NOT_FOUND	Resource not found.