From ab51186a3021f8a9ecbb3e94d296366b2edb3473 Mon Sep 17 00:00:00 2001
From: Andrei Ciobanu <andrei.ciobanu@opentofu.org>
Date: Wed, 29 Oct 2025 11:23:59 +0200
Subject: [PATCH] Add examples on how to use 'state_tags' and 'lock_tags'
 (#3437)

Signed-off-by: Andrei Ciobanu <andrei.ciobanu@opentofu.org>
---
 .../docs/language/settings/backends/s3.mdx    | 37 +++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/website/docs/language/settings/backends/s3.mdx b/website/docs/language/settings/backends/s3.mdx
index 5871dceb10..70958e7721 100644
--- a/website/docs/language/settings/backends/s3.mdx
+++ b/website/docs/language/settings/backends/s3.mdx
@@ -395,6 +395,43 @@ To migrate from DynamoDB to S3 locking, the following steps can be followed:
 Remember: any changes to the `backend` block will require you to run `tofu init -reconfigure`.
 :::
 
+### Control what tags are stored on the S3 objects
+
+To enable more granular lifecycle rules for the objects OpenTofu stores in the configured S3 bucket, two attributes can be used to tag the objects with the desired tags.
+
+#### State object tags
+
+Configuring `state_tags` in the backend block will store the configured tags on the object everytime it is updated.
+
+```hcl
+terraform {
+  backend "s3" {
+    // ...
+    state_tags = {
+      "object:type": "state"
+      // ...
+    }
+  }
+}
+```
+
+#### Lock object tags
+
+When using the native S3 locking mechanism through `use_lockfile`, OpenTofu will create an object on the same bucket that is used to store the state, so to tag that you can use `lock_tags`:
+
+```hcl
+terraform {
+  backend "s3" {
+    // ...
+    use_lockfile = true
+    lock_tags = {
+      "object:type": "lock"
+      // ...
+    }
+  }
+}
+```
+
 ## Multi-account AWS Architecture
 
 A common architectural pattern is for an organization to use a number of