website: config syntax

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.