From a346aebd4c5ce195917fbe51712bec87f455c114 Mon Sep 17 00:00:00 2001 From: jakemulley Date: Tue, 2 May 2023 22:52:48 +0100 Subject: [PATCH 1/2] Add documentation workflow --- .github/workflows/documentation.yml | 17 ++++++++ README.md | 63 +++++++++++------------------ 2 files changed, 40 insertions(+), 40 deletions(-) create mode 100644 .github/workflows/documentation.yml diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 0000000..2150971 --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,17 @@ +name: Generate terraform docs +on: + - pull_request + +jobs: + docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + ref: ${{ github.event.pull_request.head.ref }} + - uses: terraform-docs/gh-actions@v1.0.0 + with: + working-dir: . + output-file: README.md + output-method: inject + git-push: "true" diff --git a/README.md b/README.md index 9d099a5..82a623c 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,8 @@ -# cloud-platform-terraform-s3-bucket module +# cloud-platform-terraform-s3-bucket [![Releases](https://img.shields.io/github/release/ministryofjustice/cloud-platform-terraform-s3-bucket/all.svg?style=flat-square)](https://github.com/ministryofjustice/cloud-platform-terraform-s3-bucket/releases) -Terraform module that will create an S3 bucket in AWS and a relevant user account that will have access to bucket. - -The bucket created will have a randomised name of the format `cloud-platform-7a5c4a2a7e2134a`. This ensures that the bucket created is globally unique. - -The bucket will be encrypted at rest using AES256 [see main.tf](https://github.com/ministryofjustice/cloud-platform-terraform-s3-bucket/blob/main/main.tf#L103-L109) +This Terraform module will create an [Amazon S3](https://aws.amazon.com/s3/) bucket for use on the Cloud Platform. ## Usage @@ -15,18 +11,20 @@ Be sure to create the relevant providers, see example/main.tf From module version 3.2, this replaces the use of the `aws-s3-region`.** ```hcl -module "example_team_s3" { - source = "github.com/ministryofjustice/cloud-platform-terraform-s3-bucket?ref=4.2" - - team_name = "example-repo" - acl = "public-read" - versioning = true - business-unit = "example-bu" - application = "example-app" - is-production = "false" - environment-name = "development" - infrastructure-support = "example-team@digtal.justice.gov.uk" - +module "s3" { + source = "github.com/ministryofjustice/cloud-platform-terraform-s3-bucket?ref=version" # use the latest release + + # S3 configuration + versioning = true + + # Tags + business-unit = var.business_unit + application = var.application + is-production = var.is_production + team_name = var.team_name + namespace = var.namespace + environment-name = var.environment + infrastructure-support = var.infrastructure_support /* * Public Buckets: It is strongly advised to keep buckets 'private' and only make public where necessary. @@ -65,6 +63,9 @@ module "example_team_s3" { } ``` +See the [example/](example/) folder for more information. + + ## Inputs | Name | Description | Type | Default | Required | @@ -78,31 +79,13 @@ module "example_team_s3" { log_path | Path of logs on the target bucket e.g log/ | providers | provider to use | array of string | default provider | no | bucket_name | bucket_name, not recommended | string| empty, auto-generated | no + +## Tags +Some of the inputs for this module are tags. All infrastructure resources must be tagged to meet the MOJ Technical Guidance on [Documenting owners of infrastructure](https://technical-guidance.service.justice.gov.uk/documentation/standards/documenting-infrastructure-owners.html). -### Tags - -Some of the inputs are tags. All infrastructure resources need to be tagged according to the [MOJ techincal guidence](https://technical-guidance.service.justice.gov.uk/documentation/standards/documenting-infrastructure-owners.html). The tags are stored as variables that you will need to fill out as part of your module. - -| Name | Description | Type | Default | Required | -|------|-------------|:----:|:-----:|:-----:| -| application | | string | - | yes | -| business-unit | Area of the MOJ responsible for the service | string | `mojdigital` | yes | -| environment-name | | string | - | yes | -| infrastructure-support | The team responsible for managing the infrastructure. Should be of the form team-email | string | - | yes | -| is-production | | string | `false` | yes | -| team_name | | string | - | yes | - - -## Outputs - -| Name | Description | -|------|-------------| -| access_key_id | Access key id for s3 account | -| bucket_arn | Arn for s3 bucket created | -| bucket_name | bucket name | -| secret_access_key | Secret key for s3 account | +You should use your namespace variables to populate these. See the [Usage](#usage) section for more information. ## Migrate from existing buckets From ae09fc2d3d2465c3802cb97144945dbba671de89 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Tue, 2 May 2023 21:53:32 +0000 Subject: [PATCH 2/2] terraform-docs: automated action --- README.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 63 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 82a623c..5d866f5 100644 --- a/README.md +++ b/README.md @@ -66,19 +66,72 @@ module "s3" { See the [example/](example/) folder for more information. +## Requirements + +| Name | Version | +|------|---------| +| [terraform](#requirement\_terraform) | >= 1.2.5 | +| [aws](#requirement\_aws) | >= 4.27.0 | +| [random](#requirement\_random) | >= 2.0.0 | +| [template](#requirement\_template) | >= 2.0.0 | + +## Providers + +| Name | Version | +|------|---------| +| [aws](#provider\_aws) | >= 4.27.0 | +| [random](#provider\_random) | >= 2.0.0 | +| [template](#provider\_template) | >= 2.0.0 | + +## Modules + +No modules. + +## Resources + +| Name | Type | +|------|------| +| [aws_iam_access_key.user](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_access_key) | resource | +| [aws_iam_user.user](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_user) | resource | +| [aws_iam_user_policy.policy](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_user_policy) | resource | +| [aws_s3_bucket.bucket](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket) | resource | +| [aws_s3_bucket_public_access_block.block_public_access](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_public_access_block) | resource | +| [random_id.id](https://registry.terraform.io/providers/hashicorp/random/latest/docs/resources/id) | resource | +| [aws_iam_policy_document.policy](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source | +| [template_file.bucket_policy](https://registry.terraform.io/providers/hashicorp/template/latest/docs/data-sources/file) | data source | +| [template_file.user_policy](https://registry.terraform.io/providers/hashicorp/template/latest/docs/data-sources/file) | data source | + ## Inputs | Name | Description | Type | Default | Required | -|------|-------------|:----:|:-----:|:-----:| -| acl | acl manages access to your bucket | string | `private` | no | -| bucket_policy | The S3 bucket policy to set. If empty, no policy will be set | string | `""` | no | -| user_policy | The IAM policy to assign to the generated user. If empty, the default policy is used | string | `""` | no | -| versioning | version objects stored within your bucket. | boolean | `false` | no | -| logging_enabled | When set to true enables logging -| log_target_bucket | Target bucket where logs are to be delivered to - log_path | Path of logs on the target bucket e.g log/ -| providers | provider to use | array of string | default provider | no -| bucket_name | bucket_name, not recommended | string| empty, auto-generated | no +|------|-------------|------|---------|:--------:| +| [acl](#input\_acl) | The bucket ACL to set | `string` | `"private"` | no | +| [application](#input\_application) | Your application name | `string` | n/a | yes | +| [bucket\_name](#input\_bucket\_name) | Set the name of the S3 bucket. If left blank, a name will be automatically generated (recommended) | `string` | `""` | no | +| [bucket\_policy](#input\_bucket\_policy) | The S3 bucket policy to set. If empty, no policy will be set | `string` | `""` | no | +| [business-unit](#input\_business-unit) | Area of the MOJ responsible for the service | `string` | `"mojdigital"` | no | +| [cors\_rule](#input\_cors\_rule) | cors rule | `any` | `[]` | no | +| [enable\_allow\_block\_pub\_access](#input\_enable\_allow\_block\_pub\_access) | Enable whether to allow for the bucket to be blocked from public access | `bool` | `true` | no | +| [environment-name](#input\_environment-name) | Your environment name | `string` | n/a | yes | +| [infrastructure-support](#input\_infrastructure-support) | The team responsible for managing the infrastructure. Should be of the form () | `string` | n/a | yes | +| [is-production](#input\_is-production) | Whether this S3 bucket is for production or not | `string` | `"false"` | no | +| [lifecycle\_rule](#input\_lifecycle\_rule) | lifecycle | `any` | `[]` | no | +| [log\_path](#input\_log\_path) | Set the path of the logs | `string` | `""` | no | +| [log\_target\_bucket](#input\_log\_target\_bucket) | Set the target bucket for logs | `string` | `""` | no | +| [logging\_enabled](#input\_logging\_enabled) | Set the logging for bucket | `bool` | `false` | no | +| [namespace](#input\_namespace) | Your namespace | `string` | n/a | yes | +| [team\_name](#input\_team\_name) | Your team name | `string` | n/a | yes | +| [user\_policy](#input\_user\_policy) | The IAM policy to assign to the generated user. If empty, the default policy is used | `string` | `""` | no | +| [versioning](#input\_versioning) | Enable object versioning for the bucket | `bool` | `false` | no | + +## Outputs + +| Name | Description | +|------|-------------| +| [access\_key\_id](#output\_access\_key\_id) | Access key id for s3 account | +| [bucket\_arn](#output\_bucket\_arn) | Arn for s3 bucket created | +| [bucket\_name](#output\_bucket\_name) | bucket name | +| [secret\_access\_key](#output\_secret\_access\_key) | Secret key for s3 account | ## Tags