Object Storage - Conditional writes

Objective

This guide explains how to use the If-Match and If-None-Match HTTP conditional headers on PutObject, DeleteObject, and CompleteMultipartUpload requests on your OVHcloud Object Storage buckets.

Requirements

• A Public Cloud project in your OVHcloud account
• An Object Storage user already created
• AWS CLI installed and configured

Instructions

Why use conditional writes?

Object Storage is inherently concurrent - multiple application instances, microservices, or background jobs may read and write the same object at the same time. Without coordination, concurrent writes can silently overwrite each other, causing data loss that is difficult to detect and reproduce.

Conditional writes solve this problem at the storage layer, without requiring an external coordination service such as a database or a distributed lock manager. By attaching a precondition to an S3¹ API call, you ensure the operation only proceeds if the object is in the expected state at the moment the request is evaluated.

Key benefits:

• Data integrity in concurrent environments: Prevent a write from silently overwriting changes made by another process between your read and your write (a classic check-then-act race condition).
• Distributed locking primitive: Implement a lightweight, storage-native lock using If-None-Match: * on PutObject - only the first writer succeeds; all others receive 412 Precondition Failed.
• Atomic compare-and-swap: Read an object's ETag, modify it, then write back with If-Match: <original_etag>. The write is rejected if the object was modified in between, giving you a safe optimistic concurrency pattern.
• No extra infrastructure: Coordination happens inside the Object Storage service itself - no additional databases, queues, or lock managers required.
• Any S3-compatible client: The conditional headers are part of the HTTP standard (RFC 9110) and the S3 API - they work with AWS CLI, any S3 SDK, and raw HTTP calls.

Overview

Conditional requests allow you to attach a precondition to an S3 API call based on the current state of the target object. OVHcloud Object Storage evaluates the condition atomically before executing the operation. If the condition is not met, the request is rejected without modifying any data.

Two HTTP headers are supported, based on RFC 9110:

Supported operations:

Response codes

Versioning and delete markers

All conditions are evaluated against the current version of the object, regardless of whether versioning is enabled on the bucket.

PutObject - conditional write

Add a precondition to an object upload to prevent accidental overwrites or to implement first-write-wins logic.

Use cases:

• First-write-wins / distributed lock: Multiple processes race to create the same object. Only the first call with If-None-Match: * succeeds - all others receive 412.
• Safe overwrite: Read an object, modify it, write it back with If-Match: <original_etag>. If another client modified the object in between, the write is rejected.
• Idempotent initialisation: Create a configuration object without risk of overwriting an existing version.

# Write only if the object does not exist (first-write-wins)
aws s3api put-object \
  --bucket <bucket_name> \
  --key <object_key> \
  --body <local_file_path> \
  --if-none-match "*"

# Write only if the current ETag matches (safe overwrite)
aws s3api put-object \
  --bucket <bucket_name> \
  --key <object_key> \
  --body <local_file_path> \
  --if-match <current_etag>

# Write only if the object exists (any ETag)
aws s3api put-object \
  --bucket <bucket_name> \
  --key <object_key> \
  --body <local_file_path> \
  --if-match "*"

{
    "ETag": "d41d8cd98f00b204e9800998ecf8427e"
}

An error occurred (PreconditionFailed) when calling the PutObject operation:
At least one of the pre-conditions you specified did not hold

# Write only if the object does not exist
curl -X PUT \
  -H "If-None-Match: *" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @<local_file_path> \
  --aws-sigv4 "aws:amz:<region>:s3" \
  --user "<access_key>:<secret_key>" \
  "https://s3.<region>.io.cloud.ovh.net/<bucket_name>/<object_key>"

# Write only if the current ETag matches
curl -X PUT \
  -H "If-Match: <current_etag>" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @<local_file_path> \
  --aws-sigv4 "aws:amz:<region>:s3" \
  --user "<access_key>:<secret_key>" \
  "https://s3.<region>.io.cloud.ovh.net/<bucket_name>/<object_key>"

DeleteObject - conditional delete

Delete an object only if the ETag condition is satisfied. Only If-Match is supported for DeleteObject - If-None-Match is not applicable.

Use cases:

• Safe delete: Read an object's ETag, then delete it with If-Match: <etag>. The delete is rejected if the object was modified between your read and your delete.
• Delete-if-exists: Use If-Match: * to delete an object only if it currently exists.

# Delete only if the current ETag matches
aws s3api delete-object \
  --bucket <bucket_name> \
  --key <object_key> \
  --if-match <current_etag>

# Delete only if the object exists (any ETag)
aws s3api delete-object \
  --bucket <bucket_name> \
  --key <object_key> \
  --if-match "*"

# Delete a specific version only if its ETag matches
aws s3api delete-object \
  --bucket <bucket_name> \
  --key <object_key> \
  --version-id <version_id> \
  --if-match <version_etag>

CompleteMultipartUpload - conditional finalisation

Attach a precondition to the final step of a multipart upload. The condition is evaluated at the time CompleteMultipartUpload is called, not when CreateMultipartUpload was initiated.

Use cases:

• Atomic large-file replacement: Begin a multipart upload of a large replacement file. At finalisation, use If-Match: <etag> to ensure the target object has not been modified during the upload.
• First-write-wins for large files: Use If-None-Match: * at finalisation so that only one concurrent multipart upload permanently creates the object.

# Finalize only if the object does not yet exist
aws s3api complete-multipart-upload \
  --bucket <bucket_name> \
  --key <object_key> \
  --upload-id <upload_id> \
  --multipart-upload file://parts.json \
  --if-none-match "*"

# Finalize only if the current ETag matches
aws s3api complete-multipart-upload \
  --bucket <bucket_name> \
  --key <object_key> \
  --upload-id <upload_id> \
  --multipart-upload file://parts.json \
  --if-match <current_etag>

Important considerations

• Atomicity: The condition check and the operation execute as a single atomic unit. No concurrent operation can alter the object between the check and the write.
• Single header per request: You cannot combine If-Match and If-None-Match in the same request - this results in 400 Bad Request.
• 409 retry for PutObject / DeleteObject: On 409 ConditionalRequestConflict, re-fetch the object's current ETag with HeadObject and retry your request with the updated value.
• No IAM changes required: No additional permissions are needed. The existing s3:PutObject and s3:DeleteObject permissions are sufficient.
• Object Lock compatibility: Conditional headers are evaluated independently from Object Lock (WORM) rules. Both constraints apply.

Go further

Join our community of users.

¹: S3 is a trademark of Amazon Technologies, Inc. OVHcloud's service is not sponsored by, endorsed by, or otherwise affiliated with Amazon Technologies, Inc.