Contact UsGet started

Configuring an object lock

Written by
Improved by
Updated at February 21, 2025

With versioning and object lock enabled in your bucket, you can configure an object lock for a version already uploaded to the bucket.

Setting or configuring retention (governance- or compliance-mode)

The minimum required roles are as follows:

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

In compliance mode, you can only extend the retention period. You cannot shorten the retention period or change the retention mode to governance.

To set or configure an object lock:

  1. In the management console, select Object Storage from the list of services and go to the bucket containing the objects you want to configure a lock for.
  2. In the left-hand panel, select Objects.
  3. To show all object versions in the list, enable Show versions to the right of the object search field in the bucket.
  4. In the list of objects, select the one you need, click , and select Object lock.
  5. In the window that opens, enable Retention.
  6. 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.
  7. Specify Default lock period in days or years. It starts from the moment the object version is uploaded to the bucket.
  8. Click Save.

If you do not have the Yandex Cloud CLI yet, install and initialize it.

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

  1. See the description of the CLI command for configuring retention for an object version:

    yc storage s3api put-object-retention --help

  2. 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 |
+------------------+----------------------+-------------+-----------------------+---------------------+

  3. Set up retention 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********

  4. 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, while the retain_until_date field states its end date.

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

  2. 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 governance-mode retention

The minimum required role is storage.admin.

To remove retention:

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

If you do not have the Yandex Cloud CLI yet, install and initialize it.

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

  1. See the description of the CLI command for configuring retention for an object version:

    yc storage s3api put-object-retention --help

  2. 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 |
+------------------+----------------------+-------------+-----------------------+---------------------+

  3. Set up retention for an object version:

    yc storage 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.

    Result:

    request_id: m6384f81********

  4. 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.

    Running this command will return an error saying there is no lock configured for the object:

    The specified object does not have a ObjectLock configuration.

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

  2. 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 empty Retention element.

The minimum required role is storage.uploader.

To set or remove legal hold:

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

If you do not have the Yandex Cloud CLI yet, install and initialize it.

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

  1. See the description of the CLI command for setting up legal hold for an object version:

    yc storage s3api put-object-legal-hold --help

  2. 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 |
+------------------+----------------------+-------------+-----------------------+---------------------+

  3. Set up legal hold 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********

  4. Make sure the object 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

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

  2. 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 governance-mode retention with Moscow time offset (UTC+3)

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" \
Previous
Getting a public link to an object
Next
Deleting an object