Atlas Docs

Object Lock

Properties1
descriptionProtect object versions from deletion and overwrite with S3 Object Lock retention and legal holds.

6 min read

Object Lock

Object Lock keeps an object version from being deleted or overwritten until its retention date passes or its legal hold is removed. Atlas Storage runs the Ceph Object Gateway, which implements the S3 Object Lock API, so the aws CLI, S3 SDKs, and backup software with S3 Object Lock support work against https://s3.atlascloud.is with the setup in Configure AWS CLI.

Object Lock protects versions, not keys. Every upload to a versioned bucket creates a new version, and the lock applies to each version on its own.

What Object Lock does not cover

Object Lock is enforced on S3 API requests only. Deleting a bucket in the Atlas Cloud console, or with the deleteBucket API, removes the bucket and every version in it, locked versions included. That deletion is open to any Atlas Admin of the account and to administrators of its parent domains, as the CloudStack Ceph driver purges the bucket’s contents. See Deleting the bucket.

Enabling Object Lock

Object Lock is enabled through the S3 API on a bucket that has versioning enabled.

  1. Create the bucket with versioning enabled, in the Atlas Cloud console or with createBucket and versioning=true. Versioning can also be switched on afterwards:

    aws s3api put-bucket-versioning --bucket your-bucket-name --versioning-configuration Status=Enabled --profile atlas

  2. Enable Object Lock. Without a default retention rule, nothing is locked until a retention period or legal hold is set on a version:

    aws s3api put-object-lock-configuration --bucket your-bucket-name --object-lock-configuration ObjectLockEnabled=Enabled --profile atlas

  3. Confirm the configuration:

    aws s3api get-object-lock-configuration --bucket your-bucket-name --profile atlas

The object locking option on bucket creation

Selecting object locking when creating a bucket, in the console or with createBucket and objectlocking=true, does not enable Object Lock on the bucket, and on its own does not enable versioning either. The bucket’s object locking field does not reflect the bucket’s real state: a bucket configured through the S3 API shows it as off. Use get-object-lock-configuration as the source of truth. A bucket without Object Lock returns ObjectLockConfigurationNotFoundError.

Enabling Object Lock on a bucket without versioning fails with InvalidBucketState.

Default retention

A default retention rule locks every new upload that does not set its own retention. To add one, save the configuration as object-lock.json:

{
  "ObjectLockEnabled": "Enabled",
  "Rule": {
    "DefaultRetention": {
      "Mode": "GOVERNANCE",
      "Days": 30
    }
  }
}

and apply it:

aws s3api put-object-lock-configuration --bucket your-bucket-name --object-lock-configuration file://object-lock.json --profile atlas

or equivalently as one line:

aws s3api put-object-lock-configuration --bucket your-bucket-name --object-lock-configuration '{"ObjectLockEnabled":"Enabled","Rule":{"DefaultRetention":{"Mode":"GOVERNANCE","Days":30}}}' --profile atlas

Leave the default rule out for backup software that sets retention on each object itself. Veeam, for example, expects a bucket with Object Lock enabled and no default retention.

Object Lock is permanent on the bucket

Once enabled, Object Lock cannot be switched off, and versioning on that bucket can no longer be suspended. Requests to suspend versioning, from the S3 API or the console, fail with InvalidBucketState. Try retention settings on a separate bucket before applying them to production data.

Retention modes

Each locked version carries a mode and a retain-until date. The mode decides who can delete the version, or shorten its retention, before that date.

ModeDelete or overwrite a locked versionShorten or remove retentionExtend retention
GOVERNANCEDenied, unless the request sends x-amz-bypass-governance-retention (--bypass-governance-retention)Allowed with the bypass headerAllowed
COMPLIANCEDenied for every S3 API request, including with the bypass headerDeniedAllowed

The flow below shows how a delete request naming a version ID is decided:

flowchart TD
  R[Delete request with a version ID] --> H{Legal hold on?}
  H -- yes --> D[Denied: forbidden by object lock]
  H -- no --> T{Retain-until date passed?}
  T -- yes --> OK[Version deleted]
  T -- no --> M{Mode}
  M -- COMPLIANCE --> D
  M -- GOVERNANCE --> B{Bypass header sent?}
  B -- yes --> OK
  B -- no --> D

For example, a version uploaded on 1 March under a 30-day rule is locked until 31 March. In GOVERNANCE mode, a key holder can still delete it on 10 March by sending the bypass header. In COMPLIANCE mode, no S3 request can delete it before 31 March, and its retain-until date can be pushed later but not earlier.

Bucket credentials are scoped per account (see Buckets), so anyone holding the account’s access key can bypass GOVERNANCE retention. Use COMPLIANCE when no one with the key may delete data before the retention date, and start with GOVERNANCE and a short period while testing.

Per-object retention

To lock a single upload instead of using the default rule:

aws s3api put-object --bucket your-bucket-name --key path/to/file --body ./file --object-lock-mode COMPLIANCE --object-lock-retain-until-date 2027-01-01T00:00:00Z --profile atlas

To show or change the retention on an existing version:

aws s3api get-object-retention --bucket your-bucket-name --key path/to/file --version-id VERSION_ID --profile atlas
aws s3api put-object-retention --bucket your-bucket-name --key path/to/file --version-id VERSION_ID --retention Mode=COMPLIANCE,RetainUntilDate=2027-06-01T00:00:00Z --profile atlas

Retention periods are fixed dates. Atlas Storage does not implement variable retention (event holds); to keep data locked until an event whose date is unknown, use a legal hold or extend the retain-until date as needed.

A legal hold locks a version with no expiry, independent of retention mode. While the hold is on, the version cannot be deleted, including with the governance bypass header.

aws s3api put-object-legal-hold --bucket your-bucket-name --key path/to/file --version-id VERSION_ID --legal-hold Status=ON --profile atlas
aws s3api put-object-legal-hold --bucket your-bucket-name --key path/to/file --version-id VERSION_ID --legal-hold Status=OFF --profile atlas

Anyone holding the account’s access key can remove a legal hold, so on its own a legal hold protects against mistakes, not against a key holder. Combine it with COMPLIANCE retention where that matters.

Deleting objects in a locked bucket

A delete request without a version ID succeeds and adds a delete marker: the key disappears from normal listings, and the locked version stays intact underneath, visible with list-object-versions. A delete request naming a locked version ID fails with AccessDenied and the message forbidden by object lock.

Deleting the bucket

Deleting a bucket in the Atlas Cloud console, or with deleteBucket, removes the bucket together with every version in it, including versions under GOVERNANCE or COMPLIANCE retention or a legal hold. Bucket management requires the Atlas Admin role (see Buckets), so limit that role to the people who may destroy retained data, and give everyone else Atlas User or Atlas ReadOnly accounts.

Further reading

Backlinks