From 6ced245898469794bc3fbce2e4b9179331af485d Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Thu, 24 Jul 2014 16:28:20 -0700 Subject: [PATCH] website: configuration --- .../docs/configuration/interpolation.html.md | 42 +++++++++++++++ .../source/docs/configuration/load.html.md | 8 ++- .../docs/configuration/override.html.md | 52 +++++++++++++++++++ .../source/docs/configuration/syntax.html.md | 5 ++ website/source/layouts/docs.erb | 4 ++ 5 files changed, 109 insertions(+), 2 deletions(-) create mode 100644 website/source/docs/configuration/interpolation.html.md create mode 100644 website/source/docs/configuration/override.html.md diff --git a/website/source/docs/configuration/interpolation.html.md b/website/source/docs/configuration/interpolation.html.md new file mode 100644 index 0000000000..d2de8f35c6 --- /dev/null +++ b/website/source/docs/configuration/interpolation.html.md @@ -0,0 +1,42 @@ +--- +layout: "docs" +page_title: "Interpolation Syntax" +sidebar_current: "docs-config-interpolation" +--- + +# Interpolation Syntax + +Embedded within strings in Terraform, whether you're using the +Terraform syntax or JSON syntax, you can interpolate other values +into strings. These interpolations are wrapped in `${}`, such as +`${var.foo}`. + +The interpolation syntax is powerful and allows you to reference +variables, attributes of resources, call functions, etc. + +To reference variables, use the `var.` prefix followed by the +variable name. For example, `${var.foo}` will interpolate the +`foo` variable value. If the variable is a mapping, then you +can reference static keys in the map with the syntax +`var.MAP.KEY`. For example, `${var.amis.us-east-1}` would +get the value of the `us-east-1` key within the `amis` variable +that is a mapping. + +To reference attributes of other resources, the syntax is +`TYPE.NAME.ATTRIBUTE`. For example, `${aws_instance.web.id}` +will interpolate the ID attribute from the "aws\_instance" +resource named "web". + +Finally, Terraform ships with built-in functions. Functions +are called with the syntax `name(arg, arg2, ...)`. For example, +to read a file: `${file("path.txt")}`. The built-in functions +are documented below. + +## Built-in Functions + +The supported built-in functions are: + + * `file(path)` - Reads the contents of a file into the string. + + * `lookup(map, key)` - Performs a dynamic lookup into a mapping + variable. diff --git a/website/source/docs/configuration/load.html.md b/website/source/docs/configuration/load.html.md index 66ed02b9a1..7966e89f78 100644 --- a/website/source/docs/configuration/load.html.md +++ b/website/source/docs/configuration/load.html.md @@ -8,9 +8,13 @@ sidebar_current: "docs-config-load" When invoking any command that loads the Terraform configuration, Terraform loads all configuration files within the directory -specified in alphabetical order. The flies loaded must end in +specified in alphabetical order. + +The files loaded must end in either `.tf` or `.tf.json` to specify the format that is in use. -Otherwise, the files are ignored. +Otherwise, the files are ignored. Multiple file formats can +be present in the same directory; it is okay to have one Terraform +configuration file be Terraform syntax and another be JSON. [Override](/docs/configuration/override.html) files are the exception, as they're loaded after all non-override diff --git a/website/source/docs/configuration/override.html.md b/website/source/docs/configuration/override.html.md new file mode 100644 index 0000000000..cb77da49d5 --- /dev/null +++ b/website/source/docs/configuration/override.html.md @@ -0,0 +1,52 @@ +--- +layout: "docs" +page_title: "Overrides" +sidebar_current: "docs-config-override" +--- + +# Overrides + +Terraform loads all configuration files within a directory and +appends them together. Terraform also has a concept of _overrides_, +a way to create files that are loaded last and _merged_ into your +configuration, rather than appended. + +Overrides have a few use cases: + + * Machines (tools) can create overrides to modify Terraform + behavior without having to edit the Terraform configuration + tailored to human readability. + + * Temporary modifications can be made to Terraform configurations + without having to modify the configuration itself. + +Overrides names must be `override` or end in `_override`, excluding +the extension. Examples of valid override files are `override.tf`, +`override.tf.json`, `temp_override.tf`. + +Override files are loaded last in alphabetical order. + +Override files can be in Terraform syntax or JSON, just like non-override +Terraform configurations. + +## Example + +If you have a Terraform configuration `example.tf` with the contents: + +``` +resource "aws_instance" "web" { + ami = "ami-1234567" +} +``` + +And you created a file `override.tf` with the contents: + +``` +resource "aws_instance" "web" { + ami = "foo" +} +``` + +Then the AMI for the one resource will be replaced with "foo". Note +that the override syntax can be Terraform syntax or JSON. You can +mix and match syntaxes without issue. diff --git a/website/source/docs/configuration/syntax.html.md b/website/source/docs/configuration/syntax.html.md index 6d930de32e..c162d2ec67 100644 --- a/website/source/docs/configuration/syntax.html.md +++ b/website/source/docs/configuration/syntax.html.md @@ -47,6 +47,11 @@ Basic bullet point reference: * Strings are in double-quotes. + * Strings can interpolate other values using syntax wrapped + in `${}`, such as `${var.foo}`. The full syntax for interpolation + is + [documented here](/docs/configuration/interpolation.html). + * Numbers are assumed to be base 10. If you prefix a number with `0x`, it is treated as a hexadecimal number. diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index c5125efb3c..2387b8544c 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -17,6 +17,10 @@ Configuration Syntax + > + Interpolation Syntax + + > Overrides