Configuring an object lock

Written by

Updated at December 11, 2024

Put or configure a retention (governance- or compliance-mode)
Removing a governance-mode retention
Putting or removing legal holds
Examples
- Setting up a governance-mode retention with the Moscow time offset (UTC+3)

If versioning and object version locks are enabled in the bucket, you can configure locking for a version already uploaded to the bucket.

Put or configure a retention (governance- or compliance-mode)

Minimum required roles:

storage.uploader: To set lock.
storage.admin: To change an existing lock.

You can only extend a compliance-mode retention. You cannot shrink it or replace with a governance-mode retention.

To put or configure a retention:

Management console

Yandex Cloud CLI

AWS CLI

API

In the management console, select Object Storage from the list of services and go to the bucket for whose objects you want to configure a lock.
In the left-hand panel, select Objects.
To see all versions of objects in the list, enable Show versions to the right of the object search field in the bucket.
In the list of objects, select the one you need, click → Object lock.
In the window that opens, enable Retention.
Select Default lock type:
- Governance: User with the storage.admin role can bypass a lock, change its expiration date, or remove it.
- Compliance: User with the storage.admin role can only extend the retention period. Such locks cannot be bypassed, shortened, or removed until they expire.
Specify Default lock period in days or years. It starts from the moment the object version is uploaded to the bucket.
Click Save.

If you do not have the Yandex Cloud command line interface yet, install and initialize it.

The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name or --folder-id parameter.

View the description of the CLI command to set up a temporary lock for an object version:
```
yc storage s3api put-object-retention --help
```

Get a list of buckets in the default folder:

yc storage bucket list

Result:

+------------------+----------------------+-------------+-----------------------+---------------------+
|       NAME       |      FOLDER ID       |  MAX SIZE   | DEFAULT STORAGE CLASS |     CREATED AT      |
+------------------+----------------------+-------------+-----------------------+---------------------+
| first-bucket     | b1gmit33ngp6******** | 53687091200 | STANDARD              | 2022-12-16 13:58:18 |
+------------------+----------------------+-------------+-----------------------+---------------------+

Set up a temporary lock for an object version:
```
yc storage s3api put-object-retention \
  --bucket <bucket_name> \
  --key <object_key> \
  --version-id <version_ID> \
  --retention Mode=<lock_type>,RetainUntilDate="<retention_end_date>" \
  --bypass-governance-retention
```
Where:
- --bucket: Name of your bucket.
- --key: Object key.
- --version-id: Object version ID.
- --retention: Temporary lock settings (both parameters are required):
  - Mode: Lock type:
    - GOVERNANCE: Temporary managed lock. You cannot set this type if an object version is already locked in compliance mode.
    - COMPLIANCE: Temporary strict lock.
  - RetainUntilDate: Lock end date and time in RFC3339 format. For example, 2025-01-01T00:00:00Z. The lock end time value is specified in the UTC±00:00 time zone. To use a different time zone, add + or - and a UTC±00:00 offset to the end of the record. For more information, see this example. If a version object is already locked in compliance mode, you can only extend it by setting new retain until date and time that are later than the current ones.
- --bypass-governance-retention: Flag that shows that a lock is bypassed. Select it if an object version is already locked in governance mode.
Result:
```
request_id: c5984d03********
```
Make sure the object lock settings were updated:
```
yc storage s3api get-object-retention \
  --bucket <bucket_name> \
  --key <object_key> \
  --version-id <version_ID>
```
Where:
- --bucket: Name of your bucket.
- --key: Object key.
- --version-id: Object version ID.
Result:
```
request_id: 077b184e********
retention:
  mode: GOVERNANCE
  retain_until_date: "2024-12-01T10:49:08.363Z"
```
The mode field states the lock type; the retain_until_date field states the retention end date.

If you do not have the AWS CLI yet, install and configure it.
Run this command:
```
aws --endpoint-url=https://storage.yandexcloud.net/ \
  s3api put-object-retention \
  --bucket <bucket_name> \
  --key <object_key> \
  --version-id <version_ID> \
  --retention Mode=<lock_type>,RetainUntilDate="<retention_end_date>" \
  --bypass-governance-retention
```
Where:
- --bucket: Name of your bucket.
- --key: Object key.
- --version-id: Object version ID.
- --retention: Temporary lock settings (both parameters are required):
  - Mode: Lock type:
    - GOVERNANCE: Temporary managed lock. You cannot set this type if an object version is already locked in compliance mode.
    - COMPLIANCE: Temporary strict lock.
  - RetainUntilDate: Lock end date and time in RFC3339 format. For example, 2025-01-01T00:00:00Z. The lock end time value is specified in the UTC±00:00 time zone. To use a different time zone, add + or - and a UTC±00:00 offset to the end of the record. For more information, see this example. If a version object is already locked in compliance mode, you can only extend it by setting new retain until date and time that are later than the current ones.
- --bypass-governance-retention: Flag that shows that a lock is bypassed. Select it if an object version is already locked in governance mode.

Use the putObjectRetention S3 API method.

Removing a governance-mode retention

The minimum required role is storage.admin.

To remove a retention:

Management console

AWS CLI

API

In the management console, select Object Storage from the list of services and go to the bucket you need.
In the left-hand panel, select Objects.
To see all versions of objects in the list, enable Show versions to the right of the object search field in the bucket.
In the list of objects, select the one you need, click → Object lock.
In the window that opens, disable Retention.
Click Save.

If you do not have the AWS CLI yet, install and configure it.
Run this command:
```
aws --endpoint-url=https://storage.yandexcloud.net/ \
  s3api put-object-retention \
  --bucket <bucket_name> \
  --key <object_key> \
  --version-id <version_ID> \
  --retention "{}" \
  --bypass-governance-retention
```
Where:
- --bucket: Name of your bucket.
- --key: Object key.
- --version-id: Object version ID.
- --retention: Temporary lock settings. In both parameters, empty lines are specified to remove a lock.
- --bypass-governance-retention: Flag that shows that a lock is bypassed.

Use the putObjectRetention S3 API method with the X-Amz-Bypass-Governance-Retention: true header and an empty Retention element.

Putting or removing legal holds

The minimum required role is storage.uploader.

To put or configure a legal hold:

Management console

Yandex Cloud CLI

AWS CLI

API

In the management console, select Object Storage from the list of services and go to the bucket you need.
In the left-hand panel, select Objects.
To see all versions of objects in the list, enable Show versions to the right of the object search field in the bucket.
In the list of objects, select the one you need, click → Object lock.
In the window that opens, enable or disable Legal hold.
Click Save.

If you do not have the Yandex Cloud command line interface yet, install and initialize it.

The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name or --folder-id parameter.

View the description of the CLI command to set up an indefinite lock for an object version:
```
yc storage s3api put-object-legal-hold --help
```

Get a list of buckets in the default folder:

yc storage bucket list

Result:

+------------------+----------------------+-------------+-----------------------+---------------------+
|       NAME       |      FOLDER ID       |  MAX SIZE   | DEFAULT STORAGE CLASS |     CREATED AT      |
+------------------+----------------------+-------------+-----------------------+---------------------+
| first-bucket     | b1gmit33ngp6******** | 53687091200 | STANDARD              | 2022-12-16 13:58:18 |
+------------------+----------------------+-------------+-----------------------+---------------------+

Set up an indefinite lock for an object version:
```
yc storage s3api put-object-legal-hold \
  --bucket <bucket_name> \
  --key <object_key> \
  --version-id <version_ID> \
  --legal-hold Status=<lock_status>
```
Where:
- --bucket: Name of your bucket.
- --key: Object key.
- --version-id: Object version ID.
- --legal-hold: Indefinite lock settings:
  - Status: Lock status:
    - ON: Enabled.
    - OFF: Disabled.
Result:
```
request_id: cb262625********
```

Make sure the object version lock settings were applied:

yc storage s3api get-object-legal-hold \
  --bucket <bucket_name> \
  --key <object_key> \
  --version-id <version_ID>

Where:

--bucket: Name of your bucket.
--key: Object key.
--version-id: Object version ID.

Result:

request_id: 0bef4a0b********
legal_hold:
  status: ON

If you do not have the AWS CLI yet, install and configure it.

Run this command:

aws --endpoint-url=https://storage.yandexcloud.net/ \
  s3api put-object-legal-hold \
  --bucket <bucket_name> \
  --key <object_key> \
  --version-id <version_ID> \
  --legal-hold Status=<lock_status>

Where:

--bucket: Name of your bucket.
--key: Object key.
--version-id: Object version ID.
--legal-hold: Indefinite lock settings:
- Status: Lock status:
  - ON: Enabled.
  - OFF: Disabled.

Use the putObjectLegalHold S3 API method.

Examples

Setting up a governance-mode retention with the Moscow time offset (UTC+3)

Yandex Cloud CLI

AWS CLI

yc storage s3api put-object-retention \
  --bucket test-bucket \
  --key object-key/ \
  --version-id 0005FA15******** \
  --retention Mode=GOVERNANCE,RetainUntilDate=2025-01-01T00:00:00+03:00 \

aws --endpoint-url=https://storage.yandexcloud.net/ \
  s3api put-object-retention \
  --bucket test-bucket \
  --key object-key/ \
  --version-id 0005FA15******** \
  --retention Mode=GOVERNANCE,RetainUntilDate="2025-01-01T00:00:00+03:00" \

Configuring an object lock

Put or configure a retention (governance- or compliance-mode)Put or configure a retention (governance- or compliance-mode)

Removing a governance-mode retentionRemoving a governance-mode retention

Putting or removing legal holdsPutting or removing legal holds

ExamplesExamples

Setting up a governance-mode retention with the Moscow time offset (UTC+3)Setting up a governance-mode retention with the Moscow time offset (UTC+3)

Was the article helpful?

Put or configure a retention (governance- or compliance-mode)

Removing a governance-mode retention

Putting or removing legal holds

Examples

Setting up a governance-mode retention with the Moscow time offset (UTC+3)