Create an S3 bucket configuration for an SVM
POST /protocols/s3/buckets
Introduced In: 9.8
Creates the S3 bucket configuration of an SVM.
Important notes
- 
Each SVM can have one or more bucket configurations.
 - 
Aggregate lists should be specified explicitly. If not specified, then the bucket is auto-provisioned as a FlexGroup volume.
 - 
Constituents per aggregate specifies the number of components (or FlexVol volumes) per aggregate. Is specified only when an aggregate list is explicitly defined.
 - 
An access policy can be created along with a bucket create. If creating an access policy fails, bucket configurations are saved and the access policy can be created using the PATCH endpoint.
 - 
"qos_policy" can be specified if a bucket needs to be attached to a QoS group policy during creation time.
 - 
"audit_event_selector" can be specified if a bucket needs to be specify access and permission type for auditing.
 
Required properties
- 
svm.uuid or svm.name- Existing SVM in which to create the bucket configuration. - 
name- Bucket name that is to be created. 
Recommended optional properties
- 
aggregates- List of aggregates for the FlexGroup volume on which the bucket is hosted on. - 
constituents_per_aggregate- Number of constituents per aggregate. - 
size- Specifying the bucket size is recommended. - 
policy- Specifying a policy enables users to perform operations on buckets; specifying the resource permissions is recommended. - 
qos_policy- A QoS policy for buckets. - 
audit_event_selector- Audit policy for buckets. - 
versioning_state- Versioning state for buckets. 
Default property values
- 
size- 800MB - 
comment- "" - 
aggregates- No default value. - 
constituents_per_aggregate- 4 , if an aggregates list is specified. Otherwise, no default value. - 
policy.statements.actions- GetObject, PutObject, DeleteObject, ListBucket, ListBucketMultipartUploads, ListMultipartUploadParts, GetObjectTagging, PutObjectTagging, DeleteObjectTagging, GetBucketVersioning, PutBucketVersioning. - 
policy.statements.principals- all S3 users and groups in the SVM. - 
policy.statements.resources- all objects in the bucket. - 
policy.statements.conditions- list of bucket policy conditions. - 
versioning_state- disabled. 
Related ONTAP commands
- 
vserver object-store-server bucket create - 
vserver object-store-server bucket policy statement create 
Learn more
Parameters
| Name | Type | In | Required | Description | 
|---|---|---|---|---|
return_timeout  | 
integer  | 
query  | 
False  | 
The number of seconds to allow the call to execute before returning. When doing a POST, PATCH, or DELETE operation on a single record, the default is 0 seconds. This means that if an asynchronous operation is started, the server immediately returns HTTP code 202 (Accepted) along with a link to the job. If a non-zero value is specified for POST, PATCH, or DELETE operations, ONTAP waits that length of time to see if the job completes so it can return something other than 202. 
  | 
return_records  | 
boolean  | 
query  | 
False  | 
The default is false. If set to true, the records are returned. 
  | 
Request Body
| Name | Type | Description | 
|---|---|---|
aggregates  | 
array[aggregates]  | 
A list of aggregates for FlexGroup volume constituents where the bucket is hosted. If this option is not specified, the bucket is auto-provisioned as a FlexGroup volume.  | 
audit_event_selector  | 
Audit event selector allows you to specify access and permission types to audit.  | 
|
comment  | 
string  | 
Can contain any additional information about the bucket being created or modified.  | 
constituents_per_aggregate  | 
integer  | 
Specifies the number of constituents or FlexVol volumes per aggregate. A FlexGroup volume consisting of all such constituents across all specified aggregates is created. This option is used along with the aggregates option and cannot be used independently.  | 
encryption  | 
||
logical_used_size  | 
integer  | 
Specifies the bucket logical used size up to this point.  | 
name  | 
string  | 
Specifies the name of the bucket. Bucket name is a string that can only contain the following combination of ASCII-range alphanumeric characters 0-9, a-z, ".", and "-".  | 
policy  | 
A policy is an object associated with a bucket. It defines resource (bucket, folder, or object) permissions. These policies get evaluated when an S3 user makes a request by executing a specific command. The user must be part of the principal (user or group) specified in the policy. Permissions in the policies determine whether the request is allowed or denied.  | 
|
protection_status  | 
Specifies attributes of bucket protection.  | 
|
qos_policy  | 
Specifes "qos_policy.max_throughput_iops" and/or "qos_policy.max_throughput_mbps" or "qos_policy.min_throughput_iops" and/or "qos_policy.min_throughput_mbps". Specifying "min_throughput_iops" or "min_throughput_mbps" is only supported on volumes hosted on a node that is flash optimized. A pre-created QoS policy can also be used by specifying "qos_policy.name" or "qos_policy.uuid" properties. Setting or assigning a QoS policy to a bucket is not supported if its containing volume or SVM already has a QoS policy attached.  | 
|
role  | 
string  | 
Specifies the role of the bucket.  | 
size  | 
integer  | 
Specifies the bucket size in bytes; ranges from 80MB to 64TB.  | 
storage_service_level  | 
string  | 
Specifies the storage service level of the FlexGroup volume on which the bucket should be created. Valid values are "value", "performance" or "extreme".  | 
svm  | 
||
uuid  | 
string  | 
Specifies the unique identifier of the bucket.  | 
versioning_state  | 
string  | 
Specifies the versioning state of the bucket. Valid values are "disabled", "enabled" or "suspended". Note that the versioning state cannot be modified to 'disabled' from any other state.  | 
volume  | 
Specifies the FlexGroup volume name and UUID where the bucket is hosted.  | 
Example request
{
  "aggregates": [
    {
      "name": "aggr1",
      "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
    }
  ],
  "audit_event_selector": {
    "access": "string",
    "permission": "string"
  },
  "comment": "S3 bucket.",
  "constituents_per_aggregate": 4,
  "logical_used_size": 0,
  "name": "bucket1",
  "policy": {
    "statements": [
      {
        "actions": [
          "GetObject",
          "PutObject",
          "DeleteObject",
          "ListBucket"
        ],
        "conditions": [
          {
            "delimiters": [
              "/"
            ],
            "max_keys": [
              1000
            ],
            "operator": "ip_address",
            "prefixes": [
              "pref"
            ],
            "source_ips": [
              "1.1.1.1",
              "1.2.2.0/24"
            ],
            "usernames": [
              "user1"
            ]
          }
        ],
        "effect": "allow",
        "principals": [
          "user1",
          "group/grp1"
        ],
        "resources": [
          "bucket1",
          "bucket1/*"
        ],
        "sid": "FullAccessToUser1"
      }
    ]
  },
  "qos_policy": {
    "max_throughput_iops": 10000,
    "max_throughput_mbps": 500,
    "min_throughput_iops": 2000,
    "min_throughput_mbps": 500,
    "name": "performance",
    "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
  },
  "role": "string",
  "size": 1677721600,
  "storage_service_level": "value",
  "svm": {
    "name": "svm1",
    "uuid": "02c9e252-41be-11e9-81d5-00a0986138f7"
  },
  "uuid": "414b29a1-3b26-11e9-bd58-0050568ea055",
  "versioning_state": "enabled",
  "volume": {
    "name": "volume1",
    "uuid": "028baa66-41bd-11e9-81d5-00a0986138f7"
  }
}
Response
Status: 202, Accepted
| Name | Type | Description | 
|---|---|---|
job  | 
Example response
{
  "job": {
    "uuid": "string"
  }
}
Error
Status: Default
ONTAP Error Response Codes
| Error code | Message | 
|---|---|
92405777  | 
"Failed to create bucket "{bucket name}" for SVM "{svm.name}". Reason: {Reason of failure}. ";  | 
92405785  | 
"Bucket name "{bucket name}" contains invalid characters. Valid characters for a bucket name are 0-9, a-z, ".", and "-". ";  | 
92405786  | 
"Bucket name "{bucket name}" is not valid. Bucket names must have between 3 and 63 characters. ";  | 
92405811  | 
"Failed to create bucket "{bucket name}" for SVM "{svm.name}". Wait a few minutes and try the operation again.";  | 
92405812  | 
"Failed to create the object store volume. Reason: {Reason for failure}.";  | 
92405819  | 
"Cannot provision an object store server volume for bucket "{bucket name}" in SVM "{svm.name}" on the following aggregates because they are SnapLock aggregates: {List of aggregates.name}.";  | 
92405820  | 
"Failed to check whether the aggregate "{aggregates.name}" is a FabricPool. Reason: {Reason for failure}.";  | 
92405821  | 
"Cannot provision an object store server volume for bucket "{bucket name}" in SVM "{svm.name}" on the following aggregates because they are FabricPool: {List of aggregates.name}.";  | 
92405827  | 
"Internal Error. Unable to generate object store volume name.";  | 
92405857  | 
"One or more aggregates must be specified if "constituents_per_aggregate" is specified.";  | 
92405858  | 
"Failed to "create" the "bucket" because the operation is only supported on data SVMs.";  | 
92405859  | 
"The specified "aggregates.uuid" "{aggregates.uuid}" does not exist.";  | 
92405860  | 
"The specified "aggregates.name" "{aggregates.name}" and "aggregates.uuid" "{aggregates.uuid}" refer to different aggregates.";  | 
92405861  | 
"The specified SVM UUID or bucket UUID does not exist.";  | 
92405863  | 
"An error occurs when creating an access policy. The reason for failure is detailed in the error message.";  | 
92405891  | 
The resources specified in the access policy are not valid. Valid ways to specify a resource are *, <bucket-name>, <bucket-name>/…/…. Valid characters for a resource are 0-9, A-Z, a-z, _, +, comma, ;, :, =, ., &, @,?, (, ), single quote, *, !, - and $.  | 
92405894  | 
"Statements, principals and resources list can have a maximum of 10 entries.";  | 
92405897  | 
The principals specified in the access policy are not in the correct format. User name must be in between 1 and 64 characters. Valid characters for a user name are 0-9, A-Z, a-z, _, +, =, comma, ., @, and - .  | 
92405898  | 
"The SID specified in the access policy is not valid. Valid characters for a SID are 0-9, A-Z and a-z.";  | 
Definitions
See Definitions
href
| Name | Type | Description | 
|---|---|---|
href  | 
string  | 
_links
aggregates
| Name | Type | Description | 
|---|---|---|
name  | 
string  | 
|
uuid  | 
string  | 
audit_event_selector
Audit event selector allows you to specify access and permission types to audit.
| Name | Type | Description | 
|---|---|---|
access  | 
string  | 
Specifies read and write access types.  | 
permission  | 
string  | 
Specifies allow and deny permission types.  | 
encryption
| Name | Type | Description | 
|---|---|---|
enabled  | 
boolean  | 
Specifies whether encryption is enabled on the bucket. By default, encryption is disabled on a bucket.  | 
s3_bucket_policy_condition
Information about policy conditions based on various condition operators and condition keys.
| Name | Type | Description | 
|---|---|---|
delimiters  | 
array[string]  | 
An array of delimiters that are compared with the delimiter value specified at the time of execution of an S3-based command, using the condition operator specified.  | 
max_keys  | 
array[integer]  | 
An array of maximum keys that are allowed or denied to be retrieved using an S3 list operation, based on the condition operator specified.  | 
operator  | 
string  | 
Condition operator that is applied to the specified condition key.  | 
prefixes  | 
array[string]  | 
An array of prefixes that are compared with the input prefix value specified at the time of execution of an S3-based command, using the condition operator specified.  | 
source_ips  | 
array[string]  | 
An array of IP address ranges that are compared with the IP address of a source command at the time of execution of an S3-based command, using the condition operator specified.  | 
usernames  | 
array[string]  | 
An array of usernames that a current user in the context is evaluated against using the condition operators.  | 
s3_bucket_policy_statement
Specifies information about a single access permission.
| Name | Type | Description | 
|---|---|---|
actions  | 
array[string]  | 
|
conditions  | 
array[s3_bucket_policy_condition]  | 
Specifies bucket policy conditions.  | 
effect  | 
string  | 
Specifies whether access is allowed or denied when a user requests the specific action. If access (to allow) is not granted explicitly to a resource, access is implicitly denied. Access can also be denied explicitly to a resource, in order to make sure that a user cannot access it, even if a different policy grants access.  | 
principals  | 
array[string]  | 
|
resources  | 
array[string]  | 
|
sid  | 
string  | 
Specifies the statement identifier used to differentiate between statements.  | 
policy
A policy is an object associated with a bucket. It defines resource (bucket, folder, or object) permissions. These policies get evaluated when an S3 user makes a request by executing a specific command. The user must be part of the principal (user or group) specified in the policy. Permissions in the policies determine whether the request is allowed or denied.
| Name | Type | Description | 
|---|---|---|
statements  | 
array[s3_bucket_policy_statement]  | 
Specifies bucket access policy statement.  | 
destination
| Name | Type | Description | 
|---|---|---|
is_cloud  | 
boolean  | 
Specifies whether a bucket is protected within the Cloud.  | 
is_ontap  | 
boolean  | 
Specifies whether a bucket is protected within ONTAP. 
  | 
protection_status
Specifies attributes of bucket protection.
| Name | Type | Description | 
|---|---|---|
destination  | 
||
is_protected  | 
boolean  | 
Specifies whether a bucket is a source and if it is protected within ONTAP and/or an external cloud. 
  | 
qos_policy
Specifes "qos_policy.max_throughput_iops" and/or "qos_policy.max_throughput_mbps" or "qos_policy.min_throughput_iops" and/or "qos_policy.min_throughput_mbps". Specifying "min_throughput_iops" or "min_throughput_mbps" is only supported on volumes hosted on a node that is flash optimized. A pre-created QoS policy can also be used by specifying "qos_policy.name" or "qos_policy.uuid" properties. Setting or assigning a QoS policy to a bucket is not supported if its containing volume or SVM already has a QoS policy attached.
| Name | Type | Description | 
|---|---|---|
max_throughput_iops  | 
integer  | 
Specifies the maximum throughput in IOPS, 0 means none. This is mutually exclusive with name and UUID during POST and PATCH.  | 
max_throughput_mbps  | 
integer  | 
Specifies the maximum throughput in Megabytes per sec, 0 means none. This is mutually exclusive with name and UUID during POST and PATCH.  | 
min_throughput_iops  | 
integer  | 
Specifies the minimum throughput in IOPS, 0 means none. Setting "min_throughput" is supported on AFF platforms only, unless FabricPool tiering policies are set. This is mutually exclusive with name and UUID during POST and PATCH.  | 
min_throughput_mbps  | 
integer  | 
Specifies the minimum throughput in Megabytes per sec, 0 means none. This is mutually exclusive with name and UUID during POST and PATCH.  | 
name  | 
string  | 
The QoS policy group name. This is mutually exclusive with UUID and other QoS attributes during POST and PATCH.  | 
uuid  | 
string  | 
The QoS policy group UUID. This is mutually exclusive with name and other QoS attributes during POST and PATCH.  | 
svm
| Name | Type | Description | 
|---|---|---|
name  | 
string  | 
The name of the SVM.  | 
uuid  | 
string  | 
The unique identifier of the SVM.  | 
volume
Specifies the FlexGroup volume name and UUID where the bucket is hosted.
| Name | Type | Description | 
|---|---|---|
name  | 
string  | 
The name of the volume.  | 
uuid  | 
string  | 
Unique identifier for the volume. This corresponds to the instance-uuid that is exposed in the CLI and ONTAPI. It does not change due to a volume move. 
  | 
s3_bucket
A bucket is a container of objects. Each bucket defines an object namespace. S3 requests specify objects using a bucket-name and object-name pair. An object resides within a bucket.
| Name | Type | Description | 
|---|---|---|
aggregates  | 
array[aggregates]  | 
A list of aggregates for FlexGroup volume constituents where the bucket is hosted. If this option is not specified, the bucket is auto-provisioned as a FlexGroup volume.  | 
audit_event_selector  | 
Audit event selector allows you to specify access and permission types to audit.  | 
|
comment  | 
string  | 
Can contain any additional information about the bucket being created or modified.  | 
constituents_per_aggregate  | 
integer  | 
Specifies the number of constituents or FlexVol volumes per aggregate. A FlexGroup volume consisting of all such constituents across all specified aggregates is created. This option is used along with the aggregates option and cannot be used independently.  | 
encryption  | 
||
logical_used_size  | 
integer  | 
Specifies the bucket logical used size up to this point.  | 
name  | 
string  | 
Specifies the name of the bucket. Bucket name is a string that can only contain the following combination of ASCII-range alphanumeric characters 0-9, a-z, ".", and "-".  | 
policy  | 
A policy is an object associated with a bucket. It defines resource (bucket, folder, or object) permissions. These policies get evaluated when an S3 user makes a request by executing a specific command. The user must be part of the principal (user or group) specified in the policy. Permissions in the policies determine whether the request is allowed or denied.  | 
|
protection_status  | 
Specifies attributes of bucket protection.  | 
|
qos_policy  | 
Specifes "qos_policy.max_throughput_iops" and/or "qos_policy.max_throughput_mbps" or "qos_policy.min_throughput_iops" and/or "qos_policy.min_throughput_mbps". Specifying "min_throughput_iops" or "min_throughput_mbps" is only supported on volumes hosted on a node that is flash optimized. A pre-created QoS policy can also be used by specifying "qos_policy.name" or "qos_policy.uuid" properties. Setting or assigning a QoS policy to a bucket is not supported if its containing volume or SVM already has a QoS policy attached.  | 
|
role  | 
string  | 
Specifies the role of the bucket.  | 
size  | 
integer  | 
Specifies the bucket size in bytes; ranges from 80MB to 64TB.  | 
storage_service_level  | 
string  | 
Specifies the storage service level of the FlexGroup volume on which the bucket should be created. Valid values are "value", "performance" or "extreme".  | 
svm  | 
||
uuid  | 
string  | 
Specifies the unique identifier of the bucket.  | 
versioning_state  | 
string  | 
Specifies the versioning state of the bucket. Valid values are "disabled", "enabled" or "suspended". Note that the versioning state cannot be modified to 'disabled' from any other state.  | 
volume  | 
Specifies the FlexGroup volume name and UUID where the bucket is hosted.  | 
job_link
| Name | Type | Description | 
|---|---|---|
uuid  | 
string  | 
The UUID of the asynchronous job that is triggered by a POST, PATCH, or DELETE operation.  | 
error_arguments
| Name | Type | Description | 
|---|---|---|
code  | 
string  | 
Argument code  | 
message  | 
string  | 
Message argument  | 
error
| Name | Type | Description | 
|---|---|---|
arguments  | 
array[error_arguments]  | 
Message arguments  | 
code  | 
string  | 
Error code  | 
message  | 
string  | 
Error message  | 
target  | 
string  | 
The target parameter that caused the error.  |