From 9ccc8aebf1a782c8d280bd779431034cf7d72183 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Mon, 13 Oct 2014 11:57:43 -0700 Subject: [PATCH] website: update getting started guide for TF 0.3 features --- .../intro/getting-started/build.html.md | 4 +- .../intro/getting-started/destroy.html.md | 42 +++--- .../intro/getting-started/modules.html.md | 135 ++++++++++++++++++ .../intro/getting-started/outputs.html.md | 6 +- .../intro/getting-started/provision.html.md | 4 +- .../intro/getting-started/variables.html.md | 21 ++- website/source/layouts/intro.erb | 4 + 7 files changed, 179 insertions(+), 37 deletions(-) create mode 100644 website/source/intro/getting-started/modules.html.md diff --git a/website/source/intro/getting-started/build.html.md b/website/source/intro/getting-started/build.html.md index a75bf8f69..e2f41f839 100644 --- a/website/source/intro/getting-started/build.html.md +++ b/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 diff --git a/website/source/intro/getting-started/destroy.html.md b/website/source/intro/getting-started/destroy.html.md index 0fb0129c7..9c0d21ad3 100644 --- a/website/source/intro/getting-started/destroy.html.md +++ b/website/source/intro/getting-started/destroy.html.md @@ -18,37 +18,27 @@ 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. @@ -56,11 +46,15 @@ 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 diff --git a/website/source/intro/getting-started/modules.html.md b/website/source/intro/getting-started/modules.html.md new file mode 100644 index 000000000..b9d63abce --- /dev/null +++ b/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). + +
+

+Warning: The examples on this page are +not eligible for the +AWS +free-tier. Do not execute +the examples on this page unless you're willing to spend a small +amount of money. +

+
+ +## 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. diff --git a/website/source/intro/getting-started/outputs.html.md b/website/source/intro/getting-started/outputs.html.md index 82e55a77d..9eb319dd7 100644 --- a/website/source/intro/getting-started/outputs.html.md +++ b/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. diff --git a/website/source/intro/getting-started/provision.html.md b/website/source/intro/getting-started/provision.html.md index 188570b0c..0aeb497f8 100644 --- a/website/source/intro/getting-started/provision.html.md +++ b/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: ``` diff --git a/website/source/intro/getting-started/variables.html.md b/website/source/intro/getting-started/variables.html.md index e2c755686..d9bb5f6a1 100644 --- a/website/source/intro/getting-started/variables.html.md +++ b/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. diff --git a/website/source/layouts/intro.erb b/website/source/layouts/intro.erb index 2a159e6a2..de73e9bfd 100644 --- a/website/source/layouts/intro.erb +++ b/website/source/layouts/intro.erb @@ -66,6 +66,10 @@ Output Variables + > + Modules + + > Next Steps