diff --git a/website/docs/commands/show.html.markdown b/website/docs/commands/show.html.markdown index b6dc92122..42e34377d 100644 --- a/website/docs/commands/show.html.markdown +++ b/website/docs/commands/show.html.markdown @@ -28,7 +28,7 @@ For Terraform state files (including when no path is provided), For Terraform plan files, `terraform show -json` will show a JSON representation of the plan, configuration, and current state. -The output format is covered in detail in [JSON Format](/docs/internals/json-format.html). +The output format is covered in detail in [JSON Output Format](/docs/internals/json-format.html). ## Usage diff --git a/website/docs/internals/json-format.html.md b/website/docs/internals/json-format.html.md index 3ea0b2a7a..b67afe93e 100644 --- a/website/docs/internals/json-format.html.md +++ b/website/docs/internals/json-format.html.md @@ -1,34 +1,158 @@ --- layout: "docs" -page_title: "Internals: JSON format" +page_title: "Internals: JSON Output Format" sidebar_current: "docs-internals-json" description: |- Terraform provides a machine-readable JSON representation of state, configuration and plan. --- -# Introduction - -Terraform 0.11 and earlier had two formats for communicating planned changes: printing human-readable output to the terminal, or printing a binary plan file intended to be read only by Terraform. - -This binary plan file is designed so that in principle we could document it as stable in the long run, but in practice it is required to encode very precise details about a Terraform plan, which makes it hard to make any compatibility promises in the face of changes to Terraform internals. We will continue to consider it an opaque format for the foreseeable future. - -To meet the need for machine consumption of plan data by code outside of Terraform CLI, Terraform 0.12 introduces a third format: a JSON summary of the plan designed for consumption by external software. The structure of this format -- described in detail in subsequent sections -- is intended to represent sufficient details for external tools to analyze the implications of the plan but to do so at an end-user-oriented level of abstraction that is less likely to see significant breaking changes in future versions of Terraform. - -**NOTE** - -The JSON format is experimental and subject to change. A "format_version" key is included in the output. The minor version portion will be incremented for compatible additions to the output, and the major version portion will be incremented for any format changes which require mandatory changes for correct processing. - # JSON Output Format -The full structure of this file will be discussed by example in parts in the following sub-sections, followed by any additional constraints or considerations that cannot be reflected directly in the examples. We will use a pseudo-JSON notation with `` to indicate how these different portions of the output are combined without excessive repetition. +-> **Note:** This format is available in Terraform 0.12 and later. -The JSON representation of a Terraform Planfile or Statefile is generated by running [`terraform show -json $filename`](/docs/commands/show.html) (if `$filename` is omitted, terraform will output the json representation of the current state). +When Terraform plans changes, it prints a human-readable summary to the terminal. It can also, when run with `-out=`, write a much more detailed binary plan file, which can later be used to apply those changes. -## Common "values" Representation +Since the format of plan files isn't suited for use with external tools (and likely never will be), Terraform can output a machine-readable JSON representation of a plan file's changes. It can also convert state files to the same format, to simplify data loading and provide better long-term compatibility. -The "values" object, described here, is used in the "state" and "plan" sections to describe current state (which is always complete) and planned state (which will omit values not known until apply) values respectively. +Use `terraform show -json ` to generate a JSON representation of a plan or state file. See [the `terraform show` documentation](/docs/commands/show.html) for more details. -The following example illustrates the structure of the common ``: +-> **Note:** The JSON output format is experimental and subject to change. A `"format_version"` key is included in the output. The minor version portion will be incremented for compatible additions to the output, and the major version portion will be incremented for any format changes which require changes for correct processing. + +## Format Summary + +The following sections describe the JSON output format by example, using a pseudo-JSON notation. + +Important elements are described with comments, which are prefixed with `//`. + +To avoid excessive repetition, we've split the complete format into several discrete sub-objects, described under separate headers. References wrapped in angle brackets (like ``) are placeholders which, in the real output, would be replaced by an instance of the specified sub-object. + +The JSON output format consists of the following objects and sub-objects: + +- [State Representation](#state-representation) — The complete top-level object returned by `terraform show -json `. +- [Plan Representation](#plan-representation) — The complete top-level object returned by `terraform show -json `. +- [Values Representation](#values-representation) — A sub-object of both plan and state output that describes current state or planned state. +- [Configuration Representation](#configuration-representation) — A sub-object of plan output that describes a parsed Terraform configuration. + - [Expression Representation](#expression-representation) — A sub-object of a configuration representation that describes an unevaluated expression. + - [Expressions Representation](#expressions-representation) — A sub-object of a configuration representation that describes the contents of a block that includes expressions. +- [Change Representation](#change-representation) — A sub-object of plan output that describes planned changes to an object. + +## State Representation + +Because state does not currently have any significant metadata not covered by the common values representation ([described below](#values-representation)), the `` is straightforward: + +```javascript +{ + // "values" is a values representation object + // derived from the values in the state. Because the state + // is always fully known, this is always complete. + "values": + + "terraform_version": "version.string" +} +``` + +The extra wrapping object here will allow for any extension we may need to add in future versions of this format. + +## Plan Representation + +A plan consists of a prior state, the configuration that is being applied to that state, and the set of changes Terraform plans to make to achieve that. + +For ease of consumption by callers, the plan representation includes a partial representation of the values in the final state (using a [value representation](#value-representation)), allowing callers to easily analyze the planned outcome using similar code as for analyzing the prior state. + +```javascript +{ + // "prior_state" is a representation of the state that the configuration is + // being applied to, using the state representation described above. + "prior_state": , + + // "config" is a representation of the configuration being applied to the + // prior state, using the configuration representation described above. + "config": , + + // "planned_values" is a description of what is known so far of the outcome in + // the standard value representation, with any as-yet-unknown values omitted. + "planned_values": , + + // "proposed_unknown" is a representation of the attributes, including any + // potentially-unknown attributes. Each value is replaced with "true" or + // "false" depending on whether it is known in the proposed plan. + "proposed_unknown": , + + // "variables" is a representation of all the variables provided for the given + // plan. This is structured as a map similar to the output map so we can add + // additional fields in later. + "variables": { + "varname": { + "value": "varvalue" + }, + }, + + // "changes" is a description of the individual change actions that Terraform + // plans to use to move from the prior state to a new state matching the + // configuration. + "resource_changes": [ + // Each element of this array describes the action to take + // for one instance object. All resources in the + // configuration are included in this list. + { + // "address" is the full absolute address of the resource instance this + // change applies to, in the same format as addresses in a value + // representation + "address": "module.child.aws_instance.foo[0]", + + // "module_address", if set, is the module portion of the above address. + // Omitted if the instance is in the root module. + "module_address": "module.child", + + // "mode", "type", "name", and "index" have the same meaning as in a + // value representation. + "mode": "managed", + "type": "aws_instance", + "name": "foo", + "index": 0, + + // "deposed", if set, indicates that this action applies to a "deposed" + // object of the given instance rather than to its "current" object. + // Omitted for changes to the current object. "address" and "deposed" + // together form a unique key across all change objects in a particular + // plan. The value is an opaque key representing the specific deposed + // object. + "deposed": "deadbeef", + + // "change" describes the change that will be made to the indicated + // object. The is detailed in a section below. + "change": + } + ], + + // "output_changes" describes the planned changes to the output values of the + // root module. + "output_changes": { + // Keys are the defined output value names. + "foo": { + + // "change" describes the change that will be made to the indicated output + // value, using the same representation as for resource changes except + // that the only valid actions values are: + // ["create"] + // ["update"] + // ["delete"] + // In the Terraform CLI 0.12.0 release, Terraform is not yet fully able to + // track changes to output values, so the actions indicated may not be + // fully accurate, but the "after" value will always be correct. + "change": , + } + } +} +``` + +This overall plan structure, fully expanded, is what will be printed by the `terraform show -json ` command. + +## Values Representation + +A values representation is used in both state and plan output to describe current state (which is always complete) and planned state (which omits values not known until apply). + +The following example illustrates the structure of a ``: ```javascript { @@ -119,34 +243,17 @@ The following example illustrates the structure of the common `` is straightforward: - -```javascript -{ - // "values" is an object in the common values representation - // derived from the values in the state. Because the state - // is always fully-known, this is always complete. - "values": - - "terraform_version": "version.string" -} -``` - -The extra wrapping object here will allow for any extension we may need to add in future versions of this format. +The intent of this structure is to give a caller access to a similar level of detail as is available to expressions within the configuration itself. This common representation is not suitable for all use-cases because it loses information compared to the data structures it is built from. For more complex needs, use the more elaborate changes and configuration representations. ## Configuration Representation Configuration is the most complicated structure in Terraform, since it includes unevaluated expression nodes and other complexities. -Because the configuration models are produced at a stage prior to expression evaluation, it is not possible to produce a common values representation for configuration. Instead, we describe the physical structure of the configuration, giving access to constant values where possible and allowing callers to analyze any references to other objects that are present, in the ``: +Because the configuration models are produced at a stage prior to expression evaluation, it is not possible to produce a values representation for configuration. Instead, we describe the physical structure of the configuration, giving access to constant values where possible and allowing callers to analyze any references to other objects that are present: ```javascript { @@ -201,7 +308,7 @@ Because the configuration models are produced at a stage prior to expression eva "address": "aws_instance.example", // "mode", "type", and "name" have the same meaning as for the resource - // portion of the common value representation. + // portion of a value representation. "mode": "managed", "type": "aws_instance", "name": "example", @@ -279,13 +386,13 @@ Because the configuration models are produced at a stage prior to expression eva ### Expression Representation -Each unparsed expression in the configuration is represented with an `` object with the following structure: +Each unevaluated expression in the configuration is represented with an `` object with the following structure: ```javascript { // "constant_value" is set only if the expression contains no references to // other objects, in which case it gives the resulting constant value. This is - // mapped as for the individual values in the common value representation. + // mapped as for the individual values in a value representation. "constant_value": "hello", // Alternatively, "references" will be set to a list of references in the @@ -340,99 +447,6 @@ In some cases, it is the entire content of a block (possibly after certain speci For now we expect callers to just hard-code assumptions about the schemas of particular resource types in order to process these expression representations. In a later release we will add new inspection commands to return machine-readable descriptions of the schemas themselves, allowing for more generic handling in programs such as visualization tools. -## Representation of Plan - -A plan consists of a prior state, the configuration that is being applied to that state, and the set of changes Terraform plans to make to achieve that. For ease of consumption by callers, our representation of plans will additionally include a partial representation of the values in the final state using the common value representation, allowing callers to easily analyze the planned outcome using similar code as for analyzing the prior state. - -```javascript -{ - // "prior_state" is a representation of the state that the configuration is - // being applied to, using the state representation described above. - "prior_state": , - - // "config" is a representation of the configuration being applied to the - // prior state, using the configuration representation described above. - "config": , - - // "planned_values" is a description of what is known so far of the outcome in - // the standard value representation, with any as-yet-unknown values omitted. - "planned_values": , - - // "proposed_unknown" is a representation of the attributes, including any - // potentially-unknown attributes. Each value is replaced with "true" or - // "false" depending on whether it is known in the proposed plan. - "proposed_unknown": , - - // "variables" is a representation of all the variables provided for the given - // plan. This is structured as a map similar to the output map so we can add - // additional fields in later. - "variables": { - "varname": { - "value": "varvalue" - }, - }, - - // "changes" is a description of the individual change actions that Terraform - // plans to use to move from the prior state to a new state matching the - // configuration. - "resource_changes": [ - // Each element of this array describes the action to take - // for one instance object. All resources in the - // configuration are included in this list. - { - // "address" is the full absolute address of the resource instance this - // change applies to, in the same format as addresses in the common value - // representation - "address": "module.child.aws_instance.foo[0]", - - // "module_address", if set, is the module portion of the above address. - // Omitted if the instance is in the root module. - "module_address": "module.child", - - // "mode", "type", "name", and "index" have the same meaning as in the - // common value representation. - "mode": "managed", - "type": "aws_instance", - "name": "foo", - "index": 0, - - // "deposed", if set, indicates that this action applies to a "deposed" - // object of the given instance rather than to its "current" object. - // Omitted for changes to the current object. "address" and "deposed" - // together form a unique key across all change objects in a particular - // plan. The value is an opaque key representing the specific deposed - // object. - "deposed": "deadbeef", - - // "change" describes the change that will be made to the indicated - // object. The is detailed in a section below. - "change": - } - ], - - // "output_changes" describes the planned changes to the output values of the - // root module. - "output_changes": { - // Keys are the defined output value names. - "foo": { - - // "change" describes the change that will be made to the indicated output - // value, using the same representation as for resource changes except - // that the only valid actions values are: - // ["create"] - // ["update"] - // ["delete"] - // In the Terraform CLI 0.12.0 release, Terraform is not yet fully able to - // track changes to output values, so the actions indicated may not be - // fully accurate, but the "after" value will always be correct. - "change": , - } - } -} -``` - -This overall plan structure, fully expanded, is what will be printed by the `terraform show -json ` command. - ## Change Representation A `` describes the change that will be made to the indicated object. @@ -463,4 +477,4 @@ A `` describes the change that will be made to the indica "before": , "after": } -``` \ No newline at end of file +```