From a8068e50234a33a368b1e3bcb696fcd15c3e5e56 Mon Sep 17 00:00:00 2001 From: Marques Johansson Date: Tue, 23 Jul 2024 10:05:01 -0400 Subject: [PATCH] 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 --- .github/workflows/documentation.yaml | 57 ++++++++++++++++++++++++++++ README.md | 23 +++++------ 2 files changed, 67 insertions(+), 13 deletions(-) create mode 100644 .github/workflows/documentation.yaml diff --git a/.github/workflows/documentation.yaml b/.github/workflows/documentation.yaml new file mode 100644 index 0000000..b3491ca --- /dev/null +++ b/.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/gh-actions@v1.0.0 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 + 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 diff --git a/README.md b/README.md index 25d5e02..7448321 100644 --- a/README.md +++ b/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