diff --git a/standard/README.md b/standard/README.md new file mode 100644 index 0000000..40f0d9a --- /dev/null +++ b/standard/README.md @@ -0,0 +1,243 @@ +# 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 |