TFLInt JSON Configuration Support

[rorychatterton]

Introduction

TFLint currently appears to only accepts configuration files in HCL format (.tflint.hcl). This limitation makes it challenging to programmatically generate TFLint configurations from build systems and tools that natively work with JSON. Supporting JSON format for TFLint configuration files would enable better integration with automated tooling and build systems.

Proposal

Add support for JSON-formatted configuration files in TFLint, similar to how Terraform itself supports both .tf (HCL) and .tf.json (JSON) formats. This would allow TFLint to accept configuration files named .tflint.json in addition to the existing .tflint.hcl.

For what it's worth, this should likely be simply a case of exposing the json parser of the hcl/v2 library using hclparse.ParseJSON(). If you're happy to proceed, I will make a PR, with tests, to introduce it to the parser.

Use cases:

• Build systems like Bazel that have strong JSON support can programmatically generate TFLint configurations
• CI/CD pipelines can dynamically create configurations using JSON templating tools
• Teams using infrastructure-as-code generators can emit TFLint config alongside Terraform JSON
• Integration with tools that already output JSON-based configurations (e.g., policy engines, compliance tools)

Example .tflint.json:

{
  "config": {
    "format": "compact",
    "module": true
  },
  "plugin": {
    "aws": {
      "enabled": true,
      "version": "0.21.0",
      "source": "github.com/terraform-linters/tflint-ruleset-aws"
    }
  },
  "rule": {
    "terraform_naming_convention": {
      "enabled": true
    }
  }
}

Implementation Approach

• Accept both .tflint.hcl and .tflint.json as valid configuration filenames
• When .tflint.json is detected, parse it as JSON and convert to the internal configuration structure
• Maintain backward compatibility by continuing to support HCL format
• Follow the same JSON structure conventions that Terraform uses for .tf.json files

References

• Terraform JSON Configuration Syntax: https://www.terraform.io/docs/language/syntax/json.html
• Bazel's native JSON support via json.encode(): https://bazel.build/rules/lib/json
• Similar feature in Terraform allowing both HCL and JSON formats

[wata727]

@rorychatterton Great proposal. Are you interested in working on this? Most of the things you suggest can be implemented as you suggest.

• Loading a config file is implemented in loadConfig, which simply switches the parser depending on the file name.

  • tflint/tflint/config.go

    Line 208 in 4d11a44

    func loadConfig(file afero.File) (*Config, error) {

• Note that you can pass any filename in the TFLINT_CONFIG_FILE environment variable. We'll probably want to switch to processing by extension rather than a hard-coded filename.
• We need to consider the logic for when both .tflint.hcl and .tflint.json files exist.
• Config files may be referenced by plugins, and in this case the source code representation is sent via gRPC, so we need to make sure that the JSON is processed correctly.

  • tflint/tflint/config.go

    Line 483 in 4d11a44

    func (c *Config) Sources() map[string][]byte {

  • https://github.com/terraform-linters/tflint/blob/4d11a440164a6a7d149f1e026eb4fedbb93c7565/docs/developer-guide/architecture.md#apply-configs-to-plugins-rulesetapplyconfig
  • The file that activates the bundled plugin is HCL, so it is important to ensure that it works correctly when JSON and HCL are mixed.

    • tflint/tflint/config.go

      Lines 443 to 446 in 4d11a44

      	// Enable the "recommended" preset if the bundled plugin is automatically enabled.
      	var bundledPluginConfigFilename = "__bundled_plugin_config.hcl"
      	var bundledPluginConfigContent = `
      	preset = "recommended"

• Support for JSON format should be documented with a concrete example.

If you have any questions, please let me know and I'll help you.

[rorychatterton]

Yeah, I'll aim to have a crack at it in the next couple of days.

For what it's worth, I've been building a set of rules for Bazel with Terraform that we use internally. As part of that, we auto-generate configurations for tflint based upon which providers are passed into the build (as well as a few of our own rules in our own plugin).

Right now, it's a bit of hacky hcl concatenation stuff, but once I have this working and at a point that I'm happy to open source my Bazel Module that wraps, I'll be happy to share how it works.

I don't suspect it'll be useful for the majority, but I've got a catalogue of a few hundred modules from years of work, and am looking to bazel as a way to streamline getting consistancy across (i.e. feed my catalogue into the AI Slop machine, using linting rules to force standards across them to maintain my internal catalogue).

[rorychatterton]

Config files may be referenced by plugins, and in this case the source code representation is sent via gRPC, so we need to make sure that the JSON is processed correctly.

I've implemented JSON config file support. The parsing itself works fine - TFLint can read JSON configs using HCL's ParseJSON() without issues.

My concern is about the Config.Sources() method that returns map[string][]byte containing raw source file bytes sent to plugins via gRPC.

tflint/tflint/config.go

Line 70 in 4d11a44

type Config struct {

I can see that:

• Plugins primarily consume the parsed protobuf config data (structured format)
• The source map contains raw file bytes for some purpose

What I'd like to clarify is:

• How exactly do plugins use these raw source bytes from the source map?
• Are there any use cases where plugins expect HCL syntax specifically?
• Could sending raw JSON bytes in the source map break existing plugins, even if they primarily use the parsed protobuf representation fo the config?

Should we convert JSON configs to HCL representation in the source map for plugin compatibility, or is it safe to send the raw JSON bytes?

The conversion is straightforward to implement, but I want to avoid unnecessary complexity if plugins treat the source map as opaque diagnostic data.

[wata727]

How exactly do plugins use these raw source bytes from the source map?

The plugin (or more precisely the plugin SDK) uses the source bytes to restore the contents of the config file as an HCL syntax tree.

TFLint allows you to have plugin-specific settings in the plugin block or rule block as follows:

plugin "terraform" {
  preset = "recommended" # plugin defined schema
}

rule "terraform_module_pinned_source" {
  enabled = true
  style   = "flexible" # plugin defined schema
}

The plugin sends the requested schema (hcl.BodySchema) to the host gRPC server, which returns the body (hcl.BodyContent). At this time, the body is encoded into source bytes and ranges (hcl.Range) and sent over the wire.
https://github.com/terraform-linters/tflint-plugin-sdk/blob/v0.22.0/plugin/internal/proto/tflint.proto#L268-L273
https://github.com/terraform-linters/tflint-plugin-sdk/blob/v0.22.0/plugin/internal/toproto/toproto.go#L115-L131
https://github.com/terraform-linters/tflint-plugin-sdk/blob/v0.22.0/plugin/internal/fromproto/fromproto.go#L152-L166

Are there any use cases where plugins expect HCL syntax specifically?

As far as I know, probably not. This would be a breaking change if users implicitly expected an hclsyntax.Expression as part of the argument to ApplyConfig, which I think is outside the scope of the compatibility promise.
https://pkg.go.dev/github.com/terraform-linters/tflint-plugin-sdk@v0.22.0/tflint#BuiltinRuleSet.ApplyConfig

Could sending raw JSON bytes in the source map break existing plugins, even if they primarily use the parsed protobuf representation fo the config?

One thing that comes to mind is that the source bytes may not be able to be parsed as JSON when decoding. Currently, hclext.ParseExpression only parses files named .tf.json as JSON. This means that .tflint.json cannot be parsed as JSON and may result in a failure to decode.
https://github.com/terraform-linters/tflint-plugin-sdk/blob/v0.22.0/hclext/parse.go#L23

It's a good idea to check whether your custom settings are properly reflected in JSON format.

The solution to this is essentially to fix hclext.ParseExpression to parse files named .json as JSON, but this leaves an issue where plugins built with older versions of the SDK cannot be used.

There are two possible alternatives:

• Parse .tflint.json as .tflint.tf.json internally.
  • One concern is that if the config file fails to parse properly, the file name may be different, causing the contents of the config file to be displayed incorrectly.
• Convert JSON to HCL internally.
  • As with the other alternative, this may break syntax highlighting and line numbers when an error occurs.

[rorychatterton]

I've confirmed that the complex config fails due to https://github.com/terraform-linters/tflint-plugin-sdk/blob/v0.22.0/hclext/parse.go#L23.

It looks like the SDK version is exposed by the client to the Server, as seen https://github.com/terraform-linters/tflint/blob/eb114ce673cc39317d9ff8b6980b5284384aae56/cmd/inspect.go#L129C17-L143C33.

Maybe we update the SDK to support JSON from 0.23, and add a check to tflint to ensure it only supports JSON configuration with compatible clients?

---

Edit, I've confirmed that I can successfully check the version in the flow before we hit the broken logic. Would you prefer that we:

• Output to the user that 0.22 and below is incompatible with the respective plugin, and to upgrade, or:
• Internally convert it?

Marking it as .tflint.tf.json seems 'cleaner' than converting it to HCL, as it's more likely for the debugging heuristics to work (other than the file name).

---

Edit 2:

• Made a PR for the SDK to support JSON. Once thats merged, we can publish it as 0.23.0
• I've updated the tflint PR so that it has a shim that relabels json to tf.json for plugins < 0.22.0. It works for 3rd party plugins, but the bundled rules are a bit special and bypass the init sequence, so I'll need to wait until 0.23 is published before we merge those changes.

[wata727]

Output to the user that 0.22 and below is incompatible with the respective plugin, and to upgrade

I prefer this one, and I believe that not many users will want JSON config, so returning an error is probably acceptable.

Perhaps it would be better to check for the existence of a JSON config file in the precondition checks and, if so, change the required SDK version constraints.

tflint/cmd/inspect.go

Lines 128 to 144 in eb114ce

	// Check preconditions
	sdkVersions := map[string]*version.Version{}
	for name, ruleset := range rulesetPlugin.RuleSets {
	sdkVersion, err := ruleset.SDKVersion()
	if err != nil {
	if st, ok := status.FromError(err); ok && st.Code() == codes.Unimplemented {
	// SDKVersion endpoint is available in tflint-plugin-sdk v0.14+.
	return issues, changes, fmt.Errorf(`Plugin "%s" SDK version is incompatible. Compatible versions: %s`, name, plugin.SDKVersionConstraints)
	} else {
	return issues, changes, fmt.Errorf(`Failed to get plugin "%s" SDK version; %w`, name, err)
	}
	}
	if !plugin.SDKVersionConstraints.Check(sdkVersion) {
	return issues, changes, fmt.Errorf(`Plugin "%s" SDK version (%s) is incompatible. Compatible versions: %s`, name, sdkVersion, plugin.SDKVersionConstraints)
	}
	sdkVersions[name] = sdkVersion
	}

Because the precondition checks can get complicated like this, it might be better to extract them into a separate file.