AWS S3 Module

This module configures and manages an S3 bucket and its various configurations such as static website and lifecycle rules.

Table of Contents

• Example Usage
  • Basic Usage
  • Static Web Hosting
  • Lifecycle Rules
  • S3 Event Notifications
  • Bucket Level Encryption
  • S3 Intelligent Tiering
  • S3 Inventory
  • S3 Bucket Replication
  • Enables Object Lock For New Bucket
  • Enables Object Lock For Existing Bucket
• Argument Reference
  • Mandatory
  • Optional
• Outputs

Example Usage

Basic Usage

module "demo_bucket" {
  source = "github.com/FriendsOfTerraform/aws-s3.git?ref=v1.1.0"

  name = "demo-bucket"
}

Static Web Hosting

This example uses a public read bucket policy to allow anonymous access to all objects in the bucket.

module "static_web_hosting" {
  source = "github.com/FriendsOfTerraform/aws-s3.git?ref=v1.1.0"

  name = "demo-bucket"

  policy = <<-EOF
  {
    "Version": "2012-10-17",
    "Statement": {
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::demo-bucket/*"
    }
  }
  EOF

  static_website_hosting_config = {
    static_website = {
      index_document = "index.html"
      error_document = "error.html"
    }
  }
}

Lifecycle Rules

This example shows a basic lifecycle rule to auto rotate logs that are tagged with “AutoRotate = true” that are saved in the “log/” path. After 30 days, the logs will be transitioned to the STANDARD_IA storage class, then to the GLACIER storage class after another 60 days. Finally, all logs will be expired (deleted) after another 90 days. Additionally, delete markers will be cleaned up, effectively making the deletion permanent if versoning is enabled. All previous versioned objects will be expired after 60 days.

module "lifecycle_rule_demo" {
  source = "github.com/FriendsOfTerraform/aws-s3.git?ref=v1.1.0"

  name               = "demo-bucket"
  versioning_enabled = true

  lifecycle_rules = {
    # The key of the map will be the lifecycle rule's name
    "rotate-logs" = {
      # This rule is scoped to objects with prefix AND tags
      filter = {
        prefix = "log/"

        object_tags = {
          AutoRotate = "true"
        }
      }

      transitions = [
        {
          days_after_object_creation = 30
          storage_class              = "STANDARD_IA"
        },
        {
          days_after_object_creation = 90
          storage_class              = "GLACIER"
        }
      ]

      expiration = {
        days_after_object_creation             = 180
        clean_up_expired_object_delete_markers = true
      }

      noncurrent_version_expiration = {
        days_after_objects_become_noncurrent = 60
      }
    }
  }
}

S3 Event Notifications

This example configures the bucket to send notifications to a lambda function to process .jpg files uploaded into the “photo/” folder. It also configures the bucket to send notification to an SNS topic to notify administrators of all deletion events.

locals {
  lambda_arn = "arn:aws:lambda:us-west-2:111122223333:function:ProcessPhotos",
  sns_arn = "arn:aws:sns:us-west-2:111122223333:Admins"
}

module "bucket_notification_demo" {
  source = "github.com/FriendsOfTerraform/aws-s3.git?ref=v1.1.0"

  name = "demo-bucket"

  notification_config = {
    destinations = {
      # The key of the map will be the destination's ARN
      local.lambda_arn = [{
        events        = ["s3:ObjectCreated:Put", "s3:ObjectCreated:Post"]
        filter_prefix = "photo/"
        filter_suffix = ".jpg"
      },
      {
        events = ["s3:ObjectCreated:Put", "s3:ObjectCreated:Post"]
        filter_prefix = "video/"
        filter_suffix = ".mpeg"
      }],
      local.sns_arn = [{
        events = ["s3:ObjectRemoved:*"]
      }]
    }
  }
}

Notes

• You must ensure proper permissions are granted to S3 on each destination. Refers to the following documentations for more detail:
  • Lambda Permission
  • SNS Permission
  • SQS Permission

Bucket Level Encryption

module "bucket_encryption_demo" {
  source = "github.com/FriendsOfTerraform/aws-s3.git?ref=v1.1.0"

  name = "demo-bucket"

  encryption_config = {
    use_kms_master_key = "arn:aws:kms:us-west-2:111122223333:key/6bfabcde-0d12-48ad-927f-48a805b2c62d"
    bucket_key_enabled = true
  }
}

Notes

• This example enables bucket level encryption using SSE:KMS. To use SSE:S3 instead, set use_kms_master_key to null.

S3 Intelligent Tiering

module "s3_intelligent_tiering_demo" {
  source = "github.com/FriendsOfTerraform/aws-s3.git?ref=v1.1.0"

  name = "demo-bucket"

  intelligent_tiering_archive_configurations = {
    # The key of the map will be the tiering rule's name

    # Archive logs after 180 days of no access
    "archive-logs" = {
      filter = {
        prefix = "logs*"
      }

      access_tier           = "ARCHIVE_ACCESS"
      days_until_transition = 180
    }

    # Deeply achive backups after 90 days of no access
    "archive-backup" = {
      filter = {
        prefix = "backup*"
      }

      access_tier           = "DEEP_ARCHIVE_ACCESS"
      days_until_transition = 90
    }
  }
}

Notes

• You must grant the necessary permissions to the source and destination bucket via bucket policy.
• bucket permission

S3 Inventory

module "s3_inventory_demo" {
  source = "github.com/FriendsOfTerraform/aws-s3.git?ref=v1.1.0"

  name = "demo-bucket"

  inventory_config = {
    # The key of the map will be the inventory rule's name

    # Daily inventory on backup
    "backup-daily-report" = {
      destination                = { bucket_arn = "arn:aws:s3:::psin-backup-inventory" }
      frequency                  = "Daily"
      additional_metadata_fields = ["Size", "LastModifiedDate", "StorageClass"]

      filter = {
        prefix = "backup*"
      }
    }
    # Weekly inventory on logs
    "log-weekly-report" = {
      destination = { bucket_arn = "arn:aws:s3:::psin-log-inventory" }
      frequency   = "Weekly"
    }
  }
}

S3 Bucket Replication

module "s3_bucket_replication_demo" {
  source = "github.com/FriendsOfTerraform/aws-s3.git?ref=v1.1.0"

  name = "demo-bucket"

  replication_config = {
    rules = {
      # The key of the map will be the replication rule's name

      # Replicate to bucket belonging to the same account, including encrypted objects
      "same-account-example" = {
        destination_bucket_arn = "arn:aws:s3:::psin-replication-dest"
        priority               = 0

        additional_replication_options = {
          replication_time_control_enabled  = true
          replication_metrics_enabled       = true
          replica_modification_sync_enabled = true
          delete_marker_replication_enabled = true
        }

        replicate_encrypted_objects = {
          kms_key_for_encrypting_destination_objects = "arn:aws:kms:us-east-2:111122223333:key/aaabbbccc-edac-44b6-81b6-29b58ae1bdfb"
        }
      }
      # Replicate to bucket belonging to another account
      "cross-account" = {
        destination_bucket_arn = "arn:aws:s3:::psin-replication-dest-777788889999"
        priority               = 1

        additional_replication_options = {
          delete_marker_replication_enabled = true
        }

        change_object_ownership_to_destination_bucket_owner = {
          destination_account_id = "777788889999"
        }
      }
    }
  }
}

Enables Object Lock For New Bucket

module "s3_bucket_object_lock_demo" {
  source = "github.com/FriendsOfTerraform/aws-s3.git?ref=v1.1.0"

  name                = "demo-bucket"
  versioning_enabled  = true
  enables_object_lock = {}
}

Enables Object Lock For Existing Bucket

module "s3_bucket_object_lock_demo" {
  source = "github.com/FriendsOfTerraform/aws-s3.git?ref=v1.1.0"

  name = "demo-bucket"

  ##
  ## 1. Enables versioning. Doing so will generate an "Object lock token" in the back-end
  ##
  versioning_enabled = true

  ##
  ## 2. Contact AWS Support to provide you with the "Object Lock token" for the specified bucket and use the token to enables object lock
  ##
  enables_object_lock = {
    token = "NG2MKsfoLqV3A+aquXneSG4LOu/ekrlXkRXwIPFVfERT7XOPos+/k444d7RIH0E3W3p5"
  }
}

Argument Reference

Mandatory

• (string) name [since v1.0.0]

  Name of the S3 bucket. Must be globally unique

Optional

• (map(string)) additional_tags = {} [since v1.0.0]

  Additional tags for the S3 bucket

• (map(string)) additional_tags_all = {} [since v1.0.0]

  Additional tags for all resources deployed with this module

• (string) bucket_owner_account_id = null [since v1.0.0]

  The account ID of the expected bucket owner

• (list(object)) cors_configurations = null [since v1.1.0]

  Configures cross-origin resource sharing (CORS)

  • (list(string)) allowed_methods [since v1.1.0]

    List of HTTP methods that you allow the origin to execute. Valid values are "GET", "PUT", "HEAD", "POST", "DELETE"

  • (list(string)) allowed_origins [since v1.1.0]

    Specify the origins that you want to allow cross-domain requests from. The origin string can contain only one * wildcard character, such as "http://*.example.com". You can optionally specify "*" as the origin to enable all the origins to send cross-origin requests. You can also specify https to enable only secure origins.

  • (list(string)) allowed_headers = null [since v1.1.0]

    Specify which headers are allowed in a preflight request through the Access-Control-Request-Headers header. Each header name in the Access-Control-Request-Headers header must match a corresponding entry in the element. Amazon S3 will send only the allowed headers in a response that were requested. Each header string can contain at most one * wildcard character. For example, "x-amz-*" will enable all Amazon-specific headers.

  • (list(string)) expose_headers = null [since v1.1.0]

    Specify a list of headers in the response that you want customers to be able to access from their applications

  • (string) id = null [since v1.1.0]

    Unique identifier for the cors rule. The value cannot be longer than 255 characters.

  • (number) max_age_seconds = null [since v1.1.0]

    Specify the time in seconds that your browser can cache the response for a preflight request as identified by the resource, the HTTP method, and the origin.

• (object) enables_object_lock = null [since v1.0.0]

  Configures S3 Object Lock. You must also set versioning_enabled = true to enable object lock. See example

  • (object) default_retention = null [since v1.0.0]

    Configures default retention rule

    • (number) retention_days [since v1.0.0]

      Number of days the objects should be retained

    • (string) retention_mode [since v1.0.0]

      Default Object Lock retention mode you want to apply to new objects placed in the specified bucket. Valid values: "COMPLIANCE", "GOVERNANCE"

  • (string) token = null [since v1.0.0]

    Token to allow Object Lock to be enabled for an existing bucket. You must contact AWS support for the bucket's "Object Lock token". The token is generated in the back-end when versioning is enabled on a bucket. See example

• (object) encryption_config = null [since v1.0.0]

  Configures bucket level encryption

  • (bool) bucket_key_enabled = false [since v1.0.0]

    Enables S3 bucket key for encryption

  • (string) use_kms_master_key = null [since v1.0.0]

    CMK arn, encrypts bucket using sse:kms. If this is set to null, sse:s3 will be used. e.g. arn:aws:kms:us-west-2:111122223333:key/6bfabcde-0d12-48ad-927f-48a805b2c62d

• (bool) force_destroy = false [since v1.0.0]

  Force destroy of the bucket even if it is not empty

• (map(object)) intelligent_tiering_archive_configurations = {} [since v1.0.0]

  Configures S3 intelligent tiering. See example

  • (string) access_tier [since v1.0.0]

    S3 Intelligent-Tiering access tier. Valid values are "ARCHIVE_ACCESS" and "DEEP_ARCHIVE_ACCESS"

    Restore time:

    Tier	Expedited	Standard	Bulk
    Archive Access	1 - 5 mins	3 - 5 hours	5 - 12 hours
    Deep Archive Access	N/A	Within 12 hours	Within 48 hours

  • (number) days_until_transition [since v1.0.0]

    Number of consecutive days of no access after which an object will be eligible to be transitioned to the corresponding tier

  • (object) filter = null [since v1.0.0]

    Limit the scope of this configuration using one or more filters

    • (map(string)) object_tags = null [since v1.0.0]

      All of these tags must exist in the object's tag set in order for the configuration to apply

    • (string) prefix = null [since v1.0.0]

      Object key name prefix that identifies the subset of objects to which the configuration applies

• (map(object)) inventory_config = {} [since v1.0.0]

  Configures S3 inventory. See example

  • (string) frequency [since v1.0.0]

    Specifies how frequently inventory results are produced. Valid values: "Daily", "Weekly"

  • (list(string)) additional_metadata_fields = null [since v1.0.0]

    List of optional metadatas to be included in the inventory results. Please refer to this documentation for a list of valid values.

  • (object) destination = null [since v1.0.0]

    Configures the destination where the report will be sent

    • (string) account_id = null [since v1.0.0]

      The account ID that owns the destination bucket. Must be set to ensure correct ownership of the report.

    • (string) bucket_arn = null [since v1.0.0]

      Destination bucket arn. The current bucket will be used if set to null

  • (object) encrypt_inventory_report = null [since v1.0.0]

    Configures the type of server-side encryption to use to encrypt the inventory report

    • (string) kms_key_id = null [since v1.0.0]

      ARN of the KMS customer master key (CMK) used to encrypt the inventory file. If left empty (null), sse_s3 will be used for encryption

  • (object) filter = null [since v1.0.0]

    Limit the scope of this configuration using one or more filters

    • (string) prefix = null [since v1.0.0]

      Object key name prefix that identifies the subset of objects to which the configuration applies

  • (bool) include_noncurrent_objects = true [since v1.0.0]

    Specify if the report should include non current object versions

  • (string) output_format = "CSV" [since v1.0.0]

    Specifies the output format of the inventory results. Can be "CSV", "ORC" or "Parquet"

• (map(object)) lifecycle_rules = null [since v1.0.0]

  Configures S3 lifecycle rules. See example

  • (number) clean_up_incomplete_multipart_uploads_after = null [since v1.0.0]

    Delete failed multipart uploads after x days

  • (object) expiration = null [since v1.0.0]

    Expiration configuration to expires current objects

    • (bool) clean_up_expired_object_delete_markers = false [since v1.0.0]

      Permanently delete an object even if versioning is enabled

    • (number) days_after_object_creation = null [since v1.0.0]

      Expires objects after x days

  • (object) filter = null [since v1.0.0]

    Limit the scope of this configuration using one or more filters

    • (number) maximum_object_size = null [since v1.0.0]

      Maximum object size (in bytes) to which the rule applies.

    • (number) minimum_object_size = null [since v1.0.0]

      Minimum object size (in bytes) to which the rule applies.

    • (map(string)) object_tags = null [since v1.0.0]

      All of these tags must exist in the object's tag set in order for the configuration to apply

    • (string) prefix = null [since v1.0.0]

      Object key name prefix that identifies the subset of objects to which the configuration applies

  • (object) noncurrent_version_expiration = null [since v1.0.0]

    Expiration configuration to expires noncurrent s3 objects

    • (number) days_after_objects_become_noncurrent [since v1.0.0]

      Expires noncurrent objects after x days

    • (number) number_of_newer_versions_to_retain = null [since v1.0.0]

      Number of noncurrent versions Amazon S3 will retain

  • (list(object)) noncurrent_version_transitions = [] [since v1.0.0]

    Transitions noncurrent s3 objects to other storage class.

    • (number) days_after_objects_become_noncurrent [since v1.0.0]

      Transition noncurrent objects after x days

    • (string) storage_class [since v1.0.0]

      Specify the destination storage class. Valid values: "ONEZONE_IA", "STANDARD_IA", "INTELLIGENT_TIERING", "GLACIER", "DEEP_ARCHIVE", or "GLACIER_IR"

    • (number) number_of_newer_versions_to_retain = null [since v1.0.0]

      Number of noncurrent versions Amazon S3 will retain

  • (list(object)) transitions = [] [since v1.0.0]

    Transitions s3 objects to other storage class.

    • (number) days_after_object_creation [since v1.0.0]

      Transition objects after x days

    • (string) storage_class [since v1.0.0]

      Specify the destination storage class. Valid values: "ONEZONE_IA", "STANDARD_IA", "INTELLIGENT_TIERING", "GLACIER", "DEEP_ARCHIVE", or "GLACIER_IR"

• (object) notification_config = null [since v1.0.0]

  Configures S3 event notifiactions. See example

  • (map(list(object))) destinations [since v1.0.0]

    Map of event notification in {destinationARN = [events]}. Supported AWS services include Lambda, SQS, and SNS. You can include up to one each SQS and SNS destination, but you can include multiple Lambda destinations.

    • (list(string)) events [since v1.0.0]

      S3 Events for which to send notifications

    • (string) filter_prefix = null [since v1.0.0]

      Filters objects by key name prefix

    • (string) filter_suffix = null [since v1.0.0]

      Filters objects by key name suffix

• (string) object_ownership = "BucketOwnerEnforced" [since v1.0.0]

  Control ownership of objects written to this bucket from other AWS accounts and the use of access control lists (ACLs). Object ownership determines who can specify access to objects. Valid values: "BucketOwnerEnforced", "BucketOwnerPreferred", "ObjectWriter".

• (string) policy = null [since v1.0.0]

  Text of the S3 policy document to attach

• (object) public_access_block = null [since v1.0.0]

  Configures bucket to block public access

  • (bool) block_public_acls = false [since v1.0.0]

    Whether Amazon S3 should block public ACLs for this bucket

  • (bool) block_public_policy = false [since v1.0.0]

    Whether Amazon S3 should block public bucket policies for this bucket

  • (bool) ignore_public_acls = false [since v1.0.0]

    Whether Amazon S3 should ignore public ACLs for this bucket

  • (bool) restrict_public_buckets = false [since v1.0.0]

    Whether Amazon S3 should restrict public bucket policies for this bucket

• (object) replication_config = null [since v1.0.0]

  Manage bucket replicatoin. See example

  • (map(object)) rules [since v1.0.0]

    Configures bucket replicatoin rules. In {rule_name = replication_config} format

    • (string) destination_bucket_arn [since v1.0.0]

      ARN of the bucket where you want Amazon S3 to store the results

    • (number) priority [since v1.0.0]

      Priority associated with the rule. Priority must be unique between multiple rules.

    • (object) additional_replication_options = null [since v1.0.0]

      Enables additional replication options

      • (bool) delete_marker_replication_enabled = false [since v1.0.0]

        Delete markers created by S3 delete operations will be replicated. Delete markers created by lifecycle rules are not replicated.

      • (bool) replica_modification_sync_enabled = false [since v1.0.0]

        Replicate metadata changes made to replicas in this bucket to the destination bucket.

      • (bool) replication_metrics_enabled = false [since v1.0.0]

        With replication metrics, you can monitor the total number and size of objects that are pending replication, and the maximum replication time to the destination Region. You can also view and diagnose replication failures.

      • (bool) replication_time_control_enabled = false [since v1.0.0]

        Replication Time Control replicates 99.99% of new objects within 15 minutes and includes replication metrics.

    • (object) change_object_ownership_to_destination_bucket_owner = null [since v1.0.0]

      specifies the overrides to use for object owners on replication. Specify this only in a cross-account scenario (where source and destination bucket owners are not the same), and you want to change replica ownership to the AWS account that owns the destination bucket. If this is not specified in the replication configuration, the replicas are owned by same AWS account that owns the source object.

      • (string) destination_account_id [since v1.0.0]

        Account ID to specify the replica ownership

    • (string) destination_storage_class = null [since v1.0.0]

      Specify the destination storage class. Defaults to the same storage class of the source object

    • (object) filter = null [since v1.0.0]

      Limit the scope of this configuration using one or more filters

      • (map(string)) object_tags = null [since v1.0.0]

        All of these tags must exist in the object's tag set in order for the configuration to apply

      • (string) prefix = null [since v1.0.0]

        Object key name prefix that identifies the subset of objects to which the configuration applies

    • (object) replicate_encrypted_objects = null [since v1.0.0]

      specifies whether encrypted objects will be replicated

      • (string) kms_key_for_encrypting_destination_objects [since v1.0.0]

        ARN of the customer managed AWS KMS key stored in AWS Key Management Service (KMS) used to encrypt replicated objects

  • (string) iam_role_arn = null [since v1.0.0]

    ARN of the IAM role for Amazon S3 to assume when replicating the objects. One will be automatically generated by the module if this is left empty (null).

  • (string) token = null [since v1.0.0]

    Token to allow replication to be enabled on an Object Lock-enabled bucket. You must contact AWS support for the bucket's "Object Lock token". Please refer to this documentation for more information

• (bool) requester_pays_enabled = false [since v1.0.0]

  Enables Requester Pays bucket so that the requester pays the cost of the request and data download instead of the bucket owner. Must also specify bucket_owner_account_id

• (object) static_website_hosting_config = null [since v1.0.0]

  Configures static website hosting

  • (object) redirect_requests_for_an_object = null [since v1.0.0]

    Configures a webpage redirect. Mutually exclusive to static_website

    • (string) host_name [since v1.0.0]

      Name of the host where requests are redirected

    • (string) protocol = null [since v1.0.0]

      Protocol to use when redirecting requests. The default is the protocol that is used in the original request. Valid values: "http", "https"

  • (object) static_website = null [since v1.0.0]

    Manages documents S3 returns when a request is made to its web endpoint. Mutually exclusive to redirect_requests_for_an_object

    • (string) index_document [since v1.0.0]

      Index document when requests are made to the root domain

    • (string) error_document = null [since v1.0.0]

      Document to return in case of a 4XX error

• (bool) transfer_acceleration_enabled = false [since v1.0.0]

  Enables transfer acceleration

• (bool) versioning_enabled = false [since v1.0.0]

  Enables bucket versioning

Outputs

• (string) bucket_arn [since v1.0.0]

  ARN of the S3 bucket

• (string) bucket_domain_name [since v1.0.0]

  Bucket domain name. Will be of format bucketname.s3.amazonaws.com

• (string) bucket_name [since v1.0.0]

  Name of the S3 bucket

• (string) bucket_region [since v1.0.0]

  AWS region this bucket resides in

• (string) website_domain [since v1.0.0]

  Domain of the website endpoint. This is used to create Route 53 alias records.

• (string) website_endpoint [since v1.0.0]

  Website endpoint.