Skip to content

Resource: awsS3Object

Provides an S3 object resource.

Example Usage

Uploading a file to a bucket

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
new aws.s3Object.S3Object(this, "object", {
  bucket: "your_bucket_name",
  etag: '${filemd5("path/to/file")}',
  key: "new_object_key",
  source: "path/to/file",
});

Encrypting with KMS Key

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
const awsKmsKeyExamplekms = new aws.kmsKey.KmsKey(this, "examplekms", {
  deletionWindowInDays: 7,
  description: "KMS key 1",
});
const awsS3BucketExamplebucket = new aws.s3Bucket.S3Bucket(
  this,
  "examplebucket",
  {
    bucket: "examplebuckettftest",
  }
);
new aws.s3BucketAcl.S3BucketAcl(this, "example", {
  acl: "private",
  bucket: awsS3BucketExamplebucket.id,
});
const awsS3ObjectExample = new aws.s3Object.S3Object(this, "example_3", {
  bucket: awsS3BucketExamplebucket.id,
  key: "someobject",
  kmsKeyId: awsKmsKeyExamplekms.arn,
  source: "index.html",
});
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
awsS3ObjectExample.overrideLogicalId("example");

Server Side Encryption with S3 Default Master Key

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
const awsS3BucketExamplebucket = new aws.s3Bucket.S3Bucket(
  this,
  "examplebucket",
  {
    bucket: "examplebuckettftest",
  }
);
new aws.s3BucketAcl.S3BucketAcl(this, "example", {
  acl: "private",
  bucket: awsS3BucketExamplebucket.id,
});
const awsS3ObjectExample = new aws.s3Object.S3Object(this, "example_2", {
  bucket: awsS3BucketExamplebucket.id,
  key: "someobject",
  serverSideEncryption: "aws:kms",
  source: "index.html",
});
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
awsS3ObjectExample.overrideLogicalId("example");

Server Side Encryption with AWS-Managed Key

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
const awsS3BucketExamplebucket = new aws.s3Bucket.S3Bucket(
  this,
  "examplebucket",
  {
    bucket: "examplebuckettftest",
  }
);
new aws.s3BucketAcl.S3BucketAcl(this, "example", {
  acl: "private",
  bucket: awsS3BucketExamplebucket.id,
});
const awsS3ObjectExample = new aws.s3Object.S3Object(this, "example_2", {
  bucket: awsS3BucketExamplebucket.id,
  key: "someobject",
  serverSideEncryption: "AES256",
  source: "index.html",
});
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
awsS3ObjectExample.overrideLogicalId("example");

S3 Object Lock

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
const awsS3BucketExamplebucket = new aws.s3Bucket.S3Bucket(
  this,
  "examplebucket",
  {
    bucket: "examplebuckettftest",
    objectLockEnabled: true,
  }
);
new aws.s3BucketAcl.S3BucketAcl(this, "example", {
  acl: "private",
  bucket: awsS3BucketExamplebucket.id,
});
const awsS3BucketVersioningExample =
  new aws.s3BucketVersioning.S3BucketVersioningA(this, "example_2", {
    bucket: awsS3BucketExamplebucket.id,
    versioningConfiguration: {
      status: "Enabled",
    },
  });
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
awsS3BucketVersioningExample.overrideLogicalId("example");
new aws.s3Object.S3Object(this, "examplebucket_object", {
  bucket: awsS3BucketExamplebucket.id,
  depends_on: [`\${${awsS3BucketVersioningExample.fqn}}`],
  forceDestroy: true,
  key: "someobject",
  objectLockLegalHoldStatus: "ON",
  objectLockMode: "GOVERNANCE",
  objectLockRetainUntilDate: "2021-12-31T23:59:60Z",
  source: "important.txt",
});

Argument Reference

-> Note: If you specify contentEncoding you are responsible for encoding the body appropriately. source, content, and contentBase64 all expect already encoded/compressed bytes.

The following arguments are required:

  • bucket - (Required) Name of the bucket to put the file in. Alternatively, an S3 access point ARN can be specified.
  • key - (Required) Name of the object once it is in the bucket.

The following arguments are optional:

  • acl - (Optional) Canned ACL to apply. Valid values are private, publicRead, publicReadWrite, awsExecRead, authenticatedRead, bucketOwnerRead, and bucketOwnerFullControl. Defaults to private.
  • bucketKeyEnabled - (Optional) Whether or not to use Amazon S3 Bucket Keys for SSE-KMS.
  • cacheControl - (Optional) Caching behavior along the request/reply chain Read w3c cache_control for further details.
  • contentBase64 - (Optional, conflicts with source and content) 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 such as the result of the gzipbase64 function with small text strings. For larger objects, use source to stream the content from a disk file.
  • contentDisposition - (Optional) Presentational information for the object. Read w3c content_disposition for further information.
  • contentEncoding - (Optional) Content encodings that 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. Read w3c content encoding for further information.
  • contentLanguage - (Optional) Language the content is in e.g., en-US or en-GB.
  • contentType - (Optional) 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 - (Optional, conflicts with source and contentBase64) Literal string value to use as the object content, which will be uploaded as UTF-8-encoded text.
  • etag - (Optional) Triggers updates when the value changes. The only meaningful value is filemd5("path/to/file") (Terraform 0.11.12 or later) or ${md5(file("path/to/file"))} (Terraform 0.11.11 or earlier). This attribute is not compatible with KMS encryption, kmsKeyId or serverSideEncryption = "aws:kms", also if an object is larger than 16 MB, the AWS Management Console will upload or copy that object as a Multipart Upload, and therefore the ETag will not be an MD5 digest (see sourceHash instead).
  • forceDestroy - (Optional) Whether to allow the object to be deleted by removing any legal hold on any object version. Default is false. This value should be set to true only if the bucket has S3 object lock enabled.
  • kmsKeyId - (Optional) 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 awsKmsKey resource, use the arn attribute. If referencing the awsKmsAlias data source or resource, use the targetKeyArn attribute. Terraform will only perform drift detection if a configuration value is provided.
  • metadata - (Optional) Map of keys/values to provision metadata (will be automatically prefixed by xAmzMeta, note that only lowercase label are currently supported by the AWS Go API).
  • objectLockLegalHoldStatus - (Optional) Legal hold status that you want to apply to the specified object. Valid values are on and off.
  • objectLockMode - (Optional) Object lock retention mode that you want to apply to this object. Valid values are governance and compliance.
  • objectLockRetainUntilDate - (Optional) Date and time, in RFC3339 format, when this object's object lock will expire.
  • serverSideEncryption - (Optional) Server-side encryption of the object in S3. Valid values are "aes256" and "aws:kms".
  • sourceHash - (Optional) 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.)
  • source - (Optional, conflicts with content and contentBase64) Path to a file that will be read and uploaded as raw bytes for the object content.
  • storageClass - (Optional) Storage Class for the object. Defaults to "standard".
  • tags - (Optional) Map of tags to assign to the object. If configured with a provider defaultTags configuration block present, tags with matching keys will overwrite those defined at the provider-level.
  • websiteRedirect - (Optional) Target URL for website redirect.

If no content is provided through source, content or contentBase64, then the object will be empty.

-> Note: Terraform ignores all leading /s in the object's key and treats multiple /s in the rest of the object's key as a single /, so values of /indexHtml and indexHtml correspond to the same S3 object as do first//second///third// and first/second/third/.

Attributes Reference

In addition to all arguments above, the following attributes are exported:

  • etag - ETag generated for the object (an MD5 sum of the object content). For plaintext objects or objects encrypted with an AWS-managed key, the hash is an MD5 digest of the object data. For objects encrypted with a KMS key or objects created by either the Multipart Upload or Part Copy operation, the hash is not an MD5 digest, regardless of the method of encryption. More information on possible values can be found on Common Response Headers.
  • id - key of the resource supplied above
  • tagsAll - Map of tags assigned to the resource, including those inherited from the provider defaultTags configuration block.
  • versionId - Unique version ID value for the object, if bucket versioning is enabled.

Import

Objects can be imported using the id. The id is the bucket name and the key together e.g.,

$ terraform import aws_s3_object.object some-bucket-name/some/key.txt

Additionally, s3 url syntax can be used, e.g.,

$ terraform import aws_s3_object.object s3://some-bucket-name/some/key.txt