diff --git a/standard/README.md b/standard/README.md deleted file mode 100644 index 40f0d9a..0000000 --- a/standard/README.md +++ /dev/null @@ -1,243 +0,0 @@ -# About aws-s3 :: standard - -This submodule allows you to create an S3 bucket using the standard prefixes and settings required for -non-FTI Data. This includes -- Server Access Logging - -Other configurations such as versioning or data safegurad tagging (only on the bucket/keys) are oiptional - -# Usage -To use the new refactored module with the AWS provider v4.x, use `?ref=3`, otherwise leave this part off. -If you are converting an older version of the module to the new AWS provider with `?ref=3, please follow -the [updating directions](updating-buckets.md). - -**Note**: version 2 and version 3 of this module cannot coexist in a directory. All S3 buckets using this module -must use the same version. If you are using the version 2 of the module (without the `?ref=3`), you must -also include a `versions.tf` which pins the AWS provider at < 4.0. If using version 3 of the module, -do not include a `versions.tf`, do not pin the AWS provider. Two different versions of the provider cannot -coexist (easily). - -````hcl -module "my-bucket" { - source = "git@github.e.it.census.gov:terraform-modules/aws-s3.git//standard?ref=3" - - bucket_name = "my-normalbucket" - access_log_bucket = "my-logbucket" - # kms_admin_roles = [ aws_iam_role.cloud-admin.arn ] - - ## optional - # kms_policy_document = data.aws_iam_policy_document.my-policy.json - # bucket_policy_document = data.aws_iam_policy_document.my-bucketpolicy.json - # bucket_policy_document_template = data.aws_iam_policy_document.my-bucketpolicy-template.json - # name_include_account = true - # name_include_region = true - # name_include_region_compact = true - # name_enforce_region_compact = false -} - -output "my-bucket-info" { - description = "S3 Standard Bucket Info" - value = { - arn = module.my-bucket.s3_bucket_arn - id = module.my-bucket.s3_bucket_id - } -} -``` - -Sample policy for write access to the bucket and use of KMS key - -```hcl -data "aws_iam_policy_document" "policy" { - statement { - sid = "ListBuckets" - actions = [ - "s3:ListAllMyBuckets", - "s3:GetBucketLocation" - ] - resources = ["*"] - } - statement { - sid = "S3WriteAccess" - effect = "Allow" - actions = [ - "s3:ListBucket", - "s3:PutObject*", - "s3:GetObject*", - "s3:GetObjectAcl", - "s3:DeleteObject" - ] - resources = [ - module.mybucket.s3_bucket_arn, - format("%v/*", mybucket.s3_bucket_arn), - ] - } - statement { - sid = "S3AccessEncryptionKey" - effect = "Allow" - actions = [ - "kms:ReEncrypt*", - "kms:GenerateDataKey", - "kms:Encrypt", - "kms:Decrypt" - ] - resources = [module.mybucket.kms_key_id] - } -} - -resource "aws_iam_policy" "policy" { - name = "mypolicy-s3-access" - description = "Policy for S3 access" - policy = data.aws_iam_policy_document.policy.json -} -``` - -This automaticaly creates an AWS KMS key used just for this bucket. - -It will set a key usage/management policy by default with the `root` account, along with any other -roles in the variable `kms_admin_roles` list. This is **full** access to the KMS key. - -If `kms_policy_document` is provided it needs to be a valid IAM policy as would apply to key usage, -such as read access (decrypt) or write access (encrypt, re-encrypt). A later enhancement may be -to provide variables granting read and write access to the key. - -If `bucket_policy_document` is provided it needs to be a valid IAM policy as would apply a bucket. -This will be merged with the default bucket policy which requires TLS and, via other settings, -optionally requires explicit encryption (`require_explicit_encryption` flag, default false) -and address restrictions (lists `allowed_cidr` and `allowed_endpoints`). - -# Options -## Options :: name\_include\_account -Use of this flag as true will include AWS account ID after the bucket name (name-ACCOUNTID). Default -is false. - -## Options :: name\_include\_region -Use of this flag as true will include current region after the bucket name (name-REGION). Default -is false. If used in conjunction with `name_include_account`, the region will be at the end. - -## Options :: name\_include\_region\_compact -This flag determines if we compact the region to a shorter name, and use it if the name with the full -region is longer than the maximum of 63 characters. It takes the first character of the full region -name and uses that. For example, `us-gov-west-1` becomes `ugw1`. The default value is true. -It is still possible to construct a name that is longer than 63 characters and get a failure, even with -this shorter region value. - -## Options :: name\_enforce\_region\_compact -This flag always compacts the region, no mater whehter the name is longer than 63 characters or not. - -## Options :: object\_lock\_enable -This is usable on bucket creation, and it will allow you to add external to this module an object lock -configuration (aws\_s3\_object\_lock\_configuration). See the [Object Lock](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock-overview.html) -and the [Terraform AWS Provider](https://registry.terraform.io/providers/hashicorp%20%20/aws/4.7.0/docs/resources/s3_bucket_object_lock_configuration) docs for -more details. Setting this after bucket creation is possible but requires a support tickets, so you're better off doing it up front. - -# Outputs -One output of note is the `s3_module_settings`. With this, you can get the settings used when calling the -module, the original bucket name before prefix and suffixes, and other things. It is a map. - -```hcl -output "s3_module_settings" { - description = "S3 module settings and values" - value = { - bucket_name = var.bucket_name - resulting_bucket_name = local.bucket_name - resulting_bucket_arn = aws_s3_bucket.this.arn - name_include_region = var.name_include_region - name_include_account = var.name_include_account - name_include_region_compact = var.name_include_region_compact - name_enforce_region_compact = var.name_enforce_region_compact - account_id = local.account_id - region = local.region - region_short = local.region_short - } -} -``` - -## Requirements - -| Name | Version | -|------|---------| -| [aws](#requirement\_aws) | >= 4.0 | -| [null](#requirement\_null) | >= 3.1.0 | - -## Providers - -| Name | Version | -|------|---------| -| [aws](#provider\_aws) | >= 4.0 | -| [null](#provider\_null) | >= 3.1.0 | -| [template](#provider\_template) | n/a | - -## Modules - -No modules. - -## Resources - -| Name | Type | -|------|------| -| [aws_kms_alias.key](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/kms_alias) | resource | -| [aws_kms_key.key](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/kms_key) | resource | -| [aws_s3_bucket.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket) | resource | -| [aws_s3_bucket_acl.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_acl) | resource | -| [aws_s3_bucket_logging.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_logging) | resource | -| [aws_s3_bucket_object.this_objects](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_object) | resource | -| [aws_s3_bucket_ownership_controls.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_ownership_controls) | resource | -| [aws_s3_bucket_policy.policy](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_policy) | resource | -| [aws_s3_bucket_public_access_block.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_public_access_block) | resource | -| [aws_s3_bucket_server_side_encryption_configuration.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_server_side_encryption_configuration) | resource | -| [aws_s3_bucket_versioning.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_versioning) | resource | -| [null_resource.name_too_long](https://registry.terraform.io/providers/hashicorp/null/latest/docs/resources/resource) | resource | -| [null_resource.policy_delay](https://registry.terraform.io/providers/hashicorp/null/latest/docs/resources/resource) | resource | -| [aws_arn.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/arn) | data source | -| [aws_caller_identity.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity) | data source | -| [aws_iam_policy_document.bucket_policy_combined](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source | -| [aws_iam_policy_document.empty](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source | -| [aws_iam_policy_document.key_admin](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source | -| [aws_iam_policy_document.key_policy_combined](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source | -| [aws_iam_policy_document.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source | -| [aws_kms_key.incoming_key](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/kms_key) | data source | -| [aws_region.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/region) | data source | -| [template_file.policy](https://registry.terraform.io/providers/hashicorp/template/latest/docs/data-sources/file) | data source | - -## Inputs - -| Name | Description | Type | Default | Required | -|------|-------------|------|---------|:--------:| -| [access\_log\_bucket](#input\_access\_log\_bucket) | Server Access Logging Bucket ID | `string` | n/a | yes | -| [access\_log\_bucket\_prefix](#input\_access\_log\_bucket\_prefix) | Access log bucket prefix, to which the bucket name will be appended to make the target\_prefix | `string` | `"s3"` | no | -| [allowed\_cidr](#input\_allowed\_cidr) | List of allowed source IPs (NOT from within the VPC). If empty, there will be no restrictions on source IP. If provided, you must also use allowed\_endpoints for access within a VPC. | `list(string)` | `[]` | no | -| [allowed\_endpoints](#input\_allowed\_endpoints) | List of allowed VPC endpoint IDs. If used, it will enable access to the bucket from the specific VPC endpoints. | `list(string)` | `[]` | no | -| [bucket\_folders](#input\_bucket\_folders) | List of folders (keys) to create after creation of bucket. They will have object metadata provided based on metadata\_tags and data\_safeguard labels. | `list(string)` | `[]` | no | -| [bucket\_key\_enabled](#input\_bucket\_key\_enabled) | Enable or disable the use of S3 Bucket Keys (see AWS documenation at https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-key.html). | `bool` | `false` | no | -| [bucket\_name](#input\_bucket\_name) | AWS Bucket Name. Standard prefix will be applied here, do not include here. | `string` | n/a | yes | -| [bucket\_owner](#input\_bucket\_owner) | One of BucketOwnerPreferred, ObjectWriter, or BucketOwnerEnforced. See S3 Documentation for more information (default: BucketOwnerPreferred, requires bucket-owner-full-control option when uploading | `string` | `"BucketOwnerPreferred"` | no | -| [bucket\_policy\_document](#input\_bucket\_policy\_document) | IAM Policy document describing additional policy to be attached to the bucket beyond the default | `string` | `""` | no | -| [bucket\_policy\_document\_template](#input\_bucket\_policy\_document\_template) | IAM Policy document template describing additional policy to be attached to the bucket beyond the default. This is so we can inject the S3 Bucket ARN into a policy without a loop. Construct the policy with ${s3\_bucket\_arn} where you need it to be in a resource. This also supports ${s3\_bucket\_id} and ${kms\_key\_arn} | `string` | `null` | no | -| [data\_safeguards](#input\_data\_safeguards) | Selected available safeguards which apply to the data in the bucket | `list(string)` | `[]` | no | -| [enable\_title26](#input\_enable\_title26) | Flag to enable bucket with Title 26 (FTI) settings | `bool` | `false` | no | -| [force\_destroy](#input\_force\_destroy) | Sets force\_destroy to allow the bucket and contents to be deleted. The deletion may take a very long time based on the number of objects. You normally want to update this to true, apply, and then destroy the resource. | `bool` | `false` | no | -| [kms\_admin\_roles](#input\_kms\_admin\_roles) | AWS KMS Key administrative role(s) which have full access to the key. The root user is included by default. | `list(string)` | `[]` | no | -| [kms\_key\_arn](#input\_kms\_key\_arn) | AWS KMS Key ARN, a key created external to this module call. | `string` | `null` | no | -| [kms\_key\_id](#input\_kms\_key\_id) | AWS KMS Key ID (one per bucket). This is currently ignored (and deprecated). | `string` | `null` | no | -| [kms\_policy\_document](#input\_kms\_policy\_document) | AWS KMS Key Policy Document JSON, merged with admin policy document | `string` | `""` | no | -| [metadata\_tags](#input\_metadata\_tags) | AWS S3 Custom metadata (prefix x-amzn-meta- automatically included, not needed here). If data\_safeguard labels are applied, they will be incorporated on any bucket objects created. | `map(string)` | `{}` | no | -| [name\_enforce\_region\_compact](#input\_name\_enforce\_region\_compact) | Flag to determine if we the rewrite the full region name to a shorter region name no matter the lenth of the string. Only usable with name\_include\_region. | `bool` | `false` | no | -| [name\_include\_account](#input\_name\_include\_account) | Flag to determine if we include the AWS Account id in the resulting bucket name | `bool` | `false` | no | -| [name\_include\_region](#input\_name\_include\_region) | Flag to determine if we include the full region name in the resulting bucket name | `bool` | `false` | no | -| [name\_include\_region\_compact](#input\_name\_include\_region\_compact) | Flag to determine if we the rewrite the full region name to a shorter region name if the resulting name > 63 characters. Only usable with name\_include\_region. | `bool` | `true` | no | -| [object\_lock\_enabled](#input\_object\_lock\_enabled) | Flag to enable object lock. This can only be set on bucket creation. See AWS documentation at https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock-overview.html | `bool` | `false` | no | -| [require\_explicit\_encryption](#input\_require\_explicit\_encryption) | When enabled, adds bucket policy to Deny unencrypted uploads and incorrect encryption header. Should not normally be needed. | `bool` | `false` | no | -| [tags](#input\_tags) | AWS Tags to apply to appropriate resources (S3, KMS). Do not include safeguard tags here, use the data\_safeguard field for such things. | `map(string)` | `{}` | no | -| [use\_kms\_encryption](#input\_use\_kms\_encryption) | Enable AWS:KMS encryption (default). If false, enables SSE-S3 (AES256), needed for some AWS services access | `bool` | `true` | no | - -## Outputs - -| Name | Description | -|------|-------------| -| [kms\_key\_alias](#output\_kms\_key\_alias) | KMS Key Alias name. If a kms\_key\_arn passed in, this will be null. | -| [kms\_key\_arn](#output\_kms\_key\_arn) | KMS Key ARN. This is the created key ARN or the key ARN of kms\_key\_arn | -| [kms\_key\_id](#output\_kms\_key\_id) | KMS Key ID. This is the created key id or the key id of kms\_key\_arn | -| [s3\_bucket\_arn](#output\_s3\_bucket\_arn) | Created S3 Bucket ARN | -| [s3\_bucket\_id](#output\_s3\_bucket\_id) | Created S3 Bucket ID | -| [s3\_module\_settings](#output\_s3\_module\_settings) | S3 module settings and values | -| [s3\_requested\_bucket\_name](#output\_s3\_requested\_bucket\_name) | Requested S3 Bucket Name before prefix and other settings |