Skip to content

Commit 3ca65bc

Browse files
jamesiarmesjamesiarmes
committed
docs: Added documentation.
1 parent 03bb9c9 commit 3ca65bc

File tree

3 files changed

+91
-49
lines changed

3 files changed

+91
-49
lines changed

‎README.md‎

Lines changed: 54 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,23 @@
1-
# Code for America OpenTofu Module Template
1+
# AWS S3 Uploads Bucket Module
22

33
[![Main Checks][badge-checks]][code-checks] [![GitHub Release][badge-release]][latest-release]
44

5-
Use this template repository to create new OpenTofu modules. Follow the steps
6-
below to use this repository:
7-
8-
1. Click the "Use this template" button to create a new repository
9-
1. Name your new repository using the format `todu-modules-<provider>-<module>`
10-
1. Add the files necessary to support your module to the root of your new
11-
repository
12-
1. Update the `README.md` file with the appropriate information for your module.
13-
Make sure you update any references to this template repository with your new
14-
repository
15-
1. Update the [codeforamerica/tofu-modules][tofu-modules] repository to include
16-
your new module in the main `README.md` and the documentation
5+
This module creates an S3 bucket for file uploads. The bucket is configured with
6+
logging, encryption, verisioning and a lifecycle configuration.
177

188
## Usage
199

2010
Add this module to your `main.tf` (or appropriate) file and configure the inputs
2111
to match your desired configuration. For example:
2212

23-
[//]: # (TODO: Update to match your module's name and inputs)
24-
2513
```hcl
2614
module "module_name" {
27-
source = "github.com/codeforamerica/tofu-modules-template?ref=1.0.0"
15+
source = "github.com/codeforamerica/tofu-modules-aws-s3-uploads-bucket?ref=1.0.0"
2816
29-
project = "my-project"
30-
environment = "development"
17+
project = "my-project"
18+
environment = "development"
19+
logging-bucket = "my-logging-bucket"
20+
name = "documents"
3121
}
3222
```
3323

@@ -46,31 +36,59 @@ tofu init -upgrade
4636

4737
## Inputs
4838

49-
[//]: # (TODO: Replace the following with your own inputs)
50-
51-
| Name | Description | Type | Default | Required |
52-
|-------------|-----------------------------------------------|----------|---------|----------|
53-
| project | Name of the project. | `string` | n/a | yes |
54-
| environment | Environment for the project. | `string` | `"dev"` | no |
55-
| tags | Optional tags to be applied to all resources. | `list` | `[]` | no |
39+
| Name | Description | Type | Default | Required |
40+
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ----------------------------------------------- | -------- |
41+
| logging_bucket | S3 bucket to send access logs to. | `string` | n/a | yes |
42+
| name | Name of the bucket. The project and environment will be prepended to this automatically. | `string` | n/a | yes |
43+
| project | Project that these resources are supporting. This is used in the prefix to all resource names. | `string` | n/a | yes |
44+
| abort_incomplete_multipart_upload_days | Number of days to abort incomplete multipart uploads. | `number` | `7` | no |
45+
| allowed_principals | List of AWS principal ARNs to allow to use the KMS key. This is used to grant access to other resources that need to use the key, such as ECS task roles. | `list(string)` | `[]` | no |
46+
| encryption_key_arn | ARN of the KMS key to use for S3 bucket encryption. If not provided, a new KMS key will be created. | `string` | `null` | no |
47+
| environment | The environment for the deployment. This is used in the prefix to all resource names. | `string` | `"development"` | no |
48+
| force_delete | Whether to force delete the bucket and its contents. Must be set to `true` _and_ applied before the bucket can be deleted. | `bool` | `false` | no |
49+
| key_recovery_period | Number of days to recover the created KMS key after deletion. Must be between `7` and `30`. | `number` | `30` | no |
50+
| noncurrent_version_expiration_days | Number of days to expire noncurrent versions of objects. | `number` | `30` | no |
51+
| [storage_class_transitions] | List of storage class transitions to apply to the buckets lifecycle configuration. | `list(object)` | `[{days = 30, storage_class = "STANDARD_IA"}]` | no |
52+
| tags | Optional tags to be applied to all resources. | `map(string)` | `{}` | no |
53+
54+
### storage_class_transitions
55+
56+
You can define multiple [storage class][storage-class] transitions for the
57+
objects in the S3 bucket. This allows you to use a reduced cost storage option
58+
for objects that need to be retained for a longer time, but won't be regularly
59+
accessed.
60+
61+
By default, objects added to the bucket will transition to the infrequent access
62+
storage tier after 30 days. To disable transitions entirely, you can set this
63+
input to an empty list (`[]`).
64+
65+
| Name | Description | Type | Default | Required |
66+
| ------------- | --------------------------------------- | -------- | ------- | -------- |
67+
| days | Number of days | `number` | n/a | yes |
68+
| storage_class | Storage class to transition objects to. | `string` | n/a | yes |
69+
70+
Possible values for `storage_class` are `DEEP_ARCHIVE`, `GLACIER`, `GLACIER_IR`,
71+
`INTELLIGENT_TIERING`, `ONEZONE_IA`, `STANDARD_IA`. For more information on the
72+
different storage classes, see the [Amazon S3 documentation][storage-class].
5673

5774
## Outputs
5875

59-
[//]: # (TODO: Replace the following with your own outputs)
60-
61-
| Name | Description | Type |
62-
|----------|-----------------------------------|----------|
63-
| id | Id of the newly created resource. | `string` |
64-
76+
| Name | Description | Type |
77+
| ------------------ | ------------------------------------------------------------------------------- | -------- |
78+
| bucket_name | Name of the created bucket. | `string` |
79+
| bucket_arn | Full ARN of the created bucket. | `string` |
80+
| bucket_domain_name | Domain name of the created bucket, in the format `bucketname.s3.amazonaws.com`. | `string` |
81+
| kms_key_arn | ARN of the KMS key used for bucket encryption. | `string` |
6582

6683
## Contributing
6784

6885
Follow the [contributing guidelines][contributing] to contribute to this
6986
repository.
7087

71-
[badge-checks]: https://github.com/codeforamerica/tofu-modules-template/actions/workflows/main.yaml/badge.svg
72-
[badge-release]: https://img.shields.io/github/v/release/codeforamerica/tofu-modules-template?logo=github&label=Latest%20Release
73-
[code-checks]: https://github.com/codeforamerica/tofu-modules-template/actions/workflows/main.yaml
88+
[badge-checks]: https://github.com/codeforamerica/tofu-modules-aws-s3-uploads-bucket/actions/workflows/main.yaml/badge.svg
89+
[badge-release]: https://img.shields.io/github/v/release/codeforamerica/tofu-modules-aws-s3-uploads-bucket?logo=github&label=Latest%20Release
90+
[code-checks]: https://github.com/codeforamerica/tofu-modules-aws-s3-uploads-bucket/actions/workflows/main.yaml
7491
[contributing]: CONTRIBUTING.md
75-
[latest-release]: https://github.com/codeforamerica/tofu-modules-template/releases/latest
76-
[tofu-modules]: https://github.com/codeforamerica/tofu-modules
92+
[latest-release]: https://github.com/codeforamerica/tofu-modules-aws-s3-uploads-bucket/releases/latest
93+
[storage-class]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/storage-class-intro.html
94+
[storage_class_transitions]: #storage_class_transitions

‎outputs.tf‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,15 @@ output "bucket_name" {
44
}
55

66
output "bucket_arn" {
7-
description = "ARN of the created bucket."
7+
description = "Full ARN of the created bucket."
88
value = module.this.arn
99
}
1010

1111
output "bucket_domain_name" {
12-
description = "Domain name of the created bucket."
12+
description = <<-EOT
13+
Domain name of the created bucket, in the format
14+
`bucketname.s3.amazonaws.com`.
15+
EOT
1316
value = module.this.bucket_domain_name
1417
}
1518

‎variables.tf‎

Lines changed: 32 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -21,25 +21,37 @@ variable "allowed_principals" {
2121

2222
variable "encryption_key_arn" {
2323
type = string
24-
description = "ARN of the KMS key to use for S3 bucket encryption. If not provided, a new KMS key will be created."
24+
description = <<-EOT
25+
ARN of the KMS key to use for S3 bucket encryption. If not provided, a new
26+
KMS key will be created.
27+
EOT
2528
default = null
2629
}
2730

2831
variable "environment" {
2932
type = string
30-
description = "The environment for the deployment."
33+
description = <<-EOT
34+
The environment for the deployment. This is used in the prefix to all
35+
resource names.
36+
EOT
3137
default = "development"
3238
}
3339

3440
variable "force_delete" {
3541
type = bool
36-
description = "Whether to force delete the bucket and its contents."
42+
description = <<-EOT
43+
Whether to force delete the bucket and its contents. Must be set to `true`
44+
_and_ applied before the bucket can be deleted.
45+
EOT
3746
default = false
3847
}
3948

4049
variable "key_recovery_period" {
4150
type = number
42-
description = "Number of days to recover the created KMS key after deletion. Must be between 7 and 30."
51+
description = <<-EOT
52+
Number of days to recover the created KMS key after deletion. Must be
53+
between `7` and `30`.
54+
EOT
4355
default = 30
4456

4557
validation {
@@ -55,7 +67,10 @@ variable "logging_bucket" {
5567

5668
variable "name" {
5769
type = string
58-
description = "Name of the bucket. The project and environment will be prepended to this automatically."
70+
description = <<-EOT
71+
Name of the bucket. The project and environment will be prepended to this
72+
automatically.
73+
EOT
5974
}
6075

6176
variable "noncurrent_version_expiration_days" {
@@ -69,24 +84,30 @@ variable "noncurrent_version_expiration_days" {
6984
}
7085
}
7186

87+
variable "project" {
88+
type = string
89+
description = <<-EOT
90+
Project that these resources are supporting. This is used in the prefix to
91+
all resource names.
92+
EOT
93+
}
94+
7295
variable "storage_class_transitions" {
7396
type = list(object({
7497
days = number
7598
storage_class = string
7699
}))
77100

78-
description = "List of storage class transitions to apply to the bucket."
101+
description = <<-EOT
102+
List of storage class transitions to apply to the buckets lifecycle
103+
configuration.
104+
EOT
79105
default = [{
80106
days = 30
81107
storage_class = "STANDARD_IA"
82108
}]
83109
}
84110

85-
variable "project" {
86-
type = string
87-
description = "Project that these resources are supporting."
88-
}
89-
90111
variable "tags" {
91112
type = map(string)
92113
description = "Optional tags to be applied to all resources."

0 commit comments

Comments
 (0)