buckets

Creates, updates, deletes, gets or lists a buckets resource.

Overview

Name	buckets
Type	Resource
Id	linode.object_storage.buckets

Fields

The following fields are returned by SELECT queries:

get_object_storage_bucket

The requested bucket.

Name	Datatype	Description
cluster	string	Deprecated The legacy clusterId equivalent for the regionId where this bucket lives. The API maintains this for backward compatibility. > 📘 > > - This value and the regionId are interchangeable when used in requests. Best practice is to use the regionId. > > - This value is empty for newer regions that don't have a legacy clusterId. (example: us-east-1)
created	string (date-time)	When this bucket was created. (example: 2019-01-01T01:23:45)
endpoint_type	string	The type of s3_endpoint available to the active user in this region. See Endpoint types for more information. (example: E1)
hostname	string	The hostname where this bucket can be accessed. This hostname can be accessed through a browser if the bucket is made public. (example: primary-bucket-1.us-east-12.linodeobjects.com)
label	string	The name of this bucket. (example: primary-bucket)
objects	integer	The number of objects stored in this bucket.
region	string	The id of the region where this Object Storage bucket lives. (example: us-east)
s3_endpoint	string	The active user's S3-compatible endpoint URL, based on the endpoint_type and region. (example: us-east-12.linodeobjects.com)
size	integer	The size of the bucket in bytes.

get_object_storage_bucketin_cluster

A paginated list of buckets on your account in this region.

Name	Datatype	Description
data	array
page	integer	Read-only The current page.
pages	integer	Read-only The total number of pages.
results	integer	Read-only The total number of results.

get_object_storage_buckets

A paginated list of buckets you own.

Name	Datatype	Description
data	array
page	integer	Read-only The current page.
pages	integer	Read-only The total number of pages.
results	integer	Read-only The total number of results.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_object_storage_bucket	select			Returns a single Object Storage bucket. > 📘 > > You can use an outside API, such as the Ceph Object Gateway S3 API for more options. OAuth scopes. <br /> object_storage:read_only<br /> Learn more...
get_object_storage_bucketin_cluster	select			Returns a list of buckets on your account, in the specified region. > 📘 > > You can use the Ceph Object Gateway S3 API for more options. OAuth scopes. <br /> object_storage:read_only<br /> Learn more...
get_object_storage_buckets	select			Returns a paginated list of all Object Storage buckets available in your account. > 📘 > > You can use an outside API, such as the Ceph Object Gateway S3 API for more options. OAuth scopes. <br /> object_storage:read_only<br /> Learn more...
post_object_storage_bucket	insert	data__label, data__cluster		Creates an Object Storage bucket in the specified data center (region). If the bucket already exists on your account, this operation returns a 200 response with that bucket as if the API just created it. > 📘 > > - Accounts with negative balances can't access this operation. > > - The API still supports the clusterId equivalent (us-west-1) when setting a region for a new bucket, but you should use the regionId (us-west) instead. > > - You can use an outside API, such as the Ceph Object Gateway S3 API for more options. OAuth scopes. <br /> object_storage:read_write<br /> Learn more...
delete_object_storage_bucket	delete			Removes a single bucket. > 📘 > > - You need to remove all objects from a bucket before you can delete it. While you can delete a bucket using the CLI, this operation fails if the bucket contains too many objects. The best way to empty large buckets is to configure lifecycle policies with an outside API, such as the Ceph Object Gateway S3 API. Set a policy to remove all objects, wait a day or more for the system to remove all objects, then delete the bucket. > > - You can use an outside API, such as the Ceph Object Gateway S3 API for more options. OAuth scopes. <br /> object_storage:read_write<br /> Learn more...
post_object_storage_object_url	exec	name, method		Creates a pre-signed URL to access a single object in a bucket. Use it to share, create, or delete objects by using the appropriate HTTP method in your request body's method parameter. > 📘 > > You can use an outside API, such as the Ceph Object Gateway S3 API for more options. OAuth scopes. <br /> object_storage:read_write<br /> Learn more...

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description

SELECT examples

get_object_storage_bucket

Returns a single Object Storage bucket.

> 📘
>
> You can use an outside API, such as the Ceph Object Gateway S3 API for more options. OAuth scopes.

<br /> object_storage:read_only<br />

Learn more...

SELECT
cluster,
created,
endpoint_type,
hostname,
label,
objects,
region,
s3_endpoint,
size
FROM linode.object_storage.buckets;

get_object_storage_bucketin_cluster

Returns a list of buckets on your account, in the specified region.

> 📘
>
> You can use the Ceph Object Gateway S3 API for more options. OAuth scopes.

<br /> object_storage:read_only<br />

Learn more...

SELECT
data,
page,
pages,
results
FROM linode.object_storage.buckets;

get_object_storage_buckets

Returns a paginated list of all Object Storage buckets available in your account.

> 📘
>
> You can use an outside API, such as the Ceph Object Gateway S3 API for more options. OAuth scopes.

<br /> object_storage:read_only<br />

Learn more...

SELECT
data,
page,
pages,
results
FROM linode.object_storage.buckets;

INSERT examples

post_object_storage_bucket

Creates an Object Storage bucket in the specified data center (region). If the bucket already exists on your account, this operation returns a 200 response with that bucket as if the API just created it.

> 📘
>
> - Accounts with negative balances can't access this operation.
>
> - The API still supports the clusterId equivalent (us-west-1) when setting a region for a new bucket, but you should use the regionId (us-west) instead.
>
> - You can use an outside API, such as the Ceph Object Gateway S3 API for more options. OAuth scopes.

<br /> object_storage:read_write<br />

Learn more...

INSERT INTO linode.object_storage.buckets (
data__acl,
data__cors_enabled,
data__endpoint_type,
data__label,
data__region,
data__s3_endpoint
)
SELECT 
'{{ acl }}',
{{ cors_enabled }},
'{{ endpoint_type }}',
'{{ label }}' --required,
'{{ region }}',
'{{ s3_endpoint }}'
RETURNING
cluster,
created,
endpoint_type,
hostname,
label,
objects,
region,
s3_endpoint,
size
;

Manifest

# Description fields are for documentation purposes
- name: buckets
  props:
    - name: acl
      value: string
      description: >
        The S3 predefined collection of grantees and permissions set for the bucket, also referred to as a [Canned ACL](https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#canned-acl).
        
      valid_values: ['private', 'public-read', 'authenticated-read', 'public-read-write']
      default: private
    - name: cors_enabled
      value: boolean
      description: >
        If set to `false`, cross-origin resource sharing (CORS) is disabled for all origins in the bucket.
        
    - name: endpoint_type
      value: string
      description: >
        The type of `s3_endpoint` available to the active `user` in this `region`. See [Endpoint types](https://techdocs.akamai.com/cloud-computing/docs/object-storage#endpoint-types) for more information.
        
      valid_values: ['E0', 'E1', 'E2', 'E3']
    - name: label
      value: string
      description: >
        The name for this bucket.

* A bucket name can contain from 3 to 63 alphanumeric characters, dashes (`-`), or dots (`.`).
* A bucket name can't end in a dash and you can't use two consecutive dashes.
* A bucket name can't start or end in a dot, and you can't use two consecutive dots. As a best practice, only use dots if a certificate you're using with your bucket requires it. (For example, if you're using a custom TLS certificate.)
* A bucket name needs to be unique in the `region` where you're creating the bucket. The API only reserves labels for the `region` where active buckets are created and stored. If you want to reserve this bucket's label in another `region`, create a new bucket with the same label in the new `region`.
        
    - name: region
      value: string
      description: >
        The `id` assigned to the data center ([region](https://techdocs.akamai.com/linode-api/reference/get-regions)) where this Object Storage bucket should be created.

> 📘
>
> This supports legacy `clusterId` values that represented a specific region. For example, `us-east-1` is the legacy reference for the `us-east` region.
        
    - name: s3_endpoint
      value: string
      description: >
        The active user's S3-compatible endpoint URL, based on the `endpoint_type` and `region`.
        

DELETE examples

delete_object_storage_bucket

Removes a single bucket.

> 📘
>
> - You need to remove all objects from a bucket before you can delete it. While you can delete a bucket using the CLI, this operation fails if the bucket contains too many objects. The best way to empty large buckets is to configure lifecycle policies with an outside API, such as the Ceph Object Gateway S3 API. Set a policy to remove all objects, wait a day or more for the system to remove all objects, then delete the bucket.
>
> - You can use an outside API, such as the Ceph Object Gateway S3 API for more options. OAuth scopes.

<br /> object_storage:read_write<br />

Learn more...

DELETE FROM linode.object_storage.buckets;

Lifecycle Methods

post_object_storage_object_url

Creates a pre-signed URL to access a single object in a bucket. Use it to share, create, or delete objects by using the appropriate HTTP method in your request body's method parameter.

> 📘
>
> You can use an outside API, such as the Ceph Object Gateway S3 API for more options. OAuth scopes.

<br /> object_storage:read_write<br />

Learn more...

EXEC linode.object_storage.buckets.post_object_storage_object_url 
@@json=
'{
"content_type": "{{ content_type }}", 
"expires_in": {{ expires_in }}, 
"method": "{{ method }}", 
"name": "{{ name }}"
}';