tflens

tflens lets you compare terraform modules across environments.

Note

tflens is alpha software. It's behaviour and interface is likely to change for a while.

Install

homebrew:

brew install dhth/tap/tflens

go:

go install github.com/dhth/tflens@latest

Or get the binary directly from a release. Read more about verifying the authenticity of released artifacts here.

Usage

Consider a terragrunt codebase with three different deployment environments: dev, prod-us, and prod-eu. If you want to compare modules across all three environments, you can define a comparison in tflens.yml:

compareModules:
  # list of configured comparisons
  comparisons:
    # will be used when specifying the comparison to be run
    - name: apps
      # the attribute to use for comparison
      attributeKey: source
      # where to look for terraform files
      sources:
        - path: environments/dev/virginia/apps/main.tf
          # this label will appear in the comparison output
          label: dev
        - path: environments/prod/virginia/apps/main.tf
          label: prod-us
        - path: environments/prod/frankfurt/apps/main.tf
          # regex to extract the desired string from the attribute value
          # only applies to this source, overrides the global valueRegex
          # optional
          valueRegex: "v?(\\d+\\.\\d+\\.\\d+)"
          label: prod-eu
      # specifies the command to be run for generating diffs between two
      # versions of a module; can be useful in the case the attribute being
      # compared contains a version tag
      # eg. source = "git@github.com:owner/repo//modules/module_a?ref=module-a-v1.3.0"
      # optional
      diffConfig:
        # the label to use for the base ref
        baseLabel: prod-us
        # the label to use for the head ref
        headLabel: dev
        # the command to use, as an array
        # tflens will populate the following environment variables for this
        # command execution
        # - TFLENS_DIFF_BASE_REF
        # - TFLENS_DIFF_HEAD_REF
        # - TFLENS_DIFF_MODULE_NAME
        cmd: ["./scripts/generate-diff.sh", "apps"]
      # list of modules to ignore while comparing
      # optional
      ignoreModules:
        - module_x
        - module_y

  # regex to extract the desired string from the attribute value
  # applies to all comparisons
  # optional
  valueRegex: "v?(\\d+\\.\\d+\\.\\d+)"

You can then compare the modules as follows.

tflens compare-modules -h

Usage:
  tflens compare-modules <COMPARISON> [flags]

Flags:
  -c, --config-path string       path to tflens' configuration file (default "tflens.yml")
  -h, --help                     help for compare-modules
      --html-output string       path where the HTML report should be written (default "tflens-report.html")
      --html-template string     path to a custom HTML template (optional)
      --html-title string        title for the HTML report (default "report")
  -i, --ignore-missing-modules   to not have the absence of a module lead to an out-of-sync status
  -d, --include-diffs            include diffs between versions in report (requires diffConfig in tflens' config)
  -o, --output-format string     output format for results; allowed values: [stdout html] (default "stdout")
      --stdout-plain             do not use colors in stdout output

tflens compare-modules apps

 module       dev        prod-us     prod-eu     in-sync

 module_a     1.0.24     1.0.24      1.0.24      ✓
 module_b     0.2.0      0.2.0       -           ✗
 module_c     1.1.1      1.1.1       1.1.0       ✗

tflens can also generate an HTML report via the --output-format flag.

🔐 Verifying release artifacts

In case you get the tflens binary directly from a release, you may want to verify its authenticity. Checksums are applied to all released artifacts, and the resulting checksum file is signed using cosign.

Steps to verify (replace A.B.C in the commands listed below with the version you want):

1. Download the following files from the release:

   • tflens_A.B.C_checksums.txt
   • tflens_A.B.C_checksums.txt.pem
   • tflens_A.B.C_checksums.txt.sig

2. Verify the signature:

   cosign verify-blob tflens_A.B.C_checksums.txt \
       --certificate tflens_A.B.C_checksums.txt.pem \
       --signature tflens_A.B.C_checksums.txt.sig \
       --certificate-identity-regexp 'https://github\.com/dhth/tflens/\.github/workflows/.+' \
       --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

3. Download the compressed archive you want, and validate its checksum:

   curl -sSLO https://github.com/dhth/tflens/releases/download/vA.B.C/tflens_A.B.C_linux_amd64.tar.gz
   sha256sum --ignore-missing -c tflens_A.B.C_checksums.txt

4. If checksum validation goes through, uncompress the archive:

   tar -xzf tflens_A.B.C_linux_amd64.tar.gz
   ./tflens -h
   # profit!