Commit bc9aaba0 authored by Pierre Smeyers's avatar Pierre Smeyers
Browse files

feat(tf-docs): add terraform docs build support

parent 1d301d4b

README.md

+17 −1
Original line number Diff line number Diff line
@@ -518,7 +518,6 @@ The terraform [`fmt` command](https://developer.hashicorp.com/terraform/cli/comm 


This job uses the _check_ mode, and fails if any file appears not being properly formatted. It uses the following variables:





| Name                 | description                                                                                | default value        |

| -------------------- | ------------------------------------------------------------------------------------------ | -------------------- |

| `TF_FMT_ENABLED`     | Set to `true` to enable terraform fmt                                                      | _none_ (disabled)    |
@@ -532,6 +531,23 @@ The terraform [`validate` command](https://developer.hashicorp.com/terraform/cli 
| -------------------- | ------------------------------------------------------------------------------------------ | -------------------- |

| `TF_VALIDATE_ENABLED`     | Set to `true` to enable terraform validate                                            | _none_ (disabled)    |



### `tf-docs` job



Build Terraform documentation based on [terraform docs](https://terraform-docs.io/).



| Name                 | description                                                                                | default value        |

| -------------------- | ------------------------------------------------------------------------------------------ | -------------------- |

| `TF_DOCS_ENABLED`| Set to `true` to enable terraform docs | _none_ (disabled) |

| `TF_DOCS_IMAGE`| [terraform docs](https://terraform-docs.io/) container image | `quay.io/terraform-docs/terraform-docs:edge` |

| `TF_DOCS_EXTRA_OPTS`| Extra [terraform docs option](https://terraform-docs.io/reference/terraform-docs/) | _none_ |

| `TF_DOCS_CONFIG`| terraform docs [configuration file](https://terraform-docs.io/user-guide/configuration/) (relative to `$TF_PROJECT_DIR`) | `.terraform-docs.yml` |

| `TF_DOCS_OUTPUT_DIR`| terraform docs output directory (relative to `$TF_PROJECT_DIR`). | `docs` |



In order to generate your documentation with the right format and options, you should add a [terraform docs configuration file](https://terraform-docs.io/user-guide/configuration/) 

(`.terraform-docs.yml`) at the root of your Terraform project (`$TF_PROJECT_DIR`) in your Git repository.

As long as you don't, this job will simply generate the [pretty](https://terraform-docs.io/reference/pretty/)

doc format in the output console.



## Variants



The Terraform template can be used in conjunction with template variants to cover specific cases.

kicker.json

+31 −0
Original line number Diff line number Diff line
@@ -172,6 +172,37 @@ 
      "enable_with": "TF_VALIDATE_ENABLED",

      "variables": []

    },

    {

      "id": "tfdocs",

      "name": "terraform docs",

      "description": "Build Terraform documentation based on [terraform docs](https://terraform-docs.io/)",

      "enable_with": "TF_DOCS_ENABLED",

      "variables": [

        {

          "name": "TF_DOCS_IMAGE",

          "description": "[terraform docs](https://terraform-docs.io/) container image",

          "default": "quay.io/terraform-docs/terraform-docs:edge",

          "advanced": true

        },

        {

          "name": "TF_DOCS_EXTRA_OPTS",

          "description": "Extra [terraform docs options](https://terraform-docs.io/reference/terraform-docs/)",

          "advanced": true

        },

        {

          "name": "TF_DOCS_CONFIG",

          "description": "terraform docs [configuration file](https://terraform-docs.io/user-guide/configuration/) (relative to `$TF_PROJECT_DIR`)",

          "default": ".terraform-docs.yml",

          "advanced": true

        },

        {

          "name": "TF_DOCS_OUTPUT_DIR",

          "description": "terraform docs output directory (relative to `$TF_PROJECT_DIR`)",

          "default": "docs",

          "advanced": true

        }

      ]

    },

    {

      "id": "review",

      "name": "Review",

templates/gitlab-ci-terraform.yml

+34 −0
Original line number Diff line number Diff line
@@ -70,6 +70,10 @@ variables: 
  TF_INFRACOST_ARGS: "breakdown"

  TF_INFACOST_USAGE_FILE: "infracost-usage.yml"

  TF_FMT_ARGS: "-diff -recursive"

  # tf-docs job config

  TF_DOCS_IMAGE: "quay.io/terraform-docs/terraform-docs:edge"

  TF_DOCS_CONFIG: ".terraform-docs.yml"

  TF_DOCS_OUTPUT_DIR: "docs"



  # root module directory

  TF_PROJECT_DIR: "."
@@ -833,6 +837,36 @@ tf-validate: 
      when: never

    - !reference [.test-policy, rules]



tf-docs:

  stage: build

  image:

    name: $TF_DOCS_IMAGE

    entrypoint: [""]

  before_script:

    - *tf-scripts

    - install_ca_certs "${CUSTOM_CA_CERTS:-$DEFAULT_CA_CERTS}"

    - cd "$TF_PROJECT_DIR"

  script:

    - mkdir -p -m 777 "$TF_DOCS_OUTPUT_DIR"

    - |

      if [[ -f "$TF_DOCS_CONFIG" ]]

      then

        log_info "terraform-docs configuration \\e[33;1m${TF_DOCS_CONFIG}\\e[0m found: use"

        terraform-docs --config "$TF_DOCS_CONFIG" ${TF_DOCS_EXTRA_ARGS} .

      else

        log_info "No terraform-docs configuration file found: generate pretty format doc"

        log_info "Hint: add a \\e[33;1m${TF_PROJECT_DIR}/${TF_DOCS_CONFIG}\\e[0m file to generate the doc with desired format and options"

        terraform-docs pretty ${TF_DOCS_EXTRA_ARGS} .

      fi

  artifacts:

    name: "$CI_JOB_NAME artifacts from $CI_PROJECT_NAME on $CI_COMMIT_REF_SLUG"

    expire_in: 1 day

    paths:

      - "$TF_PROJECT_DIR/$TF_DOCS_OUTPUT_DIR"

  rules:

    # only if $TF_DOCS_ENABLED set

    - if: '$TF_DOCS_ENABLED == "true"'



# =============================================================================

# === Review env jobs

# =============================================================================