Retention periods and policies

ECS provides the ability to prevent data from being modified or deleted within a specified retention period.

You can specify retention by using retention periods and retention policies that are defined in the metadata that is associated with objects and buckets. The retention periods and retention policies are checked each time a request to modify an object is made. Retention periods are supported on all ECS object protocols (S3, Swift, Atmos, and CAS).

For detailed information about setting retention on object interfaces, including CAS retention and CAS advanced retention, see the ECS Data Access Guide, available from the ECS Product Documentation page.
Retention Periods
You can assign retention periods at the object level or the bucket level. Each time a user requests to modify or delete an object, an expiration time is calculated, where the object expiration time equals the object creation time plus the retention period. When you assign a retention period for a bucket, the object expiration time is calculated based on the retention period set on the object and the retention period set on the bucket, whichever is the longest.
When you apply a retention period to a bucket, the retention period for all objects in a bucket can be changed at any time, and can override the value written to the object by an object client by setting it to a longer period.
You can specify that an object is retained indefinitely.
Auto-Commit Period
Auto-commit period is the time interval in which the updates through NFS or HDFS are allowed for objects under retention. This attribute enables NFS or HDFS files that are written to ECS to be WORM compliant. The interval is calculated from the last modification time.
The auto-commit value must be less than or equal to the retention value with a maximum of 1 day. A value of 0 indicates no auto-commit period.
Retention Policies
Retention polices are associated with a namespace. Any policy that is associated with the namespace can be assigned to an object belonging to the namespace. A retention policy has an associated retention period.
When you change the retention period that is associated with a policy, the retention period automatically changes for objects that have that policy assigned.
You can apply a retention policy to an object. When a user attempts to modify or delete an object, the retention policy is retrieved. The retention period in the retention policy is used with object retention period and bucket retention period to verify whether the request is allowed.
For example, you could define a retention policy for each of the following document types, and each policy could have an appropriate retention period. When a user requests to modify or delete the legal document four years after it was created, the larger of the bucket retention period or the object retention period is used to verify whether the operation can be performed. In this case, the request is not allowed, and the document cannot be modified or deleted for one more year.
  • Email - six months
  • Financial - three years
  • Legal - five years

ECS Management REST API retention policy methods

The retention policy creation and configuration tasks that can be performed in the ECS Portal can also be performed using the ECS Management REST API. The following table describes the ECS Management REST API methods that relate to retention policies.

ECS Management REST API method Description
PUT /object/bucket/{bucketName}/retention The retention value for a bucket that defines a mandatory retention period which is applied to every object within a bucket. If the retention value is one year, an object from the bucket can not be modified or deleted for one year.
GET /object/bucket/{bucketName}/retention Returns the retention period that is currently set for a specified bucket.
POST /object/namespaces/namespace/{namespace}/retention The retention setting for namespaces that acts like a policy, where each policy is a <name>: <retention period> pair. You can define a number of retention policies for a namespace and you can assign a policy, by name, to an object within the namespace. This allows you to change the retention period for a set of objects that have the same policy assigned, by changing the corresponding policy.
PUT /object/namespaces/namespace/{namespace}/retention/{class} Updates the period for a retention class that is associated with a namespace.
GET /object/namespaces/namespace/{namespace}/retention Returns the retention classes that are defined for a namespace.

For information on how to access the ECS Management REST API, see the ECS Data Access Guide, available from the ECS Product Documentation page.