-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
243 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | | ||
| |------|---------| | ||
| | <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 4.0 | | ||
| | <a name="requirement_null"></a> [null](#requirement\_null) | >= 3.1.0 | | ||
| ## Providers | ||
| | Name | Version | | ||
| |------|---------| | ||
| | <a name="provider_aws"></a> [aws](#provider\_aws) | >= 4.0 | | ||
| | <a name="provider_null"></a> [null](#provider\_null) | >= 3.1.0 | | ||
| | <a name="provider_template"></a> [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 | | ||
| |------|-------------|------|---------|:--------:| | ||
| | <a name="input_access_log_bucket"></a> [access\_log\_bucket](#input\_access\_log\_bucket) | Server Access Logging Bucket ID | `string` | n/a | yes | | ||
| | <a name="input_access_log_bucket_prefix"></a> [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 | | ||
| | <a name="input_allowed_cidr"></a> [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 | | ||
| | <a name="input_allowed_endpoints"></a> [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 | | ||
| | <a name="input_bucket_folders"></a> [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 | | ||
| | <a name="input_bucket_key_enabled"></a> [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 | | ||
| | <a name="input_bucket_name"></a> [bucket\_name](#input\_bucket\_name) | AWS Bucket Name. Standard prefix will be applied here, do not include here. | `string` | n/a | yes | | ||
| | <a name="input_bucket_owner"></a> [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 | | ||
| | <a name="input_bucket_policy_document"></a> [bucket\_policy\_document](#input\_bucket\_policy\_document) | IAM Policy document describing additional policy to be attached to the bucket beyond the default | `string` | `""` | no | | ||
| | <a name="input_bucket_policy_document_template"></a> [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 | | ||
| | <a name="input_data_safeguards"></a> [data\_safeguards](#input\_data\_safeguards) | Selected available safeguards which apply to the data in the bucket | `list(string)` | `[]` | no | | ||
| | <a name="input_enable_title26"></a> [enable\_title26](#input\_enable\_title26) | Flag to enable bucket with Title 26 (FTI) settings | `bool` | `false` | no | | ||
| | <a name="input_force_destroy"></a> [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 | | ||
| | <a name="input_kms_admin_roles"></a> [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 | | ||
| | <a name="input_kms_key_arn"></a> [kms\_key\_arn](#input\_kms\_key\_arn) | AWS KMS Key ARN, a key created external to this module call. | `string` | `null` | no | | ||
| | <a name="input_kms_key_id"></a> [kms\_key\_id](#input\_kms\_key\_id) | AWS KMS Key ID (one per bucket). This is currently ignored (and deprecated). | `string` | `null` | no | | ||
| | <a name="input_kms_policy_document"></a> [kms\_policy\_document](#input\_kms\_policy\_document) | AWS KMS Key Policy Document JSON, merged with admin policy document | `string` | `""` | no | | ||
| | <a name="input_metadata_tags"></a> [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 | | ||
| | <a name="input_name_enforce_region_compact"></a> [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 | | ||
| | <a name="input_name_include_account"></a> [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 | | ||
| | <a name="input_name_include_region"></a> [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 | | ||
| | <a name="input_name_include_region_compact"></a> [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 | | ||
| | <a name="input_object_lock_enabled"></a> [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 | | ||
| | <a name="input_require_explicit_encryption"></a> [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 | | ||
| | <a name="input_tags"></a> [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 | | ||
| | <a name="input_use_kms_encryption"></a> [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 | | ||
| |------|-------------| | ||
| | <a name="output_kms_key_alias"></a> [kms\_key\_alias](#output\_kms\_key\_alias) | KMS Key Alias name. If a kms\_key\_arn passed in, this will be null. | | ||
| | <a name="output_kms_key_arn"></a> [kms\_key\_arn](#output\_kms\_key\_arn) | KMS Key ARN. This is the created key ARN or the key ARN of kms\_key\_arn | | ||
| | <a name="output_kms_key_id"></a> [kms\_key\_id](#output\_kms\_key\_id) | KMS Key ID. This is the created key id or the key id of kms\_key\_arn | | ||
| | <a name="output_s3_bucket_arn"></a> [s3\_bucket\_arn](#output\_s3\_bucket\_arn) | Created S3 Bucket ARN | | ||
| | <a name="output_s3_bucket_id"></a> [s3\_bucket\_id](#output\_s3\_bucket\_id) | Created S3 Bucket ID | | ||
| | <a name="output_s3_module_settings"></a> [s3\_module\_settings](#output\_s3\_module\_settings) | S3 module settings and values | | ||
| | <a name="output_s3_requested_bucket_name"></a> [s3\_requested\_bucket\_name](#output\_s3\_requested\_bucket\_name) | Requested S3 Bucket Name before prefix and other settings | |