Skip to content

lint.md

Latest commit

 

History

History
205 lines (157 loc) · 6.07 KB

lint.md

File metadata and controls

205 lines (157 loc) · 6.07 KB

Lint Engine

The lint engine performs static analysis to detect potential errors, best practice violations, and security issues in your Terraform code.

Overview

The lint engine provides static analysis through built-in AST-based rules and optional TFLint integration. Built-in rules cover core Terraform hygiene (versioning, naming, security), while TFLint integration adds provider-specific checks when TFLint is installed.

Usage

# Run linting
terratidy lint

# Use a custom TFLint config file
terratidy lint --tflint-config .tflint.custom.hcl

# Enable specific rules
terratidy lint --rule terraform-required-version

# Enable a provider plugin
terratidy lint --plugin aws

Configuration

engines:
  lint:
    enabled: true
    config_file: .tflint.hcl      # Path to TFLint config
    plugins:                       # TFLint plugins to enable
      - aws
      - google
    args:                          # Extra arguments to pass to TFLint
      - --force
      - --no-color
    use_tflint: true               # Enable TFLint subprocess integration
    tflint_path: /usr/local/bin/tflint  # Custom TFLint binary path
    fallback_builtin: true         # Use built-in rules if TFLint unavailable
    rules:                         # Rule-specific configuration
      lint.terraform-deprecated-syntax:
        enabled: true
        severity: error
Option Type Default Description
enabled bool true Enable/disable the lint engine
config_file string .tflint.hcl Path to TFLint configuration file
plugins list [] TFLint plugins to enable
args list [] Extra arguments to pass to TFLint
use_tflint bool false Enable TFLint subprocess integration
tflint_path string tflint Custom path to TFLint binary
fallback_builtin bool false Use built-in rules if TFLint is unavailable
rules map {} Rule-specific configuration

Rule Categories

Built-in Rules

TerraTidy includes 11 built-in Terraform lint rules covering versioning, documentation, naming, security, and more. A few examples:

Rule Description
terraform-required-version Requires a terraform.required_version constraint
terraform-deprecated-syntax Detects deprecated Terraform syntax
terraform-unused-declarations Finds unused variables and locals
terraform-hardcoded-secrets Detects hardcoded secrets in configuration

For the full list, see Lint Rules.

Provider-Specific Rules

Provider-specific rules (AWS, Google Cloud, Azure) are supplied by TFLint plugins, not built into TerraTidy. Enable them via your .tflint.hcl configuration or the plugins config key. See the TFLint ruleset registry for available provider rulesets.

TFLint Integration

TerraTidy can optionally invoke TFLint as an external CLI tool (subprocess) for comprehensive provider-specific linting. TFLint is not embedded or linked as a library. You can use existing TFLint configuration files:

# .tflint.hcl
plugin "aws" {
  enabled = true
  version = "0.27.0"
  source  = "github.com/terraform-linters/tflint-ruleset-aws"
}

rule "aws_instance_invalid_type" {
  enabled = true
}

Example Output

main.tf:15:1: error: aws_instance_invalid_type - "t2.superxlarge" is an invalid value as instance_type
main.tf:23:5: warning: aws_security_group_rule - Security group allows unrestricted ingress
variables.tf:8:1: warning: terraform_unused_declarations - variable "unused_var" is declared but not used

Fixing Issues

The lint command is a read-only analysis that never modifies files. Unlike fmt and style, there is no --check or --diff flag because lint only reports issues. To fix lint issues, you must edit your Terraform code manually.

For formatting and style issues that can be auto-fixed, use terratidy fix or terratidy style --fix.

Plugin Rules

The lint engine supports custom rules loaded from plugin directories. Plugin rules run alongside built-in lint rules and produce findings in the same output.

Enabling Plugin Rules

plugins:
  enabled: true
  directories:
    - .terratidy/plugins
    - ~/.terratidy/plugins

Plugin rules can be YAML files, Bash scripts, or Go plugins. See the Plugin Development guide for details on creating custom rules.

Plugin Rule Example

A YAML rule that checks for required tags:

# .terratidy/plugins/require-tags.yaml
name: require-tags
description: Resources must have tags
severity: warning
enabled: true
message: "Resource is missing a 'tags' attribute"
patterns:
  required_attributes:
    - tags

Configuring Plugin Rules

Plugin rules can be enabled, disabled, or have their severity overridden:

plugins:
  enabled: true
  directories:
    - .terratidy/plugins
  rules:
    require-tags:
      enabled: true
      severity: error  # Override default severity

Disabling Rules

Suppress specific rules using inline annotations:

# Suppress on the next block
# terratidy:ignore:lint.terraform-unused-declarations
variable "legacy_var" {
  type = string
}

# Suppress inline (same line as code)
variable "temp_var" { type = string } # terratidy:ignore:lint.terraform-typed-variables

# Suppress for the entire file
# terratidy:ignore-file:lint.terraform-required-version

# Suppress all lint rules for the file
# terratidy:ignore-file:lint.*

Or disable globally in configuration:

engines:
  lint:
    rules:
      lint.terraform-unused-declarations:
        enabled: false

License Note

TFLint is invoked as an external CLI tool (subprocess), not embedded or linked as a library. TFLint uses MPL-2.0 for its own code and BUSL-1.1 for embedded Terraform code (required since Terraform's license change in August 2023). TerraTidy's subprocess invocation pattern is compliant with these licenses. TerraTidy itself remains MIT-licensed.