New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Initial stab at JSON plan output #3170

Closed
wants to merge 1 commit into
base: master
from

Conversation

Projects
None yet
@glenjamin
Contributor

glenjamin commented Sep 3, 2015

Guidelines said to submit even if it's early work, so here goes.

I'm pretty new to go, but have found it pretty easy to onboard into a build environment and navigating the codebase, good work everyone!

This relates to #2460 - specifically supporting JSON as plan output.

The particular scenario that led me to implement this went like this:

  1. Run terraform apply to create a VM (via cloudstack)
  2. VM takes ages to provision, terraform times out
  3. VM was actually created, but terraform doesn't know about it

At this point, one option is to manually fill in the state file with a name and id for the resource, and terraform is then able to refresh and figure out where it got to.

My thinking was that it'd be nice to be able to machine read the plan (or the whole config perhaps?), and then consume this with a different tool that knows which fields should be unique, and can go fill out my state file based on what the plan might have acheived.

What do you think?

@apparentlymart

This comment has been minimized.

Show comment
Hide comment
@apparentlymart

apparentlymart Sep 4, 2015

Contributor

Hmm interesting... I've found myself wanting to parse the plans before, just to render them in a different way. So this seems useful to me.

I wonder though if it's necessary to complicate the UI with this option or whether Terraform could just switch to using a JSON plan in all cases. I believe that historically Terraform had a pretty opaque state file format too, and that was changed to JSON. As long as all the necessary info can be packed in there I'd assume it doesn't matter too much what the serialization is.

I must admit I've never looked too closely at the details of what gets saved in a plan file, though. Is there something in there that is difficult to represent in JSON?

Contributor

apparentlymart commented Sep 4, 2015

Hmm interesting... I've found myself wanting to parse the plans before, just to render them in a different way. So this seems useful to me.

I wonder though if it's necessary to complicate the UI with this option or whether Terraform could just switch to using a JSON plan in all cases. I believe that historically Terraform had a pretty opaque state file format too, and that was changed to JSON. As long as all the necessary info can be packed in there I'd assume it doesn't matter too much what the serialization is.

I must admit I've never looked too closely at the details of what gets saved in a plan file, though. Is there something in there that is difficult to represent in JSON?

@glenjamin

This comment has been minimized.

Show comment
Hide comment
@glenjamin

glenjamin Sep 4, 2015

Contributor

I did originally just dump the whole plan out, but it contained the entire state and a bunch of stuff which didn't seem relevant for this use case.

The diff seems to be most relevant part.

Contributor

glenjamin commented Sep 4, 2015

I did originally just dump the whole plan out, but it contained the entire state and a bunch of stuff which didn't seem relevant for this use case.

The diff seems to be most relevant part.

@josephholsten

This comment has been minimized.

Show comment
Hide comment
@josephholsten

josephholsten Sep 24, 2015

Contributor

@glenjamin this looks awesome. What would the simplest possible test case look like?

Contributor

josephholsten commented Sep 24, 2015

@glenjamin this looks awesome. What would the simplest possible test case look like?

@glenjamin

This comment has been minimized.

Show comment
Hide comment
@glenjamin

glenjamin Sep 26, 2015

Contributor

It wouldn't be difficult to add some unit tests, me adding some mostly depends on whether this is considered an appropriate direction.

Contributor

glenjamin commented Sep 26, 2015

It wouldn't be difficult to add some unit tests, me adding some mostly depends on whether this is considered an appropriate direction.

@thegedge

This comment has been minimized.

Show comment
Hide comment
@thegedge

thegedge Oct 7, 2015

Contributor

My team recently discussed wanting to parse the plan files to present something differently to our users. We have a team dedicated to cloud infrastructure that understands terraform, but we want to roll something out to application developers so that they can easily deploy their own infrastructure. In doing so, we want to hide certain details about what terraform may be doing, or make it more understandable to an application developer. Also, for me personally, I oftentimes only care about why a resource has to be destroyed/created, which means I'd filter out the "(forces new resource)" lines. Seeing foo = "${some interpolation}" isn't particularly useful information.

With regards to this specific PR, I'd personally either a) use the extension on -out to determine whether or not to output JSON, or b) go with a -format=json approach, as mentioned in #2460.

Contributor

thegedge commented Oct 7, 2015

My team recently discussed wanting to parse the plan files to present something differently to our users. We have a team dedicated to cloud infrastructure that understands terraform, but we want to roll something out to application developers so that they can easily deploy their own infrastructure. In doing so, we want to hide certain details about what terraform may be doing, or make it more understandable to an application developer. Also, for me personally, I oftentimes only care about why a resource has to be destroyed/created, which means I'd filter out the "(forces new resource)" lines. Seeing foo = "${some interpolation}" isn't particularly useful information.

With regards to this specific PR, I'd personally either a) use the extension on -out to determine whether or not to output JSON, or b) go with a -format=json approach, as mentioned in #2460.

@alexgervais

This comment has been minimized.

Show comment
Hide comment
@alexgervais

alexgervais Oct 19, 2015

Love this! Using the JSON output would allow me to build unit test cases around our terraform modules and setup proper validations/CI.

alexgervais commented Oct 19, 2015

Love this! Using the JSON output would allow me to build unit test cases around our terraform modules and setup proper validations/CI.

@josephholsten

This comment has been minimized.

Show comment
Hide comment
@josephholsten

josephholsten Feb 4, 2016

Contributor

@phinze, @mitchellh can you give this 👀 and say whether this is worth pursuing? Needs test & doc.

Contributor

josephholsten commented Feb 4, 2016

@phinze, @mitchellh can you give this 👀 and say whether this is worth pursuing? Needs test & doc.

@josephholsten josephholsten referenced this pull request Feb 5, 2016

Closed

[WIP] JSON plan format #4610

2 of 3 tasks complete
@jzohrab

This comment has been minimized.

Show comment
Hide comment
@jzohrab

jzohrab Feb 18, 2016

Contributor

@thegedge (and others here), I don't know if this is at all useful for you: https://github.com/jzohrab/terraform_tfstate_report

It's a rough tool that should let you create a report in ERB. Right now the ERB template is hardcoded, but it could easily be extended. (Should be easily extensible, anyway)

Contributor

jzohrab commented Feb 18, 2016

@thegedge (and others here), I don't know if this is at all useful for you: https://github.com/jzohrab/terraform_tfstate_report

It's a rough tool that should let you create a report in ERB. Right now the ERB template is hardcoded, but it could easily be extended. (Should be easily extensible, anyway)

@dtolnay

This comment has been minimized.

Show comment
Hide comment
@dtolnay

dtolnay Sep 23, 2016

Contributor

👍 for the idea of outputting a JSON representation of plan. This would give us an easy way to write unit tests for our Terraform modules in any language. Also useful for plan-only testing workflows in Test Kitchen newcontext-oss/kitchen-terraform#37.

Contributor

dtolnay commented Sep 23, 2016

👍 for the idea of outputting a JSON representation of plan. This would give us an easy way to write unit tests for our Terraform modules in any language. Also useful for plan-only testing workflows in Test Kitchen newcontext-oss/kitchen-terraform#37.

@apparentlymart

This comment has been minimized.

Show comment
Hide comment
@apparentlymart

apparentlymart May 5, 2017

Contributor

Hi @glenjamin,

First of all, sorry for letting this PR languish here for well over a year. 😖 We let this one slip through the cracks, and for that we wholeheartedly apologize.

We've gone back and forth on the idea of creating more machine-readable output for many Terraform commands. Since Terraform is still pre-1.0 software we're concerned about creating too many compatibility constraints; already since this issue was opened there have been changes to Terraform that would've required us to break a JSON format for plans, and this is likely to continue for the foreseeable future as plans are a very fundamental part of Terraform's architecture.

So it is with a heavy heart that we're going to say no to this idea for the moment, though that doesn't mean we won't revisit it as Terraform evolves and its model becomes more stable.

In the mean time, there is a third-party tool terraform-landscape that scrapes the human-oriented plan output. Of course a tool like this is very likely to be broken by future Terraform releases, since we don't consider the human-oriented plan output to be a compatibility constraint, but in a pinch this approach could be helpful for certain specific use-cases where machine-analysis of plans is required.

Thank you very much for working on this, and again sorry for the long silence without any feedback.


(I'd also like to clarify, for anyone looking back on this discussion in future, that my earlier contributions to this discussion and similar PRs were as a community contributor, before I joined the Terraform team full-time.)

Contributor

apparentlymart commented May 5, 2017

Hi @glenjamin,

First of all, sorry for letting this PR languish here for well over a year. 😖 We let this one slip through the cracks, and for that we wholeheartedly apologize.

We've gone back and forth on the idea of creating more machine-readable output for many Terraform commands. Since Terraform is still pre-1.0 software we're concerned about creating too many compatibility constraints; already since this issue was opened there have been changes to Terraform that would've required us to break a JSON format for plans, and this is likely to continue for the foreseeable future as plans are a very fundamental part of Terraform's architecture.

So it is with a heavy heart that we're going to say no to this idea for the moment, though that doesn't mean we won't revisit it as Terraform evolves and its model becomes more stable.

In the mean time, there is a third-party tool terraform-landscape that scrapes the human-oriented plan output. Of course a tool like this is very likely to be broken by future Terraform releases, since we don't consider the human-oriented plan output to be a compatibility constraint, but in a pinch this approach could be helpful for certain specific use-cases where machine-analysis of plans is required.

Thank you very much for working on this, and again sorry for the long silence without any feedback.


(I'd also like to clarify, for anyone looking back on this discussion in future, that my earlier contributions to this discussion and similar PRs were as a community contributor, before I joined the Terraform team full-time.)

@philips

This comment has been minimized.

Show comment
Hide comment
@philips

philips May 12, 2017

I updated this tool for TF 0.9 https://github.com/philips/tfjson

philips commented May 12, 2017

I updated this tool for TF 0.9 https://github.com/philips/tfjson

@daluu daluu referenced this pull request Aug 20, 2018

Open

Parse terraform files #18269

@jcmcken

This comment has been minimized.

Show comment
Hide comment
@jcmcken

jcmcken Sep 25, 2018

@apparentlymart

To rant a little bit:

Terraform has been pre-1.0 for years now! When, if ever, will it hit 1.0? Clearly Sentinel has some capacity to introspect Terraform. If there are no plans to ever produce a stable API or tooling for parsing Terraform data in the open source tools, just say so instead of doing this dance for years on end about waiting for a 1.0 release.

jcmcken commented Sep 25, 2018

@apparentlymart

To rant a little bit:

Terraform has been pre-1.0 for years now! When, if ever, will it hit 1.0? Clearly Sentinel has some capacity to introspect Terraform. If there are no plans to ever produce a stable API or tooling for parsing Terraform data in the open source tools, just say so instead of doing this dance for years on end about waiting for a 1.0 release.

@apparentlymart

This comment has been minimized.

Show comment
Hide comment
@apparentlymart

apparentlymart Sep 25, 2018

Contributor

Hi @jcmcken,

This is not really a great place to talk about Terraform's overall roadmap, but I'll try to summarize the situation here: Terraform will be marked as 1.0 once we believe there will be no more breaking changes for some time, at which point we will make a promise similar to the Go 1.0 compatibility promise about what will and will not change moving forward. It is not 1.0 yet because we know there are several aspects of it that need to be reworked, based on the feedback collected in GitHub issues, and that several breaking changes will be required to get that done. We're intentionally front-loading the breaking-change work to get it done in as few breaking steps as possible, which is the main reason why the Terraform 0.12 release has been the biggest major release to date. Following that, we have some work to do on the CLI workflow that are also expected to include some carefully-considered breaking changes.

At present, Terraform Enterprise Sentinel is parsing plan files directly using its own parser that copies the behavior of the one inside Terraform, which is of course something that any other program could do too using @philips's tfjson library linked above, but it would then need to be updated each time the format changes. This is exactly what the team working on Terraform Enterprise Sentinel has been doing so far, as a pragmatic way to make those features available.

With that said, we are actually planning to introduce a JSON-formatted plan in a near-future release which the Sentinel integration will then transition to. We will not be able to commit to 100% compatibility with it at first, but we believe the 0.12 work has got the plan model into a good enough shape that future changes should only be minor. Then once the various new formats -- including this one -- are proven by real-world use, then we will consider them stable, document them comprehensively, and promise not to break external software that parses them per that documentation.

Contributor

apparentlymart commented Sep 25, 2018

Hi @jcmcken,

This is not really a great place to talk about Terraform's overall roadmap, but I'll try to summarize the situation here: Terraform will be marked as 1.0 once we believe there will be no more breaking changes for some time, at which point we will make a promise similar to the Go 1.0 compatibility promise about what will and will not change moving forward. It is not 1.0 yet because we know there are several aspects of it that need to be reworked, based on the feedback collected in GitHub issues, and that several breaking changes will be required to get that done. We're intentionally front-loading the breaking-change work to get it done in as few breaking steps as possible, which is the main reason why the Terraform 0.12 release has been the biggest major release to date. Following that, we have some work to do on the CLI workflow that are also expected to include some carefully-considered breaking changes.

At present, Terraform Enterprise Sentinel is parsing plan files directly using its own parser that copies the behavior of the one inside Terraform, which is of course something that any other program could do too using @philips's tfjson library linked above, but it would then need to be updated each time the format changes. This is exactly what the team working on Terraform Enterprise Sentinel has been doing so far, as a pragmatic way to make those features available.

With that said, we are actually planning to introduce a JSON-formatted plan in a near-future release which the Sentinel integration will then transition to. We will not be able to commit to 100% compatibility with it at first, but we believe the 0.12 work has got the plan model into a good enough shape that future changes should only be minor. Then once the various new formats -- including this one -- are proven by real-world use, then we will consider them stable, document them comprehensively, and promise not to break external software that parses them per that documentation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment