terraform version shows new version number, but not when viewed as JSON

[rquadling]

Current Terraform Version

$ terraform --version
Terraform v0.15.3
on darwin_amd64
+ provider registry.terraform.io/cloudflare/cloudflare v2.20.0
+ provider registry.terraform.io/hashicorp/aws v3.40.0
+ provider registry.terraform.io/hashicorp/external v2.1.0
+ provider registry.terraform.io/hashicorp/local v2.1.0
+ provider registry.terraform.io/hashicorp/random v3.1.0

Your version of Terraform is out of date! The latest version
is 0.15.4. You can update by downloading from https://www.terraform.io/downloads.html

but

$ terraform --version --json
{
  "terraform_version": "0.15.3",
  "platform": "darwin_amd64",
  "provider_selections": {
    "registry.terraform.io/cloudflare/cloudflare": "2.20.0",
    "registry.terraform.io/hashicorp/aws": "3.40.0",
    "registry.terraform.io/hashicorp/external": "2.1.0",
    "registry.terraform.io/hashicorp/local": "2.1.0",
    "registry.terraform.io/hashicorp/random": "3.1.0"
  },
  "terraform_outdated": true
}

Use-cases

Being able to get an accurate 'next version' number when the current version is outdated is useful for us. I build containers that use multiple tools and triggering builds from a sensible format is much harder to do when the text output changes from release to release.

Attempted Solutions

Using regex to identify the next version which may or may not be present, in conjunction with the additional changes (and future changes) to the text of terraform --version ... well ... using regex is the problem, sure, but all the same, unstructured data extraction is always going to be prone to errors.

Using the same extraction on JSON data would be deemed "safer" in that this is a structured format and so easier to validate.

Proposal

Within the body of the output for terraform --version --json, include a new key terraform_latest_version which will have the value of the next available version which is reported when running terraform version.

References

As a side note, I'm wanting to learn more about Go and Terraform coding, so would be happy to give this a go for a PR. I've had 1 accepted, which was more or less follow the existing pattern of code and less about developing the code with knowledge.

[rquadling]

I've made a PR : https://github.com/hashicorp/terraform/pull/28777

[bgmonroe]

As a nit-pick, I'd ask to also make the current version string consistent between the two outputs ("v0.15.3" vs. "0.15.3"). Apologies in advance for "being that guy."

[rquadling]

@bgmonroe Hi, we can all be "that guy"!

I was keeping consistency within the format. In the --json output, the current code does not prefix the versions with v.

If that needs changing (I'd be dropping the v from the text output as I find prefixing versions with version redundant), that'd would be for another change request.

Also, it would be a BC change as anyone relying on the format would now be needing to parse/process the v (or not, depending upon which output they are processing), and I don't know what procedures that would need to go through.

[bgmonroe]

Understood. Sometimes my OCD gets the better of me. 😄

[rquadling]

How do I get this picked up for review?

[apparentlymart]

Hi @rquadling! Sorry for the delay in looking at this.

A concern I have about exposing this in a machine-readable way is that it would become a compatibility commitment to always include it, and including it depends on an external service that may not exist forever. We include it in the human-readable output as a convenience to a human operator on a best-effort basis (it only "speaks up" if the request succeeds and confirms there's a new version available; otherwise it's silent), but we would likely remove it if the service it depends on -- which is not under this team's direct control -- were to be shut down.

I can see the argument that this is technically true for terraform_outdated as well, and honestly if I'd been paying attention when that was proposed I would've raised the same concern then too, but at least for that one we could potentially just switch to it always returning false if we needed to, because that flag only serves as a signal to tell a user that Terraform is outdated, and so returning false would simply hide that error.

If you want to know what is the latest available version of Terraform, the existing public interface for that is to access https://releases.hashicorp.com/terraform/index.json to see all of the available releases and take the newest one that meets your needs. I'd suggest using that because it's the same service used by several other systems and already committed as a public interface. If that API can't return the information you need then I'd love to hear a little more about your situation.

Thanks!

[rquadling]

I see what you are saying. My only counter-argument is that as terraform DOES currently expose a value that may or may not always be accurate ... extending this to the json output is consistent (-ish).

Maybe the key for the JSON entry could be terraform_latest_known_version? Something that implies a possible inaccuracy?