Improving the terraform-config-inspect library

From all the info I’ve read (and it is quite clear on GitHub - hashicorp/terraform-config-inspect: A helper library for shallow inspection of Terraform configurations) the terraform-config-inspect library is not a library capable of extracting all the information from the .tf files (an example of what is missing Add support for presenting the error messages for input validation blocks by rquadling · Pull Request #94 · hashicorp/terraform-config-inspect · GitHub).

It is quite apparent that there is a LOT missing from the library. Considering this library is a start point, what happens in Terraform to “complete” the journey?

The PR I mentioned above exposes variable validation so that it can be (in my use case) reported by terraform-docs (a WIP/WIBNI Introduce variable validation output into markdown table output. by rquadling · Pull Request #675 · terraform-docs/terraform-docs · GitHub).

But if we look at what Terraform CAN do … it can already read my variable validations and operate on them and produce the output appropriate.

So surely, there is a library created somewhere that COULD be exposed as the v2 of terraform-config-inspect, or, if it must be unrelated, a new project terraform-config-inspect-enhanced.

As terraform-config-inspect seems to be an immutable library, the library that’s actually being used by Terraform would seem to be the thing we want to interact with to get the content of (in my example) variable validations.

My main problem is that I’m not an expert in Go or GitHub. I don’t know enough about making things secure.

Is there anyone within the Terraform team who could at least set up a repo with the right sort of security in place so that we can run on a fork and therefore pull in PRs that really only enhance terraform-config-inspect and it will be “us” who are responsible for rebasing onto the official terraform-config-inspect if and when it changes.

Another issue is exposure. Sure, everyone on the planet could fork terraform-config-inspect and have their own version for the things they need. It would be nice to have a decent community led, acknowledged by Hashicorp, version.

Or something.

The terraform-config-inspect is excellent at the level it is, but it really needs to be improved. OR the actual library that currently reads all of the .tf files could be made available.

What are our realistic options?

Is there space for some external devs to help Hashicorp on this?

Please!

Hi @rquadling,

That library started its life as the way Terraform Registry extracts information about a module’s API for display on the registry website. Its scope is greatly informed by that use-case, and we made it open source in the hope of it being useful for others with similar needs but did not intend it to be a full representation of the entire Terraform language.

There are various tradeoffs implied here that lead to the hesitation to expand its scope:

  • Since it is a separate library rather than a part of Terraform, it has the unique requirement of being able to load modules intended for any version of Terraform from v0.11 (the first version supporting module registries) to at least the most recent v1.x release. (What would happen under a hypothetical breaking change to the language remains hypothetical because there are no plans to do that.)

    The logic built into Terraform itself only needs to support the language of whatever version it’s embedded in. It would not be appropriate for a docs-generating use-case unless you were able to use code from a different version of Terraform depending on what version the given module was intended to be compatible with.

  • Anything exposed in the inspect library constrains how the Terraform language can evolve in future, because it must always be able to produce a common description of anything it exposes across all possible input.

    For entirely new features that’s not a big deal because it can just leave the relevant parts of the description unpopulated when the input is for an older language version that didn’t use that feature.

    However, often we want to make incremental improvements to existing features and in that case things get more complicated. For example, when Terraform v0.12 added support for more complex type constraints for input variables we found that the inspect library was built to treat type constraints exclusively as strings, which is a v0.11-only assumption. That constraint lives on today, forcing users of the inspect library to either just treat type constraints as opaque strings or to try to parse them from a string, and if they do the latter then they can potentially be broken by the addition of new features such as optional attributes that change what syntax is possible in that string.

    Input variable validation rules also fit into this category, because although at initial release the error message was required to be a constant string – with use-cases like the inspect library in mind – subsequent feedback indicated that supporting general expressions in that location was apparently more important than being able to generate documentation including the error messages. If we had exported the constant error message strings from the start then it may not have been possible to address that feedback, because the inspect library lacks sufficient information to do general expression evaluation.

With all of the above in mind, we tend to add new things to the library only when both of the following are true:

  • it meets a “module documentation” sort of use-case, matching the library’s original intended scope.
  • the relevant part of the language seems relatively frozen and unlikely to change significantly in future, so we can feel relatively confident that the inspect library design won’t constrain likely future evolution.

You may of course have different priorities, and that’s fine. But the team that works on Terraform Core at HashiCorp has only finite time to spend and the inspect library is not really its main purpose, so we need to be careful what we’re committing to maintain there.

If you do decide to make a new library with different scope and different tradeoffs then you could potentially use information from the internal/configs package in the main Terraform codebase to understand how Terraform currently decodes certain elements. What you make will likely have a smaller set of supported Terraform language versions due to fixing more of the current decisions in your API, but of course that is your tradeoff to make.

At this time, I think it’s unlikely that we would publish another library in the hashicorp namespace, because anything there has the expectation that some team at HashiCorp is primarily responsible for it – the organisation on GitHub is configured in a way that makes it essentially impossible to have non-employees with commit access, due to the shared source and open source repositories cohabiting with private repositories that are subject to strict controls for various reasons.

However, I don’t want to discourage you from making and publishing a library yourself in a separate namespace. I would suggest considering the above tradeoffs if you expect this to be a long-lived library serving many different use-cases, but you don’t need to make the same design decisions we did based on those tradeoffs if you have different goals in mind.

1 Like