From c8c526d25411a4b41e5dff60b5722d8fa4ba5ec9 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Thu, 24 Jul 2014 15:44:28 -0700 Subject: [PATCH] website: config syntax --- .../source/docs/configuration/syntax.html.md | 122 ++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 website/source/docs/configuration/syntax.html.md diff --git a/website/source/docs/configuration/syntax.html.md b/website/source/docs/configuration/syntax.html.md new file mode 100644 index 000000000..6d930de32 --- /dev/null +++ b/website/source/docs/configuration/syntax.html.md @@ -0,0 +1,122 @@ +--- +layout: "docs" +page_title: "Configuration Syntax" +sidebar_current: "docs-config-syntax" +--- + +# Configuration Syntax + +The syntax of Terraform configurations is custom. It is meant to +strike a balance between human readable and editable as well as being +machine-friendly. For machine-friendliness, Terraform can also +read JSON configurations. For general Terraform configurations, +however, we recommend using the Terraform syntax. + +## Terraform Syntax + +Here is an example of Terraform syntax: + +``` +# An AMI +variable "ami" { + description = "the AMI to use" +} + +/* A multi + line comment. */ +resource "aws_instance" "web" { + ami = "${var.ami}" + count = 2 + source_dest_check = false + + connection { + user = "root" + } +} +``` + +Basic bullet point reference: + + * Single line comments start with `#` + + * Multi-line comments are wrapped with `/*` and `*/` + + * Values are assigned with the syntax of `key = value` (whitespace + doesn't matter). The value can be any primitive: a string, + number, or boolean. + + * Strings are in double-quotes. + + * Numbers are assumed to be base 10. If you prefix a number with + `0x`, it is treated as a hexadecimal number. + + * Numbers can be suffxed with `kKmMgG` for some multiple of 10. + For example: `1k` is equal to `1000`. + + * Numbers can be suffxed with `[kKmMgG]b` for power of 2 multiples, + example: `1kb` is equal to `1024`. + + * Boolean values: `true`, `false`, `on`, `off`, `yes`, `no`. + + * Arrays of primitive types can be made by wrapping it in `[]`. + Example: `["foo", "bar", 42]`. + + * Maps can be made with the `{}` syntax: + `{ "foo": "bar", "bar": "baz" }`. + +In addition to the basics, the syntax supports hierarchies of sections, +such as the "resource" and "variable" in the example above. These +sections are similar to maps, but visually look better. For example, +these are nearly equivalent: + +``` +variable "ami" { + description = "the AMI to use" +} + +# is equal to: + +variable = [{ + "ami": { + "description": "the AMI to use", + } +}] +``` + +Notice that the top visually looks a lot better? By repeating multiple +`variable` sections, it adds the `variable` array. When possible, use +sections since they're visually clearer and more reasily readable. + +## JSON Syntax + +Terraform also supports reading JSON formatted configuration files. +The above example converted to JSON: + +```json +{ + "variable": { + "ami": { + "description": "the AMI to use" + } + }, + + "resource": { + "aws_instance": { + "web": { + "ami": "${var.ami}", + "count": 2, + "source_dest_check": false, + + "connection": { + "user": "root" + } + } + } + } +} +``` + +The conversion should be pretty straightforward and self-documented. + +The downsides of JSON are less human readability and the lack of +comments. Otherwise, the two are completely interoperable.