doc: updating the readme related to the pipelines (#31)

* doc: updating the readme related to the pipelines
* feat: adding the ability to control the terraform apply

.github/workflows/terraform-plan-and-apply-aws.yml

@@ -70,6 +70,12 @@ on:
         required: false
         type: boolean
 
+      enable-terraform-apply:
+        default: true
+        description: "Whether to run terraform apply on merge to main"
+        required: false
+        type: boolean
+
       environment:
         default: "production"
         description: "The environment to deploy to"
@@ -478,7 +484,7 @@ jobs:
 
   terraform-apply:
     name: "Terraform Apply"
-    if: github.ref == 'refs/heads/main' && contains(fromJSON('["push", "schedule"]'), github.event_name)
+    if: github.ref == 'refs/heads/main' && contains(fromJSON('["push", "schedule"]'), github.event_name) && inputs.enable-terraform-apply
     environment: ${{ inputs.environment }}
     runs-on: ${{ inputs.runs-on }}
     defaults:

.gitignore

@@ -1,4 +1,6 @@
 .DS_Store
 ._.DS_Store
 **/.DS_Store
-**/._.DS_Store
+**/._.DS_Store
+
+*.orig

docs/terraform-module-release.md

@@ -5,6 +5,7 @@ This GitHub Actions workflow template ([terraform-module-release.yml](../.github
 ## Usage
 
 Create a new workflow file in your Terraform repository (e.g. `.github/workflows/release.yml`) with the below contents:
+
 ```yml
 name: Release
 

docs/terraform-module-validation.md

@@ -4,25 +4,25 @@ This GitHub Actions workflow template ([terraform-module-validation.yml](../.git
 
 ## Workflow Jobs
 
+- terraform-docs
 - terraform-format
-- terraform-lint
 - terraform-init
+- terraform-lint
+- terraform-security
 - terraform-validate
-- terraform-docs
+- terraform-validate-examples
+- terraform-infracost
 
 1. **Terraform Format:** Runs the terraform fmt command to check that all Terraform files are formatted correctly.
 2. **Terraform Lint:** Runs a terraform lint to check for deprecated syntax, unused declarations, invalid types, and enforcing best practices.
 3. **Terraform Init:** Provider plugins and modules are installed.
-4. **Terraform Validate:** The Terraform configuration files are run through validation to check for syntax errors and other issues.
-5. **Terraform Docs:** The terraform-docs utility is run to check that the documentation for the module is up to date.
-6. **Get Cost Estimate:** The infracost utility is run to get a cost estimate for the module. A comment will be added to the pull request with the cost estimate.
-7. **Add PR Comment:** If the workflow is triggered via a Pull Request, a comment will be added to the ticket containing the results of the previous steps.
-
-## Inputs
-
-| Input             | Required? | Default Value | Description                     |
-| ----------------- | --------- | ------------- | ------------------------------- |
-| terraform-version | No        | 1.5.2         | The version of Terraform to use |
+4. **Terraform Security:** The module code and dependencies are examined by a static analysis tool to identify and misconfiguration or potential security issues.
+5. **Terraform Validate:** The Terraform configuration files are run through validation to check for syntax errors and other issues.
+6. **Terraform Validate Examples:** Any examples found under the ./examples are validated to ensure against `terraform validate`
+7. **Terraform Docs:** The terraform-docs utility is run to check that the documentation for the module is up to date.
+8. **Get Cost Estimate:** The infracost utility is run to get a cost estimate for the module. A comment will be added to the pull request with the cost estimate.
+9. **Terraform Infracost:** the module is run through infracost to gauge an idea of the associated cloud costs.
+10. **Add PR Comment:** If the workflow is triggered via a Pull Request, a comment will be added to the ticket containing the results of the previous steps.
 
 ## Usage
 
@@ -43,9 +43,11 @@ jobs:
     uses: appvia/appvia-cicd-workflows/.github/workflows/terraform-module-validation.yml@main
     name: Module Validation
     secrets:
+      # Required if you want to run infracost
       infracost-api-key: ${{ secrets.ORG_INFRACOST_API_KEY }}
     with:
+      aws-account-id: <ACCOUNT_ID>
+      aws-region: <AWS_REGION>
+      # Optional toggle to enable infracost
       enable-infracost: true
 ```
-
-**Note:** This template may change over time, so it is recommended that you point to a tagged version rather than the main branch.

docs/terraform-plan-and-apply-aws.md

@@ -8,53 +8,41 @@ This GitHub Actions workflow template ([terraform-plan-and-apply-aws.yml](../.gi
 2. **Terraform Format:** This step runs the terraform fmt command to check that all Terraform files are formatted correctly.
 3. **Terraform Lint:** This step runs terraform lint to check for deprecated syntax, unused declarations, invalid types, and enforcing best practices.
 4. **AWS Authentication:** The workflow uses Web Identity Federation to authenticate with AWS. The required AWS Role ARN must be provided as an input for successful authentication.
-   * A Web Identity Token File is also generated and stored in `/tmp/web_identity_token_file`, which can be referenced in Terraform Provider configuration blocks if required.
+   - A Web Identity Token File is also generated and stored in `/tmp/web_identity_token_file`, which can be referenced in Terraform Provider configuration blocks if required.
 5. **Terraform Init:** The Terraform backend is initialised and any necessary provider plugins are downloaded. The required inputs for AWS S3 bucket name and DynamoDB table name must be provided for storing the Terraform state.
-6. **Terraform Validate:** The workflow validates the Terraform configuration files using the terraform validate command to check for syntax errors and other issues.
-7. **Terraform Plan:** A Terraform plan is generated with a specified values file (overridable via inputs) using the terraform plan command.
-8. **Get Cost Estimate:** The infracost utility is run to get a cost estimate on the Terraform Plan output. A comment will be added to the pull request with the cost estimate.
-9. **Add PR Comment:** If the workflow is triggered via a Pull Request, a comment will be added to the ticket containing the results of the previous steps.
-10. **Apply Changes:** If the workflow is triggered by a push to the main branch, it automatically applies the changes using the terraform apply command. This step should be used with caution as AWS infrastructure is modified at this point.
-
-## Inputs
-
-| Input | Required? | Default Value | Description |
-|-------|-------------|-----------|---------------|
-| aws-role-arn | Yes | | The ARN of the AWS role to assume for authentication |
-| aws-s3-bucket-name | Yes | | The name of the AWS S3 bucket to store the Terraform state |
-| aws-dynamodb-table-name | Yes | | The name of the AWS DynamoDB table to use for locking |
-| aws-region | No | eu-west-2 | The AWS region to deploy the infrastructure to |
-| terraform-log-level | No | INFO | The log level of Terraform |
-| terraform-state-key | No | ${{ github.event.repository.name }}.tfstate | The name of the Terraform state file to store in S3 |
-| terraform-values-file | No | values/production.tfvars | The path to the values file to use |
-| terraform-version | No | 1.5.2 | The version of Terraform to use |
+6. **Terraform Security:** The module code and dependencies are examined by a static analysis tool to identify and misconfiguration or potential security issues.
+7. **Terraform Validate:** The workflow validates the Terraform configuration files using the terraform validate command to check for syntax errors and other issues.
+8. **Terraform Plan:** A Terraform plan is generated with a specified values file (overridable via inputs) using the terraform plan command.
+9. **Get Cost Estimate:** The infracost utility is run to get a cost estimate on the Terraform Plan output. A comment will be added to the pull request with the cost estimate.
+10. **Add PR Comment:** If the workflow is triggered via a Pull Request, a comment will be added to the ticket containing the results of the previous steps.
+11. **Apply Changes:** If the workflow is triggered by a push to the main branch, it automatically applies the changes using the terraform apply command. This step should be used with caution as AWS infrastructure is modified at this point.
 
 ## Usage
 
 Create a new workflow file in your Terraform repository (e.g. `.github/workflows/terraform.yml`) with the below contents:
+
 ```yml
 name: Terraform
 on:
   push:
     branches:
-    - main
+      - main
   pull_request:
     branches:
-    - main
+      - main
 
 jobs:
   terraform:
-      uses: appvia/appvia-cicd-workflows/.github/workflows/terraform-plan-and-apply-aws.yml@main
-      name: Plan and Apply
-      secrets:
-        infracost-api-key: ${{ secrets.ORG_INFRACOST_API_KEY }}
-      with:
-        aws-account-id: 123456789012
-        aws-role-name-readonly: your-role-ro
-        aws-role-name-readwrite: your-role-rw
-        enable-infracost: true
+    uses: appvia/appvia-cicd-workflows/.github/workflows/terraform-plan-and-apply-aws.yml@main
+    name: Plan and Apply
+    secrets:
+      infracost-api-key: ${{ secrets.ORG_INFRACOST_API_KEY }}
+    with:
+      aws-account: 123456789012
+      aws-role: <IAM_ROLE_NAME>
+      enable-infracost: true
 ```
 
-The `aws-role-name` inputs are optional and will default to the repository name (with the respective `-ro` or `-rw` suffixes) if not provided.
+The `aws-role` inputs are optional and will default to the repository name.
 
 **Note:** This template may change over time, so it is recommended that you point to a tagged version rather than the main branch.