website: update getting started guide for TF 0.3 features

Author: mitchellh

website/source/intro/getting-started/build.html.md

@@ -170,10 +170,10 @@ what it is managing. This file must be saved and distributed
 to anyone who might run Terraform. We recommend simply putting it
 into version control, since it generally isn't too large.
 
-You can inspect the state using `terraform show terraform.tfstate`:
+You can inspect the state using `terraform show`:
 
 ```
-$ terraform show terraform.tfstate
+$ terraform show
 aws_instance.example:
   id = i-e60900cd
   ami = ami-408c7f28

website/source/intro/getting-started/destroy.html.md

@@ -18,49 +18,43 @@ destroying is a useful action.
 
 ## Plan
 
-For Terraform to destroy our infrastructure, we need to ask
-Terraform to generate a destroy execution plan. This is a special
-kind of execution plan that only destroys all Terraform-managed
-infrastructure, and doesn't create or update any components.
+Before destroying our infrastructure, we can use the plan command
+to see what resources Terraform will destroy.
 
 ```
-$ terraform plan -destroy -out=terraform.tfplan
+$ terraform plan -destroy
 ...
 
 - aws_instance.example
 ```
 
-The plan command is given two new flags.
+With the `-destroy` flag, we're asking Terraform to plan a destroy,
+where all resources under Terraform management are destroyed. You can
+use this output to verify exactly what resources Terraform is managing
+and will destroy.
 
-The first flag, `-destroy` tells Terraform to create an execution
-plan to destroy the infrastructure. You can see in the output that
-our one EC2 instance will be destroyed.
+## Destroy
 
-The second flag, `-out` tells Terraform to save the execution plan
-to a file. We haven't seen this before, but it isn't limited to
-only destroys. Any plan can be saved to a file. Terraform can then
-apply a plan, ensuring that only exactly the plan you saw is executed.
-For destroys, you must save into a plan, since there is no way to
-tell `apply` to destroy otherwise.
-
-## Apply
-
-Let's apply the destroy:
+Let's destroy the infrastructure now:
 
 ```
-$ terraform apply terraform.tfplan
+$ terraform destroy
 aws_instance.example: Destroying...
 
 Apply complete! Resources: 0 added, 0 changed, 1 destroyed.
 
 ...
 ```
 
-Done. Terraform destroyed our one instance, and if you run a
-`terraform show`, you'll see that the state file is now empty.
+The `terraform destroy` command should ask you to verify that you
+really want to destroy the infrastructure. Terraform only accepts the
+literal "yes" as an answer as a safety mechanism. Once entered, Terraform
+will go through and destroy the infrastructure.
 
-For this command, we gave an argument to `apply` for the first
-time. You can give apply a specific plan to execute.
+Just like with `apply`, Terraform is smart enough to determine what order
+things should be destroyed. In our case, we only had one resource, so there
+wasn't any ordering necessary. But in more complicated cases with multiple
+resources, Terraform will destroy in the proper order.
 
 ## Next
 

website/source/intro/getting-started/modules.html.md

@@ -0,0 +1,135 @@
+---
+layout: "intro"
+page_title: "Modules"
+sidebar_current: "gettingstarted-modules"
+---
+
+# Modules
+
+Up to this point, we've been configuring Terraform by editing Terraform
+configurations directly. As our infrastructure grows, this practice has a few
+key problems: a lack of organization, a lack of reusability, and difficulties
+in management for teams.
+
+_Modules_ in Terraform are self-contained packages of Terraform configurations
+that are managed as a group. Modules are used to create reusable components,
+improve organization, and to treat pieces of infrastructure as a black box.
+
+This section of the getting started will cover the basics of using modules.
+Writing modules is covered in more detail in the
+[modules documentation](/docs/modules/index.html).
+
+<div class="alert alert-block alert-warning">
+<p>
+<strong>Warning:</strong> The examples on this page are
+<em>not eligible</em> for the
+AWS
+<a href="http://aws.amazon.com/free/">free-tier</a>. Do not execute
+the examples on this page unless you're willing to spend a small
+amount of money.
+</p>
+</div>
+
+## Using Modules
+
+If you have any instances running from prior steps in the getting
+started guide, use `terraform destroy` to destroy them, and remove all
+configuration files.
+
+As an example, we're going to use the
+[Consul Terraform module](#)
+which will setup a complete [Consul](http://www.consul.io) cluster
+for us.
+
+Create a configuration file with the following contents:
+
+```
+module "consul" {
+	source = "github.com/hashicorp/consul/terraform/aws"
+
+	key_name = "AWS SSH KEY NAME"
+	key_path = "PATH TO ABOVE PRIVATE KEY"
+	region = "AWS REGION"
+	servers = "3"
+}
+```
+
+The `module` block tells Terraform to create and manage a module. It is
+very similar to the `resource` block. It has a logical name -- in this
+case "consul" -- and a set of configurations.
+
+The `source` configuration is the only mandatory key for modules. It tells
+Terraform where the module can be retrieved. Terraform automatically
+downloads and manages modules for you. For our example, we're getting the
+module directly from GitHub. Terraform can retrieve modules from a variety
+of sources including Git, Mercurial, HTTP, and file paths.
+
+The other configurations are parameters to our module. Please fill them
+in with the proper values.
+
+## Planning and Apply Modules
+
+With the modules downloaded, we can now plan and apply it. If you run
+`terraform plan`, you should see output similar to below:
+
+```
+$ terraform plan
+TODO
+```
+
+As you can see, the module is treated like a black box. In the plan, Terraform
+shows the module managed as a whole. It does not show what resources within
+the module will be created. If you care, you can see that by specifying
+a `-module-depth=-1` flag.
+
+Next, run `terraform apply` to create the module. Note that as we warned above,
+the resources this module creates are outside of the AWS free tier, so this
+will have some cost associated with it.
+
+```
+$ terraform apply
+TODO
+```
+
+After a few minutes, you'll have a three server Consul cluster up and
+running! Without any knowledge of how Consul works, how to install Consul,
+or how to configure Consul into a cluster, you've created a real cluster in
+just minutes.
+
+## Module Outputs
+
+Just as we parameterized the module with configurations such as
+`servers` above, modules can also output information (just like a resource).
+
+You'll have to reference the module's code or documentation to know what
+outputs it supports for now, but for this guide we'll just tell you that the
+Consul module has an output named `server_address` that has the address of
+one of the Consul servers that was setup.
+
+To reference this, we'll just put it into our own output variable. But this
+value could be used anywhere: in another resource, to configure another
+provider, etc.
+
+```
+output "consul_address" {
+	value = "${module.consul.server_address}"
+}
+```
+
+The syntax for referencing module outputs should be very familiar. The
+syntax is `${module.NAME.ATTRIBUTE}`. The `NAME` is the logical name
+we assigned earlier, and the `ATTRIBUTE` is the output attribute.
+
+If you run `terraform apply` again, Terraform should make no changes, but
+you'll now see the "consul\_address" output with the address of our Consul
+server.
+
+## Next
+
+For more information on modules, the types of sources supported, how
+to write modules, and more, read the in depth
+[module documentation](/docs/modules/index.html).
+
+We've now concluded the getting started guide, however
+there are a number of [next steps](/intro/getting-started/next-steps.html)
+to get started with Terraform.

website/source/intro/getting-started/outputs.html.md

@@ -75,6 +75,6 @@ You now know how to parameterize configurations with input
 variables, extract important data using output variables,
 and bootstrap resources using provisioners.
 
-We've now concluded the getting started guide, however
-there are a number of [next steps](/intro/getting-started/next-steps.html)
-to get started with Terraform.
+Next, we're going to take a look at
+[how to use modules](/intro/getting-started/modules.html), a useful
+abstraction to organization and reuse Terraform configurations.

website/source/intro/getting-started/provision.html.md

@@ -67,8 +67,8 @@ aws_eip.ip: Creating...
 Apply complete! Resources: 2 added, 0 changed, 0 destroyed.
 ```
 
-Terraform currently doesn't output anything to indicate the provisioners
-have run. This is going to be fixed soon. However, we can verify
+Terraform will output anything from provisioners to the console,
+but in this case there is no output. However, we can verify
 everything worked by looking at the "file.txt" file:
 
 ```

website/source/intro/getting-started/variables.html.md

@@ -51,9 +51,14 @@ the AWS provider with the given variables.
 
 ## Assigning Variables
 
-There are two ways to assign variables.
+There are three ways to assign variables.
 
-First, you can set it directly on the command-line with the
+First, if you execute `terraform plan` or apply without doing
+anythiing, Terraform will ask you to input the variables interactively.
+These variables are not saved, but provides a nice user experience for
+getting started with Terraform.
+
+For another option, you can set it directly on the command-line with the
 `-var` flag. Any command in Terraform that inspects the configuration
 accepts this flag, such as `apply`, `plan`, and `refresh`:
 
@@ -64,8 +69,12 @@ $ terraform plan \
 ...
 ```
 
-Second, you can create a file and assign variables directly. Create
-a file named "terraform.tfvars" with the following contents:
+Once again, setting variables this way will not save them, and they'll
+have to be input repeatedly as commands are executed.
+
+The third way, and the way to persist variable values, is to create
+a file and assign variables within this file. Create a file named
+"terraform.tfvars" with the following contents:
 
 ```
 access_key = "foo"
@@ -75,8 +84,8 @@ secret_key = "bar"
 If a "terraform.tfvars" file is present in the current directory,
 Terraform automatically loads it to populate variables. If the file is
 named something else, you can use the `-var-file` flag directly to
-specify a file. Like configuration files, variable files can also be
-JSON.
+specify a file. These files are the same syntax as Terraform configuration
+files. And like Terraform configuration files, these files can also be JSON.
 
 We recommend using the "terraform.tfvars" file, and ignoring it from
 version control.

website/source/layouts/intro.erb

@@ -66,6 +66,10 @@
 					<a href="/intro/getting-started/outputs.html">Output Variables</a>
 					</li>
 
+					<li<%= sidebar_current("gettingstarted-modules") %>>
+					<a href="/intro/getting-started/modules.html">Modules</a>
+					</li>
+
 					<li<%= sidebar_current("gettingstarted-nextsteps") %>>
 					<a href="/intro/getting-started/next-steps.html">Next Steps</a>
 					</li>