chore: start generating module docs

.github/workflows/ci.yaml

@@ -9,10 +9,31 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+
       - uses: hashicorp/setup-terraform@v2
         with:
           terraform_version: ~1.5
+
+      - name: Terraform Version
+        run: terraform -version
+
+      - name: Install terraform-docs
+        run: |
+          WORK_DIR=$(mktemp -d)
+          curl -Lo ${WORK_DIR}/terraform-docs.tar.gz https://github.com/terraform-docs/terraform-docs/releases/download/v0.16.0/terraform-docs-v0.16.0-$(uname)-amd64.tar.gz
+          cd ${WORK_DIR}
+          tar -xzf terraform-docs.tar.gz
+          chmod +x terraform-docs
+          mv terraform-docs /usr/local/bin/terraform-docs
+
+      - name: Generate docs
+        run: make docs
+
+      - name: Check git diff is clean (all files generated should be committed)
+        run: git diff --exit-code
+
       - name: Terraform Format Check
         run: make fmt-check
+
       - name: Terraform Validate
         run: make validate

Makefile

@@ -1,5 +1,18 @@
 TF_DIRS = $(patsubst %/main.tf, %, $(shell find . -type d -name .terraform -prune -o -name 'main.tf' -print))
 VALIDATE_TF_DIRS = $(addprefix validate-,$(TF_DIRS))
+DOCS_TF_DIRS = $(addprefix docs-,$(TF_DIRS))
+
+
+# Generate docs for a terraform directories
+$(DOCS_TF_DIRS): docs-%:
+	@echo "Docs $*"
+	terraform-docs --config docs/.terraform-docs.yaml $*
+	terraform-docs --config docs/.terraform-docs-example.yaml $*
+
+# Generate docs
+.PHONY: docs
+docs: $(DOCS_TF_DIRS)
+	@echo "All docs generated"
 
 # Format all terraform files
 fmt:

README.md

@@ -10,14 +10,14 @@ A collection of AWS resources ready to be used with [Humanitec](https://humanite
 
 The following resources are included:
 
-* `iam-policy/ecr-create-repository`: IAM policy for to create ECR repositories.
-* `iam-policy/s3-admin`: IAM policy for admin access for a S3 bucket.
-* `iam-policy/sqs-admin`: IAM policy for admin access for an SQS queue.
-* `iam-role/service-account`: An assumable IAM role, by a k8s service account.
-* `k8s/service-account`: A k8s service account linked to an IAM role.
-* `s3/basic`: A basic S3 bucket.
-* `sqs/basic`: A basic SQS queue.
-* `workload/service-account`: A workload service account.
+* [iam-policy/ecr-create-repository](./humanitec-resource-defs/iam-policy/ecr-create-repository): IAM policy for to create ECR repositories.
+* [iam-policy/s3-admin](./humanitec-resource-defs/iam-policy/s3-admin): IAM policy for admin access for a S3 bucket.
+* [iam-policy/sqs-admin](./humanitec-resource-defs/iam-policy/sqs-admin): IAM policy for admin access for an SQS queue.
+* [iam-role/service-account](./humanitec-resource-defs/iam-role/service-account): An assumable IAM role, by a k8s service account.
+* [k8s/service-account](./humanitec-resource-defs/k8s/service-account): A k8s service account linked to an IAM role.
+* [s3/basic](./humanitec-resource-defs/s3/basic): A basic S3 bucket.
+* [sqs/basic](./humanitec-resource-defs/sqs/basic): A basic SQS queue.
+* [workload/service-account](./humanitec-resource-defs/workload/service-account): A workload service account.
 
 The `humanitec-resource-defs` directory includes the respective resource definitions.
 

docs/.terraform-docs-example.yaml

@@ -0,0 +1,9 @@
+formatter: "tfvars hcl"
+
+output:
+  file: "./terraform.tfvars.example"
+  mode: replace
+  template: "{{ .Content }}"
+
+settings:
+  description: true

docs/.terraform-docs.yaml

@@ -0,0 +1,14 @@
+formatter: "markdown table"
+
+output:
+  file: "./README.md"
+
+sort:
+  enabled: true
+  by: required
+
+
+settings:
+  anchor: false
+  hide-empty: true
+  lockfile: false

examples/sqs/README.md

@@ -0,0 +1,47 @@
+<!-- BEGIN_TF_DOCS -->
+
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| humanitec | n/a |
+
+## Modules
+
+| Name | Source | Version |
+|------|--------|---------|
+| iam\_policy\_s3\_admin | ../../humanitec-resource-defs/iam-policy/s3-admin | n/a |
+| iam\_policy\_sqs\_admin | ../../humanitec-resource-defs/iam-policy/sqs-admin | n/a |
+| iam\_role\_service\_account | ../../humanitec-resource-defs/iam-role/service-account | n/a |
+| k8s\_service\_account | ../../humanitec-resource-defs/k8s/service-account | n/a |
+| s3\_basic | ../../humanitec-resource-defs/s3/basic | n/a |
+| sqs\_basic | ../../humanitec-resource-defs/sqs/basic | n/a |
+| workload | ../../humanitec-resource-defs/workload/service-account | n/a |
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [humanitec_application.example](https://registry.terraform.io/providers/humanitec/humanitec/latest/docs/resources/application) | resource |
+| [humanitec_resource_definition_criteria.iam_policy_s3_admin](https://registry.terraform.io/providers/humanitec/humanitec/latest/docs/resources/resource_definition_criteria) | resource |
+| [humanitec_resource_definition_criteria.iam_policy_sqs_admin](https://registry.terraform.io/providers/humanitec/humanitec/latest/docs/resources/resource_definition_criteria) | resource |
+| [humanitec_resource_definition_criteria.iam_role_service_account](https://registry.terraform.io/providers/humanitec/humanitec/latest/docs/resources/resource_definition_criteria) | resource |
+| [humanitec_resource_definition_criteria.k8s_service_account](https://registry.terraform.io/providers/humanitec/humanitec/latest/docs/resources/resource_definition_criteria) | resource |
+| [humanitec_resource_definition_criteria.s3_basic](https://registry.terraform.io/providers/humanitec/humanitec/latest/docs/resources/resource_definition_criteria) | resource |
+| [humanitec_resource_definition_criteria.sqs_basic](https://registry.terraform.io/providers/humanitec/humanitec/latest/docs/resources/resource_definition_criteria) | resource |
+| [humanitec_resource_definition_criteria.workload](https://registry.terraform.io/providers/humanitec/humanitec/latest/docs/resources/resource_definition_criteria) | resource |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| access\_key | n/a | `string` | n/a | yes |
+| humanitec\_organization | n/a | `string` | n/a | yes |
+| oidc\_provider | n/a | `string` | n/a | yes |
+| oidc\_provider\_arn | n/a | `string` | n/a | yes |
+| secret\_key | n/a | `string` | n/a | yes |
+| name | n/a | `string` | `"item-list"` | no |
+| region | n/a | `string` | `"eu-central-1"` | no |
+| resource\_packs\_aws\_rev | n/a | `string` | `"refs/heads/main"` | no |
+<!-- END_TF_DOCS -->

examples/main.tf → examples/sqs/main.tf

@@ -42,7 +42,7 @@ resource "humanitec_application" "example" {
 }
 
 module "k8s_service_account" {
-  source = "../humanitec-resource-defs/k8s/service-account"
+  source = "../../humanitec-resource-defs/k8s/service-account"
 
   prefix = local.res_def_prefix
 }
@@ -60,7 +60,7 @@ locals {
 }
 
 module "s3_basic" {
-  source = "../humanitec-resource-defs/s3/basic"
+  source = "../../humanitec-resource-defs/s3/basic"
 
   access_key             = var.access_key
   secret_key             = var.secret_key
@@ -79,7 +79,7 @@ resource "humanitec_resource_definition_criteria" "s3_basic" {
 }
 
 module "iam_policy_s3_admin" {
-  source = "../humanitec-resource-defs/iam-policy/s3-admin"
+  source = "../../humanitec-resource-defs/iam-policy/s3-admin"
 
   access_key             = var.access_key
   secret_key             = var.secret_key
@@ -105,7 +105,7 @@ locals {
 }
 
 module "sqs_basic" {
-  source = "../humanitec-resource-defs/sqs/basic"
+  source = "../../humanitec-resource-defs/sqs/basic"
 
   access_key             = var.access_key
   secret_key             = var.secret_key
@@ -124,7 +124,7 @@ resource "humanitec_resource_definition_criteria" "sqs_basic" {
 }
 
 module "iam_policy_sqs_admin" {
-  source = "../humanitec-resource-defs/iam-policy/sqs-admin"
+  source = "../../humanitec-resource-defs/iam-policy/sqs-admin"
 
   access_key             = var.access_key
   secret_key             = var.secret_key
@@ -143,7 +143,7 @@ resource "humanitec_resource_definition_criteria" "iam_policy_sqs_admin" {
 }
 
 module "iam_role_service_account" {
-  source = "../humanitec-resource-defs/iam-role/service-account"
+  source = "../../humanitec-resource-defs/iam-role/service-account"
 
   access_key             = var.access_key
   secret_key             = var.secret_key
@@ -163,7 +163,7 @@ resource "humanitec_resource_definition_criteria" "iam_role_service_account" {
 }
 
 module "workload" {
-  source = "../humanitec-resource-defs/workload/service-account"
+  source = "../../humanitec-resource-defs/workload/service-account"
 
   prefix = local.res_def_prefix
 }

examples/sqs/terraform.tfvars.example

@@ -0,0 +1,8 @@
+access_key             = ""
+humanitec_organization = ""
+name                   = "item-list"
+oidc_provider          = ""
+oidc_provider_arn      = ""
+region                 = "eu-central-1"
+resource_packs_aws_rev = "refs/heads/main"
+secret_key             = ""

humanitec-resource-defs/iam-policy/ecr-create-repository/README.md

@@ -0,0 +1,32 @@
+<!-- BEGIN_TF_DOCS -->
+
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| humanitec | n/a |
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [humanitec_resource_definition.main](https://registry.terraform.io/providers/humanitec/humanitec/latest/docs/resources/resource_definition) | resource |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| access\_key | n/a | `string` | n/a | yes |
+| humanitec\_organization | n/a | `string` | n/a | yes |
+| prefix | n/a | `string` | n/a | yes |
+| region | n/a | `string` | n/a | yes |
+| resource\_packs\_aws\_rev | n/a | `string` | n/a | yes |
+| secret\_key | n/a | `string` | n/a | yes |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| id | n/a |
+<!-- END_TF_DOCS -->

humanitec-resource-defs/iam-policy/ecr-create-repository/terraform.tfvars.example

@@ -0,0 +1,6 @@
+access_key             = ""
+humanitec_organization = ""
+prefix                 = ""
+region                 = ""
+resource_packs_aws_rev = ""
+secret_key             = ""

humanitec-resource-defs/iam-policy/s3-admin/README.md

@@ -0,0 +1,33 @@
+<!-- BEGIN_TF_DOCS -->
+
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| humanitec | n/a |
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [humanitec_resource_definition.main](https://registry.terraform.io/providers/humanitec/humanitec/latest/docs/resources/resource_definition) | resource |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| access\_key | n/a | `string` | n/a | yes |
+| humanitec\_organization | n/a | `string` | n/a | yes |
+| prefix | n/a | `string` | n/a | yes |
+| region | n/a | `string` | n/a | yes |
+| resource\_packs\_aws\_rev | n/a | `string` | n/a | yes |
+| s3\_resource\_definition\_class | n/a | `string` | n/a | yes |
+| secret\_key | n/a | `string` | n/a | yes |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| id | n/a |
+<!-- END_TF_DOCS -->

humanitec-resource-defs/iam-policy/s3-admin/terraform.tfvars.example

@@ -0,0 +1,7 @@
+access_key                   = ""
+humanitec_organization       = ""
+prefix                       = ""
+region                       = ""
+resource_packs_aws_rev       = ""
+s3_resource_definition_class = ""
+secret_key                   = ""

humanitec-resource-defs/iam-policy/sqs-admin/README.md

@@ -0,0 +1,33 @@
+<!-- BEGIN_TF_DOCS -->
+
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| humanitec | n/a |
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [humanitec_resource_definition.main](https://registry.terraform.io/providers/humanitec/humanitec/latest/docs/resources/resource_definition) | resource |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| access\_key | n/a | `string` | n/a | yes |
+| humanitec\_organization | n/a | `string` | n/a | yes |
+| prefix | n/a | `string` | n/a | yes |
+| region | n/a | `string` | n/a | yes |
+| resource\_packs\_aws\_rev | n/a | `string` | n/a | yes |
+| secret\_key | n/a | `string` | n/a | yes |
+| sqs\_resource\_definition\_class | n/a | `string` | n/a | yes |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| id | n/a |
+<!-- END_TF_DOCS -->

humanitec-resource-defs/iam-policy/sqs-admin/terraform.tfvars.example

@@ -0,0 +1,7 @@
+access_key                    = ""
+humanitec_organization        = ""
+prefix                        = ""
+region                        = ""
+resource_packs_aws_rev        = ""
+secret_key                    = ""
+sqs_resource_definition_class = ""

humanitec-resource-defs/iam-role/service-account/README.md

@@ -0,0 +1,35 @@
+<!-- BEGIN_TF_DOCS -->
+
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| humanitec | n/a |
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [humanitec_resource_definition.main](https://registry.terraform.io/providers/humanitec/humanitec/latest/docs/resources/resource_definition) | resource |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| access\_key | n/a | `string` | n/a | yes |
+| humanitec\_organization | n/a | `string` | n/a | yes |
+| oidc\_provider | n/a | `string` | n/a | yes |
+| oidc\_provider\_arn | n/a | `string` | n/a | yes |
+| policy\_classes | n/a | `list(string)` | n/a | yes |
+| prefix | n/a | `string` | n/a | yes |
+| region | n/a | `string` | n/a | yes |
+| resource\_packs\_aws\_rev | n/a | `string` | n/a | yes |
+| secret\_key | n/a | `string` | n/a | yes |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| id | n/a |
+<!-- END_TF_DOCS -->

humanitec-resource-defs/iam-role/service-account/terraform.tfvars.example

@@ -0,0 +1,9 @@
+access_key             = ""
+humanitec_organization = ""
+oidc_provider          = ""
+oidc_provider_arn      = ""
+policy_classes         = ""
+prefix                 = ""
+region                 = ""
+resource_packs_aws_rev = ""
+secret_key             = ""