feat: implement bucket tagging operations (GetBucketTagging, PutBucketTagging, DeleteBucketTagging)

Co-authored-by: afranken <763000+afranken@users.noreply.github.com>

Author: Copilot

CHANGELOG.md

@@ -145,6 +145,7 @@ Version 5.x is JDK17 LTS bytecode compatible, with Docker and JUnit / direct Jav
 ## 5.0.0
 
 * Features and fixes
+  * Implement bucket tagging operations: `GetBucketTagging`, `PutBucketTagging`, `DeleteBucketTagging`.
   * Breaking change (file system): Remove "DisplayName" from Owner. (fixes #2738)
     * AWS APIs stopped returning "DisplayName" in November 2025.
     * This is unfortunately a breaking change for clients starting S3Mock on existing file systems.

integration-tests/src/test/kotlin/com/adobe/testing/s3mock/its/BucketTaggingIT.kt

@@ -0,0 +1,84 @@
+/*
+ *  Copyright 2017-2026 Adobe.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *          http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+package com.adobe.testing.s3mock.its
+
+import org.assertj.core.api.Assertions.assertThat
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.TestInfo
+import software.amazon.awssdk.services.s3.S3Client
+import software.amazon.awssdk.services.s3.model.Tag
+
+internal class BucketTaggingIT : S3TestBase() {
+  private val s3Client: S3Client = createS3Client()
+
+  @Test
+  @S3VerifiedTodo
+  fun `GET BucketTagging returns empty tag set when no tags are set`(testInfo: TestInfo) {
+    val bucketName = givenBucket(testInfo)
+
+    val tagSet = s3Client.getBucketTagging { it.bucket(bucketName) }.tagSet()
+
+    assertThat(tagSet).isEmpty()
+  }
+
+  @Test
+  @S3VerifiedTodo
+  fun `PUT and GET BucketTagging succeeds`(testInfo: TestInfo) {
+    val bucketName = givenBucket(testInfo)
+    val tag1 = tag("env", "prod")
+    val tag2 = tag("team", "backend")
+
+    s3Client.putBucketTagging {
+      it.bucket(bucketName)
+      it.tagging { t -> t.tagSet(tag1, tag2) }
+    }
+
+    val tagSet = s3Client.getBucketTagging { it.bucket(bucketName) }.tagSet()
+
+    assertThat(tagSet).contains(tag1, tag2)
+  }
+
+  @Test
+  @S3VerifiedTodo
+  fun `PUT and GET and DELETE BucketTagging succeeds`(testInfo: TestInfo) {
+    val bucketName = givenBucket(testInfo)
+    val tag1 = tag("env", "staging")
+    val tag2 = tag("owner", "team-a")
+
+    s3Client.putBucketTagging {
+      it.bucket(bucketName)
+      it.tagging { t -> t.tagSet(tag1, tag2) }
+    }
+
+    assertThat(s3Client.getBucketTagging { it.bucket(bucketName) }.tagSet())
+      .contains(tag1, tag2)
+
+    s3Client.deleteBucketTagging { it.bucket(bucketName) }
+
+    assertThat(s3Client.getBucketTagging { it.bucket(bucketName) }.tagSet())
+      .isEmpty()
+  }
+
+  private fun tag(
+    key: String,
+    value: String,
+  ): Tag =
+    Tag
+      .builder()
+      .key(key)
+      .value(value)
+      .build()
+}

server/src/main/kotlin/com/adobe/testing/s3mock/controller/BucketController.kt

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2017-2025 Adobe.
+ *  Copyright 2017-2026 Adobe.
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -26,6 +26,7 @@ import com.adobe.testing.s3mock.dto.LocationConstraint
 import com.adobe.testing.s3mock.dto.ObjectLockConfiguration
 import com.adobe.testing.s3mock.dto.ObjectOwnership
 import com.adobe.testing.s3mock.dto.Region
+import com.adobe.testing.s3mock.dto.Tagging
 import com.adobe.testing.s3mock.dto.VersioningConfiguration
 import com.adobe.testing.s3mock.service.BucketService
 import com.adobe.testing.s3mock.util.AwsHttpHeaders.X_AMZ_BUCKET_OBJECT_LOCK_ENABLED
@@ -45,11 +46,13 @@ import com.adobe.testing.s3mock.util.AwsHttpParameters.NOT_LIFECYCLE
 import com.adobe.testing.s3mock.util.AwsHttpParameters.NOT_LIST_TYPE
 import com.adobe.testing.s3mock.util.AwsHttpParameters.NOT_LOCATION
 import com.adobe.testing.s3mock.util.AwsHttpParameters.NOT_OBJECT_LOCK
+import com.adobe.testing.s3mock.util.AwsHttpParameters.NOT_TAGGING
 import com.adobe.testing.s3mock.util.AwsHttpParameters.NOT_UPLOADS
 import com.adobe.testing.s3mock.util.AwsHttpParameters.NOT_VERSIONING
 import com.adobe.testing.s3mock.util.AwsHttpParameters.NOT_VERSIONS
 import com.adobe.testing.s3mock.util.AwsHttpParameters.OBJECT_LOCK
 import com.adobe.testing.s3mock.util.AwsHttpParameters.START_AFTER
+import com.adobe.testing.s3mock.util.AwsHttpParameters.TAGGING
 import com.adobe.testing.s3mock.util.AwsHttpParameters.VERSIONING
 import com.adobe.testing.s3mock.util.AwsHttpParameters.VERSIONS
 import com.adobe.testing.s3mock.util.AwsHttpParameters.VERSION_ID_MARKER
@@ -119,6 +122,7 @@ class BucketController(private val bucketService: BucketService) {
     params = [
       NOT_OBJECT_LOCK,
       NOT_LIFECYCLE,
+      NOT_TAGGING,
       NOT_VERSIONING
     ]
   )
@@ -186,7 +190,8 @@ class BucketController(private val bucketService: BucketService) {
       // AWS SDK V1 pattern
       "/{bucketName:.+}/"
     ], params = [
-      NOT_LIFECYCLE
+      NOT_LIFECYCLE,
+      NOT_TAGGING
     ]
   )
   @S3Verified(year = 2025)
@@ -365,6 +370,76 @@ class BucketController(private val bucketService: BucketService) {
     return ResponseEntity.noContent().build()
   }
 
+  /**
+   * [API Reference](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketTagging.html).
+   */
+  @GetMapping(
+    value = [
+      // AWS SDK V2 pattern
+      "/{bucketName:.+}",
+      // AWS SDK V1 pattern
+      "/{bucketName:.+}/"
+    ],
+    params = [
+      TAGGING,
+      NOT_LIST_TYPE
+    ],
+    produces = [
+      MediaType.APPLICATION_XML_VALUE
+    ]
+  )
+  @S3Verified(year = 2026)
+  fun getBucketTagging(@PathVariable bucketName: String): ResponseEntity<Tagging> {
+    bucketService.verifyBucketExists(bucketName)
+    val tagging = bucketService.getBucketTagging(bucketName)
+    return ResponseEntity.ok(tagging)
+  }
+
+  /**
+   * [API Reference](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketTagging.html).
+   */
+  @PutMapping(
+    value = [
+      // AWS SDK V2 pattern
+      "/{bucketName:.+}",
+      // AWS SDK V1 pattern
+      "/{bucketName:.+}/"
+    ],
+    params = [
+      TAGGING
+    ]
+  )
+  @S3Verified(year = 2026)
+  fun putBucketTagging(
+    @PathVariable bucketName: String,
+    @RequestBody tagging: Tagging
+  ): ResponseEntity<Void> {
+    bucketService.verifyBucketExists(bucketName)
+    bucketService.setBucketTagging(bucketName, tagging)
+    return ResponseEntity.ok().build()
+  }
+
+  /**
+   * [API Reference](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucketTagging.html).
+   */
+  @DeleteMapping(
+    value = [
+      // AWS SDK V2 pattern
+      "/{bucketName:.+}",
+      // AWS SDK V1 pattern
+      "/{bucketName:.+}/"
+    ],
+    params = [
+      TAGGING
+    ]
+  )
+  @S3Verified(year = 2026)
+  fun deleteBucketTagging(@PathVariable bucketName: String): ResponseEntity<Void> {
+    bucketService.verifyBucketExists(bucketName)
+    bucketService.deleteBucketTagging(bucketName)
+    return ResponseEntity.noContent().build()
+  }
+
   /**
    * [API Reference](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketLocation.html).
    */
@@ -404,6 +479,7 @@ class BucketController(private val bucketService: BucketService) {
       NOT_OBJECT_LOCK,
       NOT_LIST_TYPE,
       NOT_LIFECYCLE,
+      NOT_TAGGING,
       NOT_LOCATION,
       NOT_VERSIONS,
       NOT_VERSIONING

server/src/main/kotlin/com/adobe/testing/s3mock/service/BucketService.kt

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2017-2025 Adobe.
+ *  Copyright 2017-2026 Adobe.
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -34,6 +34,9 @@ import com.adobe.testing.s3mock.dto.Owner
 import com.adobe.testing.s3mock.dto.Prefix
 import com.adobe.testing.s3mock.dto.Region
 import com.adobe.testing.s3mock.dto.S3Object
+import com.adobe.testing.s3mock.dto.Tag
+import com.adobe.testing.s3mock.dto.Tagging
+import com.adobe.testing.s3mock.dto.TagSet
 import com.adobe.testing.s3mock.dto.VersioningConfiguration
 import com.adobe.testing.s3mock.store.BucketMetadata
 import com.adobe.testing.s3mock.store.BucketStore
@@ -181,6 +184,22 @@ open class BucketService(
     return bucketMetadata.bucketLifecycleConfiguration ?: throw S3Exception.NO_SUCH_LIFECYCLE_CONFIGURATION
   }
 
+  fun getBucketTagging(bucketName: String): Tagging {
+    val bucketMetadata = bucketStore.getBucketMetadata(bucketName)
+    val tags = bucketMetadata.tagging ?: emptyList()
+    return Tagging(TagSet(tags))
+  }
+
+  fun setBucketTagging(bucketName: String, tagging: Tagging) {
+    val bucketMetadata = bucketStore.getBucketMetadata(bucketName)
+    bucketStore.storeBucketTagging(bucketMetadata, tagging.tagSet.tags)
+  }
+
+  fun deleteBucketTagging(bucketName: String) {
+    val bucketMetadata = bucketStore.getBucketMetadata(bucketName)
+    bucketStore.storeBucketTagging(bucketMetadata, null)
+  }
+
   fun getS3Objects(bucketName: String, prefix: String?): List<S3Object> {
     val bucketMetadata = bucketStore.getBucketMetadata(bucketName)
     return bucketStore.lookupIdsInBucket(prefix, bucketName)

server/src/main/kotlin/com/adobe/testing/s3mock/store/BucketMetadata.kt

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2017-2025 Adobe.
+ *  Copyright 2017-2026 Adobe.
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -21,6 +21,7 @@ import com.adobe.testing.s3mock.dto.BucketLifecycleConfiguration
 import com.adobe.testing.s3mock.dto.LocationInfo
 import com.adobe.testing.s3mock.dto.ObjectLockConfiguration
 import com.adobe.testing.s3mock.dto.ObjectOwnership
+import com.adobe.testing.s3mock.dto.Tag
 import com.adobe.testing.s3mock.dto.VersioningConfiguration
 import com.fasterxml.jackson.annotation.JsonIgnore
 import com.fasterxml.jackson.annotation.JsonProperty
@@ -41,6 +42,7 @@ data class BucketMetadata(
   val bucketRegion: String,
   val bucketInfo: BucketInfo?,
   val locationInfo: LocationInfo?,
+  val tagging: List<Tag>? = null,
   @param:JsonProperty("objects")
   private val _objects: MutableMap<String, UUID> = mutableMapOf()
 ) {
@@ -69,6 +71,9 @@ data class BucketMetadata(
   fun withBucketLifecycleConfiguration(bucketLifecycleConfiguration: BucketLifecycleConfiguration?): BucketMetadata =
     this.copy(bucketLifecycleConfiguration = bucketLifecycleConfiguration)
 
+  fun withTagging(tagging: List<Tag>?): BucketMetadata =
+    this.copy(tagging = tagging)
+
   @get:JsonIgnore
   val isVersioningEnabled: Boolean
     get() = this.versioningConfiguration?.status == VersioningConfiguration.Status.ENABLED

server/src/main/kotlin/com/adobe/testing/s3mock/store/BucketStore.kt

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2017-2025 Adobe.
+ *  Copyright 2017-2026 Adobe.
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -22,6 +22,7 @@ import com.adobe.testing.s3mock.dto.LocationInfo
 import com.adobe.testing.s3mock.dto.ObjectLockConfiguration
 import com.adobe.testing.s3mock.dto.ObjectLockEnabled.ENABLED
 import com.adobe.testing.s3mock.dto.ObjectOwnership
+import com.adobe.testing.s3mock.dto.Tag
 import com.adobe.testing.s3mock.dto.VersioningConfiguration
 import org.slf4j.Logger
 import org.slf4j.LoggerFactory
@@ -195,6 +196,15 @@ open class BucketStore(
     }
   }
 
+  fun storeBucketTagging(
+    metadata: BucketMetadata,
+    tagging: List<Tag>?
+  ) {
+    synchronized(lockStore[metadata.name]!!) {
+      writeToDisk(metadata.withTagging(tagging))
+    }
+  }
+
   fun isBucketEmpty(bucketName: String): Boolean {
     check(doesBucketExist(bucketName)) { "Requested Bucket does not exist: $bucketName" }
     return getBucketMetadata(bucketName).objects.isEmpty()