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"
    url: "https://github.com/cloudposse/terraform-aws-s3-bucket/releases/latest"
  - name: "Slack Community"
    image: "https://slack.cloudposse.com/badge.svg"
    url: "https://slack.cloudposse.com"

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.
  
  If `user_enabled` variable is set to `true`, the module will provision a basic IAM user with permissions to access the bucket.
  This basic IAM system user is suitable for CI/CD systems (_e.g._ TravisCI, CircleCI) or systems which are *external* to AWS that cannot leverage
  [AWS IAM Instance Profiles](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html) 
  or [AWS OIDC](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html) to authenticate and
  do not already have IAM credentials. Users or systems that have IAM credentials should either be granted access directly based on
  their IAM identity via `privileged_principal_arns` or be allowed to assume an IAM role with access.

  We do not recommend creating IAM users this way for any other purpose.

  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.

  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 module outputs are stored in plaintext in
  the Terraform state file.

# How to use this project
usage: |-
  Using a [canned ACL](https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html).

  ```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"

    acl                      = "private"
    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.
      }]
    }]
  }
  ```
  
  Using [grants](https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html) to enable access 
  to another account and for logging, and incorporating the above lifecycle configuration.

  ```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"

    acl                      = ""
    enabled                  = true
    user_enabled             = false
    versioning_enabled       = true
  
    lifecycle_configuration_rules = local.lifecycle_configuration_rules

    grants = [
      {
        id          = "012abc345def678ghi901" # Canonical user or account id
        type        = "CanonicalUser"
        permissions = ["FULL_CONTROL"]
        uri         = null
      },
      {
        id          = null
        type        = "Group"
        permissions = ["READ", "WRITE"]
        uri         = "http://acs.amazonaws.com/groups/s3/LogDelivery"
      },
    ]
  }
  ```

  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"
    acl                      = "private"
    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:
  - name: "Erik Osterman"
    github: "osterman"
  - name: "Andriy Knysh"
    github: "aknysh"
  - name: "Maxim Mironenko"
    github: "maximmi"
  - name: "Josh Myers"
    github: "joshmyers"
  - name: "Yonatan Koren"
    github: "korenyoni"
  - name: "Nuru"
    github: "Nuru"