resilien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

website/docs: add detailed documentation for the json serialization of 

terraform plan
This commit is contained in:
Kristin Laemmert 2019-02-01 10:32:10 -08:00
parent f7ab90207c
commit a43004e382
3 changed files with 462 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
command/show.go
View File

@ -186,8 +186,8 @@ Usage: terraform show [options] [path]
Options:
-no-color If specified, output won't contain any color.
-json If specified, output the Terraform plan or state in
a machine-readable form.
-json If specified, output the Terraform plan or state in
a machine-readable form.
`
return strings.TrimSpace(helpText)

2
website/docs/commands/show.html.markdown
View File

@ -30,6 +30,8 @@ path, a json representation of the current state will be shown.
When `terraform show -json` is run with a path to a Terraform plan file, a json
representation of the plan, configuration, and current state will be shown.
The output format is covered in detail in [_JSON Format_](/docs/internals/json-format.html).
## Usage
Usage: `terraform show [options] [path]`

458
website/docs/internals/json-format.html.md Normal file
View File

@ -0,0 +1,458 @@
---
layout: "docs"
page_title: "Internals: JSON 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 `<references>` to indicate how these different portions of the output are combined without excessive repetition.
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).
## Common "values" Representation
The "values" object, described here, is used 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.
The following example illustrates the structure of the common `<values-representation>`:
```
{
// "outputs" describes the outputs from the root module. Outputs from
// descendent modules are not available because they are not retained in all
// of the underlying structures we will build this values representation from.
"outputs": {
"private_ip": {
"value": "192.168.3.2",
"sensitive": false
}
},
// "root_module" describes the resources and child modules in the root module.
"root_module": {
"resources": [
// "address" is the absolute resource address, which callers must consider
// opaque but may do full string comparisons with other address strings or
// pass this verbatim to other Terraform commands that are documented to
// accept absolute resource addresses. The module-local portions of this
// address are extracted in other properties below.
"address": "aws_instance.example[1]",
// "mode" can be "managed", for resources, or "data", for data resources
"mode": "managed",
"type": "aws_instance",
"name": "example",
// If the count or for_each meta-arguments are set for this resource, the
// additional key "index" is present to give the instance index key. This
// is omitted for the single instance of a resource that isn't using count
// or for_each.
"index": 1,
// "provider_name" is the name of the provider that is responsible for
// this resource. This is only the provider name, not a provider
// configuration address, and so no module path nor alias will be
// indicated here. This is included to allow the property "type" to be
// interpreted unambiguously in the unusual situation where a provider
// offers a resource type whose name does not start with its own name,
// such as the "googlebeta" provider offering "google_compute_instance".
"provider_name": "aws",
// "schema_version" indicates which version of the resource type schema
// the "values" property conforms to.
"schema_version": 2,
// "values" is the JSON representation of the attribute values of the
// resource, whose structure depends on the resource type schema. Any
// unknown values are omitted or set to null, making them
// indistinguishable from absent values; callers which need to distinguish
// unknown from unset must use the plan-specific or config-specific
// structures described in later sections.
"values": {
"id": "i-abc123",
"instance_type": "t2.micro",
// etc, etc
}
]
"child_modules": {
// Each entry in "child_modules" has the same structure as the root_module
// object, with the additional "address" property shown below.
{
// "address" is the absolute module address, which callers must treat as
// opaque but may do full string comparisons with other module address
// strings and may pass verbatim to other Terraform commands that are
// documented as accepting absolute module addresses.
"address": "module.child",
// "resources" is the same as in "root_module" above
"resources": [
{
"address": "module.child.aws_instance.foo",
// etc, etc
}
],
// Each module object can optionally have its own
// nested "child_modules", recursively describing the
// full module tree.
"child_modules": [ ... ],
}
]
}
}
```
The translation of attribute and output values is the same intuitive mapping from HCL types to JSON types used by Terraform's jsonencode function. This mapping does lose some information: lists, sets, and tuples all lower to JSON arrays while maps and objects both lower to JSON objects. Unknown values and null values are both treated as absent or null. We assume that consumers of this simplified structure do not need to distinguish these cases; in the rare situation where exact representations are required, the Terraform's native storage file formats can be parsed directly (in a later release, once we make compatibility promises for them).
Only the "current" object for each resource instance is described. "Deposed" objects are not reflected in this structure at all, and so callers that wish to work with these must again use the native storage formats, or (in the case of the plan) refer to the plan-specific "changes" structure that includes changes to deposed objects.
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, the more elaborate plan and configuration data structures, described in later sections, should be used.
## State Representation
Because the state does not currently have any significant additional metadata not covered by the common values representation in the prior section, the `<state-representation>` is straightforward:
```
{
// "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": <values-representation>
"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.
## 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 `<configuration-representation>`:
```
{
// "provider_configs" describes all of the provider configurations throughout
// the configuration tree, flattened into a single map for convenience since
// provider configurations are the one concept in Terraform that can span
// across module boundaries.
"provider_configs": {
// Keys in this map are to be considered opaque by callers, and used just for
// lookups using the "provider_config_key" property in each resource object.
"opaque_provider_ref": {
// "name" is the name of the provider without any alias
"name": "aws",
// "alias" is the alias set for a non-default configuration, or unset for
// a default configuration.
"alias": "foo",
// "module_address" is included only for provider configurations that are
// declared in a descendent module, and gives the opaque address for the
// module that contains the provider configuration.
"module_address": "module.child",
// "expressions" describes the provider-specific content of the
// configuration block, as an expressions representation that will be
// discussed in a subsequent example.
"expressions": <expressions-representation>
}
},
// "root_module" describes the root module in the configuration, and serves
// as the root of a tree of similar objects describing descendent modules.
"root_module": {
// "outputs" describes the output value configurations in the module.
"outputs": {
// Property names here are the output value names
"example": {
"expression": <expression-representation>,
"sensitive": false
}
},
// "resources" describes the "resource" and "data" blocks in the module
// configuration.
"resources": [
{
// "address" is the opaque absolute address for the resource itself.
"address": "aws_instance.example",
// "mode", "type", and "name" have the same meaning as for the resource
// portion of the common value representation.
"mode": "managed",
"type": "aws_instance",
"name": "example",
// "provider_config_key" is the key into "provider_configs" (shown
// above) for the provider configuration that this resource is
// associated with.
"provider_config_key": "blahblahopaque",
// "provisioners" is an optional field which describes any provisioners.
// Connection info will not be included here.
"provisioners": [
{
"type": "local-exec",
// "expressions" describes the provisioner configuration
"expressions": <expressions-representation>
},
],
// "expressions" describes the resource-type-specific content of the
// configuration block.
"expressions": <expressions-representation>,
// "schema_version" is the schema version number indicated by the
// provider for the type-specific arguments described in "expressions".
"schema_version": 2,
// "count_expression" and "for_each_expression" describe the expressions
// given for the corresponding meta-arguments in the resource
// configuration block. These are omitted if the corresponding argument
// isn't set.
"count_expression": <expression-representation>,
"for_each_expression": <expression-representation>
},
],
// "module_calls" describes the "module" blocks in the module. During
// evaluation, a module call with count or for_each may expand to multiple
// module instances, but in configuration only the block itself is
// represented.
"module_calls": {
// Key is the module call name chosen in the configuration.
"child": {
// "resolved_source" is the resolved source address of the module, after
// any normalization and expansion. This could be either a
// go-getter-style source address or a local path starting with "./" or
// "../". If the user gave a registry source address then this is the
// final location of the module as returned by the registry, after
// following any redirect indirection.
"resolved_source": "./child"
// "expressions" describes the expressions for the arguments within the
// block that correspond to input variables in the child module.
"expressions": <expressions-representation>,
// "count_expression" and "for_each_expression" describe the expressions
// given for the corresponding meta-arguments in the module
// configuration block. These are omitted if the corresponding argument
// isn't set.
"count_expression": <expression-representation>,
"for_each_expression": <expression-representation>,
// "module" is a representation of the configuration of the child module
// itself, using the same structure as the "root_module" object,
// recursively describing the full module tree.
"module": <module-config-representation>,
}
}
}
}
```
### Expression Representation
Each unparsed expression in the configuration is represented with an `<expression-representation>` object with the following structure:
```
{
// "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.
"constant_value": "hello",
// Alternatively, "references" will be set to a list of references in the
// expression. Multi-step references will be unwrapped and duplicated for each
// significant traversal step, allowing callers to more easily recognize the
// objects they care about without attempting to parse the expressions.
// Callers should only use string equality checks here, since the syntax may
// be extended in future releases.
"references": [
"data.template_file.foo[1].vars[\"baz\"]",
"data.template_file.foo[1].vars", // implied by previous
"data.template_file.foo[1]", // implied by previous
"data.template_file.foo", // implied by previous
"module.foo.bar",
"module.foo", // implied by the previous
"var.example[0]",
"var.example", // implied by the previous
// Partial references like "data" and "module" are not included, because
// Terraform considers "module.foo" to be an atomic reference, not an
// attribute access.
]
}
```
### Expressions Representation
In some cases, it is the entire content of a block (possibly after certain special arguments have already been handled and removed) that must be represented. For that, we have an `<expressions-representation>` structure:
```
{
// Attribute arguments are mapped directly with the attribute name as key and
// an <expression-representation> as value.
"ami": <expression-representation>,
"instance_type": <expression-representation>,
// Nested block arguments are mapped as either a single nested
// <expressions-representation> or an array object of these, depending on the
// block nesting mode chosen in the schema.
// - "single" nesting is a direct <expressions-representation>
// - "list" and "set" produce arrays
// - "map" produces an object
"root_block_device": <expression-representation>,
"ebs_block_device": [
<expression-representation>
],
"potential_future_map_block": {
"foo": <expression-representation>
}
}
```
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.
```
{
// "prior_state" is a representation of the state that the configuration is
// being applied to, using the state representation described above.
"prior_state": <state-representation>,
// "config" is a representation of the configuration being applied to the
// prior state, using the configuration representation described above.
"config": <config-representation>,
// "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": <values-representation>,
// "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": <values-representation>,
// "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 <change-representation> is detailed in a section below.
"change": <change-representation>
}
],
// "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": <change-representation>,
}
}
}
```
This overall plan structure, fully expanded, is what will be printed by the `terraform show -json <planfile>` command.
## Change Representation
A `<change-representation>` describes the change that will be made to the indicated object.
```
{
// "actions" are the actions that will be taken on the object selected by the
// properties below.
// Valid actions values are:
// ["no-op"]
// ["create"]
// ["read"]
// ["update"]
// ["delete", "create"]
// ["create", "delete"]
// ["delete"]
// The two "replace" actions are represented in this way to allow callers to
// e.g. just scan the list for "delete" to recognize all three situations
// where the object will be deleted, allowing for any new deletion
// combinations that might be added in future.
"actions": ["update"]
// "before" and "after" are representations of the object value both before
// and after the action. For ["create"] and ["delete"] actions, either
// "before" or "after" is unset (respectively). For ["no-op"], the before and
// after values are identical. The "after" value will be incomplete if there
// are values within it that won't be known until after apply.
"before": <value-representation>,
"after": <value-representation>
}
```