Skip to main content

Use S3 Object Lock to retain objects

Contributors netapp-lhalbert
PDFs

You can use S3 Object Lock if buckets and objects must comply with regulatory requirements for retention.

Note Your grid administrator must give you permission to use specific features of S3 Object Lock.

What is S3 Object Lock?

The StorageGRID S3 Object Lock feature is an object-protection solution that is equivalent to S3 Object Lock in Amazon Simple Storage Service (Amazon S3).

When the global S3 Object Lock setting is enabled for a StorageGRID system, an S3 tenant account can create buckets with or without S3 Object Lock enabled. If a bucket has S3 Object Lock enabled, bucket versioning is required and is enabled automatically.

A bucket without S3 Object Lock can only have objects without retention settings specified. No ingested objects will have retention settings.

A bucket with S3 Object Lock can have objects with and without retention settings specified by S3 client applications. Some objects ingested will have retention settings.

A bucket with S3 Object Lock and default retention configured can have uploaded objects with retention settings specified and new objects without retention settings. The new objects use the default setting, because the retention setting hasn't been configured at the object-level.

Effectively, all newly ingested objects have retention settings when default retention is configured. Existing objects without object retention settings remain unaffected.

Retention modes

The StorageGRID S3 Object Lock feature supports two retention modes to apply different levels of protection to objects. These modes are equivalent to the Amazon S3 retention modes.

  • In compliance mode:

    • The object can't be deleted until its retain-until-date is reached.

    • The object's retain-until-date can be increased, but it can't be decreased.

    • The object's retain-until-date can't be removed until that date is reached.

  • In governance mode:

    • Users with special permission can use a bypass header in requests to modify certain retention settings.

    • These users can delete an object version before its retain-until-date is reached.

    • These users can increase, decrease, or remove an object's retain-until-date.

Retention settings for object versions

If a bucket is created with S3 Object Lock enabled, users can use the S3 client application to optionally specify the following retention settings for each object that is added to the bucket:

  • Retention mode: Either compliance or governance.

  • Retain-until-date: If an object version's retain-until-date is in the future, the object can be retrieved, but it can't be deleted.

  • Legal hold: Applying a legal hold to an object version immediately locks that object. For example, you might need to put a legal hold on an object that is related to an investigation or legal dispute. A legal hold has no expiration date, but remains in place until it is explicitly removed. Legal holds are independent of the retain-until-date.

    Note If an object is under a legal hold, no one can delete the object, regardless of its retention mode.

    For details on the object settings, see Use S3 REST API to configure S3 Object Lock.

Default retention setting for buckets

If a bucket is created with S3 Object Lock enabled, users can optionally specify the following default settings for the bucket:

  • Default retention mode: Either compliance or governance.

  • Default retention period: How long new object versions added to this bucket should be retained, starting from the day they are added.

The default bucket settings apply only to new objects that don't have their own retention settings. Existing bucket objects aren't affected when you add or change these default settings.

See Create an S3 bucket and Update S3 Object Lock default retention.

S3 Object Lock tasks

The following lists for grid administrators and tenant users contain the high-level tasks for using the S3 Object Lock feature.

Grid administrator

  • Enable global S3 Object Lock setting for entire StorageGRID system.

  • Ensure that information lifecycle management (ILM) policies are compliant; that is, they meet the requirements of buckets with S3 Object Lock enabled.

  • As needed, allow a tenant to use Compliance as the retention mode. Otherwise, only Governance mode is allowed.

  • As needed, set a maximum retention period for a tenant.

Tenant user

  • Review considerations for buckets and objects with S3 Object Lock.

  • As needed, contact grid administrator to enable global S3 Object Lock setting and set permissions.

  • Create buckets with S3 Object Lock enabled.

  • Optionally, configure default retention settings for a bucket:

    • Default retention mode: Governance or Compliance, if allowed by the grid administrator.

    • Default retention period: Must be less than or equal to maximum retention period set by grid administrator.

  • Use the S3 client application to add objects and optionally set object-specific retention:

    • Retention mode. Governance or Compliance, if allowed by the grid administrator.

    • Retain Until Date: Must be less than or equal to what is allowed by the maximum retention period set by grid administrator.

Requirements for buckets with S3 Object Lock enabled

  • If the global S3 Object Lock setting is enabled for the StorageGRID system, you can use the Tenant Manager, the Tenant Management API, or the S3 REST API to create buckets with S3 Object Lock enabled.

  • If you plan to use S3 Object Lock, you must enable S3 Object Lock when you create the bucket. You can't enable S3 Object Lock for an existing bucket.

  • When S3 Object Lock is enabled for a bucket, StorageGRID automatically enables versioning for that bucket. You can't disable S3 Object Lock or suspend versioning for the bucket.

  • Optionally, you can specify a default retention mode and retention period for each bucket using the Tenant Manager, the Tenant Management API, or the S3 REST API. The bucket's default retention settings apply only to new objects added to the bucket that don't have their own retention settings. You can override these default settings by specifying a retention mode and retain-until-date for each object version when it is uploaded.

  • Bucket lifecycle configuration is supported for buckets with S3 Object Lock enabled.

  • CloudMirror replication is not supported for buckets with S3 Object Lock enabled.

Requirements for objects in buckets with S3 Object Lock enabled

  • To protect an object version, you can specify default retention settings for the bucket, or you can specify retention settings for each object version. Object-level retention settings can be specified using the S3 client application or the S3 REST API.

  • Retention settings apply to individual object versions. An object version can have both a retain-until-date and a legal hold setting, one but not the other, or neither. Specifying a retain-until-date or a legal hold setting for an object protects only the version specified in the request. You can create new versions of the object, while the previous version of the object remains locked.

Lifecycle of objects in buckets with S3 Object Lock enabled

Each object that is saved in a bucket with S3 Object Lock enabled goes through these stages:

  1. Object ingest

    When an object version is added to bucket that has S3 Object Lock enabled, retention settings are applied as follows:

    • If retention settings are specified for the object, the object-level settings are applied. Any default bucket settings are ignored.

    • If no retention settings are specified for the object, the default bucket settings are applied, if they exist.

    • If no retention settings are specified for the object or the bucket, the object is not protected by S3 Object Lock.

    If retention settings are applied, both the object and any S3 user-defined metadata are protected.

  2. Object retention and deletion

    Multiple copies of each protected object are stored by StorageGRID for the specified retention period. The exact number and type of object copies and the storage locations are determined by the compliant rules in the active ILM policies. Whether a protected object can be deleted before its retain-until-date is reached depends on its retention mode.

    • If an object is under a legal hold, no one can delete the object, regardless of its retention mode.

Can I still manage legacy Compliant buckets?

The S3 Object Lock feature replaces the Compliance feature that was available in previous StorageGRID versions. If you created compliant buckets using a previous version of StorageGRID, you can continue to manage the settings of these buckets; however, you can no longer create new compliant buckets. For instructions, see NetApp Knowledge Base: How to manage legacy Compliant buckets in StorageGRID 11.5.