From cbb08b0708e8e6fb19d80df188f9653d464c6840 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Wed, 23 Jul 2014 19:06:37 -0700 Subject: [PATCH] website: resource dependencies --- .../getting-started/dependencies.html.md | 165 ++++++++++++++++++ website/source/layouts/intro.erb | 8 +- 2 files changed, 169 insertions(+), 4 deletions(-) create mode 100644 website/source/intro/getting-started/dependencies.html.md diff --git a/website/source/intro/getting-started/dependencies.html.md b/website/source/intro/getting-started/dependencies.html.md new file mode 100644 index 000000000..583f5ed09 --- /dev/null +++ b/website/source/intro/getting-started/dependencies.html.md @@ -0,0 +1,165 @@ +--- +layout: "intro" +page_title: "Resource Dependencies" +sidebar_current: "gettingstarted-deps" +--- + +# Resource Dependencies + +In this page, we're going to introduce resource dependencies, +where we'll not only see a configuration with multiple resources +for the first time, but also scenarios where resource parameters +use information from other resources. + +Up to this point, our example has only contained a single resource. +Real infrastructure has a diverse set of resources and resource +types. Terraform configurations can contain multiple resources, +multiple resource types, and these types can even span multiple +providers. + +On this page, we'll show a basic example of multiple resources +and how to reference the attributes of other resources to configure +subsequent resources. + +## Assigning an Elastic IP + +We'll improve our configuration by assigning an elastic IP to +the EC2 instance we're managing. Modify your `example.tf` and +add the following: + +``` +resource "aws_eip" "ip" { + instance = "${aws_instance.example.id}" +} +``` + +This should look familiar from the earlier example of adding +an EC2 instance resource, except this time we're building +an "aws\_eip" resource type. This resource type allocates +and associates an +[elastic IP](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html) +to an EC2 instance. + +The only parameter for +[aws\_eip](/docs/providers/aws/r/eip.html) is "instance" which +is the EC2 instance to assign the IP to. For this value, we +use an interpolation to use an attribute from the EC2 instance +we managed earlier. + +The syntax for this interpolation should be straightforward: +it requests the "id" attribute from the "aws\_instance.example" +resource. + +## Plan and Execute + +Run `terraform plan` to view the execution plan. The output +will look something like the following: + +``` +$ terraform plan +... + ++ aws_eip.ip + instance: "" => "${aws_instance.example.id}" + private_ip: "" => "" + public_ip: "" => "" + ++ aws_instance.example + ami: "" => "ami-aa7ab6c2" + availability_zone: "" => "" + instance_type: "" => "t1.micro" + key_name: "" => "" + private_dns: "" => "" + private_ip: "" => "" + public_dns: "" => "" + public_ip: "" => "" + security_groups: "" => "" + subnet_id: "" => "" +``` + +Terraform will create two resources: the instance and the elastic +IP. In the "instance" value for the "aws\_eip", you can see the +raw interpolation is still present. This is because this variable +won't be known until the "aws\_instance" is created. It will be +replaced at apply-time. + +Next, run `terraform apply`. The output will look similar to the +following: + +``` +aws_instance.example: Creating... + ami: "" => "ami-aa7ab6c2" + instance_type: "" => "t1.micro" +aws_eip.ip: Creating... + instance: "" => "i-0e737b25" + +Apply complete! Resources: 2 added, 0 changed, 0 destroyed. +``` + +It is clearer to see from actually running Terraform, but +Terraform creates the EC2 instance before the elastic IP +address. Due to the interpolation earlier where the elastic +IP requires the ID of the EC2 instance, Terraform is able +to infer a dependency, and knows to create the instance +first. + +## Implicit and Explicit Dependencies + +Most dependencies in Terraform are implicit: Terraform is able +to infer dependencies based on usage of attributes of other +resources. + +Using this information, Terraform builds a graph of resources. +This tells Terraform not only what order to create resources, +but also what resources can be created in parallel. In our example, +since the IP address depended on the EC2 instance, they could +not be created in parallel. + +Implicit dependencies work well and are usually all you ever need. +However, you can also specify explicit dependencies with the +`depends_on` parameter which is available on any resource. For example, +we could modify the "aws\_eip" resource to the following, which +effectively does the same thing and is redundant: + +``` +resource "aws_eip" "ip" { + instance = "${aws_instance.example.id}" + depends_on = ["aws_instance.example"] +} +``` + +If you're ever unsure about the dependency chain that Terraform +is creating, you can use the `terraform graph` command to view +the graph. This command outputs a dot-formatted graph which can be +viewed with +[Graphviz](http://www.graphviz.org/). + +## Non-Dependent Resources + +We can now augment the configuration with another EC2 instance. +Because this doesn't rely on any other resource, it can be +created in parallel to everything else. + +``` +resource "aws_instance" "another" { + ami = "ami-aa7ab6c2" + instance_type = "t1.micro" +} +``` + +You can view the graph with `terraform graph` to see that +nothing depends on this and that it will likely be created +in parallel. + +Before moving on, remove this resource from your configuration +and `terraform apply` again to destroy it. We won't use the +second instance anymore in the getting started guide. + +## Next + +In this page you were introduced to both multiple resources +as well as basic resource dependencies and resource attribute +interpolation. + +Moving on, we'll parameterize our configuration for better +shareability and maintainability. diff --git a/website/source/layouts/intro.erb b/website/source/layouts/intro.erb index 664b0e01b..59277fa5b 100644 --- a/website/source/layouts/intro.erb +++ b/website/source/layouts/intro.erb @@ -42,10 +42,6 @@ Destroy Infrastructure - > - Output Variables - - > Resource Dependencies @@ -54,6 +50,10 @@ Input Variables + > + Output Variables + + > Provision