[Yandex Cloud documentation](../../../index.md) > [Yandex Object Storage](../../index.md) > [Step-by-step guides](../index.md) > Objects > Configuring an object lock

# Configuring object locks

With [versioning](../buckets/versioning.md) and [object lock](../buckets/configure-object-lock.md) 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) {#edit-retention}

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:

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select a folder.
  1. Navigate to **Object Storage**.
  1. Select the bucket you want to configure an object lock for.
  1. In the left-hand panel, select ![image](../../../_assets/console-icons/folder-tree.svg) **Objects**.
  1. To show all object versions in the list, enable **Show versions** to the right of the object search field in the bucket.
  1. In the list of objects, select the one you need, click ![image](../../../_assets/console-icons/ellipsis.svg), and select **Object lock**.
  1. In the window that opens, enable **Retention**.
  1. Select **Default lock type**:
     * **Governance**: User with the `storage.admin` role can bypass the lock, change its expiration date, or remove it.
     * **Compliance**: User with the `storage.admin` role can only extend the retention period. You cannot override, shorten, or remove such locks until they expire.
  1. Specify **Default lock period** in days or years. It starts from the moment you upload the object version to the bucket.
  1. Click **Save**.

- Yandex Cloud CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

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

      ```bash
      yc storage s3api put-object-retention --help
      ```

  1. Get a list of buckets in the default folder:
     
     ```bash
     yc storage bucket list
     ```
     
     Result:
     
     ```text
     +------------------+----------------------+-------------+-----------------------+---------------------+
     |       NAME       |      FOLDER ID       |  MAX SIZE   | DEFAULT STORAGE CLASS |     CREATED AT      |
     +------------------+----------------------+-------------+-----------------------+---------------------+
     | first-bucket     | b1gmit33ngp6******** | 53687091200 | STANDARD              | 2022-12-16 13:58:18 |
     +------------------+----------------------+-------------+-----------------------+---------------------+
     ```
  1. Set up retention for an object version:

      ```bash
      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](../../concepts/object.md#key).
      * `--version-id`: Object version ID.
      * `--retention`: Retention settings (both parameters are required):
      
          * `Mode`: Retention [type](../../concepts/object-lock.md#types):
      
              * `GOVERNANCE`: Governance-mode retention. You cannot set this type if an object version is already locked in compliance mode.
              * `COMPLIANCE`: Compliance-mode retention.
      
          * `RetainUntilDate`: Retention expiration date and time in [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) format, e.g., `2025-01-01T00:00:00Z`. The expiration time value is specified in [UTC±00:00](https://en.wikipedia.org/wiki/UTC%2B00:00). 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](#example-lock). If an object version is already locked in compliance mode, you can only extend it by setting new expiration date and time that are later than the current ones.
      
      * `--bypass-governance-retention`: Flag to enable bypassing the lock. Select it if an object version is already locked in governance mode.

      Result:

      ```bash
      request_id: c5984d03********
      ```

  1. Make sure the object lock settings are updated:
     
     ```bash
     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:

      ```text
      request_id: 077b184e********
      retention:
        mode: GOVERNANCE
        retain_until_date: "2024-12-01T10:49:08.363Z"
      ```

      The `mode` field states the lock [type](../../concepts/object-lock.md#types), while the `retain_until_date` field states its end date.

- AWS CLI {#aws-cli}

  1. If you do not have the AWS CLI yet, [install and configure it](../../tools/aws-cli.md).
  1. Run this command:

     ```bash
     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](../../concepts/object.md#key).
     * `--version-id`: Object version ID.
     * `--retention`: Retention settings (both parameters are required):
     
         * `Mode`: Retention [type](../../concepts/object-lock.md#types):
     
             * `GOVERNANCE`: Governance-mode retention. You cannot set this type if an object version is already locked in compliance mode.
             * `COMPLIANCE`: Compliance-mode retention.
     
         * `RetainUntilDate`: Retention expiration date and time in [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) format, e.g., `2025-01-01T00:00:00Z`. The expiration time value is specified in [UTC±00:00](https://en.wikipedia.org/wiki/UTC%2B00:00). 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](#example-lock). If an object version is already locked in compliance mode, you can only extend it by setting new expiration date and time that are later than the current ones.
     
     * `--bypass-governance-retention`: Flag to enable bypassing the lock. Select it if an object version is already locked in governance mode.

- API {#api}

  Use the [putObjectRetention](../../s3/api-ref/object/putobjectretention.md) S3 API method.

{% endlist %}

During the lock period, the object version is protected from deletion and modification. You can still perform actions on the object, but these will create new versions. You will be able to [restore the locked version](restore-object-version.md) until the lock expires.

## Removing governance-mode retention {#remove-governance-retention}

The minimum required role is `storage.admin`.

To remove retention:

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select a folder.
  1. Navigate to **Object Storage**.
  1. Select the bucket from the list.
  1. In the left-hand panel, select ![image](../../../_assets/console-icons/folder-tree.svg) **Objects**.
  1. To show all object versions in the list, enable **Show versions** to the right of the object search field in the bucket.
  1. In the list of objects, select the one you need, click ![image](../../../_assets/console-icons/ellipsis.svg), and select **Object lock**.
  1. In the window that opens, disable **Retention**.
  1. Click **Save**.

- Yandex Cloud CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

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

      ```bash
      yc storage s3api put-object-retention --help
      ```

  1. Get a list of buckets in the default folder:
     
     ```bash
     yc storage bucket list
     ```
     
     Result:
     
     ```text
     +------------------+----------------------+-------------+-----------------------+---------------------+
     |       NAME       |      FOLDER ID       |  MAX SIZE   | DEFAULT STORAGE CLASS |     CREATED AT      |
     +------------------+----------------------+-------------+-----------------------+---------------------+
     | first-bucket     | b1gmit33ngp6******** | 53687091200 | STANDARD              | 2022-12-16 13:58:18 |
     +------------------+----------------------+-------------+-----------------------+---------------------+
     ```
  1. Set up retention for an object version:

      ```bash
      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](../../concepts/object.md#key).
      * `--version-id`: Object version ID.
      * `--retention`: Retention settings. In both parameters, empty lines are specified to remove a lock.
      * `--bypass-governance-retention`: Flag to enable bypassing the lock.

      Result:

      ```bash
      request_id: m6384f81********
      ```

  1. Make sure the object lock settings are updated:
     
     ```bash
     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:

      ```text
      The specified object does not have a ObjectLock configuration.
      ```

- AWS CLI {#aws-cli}

  1. If you do not have the AWS CLI yet, [install and configure it](../../tools/aws-cli.md).
  1. Run this command:

     ```bash
     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](../../concepts/object.md#key).
     * `--version-id`: Object version ID.
     * `--retention`: Retention settings. In both parameters, empty lines are specified to remove a lock.
     * `--bypass-governance-retention`: Flag to enable bypassing the lock.

- API {#api}

  Use the [putObjectRetention](../../s3/api-ref/object/putobjectretention.md) S3 API method with the `X-Amz-Bypass-Governance-Retention: true` header and empty `Retention` element.

{% endlist %}


## Setting or removing legal hold {#edit-legal-hold}

The minimum required role is `storage.uploader`.

To set or remove legal hold:

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select a folder.
  1. Navigate to **Object Storage**.
  1. Select the bucket from the list.
  1. In the left-hand panel, select ![image](../../../_assets/console-icons/folder-tree.svg) **Objects**.
  1. To show all object versions in the list, enable **Show versions** to the right of the object search field in the bucket.
  1. In the list of objects, select the one you need, click ![image](../../../_assets/console-icons/ellipsis.svg), and select **Object lock**.
  1. In the window that opens, enable or disable **Legal hold**.
  1. Click **Save**.

- Yandex Cloud CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

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

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

  1. Get a list of buckets in the default folder:
     
     ```bash
     yc storage bucket list
     ```
     
     Result:
     
     ```text
     +------------------+----------------------+-------------+-----------------------+---------------------+
     |       NAME       |      FOLDER ID       |  MAX SIZE   | DEFAULT STORAGE CLASS |     CREATED AT      |
     +------------------+----------------------+-------------+-----------------------+---------------------+
     | first-bucket     | b1gmit33ngp6******** | 53687091200 | STANDARD              | 2022-12-16 13:58:18 |
     +------------------+----------------------+-------------+-----------------------+---------------------+
     ```
  1. Set up legal hold for an object version:

      ```bash
      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](../../concepts/object.md#key).
      * `--version-id`: Object version ID.
      * `--legal-hold`: Indefinite lock settings:
      
          * `Status`: Lock status:
      
              * `ON`: Enabled.
              * `OFF`: Disabled.

      Result:

      ```bash
      request_id: cb262625********
      ```

  1. Make sure the object lock settings are updated:

      ```bash
      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:

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

- AWS CLI {#aws-cli}

  1. If you do not have the AWS CLI yet, [install and configure it](../../tools/aws-cli.md).

  1. Run this command:

     ```bash
     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](../../concepts/object.md#key).
     * `--version-id`: Object version ID.
     * `--legal-hold`: Indefinite lock settings:
     
         * `Status`: Lock status:
     
             * `ON`: Enabled.
             * `OFF`: Disabled.

- API {#api}

  Use the [putObjectLegalHold](../../s3/api-ref/object/putobjectlegalhold.md) S3 API method.

{% endlist %}

If you set a lock, the object version will be protected from deletion and modification. Actions with the object will create new versions, and it will be possible to [restore the locked version](restore-object-version.md) until the lock is removed.

## Examples {#examples}

### Setting governance-mode retention with Moscow time offset (UTC+3) {#example-lock}

{% list tabs group=instructions %}

- Yandex Cloud CLI {#cli}

  > ```bash
  > 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 CLI {#aws-cli}

  > ```bash
  > 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" \
  > ```

{% endlist %}