README.yaml

#
# This is the canonical configuration for the `README.md`
# Run `make readme` to rebuild the `README.md`
#

# Name of this project
name: terraform-aws-s3-bucket

# Tags of this project
tags:
  - aws
  - terraform
  - terraform-modules
  - s3
  - bucket
  - glacier
  - standard
  - versioning

# Categories of this project
categories:
  - terraform-modules/storage

# Logo for this project
#logo: docs/logo.png

# License of this project
license: "APACHE2"

# Canonical GitHub repo
github_repo: cloudposse/terraform-aws-s3-bucket

# Badges to display
badges:
  - name: "GitHub Action Tests"
    image: "https://github.com/cloudposse/terraform-aws-s3-bucket/workflows/test/badge.svg?branch=master"
    url: "https://github.com/cloudposse/terraform-aws-s3-bucket/actions"
  - name: Latest Release
    image: https://img.shields.io/github/release/cloudposse/terraform-aws-s3-bucket.svg?style=for-the-badge
    url: https://github.com/cloudposse/terraform-aws-s3-bucket/releases/latest
  - name: Last Updated
    image: https://img.shields.io/github/last-commit/cloudposse/terraform-aws-s3-bucket.svg?style=for-the-badge
    url: https://github.com/cloudposse/terraform-aws-s3-bucket/commits
  - name: Slack Community
    image: https://slack.cloudposse.com/for-the-badge.svg
    url: https://slack.cloudposse.com

# List any related terraform modules that this module may be used with or that this module depends on.
related:
  - name: "terraform-aws-cloudfront-s3-cdn"
    description: "Terraform module to easily provision CloudFront CDN backed by an S3 origin"
    url: "https://github.com/cloudposse/terraform-aws-cloudfront-s3-cdn"
  - name: "terraform-aws-s3-website"
    description: "Terraform Module for Creating S3 backed Websites and Route53 DNS"
    url: "https://github.com/cloudposse/terraform-aws-s3-website"
  - name: "terraform-aws-user-data-s3-backend"
    description: "Terraform Module to Offload User Data to S3"
    url: "https://github.com/cloudposse/terraform-aws-user-data-s3-backend"
  - name: "terraform-aws-s3-logs-athena-query"
    description: "A Terraform module that creates an Athena Database and Structure for querying S3 access logs"
    url: "https://github.com/cloudposse/terraform-aws-s3-logs-athena-query"
  - name: "terraform-aws-lb-s3-bucket"
    description: "Terraform module to provision an S3 bucket with built in IAM policy to allow AWS Load Balancers to ship access logs"
    url: "https://github.com/cloudposse/terraform-aws-lb-s3-bucket"
  - name: "terraform-aws-s3-log-storage"
    description: "Terraform module creates an S3 bucket suitable for receiving logs from other AWS services such as S3, CloudFront, and CloudTrail"
    url: "https://github.com/cloudposse/terraform-aws-s3-log-storage"


# Short description of this project
description: |-
  This module creates an S3 bucket with support for versioning, lifecycles, object locks, replication, encryption, ACL,
  bucket object policies, and static website hosting.

  For backward compatibility, it sets the S3 bucket ACL to `private` and the `s3_object_ownership`
  to `ObjectWriter`. Moving forward, setting `s3_object_ownership` to `BucketOwnerEnforced` is recommended,
  and doing so automatically disables the ACL.

  This module blocks public access to the bucket by default. See `block_public_acls`, `block_public_policy`,
  `ignore_public_acls`, and `restrict_public_buckets` to change the settings. See [AWS documentation](https://docs.aws.amazon.com/AmazonS3/latest/dev/access-control-block-public-access.html)
  for more details.  

  This module can optionally create an IAM User with access to the S3 bucket. This is inherently insecure in that
  to enable anyone to become the User, access keys must be generated, and anything generated by Terraform is stored
  unencrypted in the Terraform state. See the [Terraform documentation](https://www.terraform.io/docs/state/sensitive-data.html) for more details

  The best way to grant access to the bucket is to grant one or more IAM Roles access to the bucket via `privileged_principal_arns`.
  This IAM Role can be assumed by EC2 instances via their Instance Profile, or Kubernetes (EKS) services using
  [IRSA](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html).
  Entities outside of AWS can assume the Role via [OIDC](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html). 
  (See [this example of connecting GitHub](https://aws.amazon.com/blogs/security/use-iam-roles-to-connect-github-actions-to-actions-in-aws/)
  to enable GitHub actions to assume AWS IAM roles, or use [this Cloud Posse component](https://github.com/cloudposse/terraform-aws-components/tree/main/modules/github-oidc-provider)
  if you are already using the Cloud Posse reference architecture.)

  If neither of those approaches work, then as a last resort you can set `user_enabled = true` and
  this module will provision a basic IAM user with permissions to access the bucket.
  We do not recommend creating IAM users this way for any other purpose.

  If an IAM user is created, the IAM user name is constructed using [terraform-null-label](https://github.com/cloudposse/terraform-null-label)
  and some input is required. The simplest input is `name`. By default the name will be converted to lower case
  and all non-alphanumeric characters except for hyphen will be removed. See the documentation for `terraform-null-label`
  to learn how to override these defaults if desired.

  If an AWS Access Key is created, it is stored either in SSM Parameter Store or is provided as a module output,
  but not both. Using SSM Parameter Store is recommended because that will keep the secret from being easily accessible
  via Terraform remote state lookup, but the key will still be stored unencrypted in the Terraform state in any case.

# How to use this project
usage: |-
  Using [BucketOwnerEnforced](https://docs.aws.amazon.com/AmazonS3/latest/userguide/about-object-ownership.html#object-ownership-overview)

  ```hcl
  module "s3_bucket" {
    source = "cloudposse/s3-bucket/aws"
    # Cloud Posse recommends pinning every module to a specific version
    # version = "x.x.x"
    name                     = "app"
    stage                    = "test"
    namespace                = "eg"

    s3_object_ownership      = "BucketOwnerEnforced"
    enabled                  = true
    user_enabled             = false
    versioning_enabled       = false

    privileged_principal_actions   = ["s3:GetObject", "s3:ListBucket", "s3:GetBucketLocation"]
    privileged_principal_arns      = [
      {
        (local.deployment_iam_role_arn) = [""]
      },
      {
        (local.additional_deployment_iam_role_arn) = ["prefix1/", "prefix2/"]
      }
    ]
  }
  ```

  Configuring S3 [storage lifecycle](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html):

  ```hcl
  locals {
    lifecycle_configuration_rules = [{
      enabled = true # bool
      id      = "v2rule"

      abort_incomplete_multipart_upload_days = 1 # number

      filter_and = null
      expiration = {
        days = 120 # integer > 0
      }
      noncurrent_version_expiration = {
        newer_noncurrent_versions = 3  # integer > 0
        noncurrent_days           = 60 # integer >= 0
      }
      transition = [{
        days          = 30            # integer >= 0
        storage_class = "STANDARD_IA" # string/enum, one of GLACIER, STANDARD_IA, ONEZONE_IA, INTELLIGENT_TIERING, DEEP_ARCHIVE, GLACIER_IR.
        },
        {
          days          = 60           # integer >= 0
          storage_class = "ONEZONE_IA" # string/enum, one of GLACIER, STANDARD_IA, ONEZONE_IA, INTELLIGENT_TIERING, DEEP_ARCHIVE, GLACIER_IR.
      }]
      noncurrent_version_transition = [{
        newer_noncurrent_versions = 3            # integer >= 0
        noncurrent_days           = 30           # integer >= 0
        storage_class             = "ONEZONE_IA" # string/enum, one of GLACIER, STANDARD_IA, ONEZONE_IA, INTELLIGENT_TIERING, DEEP_ARCHIVE, GLACIER_IR.
      }]
    }]
  }
  ```


  Allowing specific principal ARNs to perform actions on the bucket:

  ```hcl
  module "s3_bucket" {
    source = "cloudposse/s3-bucket/aws"
    # Cloud Posse recommends pinning every module to a specific version
    # version = "x.x.x"
    s3_object_ownership      = "BucketOwnerEnforced"
    enabled                  = true
    user_enabled             = true
    versioning_enabled       = false
    allowed_bucket_actions   = ["s3:GetObject", "s3:ListBucket", "s3:GetBucketLocation"]
    name                     = "app"
    stage                    = "test"
    namespace                = "eg"

    privileged_principal_arns = [
    {
      "arn:aws:iam::123456789012:role/principal1" = ["prefix1/", "prefix2/"]
    }, {
      "arn:aws:iam::123456789012:role/principal2" = [""]
    }]
    privileged_principal_actions = [
      "s3:PutObject", 
      "s3:PutObjectAcl", 
      "s3:GetObject", 
      "s3:DeleteObject", 
      "s3:ListBucket", 
      "s3:ListBucketMultipartUploads", 
      "s3:GetBucketLocation", 
      "s3:AbortMultipartUpload"
    ]
  }
  ```

include:
  - "docs/targets.md"
  - "docs/terraform.md"

# Contributors to this project
contributors: []