Skip to content

feat(object storage): update object storage guide for the V1 release #9132

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
OvhValentin wants to merge 2 commits into
base: develop
Choose a base branch
from
Draft

feat(object storage): update object storage guide for the V1 release #9132

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fb1e680
feat(object storage): update object storage guide for the V1 release
OvhValentin Mar 3, 2026
6d44b8f
add
OvhValentin Mar 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
206 changes: 142 additions & 64 deletions pages/storage_and_backup/object_storage/s3_managing_object_lock/guide.en-gb.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,20 @@ excerpt: Object Lock is a feature that allows you to store objects using a Write
updated: 2025-03-25
---

<style>
details>summary {
color:rgb(33, 153, 232) !important;
cursor: pointer;
}
details>summary::before {
content:'\25B6';
padding-right:1ch;
}
details[open]>summary::before {
content:'\25BC';
}
</style>

## Objective

Object Lock is a feature that allows you to store objects using a **W**rite **O**nce, **R**ead **M**any (WORM) model and can be used for scenarios where it is imperative that data is not changed or deleted after it has been written.
Expand All @@ -16,25 +30,9 @@ Object Lock provides two ways to manage object retention. The first is *retentio

### How does Object Lock work ?

To understand how Object Lock lock works, we must first understand how deletion of objects and versioning work together. When a delete object operation is performed on an object in a versioning-enabled bucket, it does not delete the object permanently but it creates a delete marker on the object. This delete marker becomes the latest and current version of the object with a new version id.

A delete marker has the following properties:
Object Lock allows objects to be made immutable for a defined period (*Retention*) or indefinitely (*Legal hold*).

- A key and version ID like any other object.
- It does not have data associated with it, thus it does not retrieve anything from a GET request (you get a 404 error).
- By default, it is not displayed in the Control Panel UI anymore.
- The only operation you can use on a delete marker is DELETE, and only the bucket owner can issue such a request.

To permanently delete an object, you have to specify the version-id in your delete object request:

```bash
aws s3api delete-object --bucket my-bucket --key an-object --version-id 123456huijw0
```

The Object Lock feature prevents objects, for a fixed amount of time (retention mode) or indefinitely (legal hold), from being:

- deleted even if you specify the version id (you get an Access Denied error) ;
- overwritten by using versioning.
For the feature to work, versioning must be enabled on the bucket.

> [!primary]
>
Expand All @@ -43,22 +41,35 @@ The Object Lock feature prevents objects, for a fixed amount of time (retention

### Retention periods

A retention period specifies a fixed period of time during which an object remains locked. During this period, your object is protected and can’t be overwritten or deleted. You apply a retention period either in number of days or number of years with the minimum being 1-day and no maximum limit.
A retention period defines the length of time an object remains locked. During this period, the object is protected and cannot be modified or deleted. Retention can be defined in days or years, with a minimum of one day and no maximum limit.

When setting a retention period for your objects or buckets, you can choose the retention mode you wish to apply to your objects. You can choose either the *Governance mode* or the *Compliance mode* for your objects.
When defining a retention period for a bucket or its objects, you must choose the retention mode to apply: **Governance** or **Compliance**.

#### Governance mode

You should use the Governance mode if you want to protect objects from being deleted by most users during a pre-defined retention period, while authorising some users with special permissions to have the flexibility to alter the retention settings or delete the objects. Users with the `s3:BypassGovernanceRetention` permission can override or remove governance-mode retention settings.
**Governance** mode prevents most users from deleting or modifying objects during the retention period, while allowing certain users with specific rights to manage retention or delete objects.

Authorized users with `s3:BypassGovernanceRetention` can thus replace or delete objects in **Governance** mode.

> [!primary]
>
> **Best practice:** Use **Governance** mode when you want to protect your data while maintaining operational flexibility for specific administrative roles.
>

#### Compliance mode

You should use the Compliance mode if you have a requirement to store compliant data.
When this mode is set, an object version cannot be overwritten or deleted by any user. If this mode is configured for an object, then its retention mode cannot be changed, and its retention period can’t be shortened.
**Compliance** mode ensures that objects cannot be modified or deleted by any user, including administrators, during the entire retention period.

Once this mode is enabled for an object, its retention mode and duration cannot be changed.

> [!primary]
>
> **Best practice:** Only use **Compliance** mode if you need to ensure strict immutability for compliance or regulatory purposes.
>

> [!warning]
>
> You should only use the Compliance mode if you never want any user, including the administrator user, to be able to delete the objects during a pre-defined retention period.
> Compliance mode should only be selected if no user, including the administrator, should be able to delete or modify objects during the retention period.
>

### Legal hold
Expand Down Expand Up @@ -99,56 +110,75 @@ See our [Getting started with Object Storage](/pages/storage_and_backup/object_s

### Object Lock configuration

To use Object Lock, you have to create a bucket that supports the feature with the `--object-lock-enabled-for-bucket` flag. If a bucket is created without `--object-lock-enabled-for-bucket`, the flag cannot be added later.

> [!primary]
>
> The following command does not apply Object Lock to the bucket’s objects, it only activates the feature.
>

```bash
aws s3api create-bucket \
--bucket object-lock-bucket \
--object-lock-enabled-for-bucket
```

> [!primary]
> Enabling Object Lock does not automatically apply to existing or future objects in the bucket. It only enables the feature at the bucket level; a retention configuration must then be defined for objects to be effectively protected.
>
> This action also enables versioning of the bucket.
>

> [!tabs]
> Via AWS cli
>> To use Object Lock, you have to create a bucket that supports the feature with the `--object-lock-enabled-for-bucket` flag. If a bucket is created without `--object-lock-enabled-for-bucket`, the flag cannot be added later.
>>
>> ```bash
>> aws s3api create-bucket \
>> --bucket object-lock-bucket \
>> --object-lock-enabled-for-bucket
>> ```
>>
> Via the OVHcloud Control Panel
>> To manage an Object Storage bucket, first log in to your [OVHcloud Control Panel](/links/manager) and open your `Public Cloud`{.action} project.
>>
>> Click on `Object Storage`{.action} in the navigation bar, then click on `Create object container`{.action}.
>>
>> When creating an Object Storage bucket, a dedicated step allows you to enable Object Lock in order to store objects in WORM (Write Once, Read Many) mode.
>>
>> Once Object Lock is enabled, the setting is irreversible for the bucket concerned. All stored objects are therefore guaranteed to remain immutable until the end of the defined retention period.
>>

### How to configure Object Lock on bucket

The lock configuration enables you to set a lock configuration on a specified bucket. Once set, the rule specified in the Object Lock configuration is applied by default to every new object placed in the specified bucket.

```bash
aws s3api put-object-lock-configuration \
--bucket object-lock-bucket \
--object-lock-configuration '{ "ObjectLockEnabled": "Enabled", "Rule": { "DefaultRetention": { "Mode": "GOVERNANCE", "Days": 60 }}}'
```

To view the Object Lock configuration of a bucket, run:

```bash
aws s3api get-object-lock-configuration \
--bucket object-lock-bucket
```

The result should look like this:

```json
{
"ObjectLockConfiguration": {
"ObjectLockEnabled": "Enabled",
"Rule": {
"DefaultRetention": {
"Mode": "GOVERNANCE",
"Days": 60
}
}
}
}
```
> [!tabs]
> Via AWS cli
>> ```bash
>> aws s3api put-object-lock-configuration \
>> --bucket object-lock-bucket \
>> --object-lock-configuration '{ "ObjectLockEnabled": "Enabled", "Rule": { "DefaultRetention": { "Mode": "GOVERNANCE", "Days": 60 }}}'
>> ```
>>
>> To view the Object Lock configuration of a bucket, run:
>>
>> ```bash
>> aws s3api get-object-lock-configuration \
>> --bucket object-lock-bucket
>> ```
>>
>> The result should look like this:
>>
>> ```json
>> {
>> "ObjectLockConfiguration": {
>> "ObjectLockEnabled": "Enabled",
>> "Rule": {
>> "DefaultRetention": {
>> "Mode": "GOVERNANCE",
>> "Days": 60
>> }
>> }
>> }
>> }
>> ```
>>
> Via the OVHcloud Control Panel
>> To manage an Object Storage bucket, first log in to your [OVHcloud control panel](/links/manager) and open your `Public Cloud`{.action} project.
>>
>> Click on `Object Storage`{.action} in the navigation bar, then on the `My containers`{.action} tab, and then on the `name of your container`{.action}.
>>
>> From the `General Information`{.action} tab, click `Configure Retention`{.action}, enable retention, and then set the applicable retention mode and period. Next, click the `Save`{.action} button.
>>

### How to configure an Object Lock retention period on an object

Expand Down Expand Up @@ -241,6 +271,54 @@ The result should look like this:
}
```

### Object Lock and Object Deletion

When versioning is enabled, deleting an object does not delete the object immediately but creates a **delete flag**. This flag becomes the current version of the object with a new ID.

A delete flag:

- Has a key and version ID like any other object.
- Does not contain data (GET returns 404).
- Is not displayed by default in the customer area.
- Can only be manipulated by DELETE, by the bucket owner.

The **Object Lock** feature prevents objects from being:

- Deleted even with a version ID (returns `Access Denied`).
- Overwritten by versioning.

#### How deletions work with Object Lock

When Object Lock is enabled and an object is protected by a retention period or legal hold, deletion attempts behave differently depending on the type of request:

/// details | **Deletion with version ID (permanent DELETE)**

- Deletion is blocked during the retention period.
- The response returned is 403 Forbidden (Access denied).
- This protection applies to all users, even administrators, depending on the retention mode.

To permanently delete an object, you must specify the version ID in your request:

```bash
aws s3api delete-object --bucket my-bucket --key an-object --version-id 123456huijw0
```

> [!primary]
>
> This command will fail if the object is protected by Object Lock in Compliance or Governance mode without the appropriate bypass.
>

///

/// details | **Deletion without version ID (simple DELETE)**
- The request returns 200 OK.
- A deletion token is created in the bucket and becomes the current version of the object.
- The object remains protected by the retention period.

**Note:** Deletion markers and access errors can be managed via the corresponding APIs/CLIs.

///

## Go further

If you need training or technical assistance to implement our solutions, contact your sales representative or click on [this link](/links/professional-services) to get a quote and ask our Professional Services experts for assisting you on your specific use case of your project.
Expand Down
Loading