Skip to content

Generate Terraform module READMEs in CI #224

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ale210 merged 1 commit into from
Nov 12, 2026
+197 −397
Merged

Generate Terraform module READMEs in CI #224

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 1 addition & 3 deletions .github/ISSUE_TEMPLATE/pre-work-template-devops-security.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,6 @@ As a new member on the HfLA devops-security team, fill in the following fields a
- [ ] Follow the instructions in [Creating a backend state](https://github.com/hackforla/devops-security/blob/main/CONTRIBUTING.md#creating-backend-state) to create the S3 bucket.
- [ ] Create the S3 bucket
- [ ] Install Terraform locally by following the instructions of the installation guide mentioned in [Installing Terraform](https://github.com/hackforla/devops-security/blob/main/CONTRIBUTING.md#installing-terraform)
- [ ] Install Terraform Docs locally by following the instructions of the installation guide mentioned in [Installing Terraform docs](https://github.com/hackforla/devops-security/blob/main/CONTRIBUTING.md#installing-terraform-docs)
- [ ] Complete the instructions in [Clone the repository](https://github.com/hackforla/devops-security/blob/main/CONTRIBUTING.md#clone-the-repository)
- [ ] Submit a [new request](https://github.com/hackforla/devops-security/issues/new?assignees=&projects=&template=request-aws-iam-resources.yml) to create new AWS user account and then self-assign this issue.
- [ ] Create a new branch from main by executing the command
Expand Down Expand Up @@ -79,10 +78,9 @@ If you are unable to authenticate from your local machine using the CLI, post in
- [ ] Execute the command `terraform plan` this will output a plan replicating the same IAM resources as the devops security account. Address any failures that arise (if any).
- [ ] Then execute the command `terraform apply` this will create all of the resources that are currently managed by Devops Security. All of the resources created here incur zero cost.
- [ ] **If you have cost concerns, Run a Terraform Destroy to take down all of the resources you created (don't worry, you can recreate them just as quickly). If you create resources outside of what's described in this issue, you may incur charges.**
- [ ] Update the README using Terraform Docs to document changes
- [ ] ```terraform-docs -c .terraform.docs.yml .```
- [ ] Once you have tested your changes, stage them in git with
- [ ] `git status` command.
- [ ] then `git add path/to/file` (you can copy from above output for the file path).
- [ ] Commit the changes by executing `git commit -m "brief description of changes"`.
- [ ] Push the changes with `git push --set-upstream origin name-of-branch`
- [ ] Once you open a pull request, CI regenerates the Terraform READMEs and pushes a `terraform-docs: automated updates…` commit to your branch. Run `git pull` before pushing again. See [Generate Terraform Docs](https://github.com/hackforla/devops-security/blob/main/CONTRIBUTING.md#generate-terraform-docs).
26 changes: 26 additions & 0 deletions .github/workflows/terraform-plan.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,3 +35,29 @@ jobs:
path: terraform
backend_config_file: terraform/prod.backend.tfvars
variables: iam_only = false

terraform-docs:
name: Generate Terraform Docs
runs-on: ubuntu-latest

permissions:
contents: write
pull-requests: write

steps:
- uses: actions/checkout@v3
with:
ref: ${{ github.event.pull_request.head.ref }}

- name: Render terraform docs inside the README.md and push changes back to PR branch
uses: terraform-docs/gh-actions@v1.4.1
with:
find-dir: "terraform"
output-file: README.md
output-method: inject
git-push: "true"
# [skip ci] stops this README-only commit re-firing the pull_request event.
# That second run is attributed to github-actions[bot], which the repo's
# first_time_contributors approval policy gates, so every PR touching .tf
# needed a manual approval for a plan that was already green one commit earlier.
git-commit-message: "terraform-docs: automated updates to Terraform modules README.md [skip ci]"
19 changes: 4 additions & 15 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -164,13 +164,6 @@ Use the [Official HashiCorp install instructions](https://developer.hashicorp.co
<sub>[Back to Top](#)</sub>
***

### **Installing Terraform docs**

Follow the Terraform docs [installation guide](https://terraform-docs.io/user-guide/installation/)

<sub>[Back to Top](#)</sub>
***

## **Clone the repository**

Create a new folder in your computer that will contain `hackforla` projects.
Expand Down Expand Up @@ -285,15 +278,11 @@ terraform destroy
***

### Generate Terraform Docs
Terraform docs allow the easy updating of README files inside of Terraform directories
The README files inside the `terraform` directories are generated by [terraform-docs](https://terraform-docs.io/). You don't need to install or run it: when you open a pull request that changes a `.tf` file, CI regenerates the READMEs and pushes a `terraform-docs: automated updates…` commit to your branch.

Navigate to the directory where the changes were made
```bash
cd terraform # or other directory
```
```bash
terraform-docs -c .terraform.docs.yml .
```
Run `git pull` before pushing again, or your push will be rejected.

To add hand-written text to one of these READMEs, put it above the `<!-- BEGIN_TF_DOCS -->` marker. Anything between the markers is overwritten on every run.

<sub>[Back to Top](#)</sub>
***
Expand Down
71 changes: 0 additions & 71 deletions terraform/.terraform.docs.yml
View file
Open in desktop

This file was deleted.

88 changes: 52 additions & 36 deletions terraform/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,27 +1,66 @@
<!-- BEGIN_TF_DOCS -->
# Overview
Resources created by this code repository.

# Directory Structure
Terraform directory structure

- 📁 [terraform](./)
- 📁 [aws-custom-policies](aws-custom-policies/) - JSON documents for customer-managed policies (AWS-managed policies are referenced by ARN and not needed here)
- 📁 [existing-policies](aws-custom-policies/existing-policies/) - policy documents captured from the live account; `manage-access-keys-policy.json` is used by `aws-custom-policies-legacy.tf`, the rest are kept for reference
- 📁 [modules](modules/) - reusable Terraform configurations, each documented in its own README
- 📁 [aws-gha-oidc-providers](modules/aws-gha-oidc-providers/) - GitHub Actions OIDC identity provider and role
- 📁 [aws-groups](modules/aws-groups/) - IAM groups
- 📁 [aws-policies](modules/aws-policies/) - IAM customer-managed policies
- 📁 [aws-roles](modules/aws-roles/) - IAM roles
- 📁 [aws-users](modules/aws-users/) - IAM users
- 📄 [aws-custom-policies.tf](aws-custom-policies.tf) - maintain custom policies here
- 📄 [aws-custom-policies-legacy.tf](aws-custom-policies-legacy.tf) - policies that predate the module, declared as bare resources
- 📄 [aws-gha-oidc-providers.tf](aws-gha-oidc-providers.tf) - OIDC roles for hackforla/incubator CI and the user-bot deploy workflow
- 📄 [aws-groups.tf](aws-groups.tf) - maintain groups here
- 📄 [aws-groups-legacy.tf](aws-groups-legacy.tf) - groups that predate the module, declared as bare resources
- 📄 [aws-users.tf](aws-users.tf) - maintain users here
- 📄 [aws-users-legacy.tf](aws-users-legacy.tf) - users that predate the module, declared as bare resources
- 📄 [backend.tf](backend.tf) - Terraform and provider version pins, S3 backend and AWS provider
- 📄 [cloudtrail.tf](cloudtrail.tf) - the account's two CloudTrail trails and their log buckets
- 📄 [prod.backend.tfvars](prod.backend.tfvars) - backend configuration used by CI
- 📄 [user-bot.tf](user-bot.tf) - the user-bot Lambda that sends new IAM users their temporary console password on Slack
- 📄 [variables.tf](variables.tf) - input variables

<!-- BEGIN_TF_DOCS -->
## Requirements

| Name | Version |
|------|---------|
| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | ~> 1.16.0 |
| <a name="requirement_archive"></a> [archive](#requirement\_archive) | ~> 2.8.0 |
| <a name="requirement_aws"></a> [aws](#requirement\_aws) | ~> 6.64.0 |

## Providers

| Name | Version |
|------|---------|
| <a name="provider_archive"></a> [archive](#provider\_archive) | 2.8.1 |
| <a name="provider_aws"></a> [aws](#provider\_aws) | 6.64.0 |

## Modules

| Name | Source | Version |
| ---- | ------ | ------- |
|------|--------|---------|
| <a name="module_aws_custom_policies"></a> [aws\_custom\_policies](#module\_aws\_custom\_policies) | ./modules/aws-policies | n/a |
| <a name="module_iam_oidc_gha_incubator"></a> [iam\_oidc\_gha\_incubator](#module\_iam\_oidc\_gha\_incubator) | ./modules/aws-gha-oidc-providers | n/a |
| <a name="module_iam_read_only_group"></a> [iam\_read\_only\_group](#module\_iam\_read\_only\_group) | ./modules/aws-groups | n/a |
| <a name="module_iam_user_Ganeshswaminathan1912"></a> [iam\_user\_Ganeshswaminathan1912](#module\_iam\_user\_Ganeshswaminathan1912) | ./modules/aws-users | n/a |
| <a name="module_iam_user_Sbairamian"></a> [iam\_user\_Sbairamian](#module\_iam\_user\_Sbairamian) | ./modules/aws-users | n/a |
| <a name="module_iam_user_alexe"></a> [iam\_user\_alexe](#module\_iam\_user\_alexe) | ./modules/aws-users | n/a |
| <a name="module_iam_user_benettonkkb"></a> [iam\_user\_benettonkkb](#module\_iam\_user\_benettonkkb) | ./modules/aws-users | n/a |
| <a name="module_iam_user_herehfla"></a> [iam\_user\_herehfla](#module\_iam\_user\_herehfla) | ./modules/aws-users | n/a |
| <a name="module_iam_user_ale210"></a> [iam\_user\_ale210](#module\_iam\_user\_ale210) | ./modules/aws-users | n/a |
| <a name="module_iam_user_here"></a> [iam\_user\_here](#module\_iam\_user\_here) | ./modules/aws-users | n/a |
| <a name="module_iam_user_rsakuma"></a> [iam\_user\_rsakuma](#module\_iam\_user\_rsakuma) | ./modules/aws-users | n/a |
| <a name="module_iam_user_testiamuser"></a> [iam\_user\_testiamuser](#module\_iam\_user\_testiamuser) | ./modules/aws-users | n/a |
| <a name="module_iam_user_tylerthome"></a> [iam\_user\_tylerthome](#module\_iam\_user\_tylerthome) | ./modules/aws-users | n/a |

## Resources

| Name | Type |
| ---- | ---- |
|------|------|
| [aws_cloudtrail.management_events](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudtrail) | resource |
| [aws_cloudtrail.tf_backend_logs](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudtrail) | resource |
| [aws_cloudwatch_event_rule.user_bot](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudwatch_event_rule) | resource |
Expand All @@ -47,6 +86,8 @@ Resources created by this code repository.
| [aws_lambda_permission.user_bot_eventbridge](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lambda_permission) | resource |
| [aws_s3_bucket.management_events](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket) | resource |
| [aws_s3_bucket.tf_backend_logs](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket) | resource |
| [aws_s3_bucket_lifecycle_configuration.management_events](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_lifecycle_configuration) | resource |
| [aws_s3_bucket_lifecycle_configuration.tf_backend_logs](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_lifecycle_configuration) | resource |
| [aws_s3_bucket_ownership_controls.tf_backend_logs](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_ownership_controls) | resource |
| [aws_s3_bucket_policy.management_events](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_policy) | resource |
| [aws_s3_bucket_policy.tf_backend_logs](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_policy) | resource |
Expand All @@ -57,39 +98,14 @@ Resources created by this code repository.
| [aws_ssm_parameter.user_bot_slack_token](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ssm_parameter) | resource |
| [archive_file.user_bot_placeholder](https://registry.terraform.io/providers/hashicorp/archive/latest/docs/data-sources/file) | data source |
| [aws_caller_identity.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity) | data source |

## Inputs

| Name | Description | Type | Default | Required |
| ---- | ----------- | ---- | ------- | :------: |
|------|-------------|------|---------|:--------:|
| <a name="input_iam_only"></a> [iam\_only](#input\_iam\_only) | Manage IAM resources only, skipping the Hack for LA account's CloudTrail trails and log buckets. Set to false for the Hack for LA account. | `bool` | `true` | no |

## Providers

| Name | Version |
| ---- | ------- |
| <a name="provider_archive"></a> [archive](#provider\_archive) | 2.8.1 |
| <a name="provider_aws"></a> [aws](#provider\_aws) | 6.64.0 |
## Requirements

| Name | Version |
| ---- | ------- |
| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | ~> 1.16.0 |
| <a name="requirement_archive"></a> [archive](#requirement\_archive) | ~> 2.8.0 |
| <a name="requirement_aws"></a> [aws](#requirement\_aws) | ~> 6.64.0 |


# Directory Structure
Terraform directory structure
## Outputs

- 📁 [terraform](https://github.com/hackforla/devops-security/tree/main/terraform)
- 📁 [aws-custom-policies](https://github.com/hackforla/devops-security/tree/main/terraform/aws-custom-policies) - JSON configurations for customer-managed policies (AWS-managed policies are referenced by ARN and not needed here)
- 📁 [existing-policies](https://github.com/hackforla/devops-security/tree/main/terraform/aws-custom-policies/existing-policies) - a few of our current policy configurations for reference
- 📁 [modules](https://github.com/hackforla/devops-security/tree/main/terraform/modules) - reusable Terraform configurations
- 📄 [aws-custom-policies.tf](https://github.com/hackforla/devops-security/tree/main/terraform/modules/aws-groups) - maintain custom policies here
- 📄 [aws-groups.tf](https://github.com/hackforla/devops-security/tree/main/terraform/modules/aws-groups) - maintain groups here
- 📄 [aws-users.tf](https://github.com/hackforla/devops-security/tree/main/terraform/modules/aws-users) - maintain users here

To automatically update this documentation, install terraform-docs on your local machine run the following:
`cd <directory of README location to update>`
`terraform-docs -c .terraform.docs.yml .`
<!-- END_TF_DOCS -->
No outputs.
<!-- END_TF_DOCS -->
48 changes: 48 additions & 0 deletions terraform/modules/aws-gha-oidc-providers/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# GitHub Actions OIDC providers

This module declares all of the resources necessary to let a GitHub Actions workflow authenticate to AWS through OIDC: the GitHub OIDC identity provider and an IAM role that workflows in a given repository and branch can assume.

<!-- BEGIN_TF_DOCS -->
## Requirements

No requirements.

## Providers

| Name | Version |
|------|---------|
| <a name="provider_aws"></a> [aws](#provider\_aws) | n/a |
| <a name="provider_tls"></a> [tls](#provider\_tls) | n/a |

## Modules

No modules.

## Resources

| Name | Type |
|------|------|
| [aws_iam_openid_connect_provider.github_actions](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_openid_connect_provider) | resource |
| [aws_iam_role.github_actions_oidc](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role) | resource |
| [aws_iam_role_policy_attachment.github_actions_oidc](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy_attachment) | resource |
| [aws_caller_identity.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity) | data source |
| [tls_certificate.github_actions](https://registry.terraform.io/providers/hashicorp/tls/latest/docs/data-sources/certificate) | data source |

## Inputs

| Name | Description | Type | Default | Required |
|------|-------------|------|---------|:--------:|
| <a name="input_github_branch"></a> [github\_branch](#input\_github\_branch) | The branch name (or name wildcard pattern if use\_wildcard=true) | `string` | n/a | yes |
| <a name="input_github_environment"></a> [github\_environment](#input\_github\_environment) | The environment name (optional) | `string` | `""` | no |
| <a name="input_github_repo"></a> [github\_repo](#input\_github\_repo) | The repository name (or name wildcard pattern if use\_wildcard=true) | `string` | n/a | yes |
| <a name="input_policy_arns"></a> [policy\_arns](#input\_policy\_arns) | The ARN of the policy to attach to the role | `list(string)` | n/a | yes |
| <a name="input_role_name"></a> [role\_name](#input\_role\_name) | The name of the IAM role | `string` | n/a | yes |
| <a name="input_use_wildcard"></a> [use\_wildcard](#input\_use\_wildcard) | Specifies whether OIDC claim subject should use wildcard pattern | `bool` | n/a | yes |

## Outputs

| Name | Description |
|------|-------------|
| <a name="output_provider_arn"></a> [provider\_arn](#output\_provider\_arn) | The ARN of the OIDC provider |
| <a name="output_role_arn"></a> [role\_arn](#output\_role\_arn) | The ARN of the IAM role for the federated identity |
<!-- END_TF_DOCS -->
Loading
Loading