Skip to main content
The object submodule manages individual S3 objects within a bucket. Use it to upload files, set metadata, configure server-side encryption per object, and manage object lock settings.

​
Module Reference

module "object" {
  source = "terraform-aws-modules/s3-bucket/aws//modules/object"

  bucket = module.s3_bucket.s3_bucket_id
  key    = "path/to/object.txt"

  # ... see variables below
}

​
Input Variables

​
Core

​
create
bool
default:"true"
Whether to create this resource or not. Set to false to conditionally skip object creation.
​
region
string
default:"null"
Region where the resource(s) will be managed. Defaults to the region set in the provider configuration.
​
bucket
string
default:"\"\""
The name of the bucket to put the file in. Alternatively, an S3 access point ARN can be specified.
​
key
string
default:"\"\""
The name of the object once it is in the bucket. This is the S3 key (path) under which the object is stored.

​
Content

​
file_source
string
default:"null"
The path to a file that will be read and uploaded as raw bytes for the object content. Use this for uploading local files.
​
content
string
default:"null"
Literal string value to use as the object content, which will be uploaded as UTF-8-encoded text.
​
content_base64
string
default:"null"
Base64-encoded data that will be decoded and uploaded as raw bytes for the object content. This allows safely uploading non-UTF8 binary data, but is recommended only for small content. For larger objects, use file_source.

​
HTTP Headers

​
content_type
string
default:"null"
A standard MIME type describing the format of the object data, e.g. application/octet-stream. All valid MIME types are valid for this input.
​
content_encoding
string
default:"null"
Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
​
content_language
string
default:"null"
The language the content is in, e.g. en-US or en-GB.
​
content_disposition
string
default:"null"
Specifies presentational information for the object.
​
cache_control
string
default:"null"
Specifies caching behavior along the request/reply chain.
​
website_redirect
string
default:"null"
Specifies a target URL for website redirect.

​
Storage & Encryption

​
storage_class
string
default:"null"
Specifies the desired Storage Class for the object. Can be STANDARD, REDUCED_REDUNDANCY, ONEZONE_IA, INTELLIGENT_TIERING, GLACIER, DEEP_ARCHIVE, or STANDARD_IA. Defaults to STANDARD.
​
server_side_encryption
string
default:"null"
Specifies server-side encryption of the object in S3. Valid values are AES256 and aws:kms.
​
kms_key_id
string
default:"null"
Amazon Resource Name (ARN) of the KMS Key to use for object encryption. If the S3 Bucket has server-side encryption enabled, that value will automatically be used. If referencing the aws_kms_key resource, use the arn attribute. If referencing the aws_kms_alias data source or resource, use the target_key_arn attribute.
​
bucket_key_enabled
bool
default:"null"
Whether or not to use Amazon S3 Bucket Keys for SSE-KMS. Reduces the cost of SSE-KMS by lowering calls to AWS KMS.

​
Access Control

​
acl
string
default:"null"
The canned ACL to apply. Valid values are private, public-read, public-read-write, aws-exec-read, authenticated-read, bucket-owner-read, and bucket-owner-full-control. Defaults to private.

​
Metadata & Tags

​
metadata
map(string)
default:"{}"
A map of keys/values to provision metadata (will be automatically prefixed by x-amz-meta-). Note that only lowercase labels are currently supported by the AWS Go API.
​
tags
map(string)
default:"{}"
A map of tags to assign to the object.
​
override_default_tags
bool
default:"false"
Ignore provider default_tags. S3 objects support a maximum of 10 tags.

​
Change Detection

​
etag
string
default:"null"
Used to trigger updates. This attribute is not compatible with KMS encryption, kms_key_id, or server_side_encryption = "aws:kms".
​
source_hash
string
default:"null"
Triggers updates like etag but useful to address etag encryption limitations. Set using filemd5("path/to/source") (Terraform 0.11.12 or later). The value is only stored in state and not saved by AWS.

​
Object Lock

​
force_destroy
bool
default:"false"
Allow the object to be deleted by removing any legal hold on any object version. This value should be set to true only if the bucket has S3 object lock enabled.
​
object_lock_legal_hold_status
string
default:"null"
The legal hold status that you want to apply to the specified object. Valid values are ON and OFF.
​
object_lock_mode
string
default:"null"
The object lock retention mode that you want to apply to this object. Valid values are GOVERNANCE and COMPLIANCE.
​
object_lock_retain_until_date
string
default:"null"
The date and time, in RFC3339 format, when this object’s object lock will expire.

​
Outputs

​
s3_object_id
string
The key (path) of the S3 object.
​
s3_object_etag
string
The ETag generated for the object (an MD5 sum of the object content).
​
s3_object_version_id
string
A unique version ID value for the object, if bucket versioning is enabled.

​
Complete Example

This example demonstrates uploading objects with different content sources and encryption settings. 
module "s3_bucket" {
  source = "terraform-aws-modules/s3-bucket/aws"

  bucket = "my-app-assets"

  versioning = {
    enabled = true
  }

  server_side_encryption_configuration = {
    rule = {
      apply_server_side_encryption_by_default = {
        sse_algorithm = "AES256"
      }
    }
  }
}

# Upload a local file
module "object_from_file" {
  source = "terraform-aws-modules/s3-bucket/aws//modules/object"

  bucket      = module.s3_bucket.s3_bucket_id
  key         = "assets/logo.png"
  file_source = "${path.module}/files/logo.png"
  content_type = "image/png"

  tags = {
    Environment = "production"
  }
}

# Upload inline text content
module "object_from_content" {
  source = "terraform-aws-modules/s3-bucket/aws//modules/object"

  bucket       = module.s3_bucket.s3_bucket_id
  key          = "config/settings.json"
  content      = jsonencode({ version = "1.0", debug = false })
  content_type = "application/json"

  metadata = {
    created-by = "terraform"
  }
}

# Upload with KMS encryption and object lock
module "object_locked" {
  source = "terraform-aws-modules/s3-bucket/aws//modules/object"

  bucket                        = module.s3_bucket.s3_bucket_id
  key                           = "sensitive/data.csv"
  file_source                   = "${path.module}/files/data.csv"
  content_type                  = "text/csv"
  server_side_encryption        = "aws:kms"
  kms_key_id                    = aws_kms_key.this.arn
  object_lock_mode              = "GOVERNANCE"
  object_lock_retain_until_date = "2026-12-31T00:00:00Z"
}