chore: generate and maintain in-repo module documentation

The generate-terraform-docs workflow will use the terraform-docs/gh-actions action to generate Terraform documentation based on the module's provider requirements, variables, and outputs.

The peter-evans/create-pull-request action will open new pull requests to ensure that the README.md of each module, including the root module, includes this generated content and that the content stays up to date as changes are made to the project.

Signed-off-by: Marques Johansson <[email protected]>

.github/workflows/documentation.yaml

@@ -0,0 +1,57 @@
+name: generate-terraform-docs
+# This workflow will generate terraform docs into README.md in the root, examples, and modules folders.
+# Source: https://github.com/equinix-labs/terraform-equinix-kubernetes-addons/blob/main/.github/workflows/documentation.yaml
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "**/*.tpl"
+      - "**/*.tf"
+
+permissions:
+  contents: write # Workflow needs to push new branches to open PRs with docs changes
+  pull-requests: write # Workflow needs to open PRs with docs changes
+
+jobs:
+  tf-docs:
+    name: TF docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        id: actions-checkout
+        with:
+          ref: main
+
+      - name: Render terraform docs inside the main and the modules README.md files and push changes back to PR branch
+        id: terraform-docs
+        uses: terraform-docs/gh-actions@v1
+        with:
+          find-dir: .
+          args: --sort-by required
+          indention: 2
+          git-push: "false"
+
+      # terraform-docs/[email protected] modifies .git files with owner root:root, and the following steps fail with
+      # insufficient permission for adding an object to repository database .git/objects
+      # since the expected user is runner:docker. See https://github.com/terraform-docs/gh-actions/issues/90
+      - name: Fix .git owner
+        run: sudo chown runner:docker -R .git
+
+      - name: Create Pull Request
+        if: steps.terraform-docs.outputs.num_changed != '0'
+        uses: peter-evans/create-pull-request@v6
+        with:
+          commit-message: "generate-terraform-docs: automated action"
+          committer: GitHub <[email protected]>
+          author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com>
+          title: "generate-terraform-docs: automated action"
+          body: |
+            Update terraform docs
+          branch-suffix: timestamp
+          base: main
+          signoff: true
+          delete-branch: true
+
+      # TODO: https://github.com/peter-evans/enable-pull-request-automerge

README.md

@@ -1,22 +1,19 @@
 ## Harvester on Equinix
 
-Simple example using the terraform equinix provider to create a multi node harvester cluster.
+This project demonstrates using the [Terraform Equinix provider](https://deploy.equinix.com/labs/terraform-provider-equinix/) to create a multi-node Harvester cluster.
 
-The user needs to provide two environment variables:
+The user needs to provide three environment variables:
 
-`METAL_AUTH_TOKEN` API token to access your Equinix account
-
-`TF_VAR_api_key` API token to access your Equinix account (needed when Spot Market is enabled)
-
-`TF_VAR_project_name` or `TF_VAR_project_id` Terraform variable to identify project in your Equinix account.
-
-Optionally the user can also provide:
-
-`TF_VAR_metal_create_project` Terraform variable to create a project of name `TF_VAR_project_name` if it does not exist.
+* `METAL_AUTH_TOKEN`: API token to access your Equinix account through the Terraform Provider
+* `TF_VAR_api_key`: API token to access your Equinix Metal account through the http Provider (needed only for Spot Market pricing)
+* `TF_VAR_project_id`: Terraform variable to identify the project in your Equinix account
+
+   Alternatively, the user can provide:
+   `TF_VAR_metal_create_project`: create a project named `TF_VAR_project_name` if it does not exist
 
 You can overwrite any values in `variables.tf` by using `.tfvars` files or [other means](https://www.terraform.io/language/values/variables#assigning-values-to-root-module-variables)
 
-By default the module will create a 3 node Harvester cluster.
+By default, the module will create a 3-node Harvester cluster.
 
 The Harvester console can be accessed using an Elastic IP created by the sample.
 
@@ -27,7 +24,7 @@ terraform output -raw harvester_os_password
 terraform output -raw harvester_cluster_secret
 ```
 
-If you provide a Rancher API URL and keys, your Harvester environment can be managed by Rancher and a kubeconfig file will be saved locally.
+If you provide a Rancher API URL and keys, Rancher can manage your Harvester environment, and a `kubeconfig` file will be saved locally.
 
 ### Using `terraform.tfvars.example` to Override Variable Values