Skip to main content
REST API reference
A newer release of this product is available.

Create the S3 bucket lifecycle rule configuration

Creates S3 bucket lifecycle rule configurations to manage the lifecycle of objects within the bucket. This allows you to automate actions like transitioning objects to different storage classes or expiring objects based on specified criteria.

HTTP method and endpoint

POST /protocols/s3/services/{svm.uuid}/buckets/{s3_bucket.uuid}/rules

Introduced in

ONTAP 9.13

Usage notes

Creates the S3 bucket lifecycle rule configuration.

Required properties

  • name - Lifecycle Management rule to be created.

  • actions - Lifecycle Management actions associated with the rule.

  • enabled - Lifecycle Management rule is enabled or not.

  • object_filter.prefix - Lifecycle Management rule filter prefix.

  • object_filter.tags - Lifecycle Management rule filter tags.

  • object_filter.size_greater_than - Lifecycle Management rule filter minimum object size.

  • object_filter.size_less_than - Lifecycle Management rule filter maximum object size.

  • object_age_days - Number of days since creation after which objects can be deleted.

  • object_expiry_date - Specific date from when objects can expire.

  • expired_object_delete_marker - Cleanup object delete markers.

  • new_non_current_versions - Number of latest non-current versions to be retained.

  • non_current_days - Number of days after which non-current versions can be deleted.

  • after_initiation_days - Number of days of initiation after which uploads can be aborted.

  • vserver object-store-server bucket lifecycle-management-rule create

Parameters

Name Type In Required Description

s3_bucket.uuid

string

path

True

Unique identifier of a bucket.

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.

  • Default value: 0

  • Max value: 120

  • Min value: 0

return_records

boolean

query

False

The default is false. If set to true, the records are returned.

  • Default value:

svm.uuid

string

path

True

UUID of the SVM to which this object belongs.

  • Introduced in: 9.14

Request Body

Name Type Description

abort_incomplete_multipart_upload

abort_incomplete_multipart_upload

Specifies a way to perform abort_incomplete_multipart_upload action on filtered objects within a bucket. It cannot be specified with tags.

bucket_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 "-".

enabled

boolean

Specifies whether or not the associated rule is enabled.

expiration

expiration

Specifies a way to perform expiration action on filtered objects within a bucket.

name

string

Bucket lifecycle management rule identifier. The length of the name can range from 0 to 256 characters.

non_current_version_expiration

non_current_version_expiration

Specifies a way to perform non_current_version_expiration action on filtered objects within a bucket.

object_filter

object_filter

Specifies a way to filter objects within a bucket.

svm

svm

Specifies the name of the SVM where this bucket exists.

uuid

string

Specifies the unique identifier of the bucket.

Example request
{
  "bucket_name": "bucket1",
  "expiration": {
    "object_expiry_date": "string"
  },
  "name": "string",
  "object_filter": {
    "prefix": "/logs",
    "size_greater_than": 10240,
    "size_less_than": 10485760,
    "tags": [
      "project1=projA",
      "project2=projB"
    ]
  },
  "svm": {
    "name": "svm1",
    "uuid": "02c9e252-41be-11e9-81d5-00a0986138f7"
  },
  "uuid": "414b29a1-3b26-11e9-bd58-0050568ea055"
}

Response

Status: 202, Accepted
Name Type Description

job

job_link

Example response
{
  "job": {
    "uuid": "string"
  }
}

Headers

Name Description Type

Location

Useful for tracking the resource location

string

Response

Status: 201, Created

Error

Status: Default

ONTAP Error Response Codes

Error code Message

92405861

"The specified SVM UUID or bucket UUID does not exist.";

92406111

"Lifecycle Management rule for bucket in Vserver is invalid because of the number of tags specified. The maximum number of tags supported is four.";

92406113

"Lifecycle Management rule for bucket in Vserver is invalid because there is a mismatch in one of the filter-field. Filters must be the same for a particular rule identifier.";

92406114

"The Expiration action requires specifying either object_expiry_date, object_age_days or expired_object_delete_marker.";

92406115

"The NonCurrentVersionExpiration action requires either new_non_current_versions or non_current_days.";

92406116

"The AbortIncompleteMultipartUpload action requires after_initiation_days.";

92406117

"The Expiration action cannot have both an expiry date and an age.";

92406118

"Using Lifecycle Management rules requires an effective cluster version of 9.13.1 .";

92406119

"One or more object store buckets exist with Lifecycle Management rules. To list the buckets, run the vserver object-store-server bucket lifecycle-management-rule show command. To delete the buckets, use the vserver object-store-server bucket delete command.";

92406120

"The AbortIncompleteMultipartUpload action cannot be specified with tags.";

92406121

"Expired object delete marker cannot be specified with tags.";

92406122

"Expired object delete marker cannot be specified with object age days or expiry date.";

92406123

"Expiration is supported on object store volumes only, bucket on Vserver is not an object store volume.";

92406126

"Lifecycle Management rule for bucket in Vserver is invalid because specified tags contain one or more invalid characters. Valid characters for a tag are 0-9, A-Z, a-z, +, -, =, ., _, :, /, @.";

92406127

"Lifecycle Management rule for bucket in Vserver is invalid because specified tag length is greater than maximum allowed length: {1}.";

92406128

"Lifecycle Management rule for bucket in Vserver has tags with duplicate keys. Ensure each tag has a unique key and try the operation again.";

92406129

"Lifecycle Management rule for bucket in Vserver has a prefix that is too long. The maximum length of the prefix is 1024 characters.";

92406130

"Lifecycle Management rule for bucket in Vserver is invalid because the minimum object size is larger than the maximum object size.";

92406131

"Lifecycle Management rule for bucket in Vserver cannot be created because non_current_days must be specified when new_non_current_versions is specified.";

92406132

"Lifecycle Management rule "" for bucket "" in SVM "" requires "object_age_days" to be greater than zero."; //end row //start row

92406132 //end row //start row

"Lifecycle Management rule "" for bucket "" in SVM "" requires "new_non_current_versions" to be greater than zero."; //end row //start row

92406132 //end row //start row

"Lifecycle Management rule "" for bucket "" in SVM "" requires "after_initiation_days" to be greater than zero."; //end row //start row

92406133 //end row //start row

"Lifecycle Management rule for bucket in Vserver is invalid. The object_expiry_date must be later than January 1, 1970."; //end row //start row

92406134 //end row //start row

"Cannot exceed the max limit of 1000 Lifecycle Management rules per bucket."; //end row //start row

92406135 //end row //start row

"MetroCluster is configured on cluster. Object Expiration is not supported in a MetroCluster configuration."; //end row //start row

92406136 //end row //start row

"Lifecycle Management rule for bucket in Vserver is invalid. The object_expiry_date must be at midnight GMT."; //end row //start row

92406139 //end row //start row

"Lifecycle Management rule for bucket in Vserver with action is a stale entry. Contact technical support for assistance."; //end row //start row

92406140 //end row //start row

"Expired object delete marker must be enabled to create a Lifecycle Management rule."; //end row //start row

92406141 //end row //start row

"Lifecycle Management rule for bucket in Vserver with action cannot have expired_object_delete_marker disabled. To disable expired_object_delete_marker, run vserver object-store-server bucket lifecycle-management-rule delete"; //end row //start row

92406143 //end row //start row

"As part of Bucket Lifecycle, cannot create fabriclink relationship on bucket "" in SVM "". Reason : ."; //end row //start row

92406144 //end row //start row

"The "AbortIncompleteMultipartUpload" action cannot be specified with object size."; //end row //start row

92406150 //end row //start row

""expired_object_delete_marker" cannot be specified with "size_less_than"."; //end row

|Name |Type |Description

|href |string a|

[#_links] [.api-collapsible-fifth-title] _links [#abort_incomplete_multipart_upload] [.api-collapsible-fifth-title] abort_incomplete_multipart_upload

Specifies a way to perform abort_incomplete_multipart_upload action on filtered objects within a bucket. It cannot be specified with tags.

[cols=3*,options=header]

|Name |Type |Description

|after_initiation_days |integer a|Number of days of initiation after which uploads can be aborted.

[#expiration] [.api-collapsible-fifth-title] expiration

Specifies a way to perform expiration action on filtered objects within a bucket.

[cols=3*,options=header]

|Name |Type |Description

|expired_object_delete_marker |boolean a|Cleanup object delete markers.

|object_age_days |integer a|Number of days since creation after which objects can be deleted. This cannot be used along with object_expiry_date.

|object_expiry_date |string a|Specific date from when objects can expire. This cannot be used with object_age_days.

[#non_current_version_expiration] [.api-collapsible-fifth-title] non_current_version_expiration

Specifies a way to perform non_current_version_expiration action on filtered objects within a bucket.

[cols=3*,options=header]

|Name |Type |Description

|new_non_current_versions |integer a|Number of latest non-current versions to be retained.

|non_current_days |integer a|Number of days after which non-current versions can be deleted.

[#object_filter] [.api-collapsible-fifth-title] object_filter

Specifies a way to filter objects within a bucket.

[cols=3*,options=header]

|Name |Type |Description

|prefix |string a|A prefix that is matched against object-names within a bucket.

|size_greater_than |integer a|Size of the object greater than specified for which the corresponding lifecycle rule is to be applied.

|size_less_than |integer a|Size of the object smaller than specified for which the corresponding lifecycle rule is to be applied.

|tags |array[string] a|An array of key-value paired tags of the form or <tag=value>.

[#svm] [.api-collapsible-fifth-title] svm

Specifies the name of the SVM where this bucket exists.

[cols=3*,options=header]

|Name |Type |Description

|name |string a|The name of the SVM. This field cannot be specified in a PATCH method.

|uuid |string a|The unique identifier of the SVM. This field cannot be specified in a PATCH method.

[#s3_bucket_lifecycle_rule] [.api-collapsible-fifth-title] s3_bucket_lifecycle_rule

Information about the lifecycle management rule of a bucket.

[cols=3*,options=header]

|Name |Type |Description

|abort_incomplete_multipart_upload |abort_incomplete_multipart_upload a|Specifies a way to perform abort_incomplete_multipart_upload action on filtered objects within a bucket. It cannot be specified with tags.

|bucket_name |string a|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 "-".

|enabled |boolean a|Specifies whether or not the associated rule is enabled.

|expiration |expiration a|Specifies a way to perform expiration action on filtered objects within a bucket.

|name |string a|Bucket lifecycle management rule identifier. The length of the name can range from 0 to 256 characters.

|non_current_version_expiration |non_current_version_expiration a|Specifies a way to perform non_current_version_expiration action on filtered objects within a bucket.

|object_filter |object_filter a|Specifies a way to filter objects within a bucket.

|svm |svm a|Specifies the name of the SVM where this bucket exists.

|uuid |string a|Specifies the unique identifier of the bucket.

[#job_link] [.api-collapsible-fifth-title] job_link

[cols=3*,options=header]

|Name |Type |Description

|uuid |string a|The UUID of the asynchronous job that is triggered by a POST, PATCH, or DELETE operation.

[#error_arguments] [.api-collapsible-fifth-title] error_arguments

[cols=3*,options=header]

|Name |Type |Description

|code |string a|Argument code

|message |string a|Message argument

[#returned_error] [.api-collapsible-fifth-title] returned_error

[cols=3*,options=header]

|Name |Type |Description

|arguments |array[error_arguments] a|Message arguments

|code |string a|Error code

|message |string a|Error message

|target |string a|The target parameter that caused the error.

====