Merge pull request #1 from fac/first-release

First Release

.terraform-docs.yml

@@ -0,0 +1,25 @@
+# Config - https://github.com/terraform-docs/terraform-docs/blob/master/docs/user-guide/configuration.md
+formatter: markdown table
+
+header-from: INFO.md
+
+sections:
+  hide: [providers]
+  show: []
+
+sort:
+  enabled: true
+  by: required
+
+settings:
+  anchor: true
+  color: true
+  default: true
+  description: false
+  escape: true
+  html: true
+  indent: 2
+  lockfile: true
+  required: true
+  sensitive: true
+  type: true

CHANGELOG.md

@@ -2,8 +2,8 @@
 
 ## [Unreleased]
 
-## [maj.min.rev] - YYY-MM-DD
-
+## [0.1.0] - 2021-08-18
+* Inital release
 ----
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),

Dockerfile

@@ -0,0 +1,10 @@
+FROM quay.io/terraform-docs/terraform-docs:latest
+
+COPY entrypoint.sh /code/entrypoint.sh
+COPY .terraform-docs.yml /code/.terraform-docs.yml
+
+RUN chmod +x /code/entrypoint.sh
+
+WORKDIR /code/modules
+
+ENTRYPOINT ["sh","/code/entrypoint.sh"]

README.md

@@ -1,19 +1,87 @@
-# Action Name
+# Terraform AutoDocs Action
 
 ## Description
 
+This Github action is a wrapper for [terraform-docs](https://github.com/terraform-docs/terraform-docs), a utility to generate documentation from Terraform modules. An example is included `examples/s3-bucket/Readme.md`
+
 ## Usage
 
+```yaml
+- name: Terraform AutoDocs Action
+  uses: fac/terraform-autodocs-action@v1
+  with:
+    directories: "networking/ data-stores/ security/"
+```
+
 ## Inputs
 
-## Outputs
+### directories
 
-## Secrets
+A list of directories containing terraform files where it will look for an `INFO.md` file within each of the target directories.
 
-## Environment Variables
+### options
 
-## Authors
+The default configuration options are defined within the `.terraform-docs.yml` file but can be overwritten using the `options` input.
 
+```console
+  -c, --config string               config file name (default ".terraform-docs.yml")
+      --footer-from string          relative path of a file to read footer from (default "")
+      --header-from string          relative path of a file to read header from (default "main.tf")
+  -h, --help                        help for terraform-docs
+      --hide strings                hide section [all, data-sources, footer, header, inputs, modules, outputs, providers, requirements, resources]
+      --lockfile                    read .terraform.lock.hcl if exist (default true)
+      --output-check                check if content of output file is up to date (default false)
+      --output-file string          file path to insert output into (default "")
+      --output-mode string          output to file method [inject, replace] (default "inject")
+      --output-template string      output template (default "<!-- BEGIN_TF_DOCS -->\n{{ .Content }}\n<!-- END_TF_DOCS -->")
+      --output-values               inject output values into outputs (default false)
+      --output-values-from string   inject output values from file into outputs (default "")
+      --recursive                   update submodules recursively (default false)
+      --recursive-path string       submodules path to recursively update (default "modules")
+      --show strings                show section [all, data-sources, footer, header, inputs, modules, outputs, providers, requirements, resources]
+      --sort                        sort items (default true)
+      --sort-by string              sort items by criteria [name, required, type] (default "name")
+```
+
+
+## Running Locally
+### 1 - Build docker image
+
+```console
+$ docker build -t fac/terraform-autodocs .
+```
+
+### 2 - Running
+
+To run this on a single target directory:
+```console
+$ docker run -it \
+-v ${PWD}:/code/modules \
+-e directories="example/s3-bucket/" \
+fac/terraform-autodocs
+
+----------------------------------
+Generating Terraform Documentation
+----------------------------------
+Directories to be processed:
+example/s3-bucket
+ 
+Processing example/s3-bucket
+INFO.md exists auto creating docs in README.md
+Done
+```
+
+The defaults are defined within the `.terraform-docs.yml` file but can be overwritten using the `options` input:
+```console
+$ docker run -it \
+-v ${PWD}:/code/modules \
+-e directories="example/s3-bucket/" \
+-e options="--hide requirements" \
+fac/terraform-autodocs
+```
+
+## Authors
+* FreeAgent Operations Team opensource@freeagent.com
 ## Licence
 
 ```

action.yml

@@ -1,28 +1,15 @@
 # See: https://docs.github.com/en/actions/creating-actions
-name: TODO:Action Name
+name: Terraform AutoDocs Action
 author: FreeAgent
-description: TODO:Description
-#  inputs:
-#    foo:
-#      description: Foo level
-#      required: true
-#      default: 23
-#  outputs:
-#    bar:
-#      description: Bar output
+description: Auto generates documentation for terraform modules.
+inputs:
+    directories:
+      description: List of directories containing terraform files.
+      required: true
+    options:
+      description: Optional configuration arguments.
+      required: false
 
 runs:
-  # Pick one of the 3 possible types of action:
-
-  #using: 'composite'
-  #steps:
-  #  - name: Step One
-  #    shell: bash
-  #    run: |
-  #      echo TODO: Step One
-
-  #using: 'node12'
-  #main: main.js
-
-  #using: 'docker'
-  #image: 'Dockerfile'
+  using: 'docker'
+  image: 'Dockerfile'

entrypoint.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+
+echo "----------------------------------"
+echo "Generating Terraform Documentation"
+echo "----------------------------------"
+
+echo "Directories to be processed:"
+echo $directories
+echo " "
+
+for directory in $directories
+do
+  echo "Processing ${directory}"
+  if test -f "${directory}/INFO.md"; then
+    echo "INFO.md exists auto creating docs in README.md" 
+    terraform-docs -c /code/.terraform-docs.yml $options $directory > ${directory}/README.md
+    echo "Done"
+  else
+    echo "No INFO.md file exists. Skipping ${directory}"
+  fi
+echo " "
+done

example/s3-bucket/INFO.md

@@ -0,0 +1,3 @@
+# Terraform AWS S3 Bucket Module
+
+This Terraform Module creates an [S3 Bucket](https://docs.aws.amazon.com/AmazonS3/latest/gsg/GetStartedWithS3.html).

example/s3-bucket/README.md

@@ -0,0 +1,34 @@
+# Terraform AWS S3 Bucket Module
+
+This Terraform Module creates an [S3 Bucket](https://docs.aws.amazon.com/AmazonS3/latest/gsg/GetStartedWithS3.html).
+
+## Requirements
+
+| Name | Version |
+|------|---------|
+| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 0.12.26 |
+
+## Modules
+
+No modules.
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [aws_s3_bucket.bucket](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket) | resource |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_bucket_name"></a> [bucket\_name](#input\_bucket\_name) | Name of the S3 bucket to create. | `string` | n/a | yes |
+| <a name="input_bucket_acl"></a> [bucket\_acl](#input\_bucket\_acl) | The type of ACL to apply. Valid values are private, public-read, public-read-write, aws-exec-read, authenticated-read, and log-delivery-write. | `string` | `"private"` | no |
+| <a name="input_environment"></a> [environment](#input\_environment) | Name of the environment that the bucket is deployed to. | `string` | `"dev"` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_bucket_arn"></a> [bucket\_arn](#output\_bucket\_arn) | The ARN of the bucket. Will be of format arn:aws:s3:::bucketname. |
+| <a name="output_bucket_id"></a> [bucket\_id](#output\_bucket\_id) | The name of the bucket. |

example/s3-bucket/main.tf

@@ -0,0 +1,16 @@
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# ADD AN AMAZON S3 BUCKET
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+# ---------------------------------------------------------------------------------------------------------------------
+# CREATE S3 Bucket
+# ---------------------------------------------------------------------------------------------------------------------
+resource "aws_s3_bucket" "bucket" {
+  bucket = var.bucket_name
+  acl    = var.bucket_acl
+
+  tags = {
+    Name        = var.bucket_name
+    Environment = var.environment
+  }
+}

example/s3-bucket/outputs.tf

@@ -0,0 +1,9 @@
+output "bucket_id" {
+  value       = aws_s3_bucket.bucket.id
+  description = "The name of the bucket."
+}
+
+output "bucket_arn" {
+  value       = aws_s3_bucket.bucket.arn
+  description = "The ARN of the bucket. Will be of format arn:aws:s3:::bucketname."
+}

example/s3-bucket/vars.tf

@@ -0,0 +1,25 @@
+# ---------------------------------------------------------------------------------------------------------------------
+# MODULE PARAMETERS
+# These variables are expected to be passed in by the operator when calling this terraform module
+# ---------------------------------------------------------------------------------------------------------------------
+variable "bucket_name" {
+  description = "Name of the S3 bucket to create."
+  type        = string
+}
+
+
+# ---------------------------------------------------------------------------------------------------------------------
+# OPTIONAL PARAMETERS
+# These variables are optional
+# ---------------------------------------------------------------------------------------------------------------------
+variable "environment" {
+  description = "Name of the environment that the bucket is deployed to."
+  type        = string
+  default     = "dev"
+}
+variable "bucket_acl" {
+  description = "The type of ACL to apply. Valid values are private, public-read, public-read-write, aws-exec-read, authenticated-read, and log-delivery-write."
+  type        = string
+  default     = "private"
+}
+

example/s3-bucket/versions.tf

@@ -0,0 +1,9 @@
+terraform {
+  required_version = ">= 0.12.26"
+  required_providers {
+    aws = {
+      source = "hashicorp/aws"
+    }
+  }
+}
+