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

website: fix highlighting and line breaks

This commit is contained in:
Nick Fagerlund 2019-02-20 17:17:04 -08:00
parent 7ba654a8a9
commit f6c5e33c00
1 changed files with 23 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
website/docs/internals/json-format.html.md
View File

@ -8,7 +8,7 @@ description: |-
# 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.
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.
@ -19,16 +19,18 @@ To meet the need for machine consumption of plan data by code outside of Terrafo
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).
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 "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.
The following example illustrates the structure of the common `<values-representation>`:
```
```javascript
{
// "outputs" describes the outputs from the root module. Outputs from
// descendent modules are not available because they are not retained in all
@ -70,7 +72,7 @@ The following example illustrates the structure of the common `<values-represent
// such as the "googlebeta" provider offering "google_compute_instance".
"provider_name": "aws",
// "schema_version" indicates which version of the resource type schema
// "schema_version" indicates which version of the resource type schema
// the "values" property conforms to.
"schema_version": 2,
@ -125,7 +127,7 @@ The intent of this structure is to give a caller access to a similar level of de
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:
```
```javascript
{
// "values" is an object in the common values representation
// derived from the values in the state. Because the state
@ -139,22 +141,23 @@ Because the state does not currently have any significant additional metadata no
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.
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>`:
```
```javascript
{
// "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",
@ -174,7 +177,7 @@ Because the configuration models are produced at a stage prior to expression eva
}
},
// "root_module" describes the root module in the configuration, and serves
// "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": {
@ -188,7 +191,7 @@ Because the configuration models are produced at a stage prior to expression eva
}
},
// "resources" describes the "resource" and "data" blocks in the module
// "resources" describes the "resource" and "data" blocks in the module
// configuration.
"resources": [
{
@ -273,9 +276,10 @@ 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 `<expression-representation>` 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
@ -309,14 +313,14 @@ Each unparsed expression in the configuration is represented with an `<expressio
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:
```
```javascript
{
// 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
// 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>
@ -335,9 +339,10 @@ 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.
@ -427,9 +432,10 @@ A plan consists of a prior state, the configuration that is being applied to tha
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.
```
```javascript
{
// "actions" are the actions that will be taken on the object selected by the
// properties below.