TFLint Documentation

TFLint is a pluggable linter that does not contain rule implementations. Instead, rules are provided as external plugins launched as subprocesses. Communication between the TFLint host and plugins occurs over gRPC.

In this architecture, both the host and the plugin act as both gRPC server and client:

Plugin (Client) to Host (Server) requests:

• Retrieve Terraform configs (e.g., aws_instance.main)
• Evaluate expressions (e.g., var.foo)
• Save reported issues to the host server

Host (Client) to Plugin (Server) requests:

• Apply plugin configurations
• Request to run inspections

Plugin development is based on the TFLint plugin SDK.

The ipaddr package contains a fork of Go 1.16's net package IP address parsing functions. It is used to maintain compatibility with Terraform's built-in functions: cidrhost, cidrsubnet, cidrsubnets, and cidrnetmask.

Key Behavior: Unlike Go 1.17+, this package allows IPv4 address octets with leading zeros (e.g., 192.168.0.01). Standard Go 1.17+ rejects these to prevent ambiguity between decimal and octal interpretations.

Usage Guidance:

• Use this package if: You are implementing new functionality that must remain consistent with the behavior of Terraform's cidr* functions.
• Avoid this package if: You are building new features that do not require this specific legacy compatibility. In such cases, you should prefer the stricter, standard Go parsing functions to avoid potential security concerns related to non-normalized IP forms.

TFLint uses its own parser (a fork of Terraform's native parser) to interpret Terraform code, meaning Terraform does not need to be installed at runtime.

Key compatibility details:

• Supports Terraform v1.x syntax and semantics.
• Follows Terraform Compatibility Promises.
• The latest supported version is Terraform v1.15.
• New features require newer TFLint versions; bug and experimental feature compatibility is not guaranteed.

It is recommended to verify the authenticity of the downloaded binaries using the GitHub CLI to check Artifact Attestations.

Note: Cosign signatures are deprecated; use the GitHub CLI method instead.

gh attestation verify checksums.txt -R terraform-linters/tflint
sha256sum --ignore-missing -c checksums.txt

You can install TFLint using several methods depending on your operating system and environment.

Linux (Manual)

curl -sSLO https://github.com/terraform-linters/tflint/releases/latest/download/tflint_linux_amd64.zip
curl -sSLO https://github.com/terraform-linters/tflint/releases/latest/download/checksums.txt
gh attestation verify checksums.txt -R terraform-linters/tflint
sha256sum --ignore-missing -c checksums.txt
unzip tflint_linux_amd64.zip
sudo install -c -v tflint /usr/local/bin/

You can extend TFLint by declaring plugins in your configuration file. Once declared with a source and version, you can run tflint --init to automatically download and install them.

To install a plugin, add a plugin block to your config file and then execute the initialization command.

plugin "foo" {
  enabled = true
  version = "0.1.0"
  source  = "github.com/org/tflint-ruleset-foo"
}

$ tflint --init

TFLint can automatically resolve certain reported issues. Issues that support this feature are explicitly marked with a [Fixable] label in the output. To apply these fixes, run TFLint with the --fix flag.

Important Note: When an autofix is applied, TFLint will automatically format the entire file. This means that code ranges unrelated to the specific issue being fixed may also be modified by the formatter.

$ tflint --fix

TFLint implements the Language Server Protocol (LSP) v3.14.0, allowing it to integrate with any editor that supports LSP clients (such as VS Code). This enables real-time linting diagnostics within your editor. To start the language server, run the TFLint binary with the --langserver flag.

$ tflint --langserver

The Ephemeral value feature was introduced in SDK v0.22.0 and TFLint v0.55.0.

Compatibility Caveat: If you are using a plugin built with an older SDK (specifically v0.21.0 or lower), TFLint will return ErrSensitive instead of the ephemeral values to maintain backward compatibility.

In Terraform JSON configuration, you can suppress rules for an entire file using a top-level // comment property.

Note that tflint-ignore-file is supported in JSON, but the line-specific tflint-ignore annotation is not supported in JSON. When adding comments to the annotation in JSON, the annotation must be the first thing in the comment property string.

{
  "//": "tflint-ignore-file: aws_instance_invalid_type",
  "resource": {
    "aws_instance": {
      "foo": {
        "instance_type": "t2.micro"
      }
    }
  }
}