github.com/CodeherentUK/terraform@v0.11.10/website/intro/getting-started/build.html.md (about) 1 --- 2 layout: "intro" 3 page_title: "Build Infrastructure" 4 sidebar_current: "gettingstarted-build" 5 description: |- 6 With Terraform installed, let's dive right into it and start creating some infrastructure. 7 --- 8 9 # Build Infrastructure 10 11 With Terraform installed, let's dive right into it and start creating 12 some infrastructure. 13 14 We'll build infrastructure on 15 [AWS](https://aws.amazon.com) for the getting started guide 16 since it is popular and generally understood, but Terraform 17 can [manage many providers](/docs/providers/index.html), 18 including multiple providers in a single configuration. 19 Some examples of this are in the 20 [use cases section](/intro/use-cases.html). 21 22 If you don't have an AWS account, 23 [create one now](https://aws.amazon.com/free/). 24 For the getting started guide, we'll only be using resources 25 which qualify under the AWS 26 [free-tier](https://aws.amazon.com/free/), 27 meaning it will be free. 28 If you already have an AWS account, you may be charged some 29 amount of money, but it shouldn't be more than a few dollars 30 at most. 31 32 ~> **Warning!** If you're not using an account that qualifies under the AWS 33 [free-tier](https://aws.amazon.com/free/), you may be charged to run these 34 examples. The most you should be charged should only be a few dollars, but 35 we're not responsible for any charges that may incur. 36 37 ## Configuration 38 39 The set of files used to describe infrastructure in Terraform is simply 40 known as a Terraform _configuration_. We're going to write our first 41 configuration now to launch a single AWS EC2 instance. 42 43 The format of the configuration files is 44 [documented here](/docs/configuration/index.html). 45 Configuration files can 46 [also be JSON](/docs/configuration/syntax.html), but we recommend only using JSON when the 47 configuration is generated by a machine. 48 49 The entire configuration is shown below. We'll go over each part 50 after. Save the contents to a file named `example.tf`. Verify that 51 there are no other `*.tf` files in your directory, since Terraform 52 loads all of them. 53 54 ```hcl 55 provider "aws" { 56 access_key = "ACCESS_KEY_HERE" 57 secret_key = "SECRET_KEY_HERE" 58 region = "us-east-1" 59 } 60 61 resource "aws_instance" "example" { 62 ami = "ami-2757f631" 63 instance_type = "t2.micro" 64 } 65 ``` 66 67 ~> **Note**: The above configuration is designed to work on most EC2 accounts, 68 with access to a default VPC. For EC2 Classic users, please use `t1.micro` for 69 `instance_type`, and `ami-408c7f28` for the `ami`. If you use a region other than 70 `us-east-1` then you will need to choose an AMI in that region 71 as AMI IDs are region specific. 72 73 Replace the `ACCESS_KEY_HERE` and `SECRET_KEY_HERE` with your 74 AWS access key and secret key, available from 75 [this page](https://console.aws.amazon.com/iam/home?#security_credential). 76 We're hardcoding them for now, but will extract these into 77 variables later in the getting started guide. 78 79 ~> **Note**: If you simply leave out AWS credentials, Terraform will 80 automatically search for saved API credentials (for example, 81 in `~/.aws/credentials`) or IAM instance profile credentials. 82 This option is much cleaner for situations where tf files are checked into 83 source control or where there is more than one admin user. 84 See details [here](https://aws.amazon.com/blogs/apn/terraform-beyond-the-basics-with-aws/). 85 Leaving IAM credentials out of the Terraform configs allows you to leave those 86 credentials out of source control, and also use different IAM credentials 87 for each user without having to modify the configuration files. 88 89 This is a complete configuration that Terraform is ready to apply. 90 The general structure should be intuitive and straightforward. 91 92 The `provider` block is used to configure the named provider, in 93 our case "aws". A provider is responsible for creating and 94 managing resources. Multiple provider blocks can exist if a 95 Terraform configuration is composed of multiple providers, 96 which is a common situation. 97 98 The `resource` block defines a resource that exists within 99 the infrastructure. A resource might be a physical component such 100 as an EC2 instance, or it can be a logical resource such as 101 a Heroku application. 102 103 The resource block has two strings before opening the block: 104 the resource type and the resource name. In our example, the 105 resource type is "aws\_instance" and the name is "example." 106 The prefix of the type maps to the provider. In our case 107 "aws\_instance" automatically tells Terraform that it is 108 managed by the "aws" provider. 109 110 Within the resource block itself is configuration for that 111 resource. This is dependent on each resource provider and 112 is fully documented within our 113 [providers reference](/docs/providers/index.html). For our EC2 instance, we specify 114 an AMI for Ubuntu, and request a "t2.micro" instance so we 115 qualify under the free tier. 116 117 ## Initialization 118 119 The first command to run for a new configuration -- or after checking out 120 an existing configuration from version control -- is `terraform init`, which 121 initializes various local settings and data that will be used by subsequent 122 commands. 123 124 Terraform uses a plugin based architecture to support the numerous infrastructure 125 and service providers available. As of Terraform version 0.10.0, each "Provider" is its 126 own encapsulated binary distributed separately from Terraform itself. The 127 `terraform init` command will automatically download and install any Provider 128 binary for the providers in use within the configuration, which in this case is 129 just the `aws` provider: 130 131 132 ``` 133 $ terraform init 134 Initializing the backend... 135 Initializing provider plugins... 136 - downloading plugin for provider "aws"... 137 138 The following providers do not have any version constraints in configuration, 139 so the latest version was installed. 140 141 To prevent automatic upgrades to new major versions that may contain breaking 142 changes, it is recommended to add version = "..." constraints to the 143 corresponding provider blocks in configuration, with the constraint strings 144 suggested below. 145 146 * provider.aws: version = "~> 1.0" 147 148 Terraform has been successfully initialized! 149 150 You may now begin working with Terraform. Try running "terraform plan" to see 151 any changes that are required for your infrastructure. All Terraform commands 152 should now work. 153 154 If you ever set or change modules or backend configuration for Terraform, 155 rerun this command to reinitialize your environment. If you forget, other 156 commands will detect it and remind you to do so if necessary. 157 ``` 158 159 The `aws` provider plugin is downloaded and installed in a subdirectory of 160 the current working directory, along with various other book-keeping files. 161 162 The output specifies which version of the plugin was installed, and suggests 163 specifying that version in configuration to ensure that running 164 `terraform init` in future will install a compatible version. This step 165 is not necessary for following the getting started guide, since this 166 configuration will be discarded at the end. 167 168 ## Apply Changes 169 170 ~> **Note:** The commands shown in this guide apply to Terraform 0.11 and 171 above. Earlier versions require using the `terraform plan` command to 172 see the execution plan before applying it. Use `terraform version` 173 to confirm your running version. 174 175 In the same directory as the `example.tf` file you created, run 176 `terraform apply`. You should see output similar to below, though we've 177 truncated some of the output to save space: 178 179 ``` 180 $ terraform apply 181 # ... 182 183 + aws_instance.example 184 ami: "ami-2757f631" 185 availability_zone: "<computed>" 186 ebs_block_device.#: "<computed>" 187 ephemeral_block_device.#: "<computed>" 188 instance_state: "<computed>" 189 instance_type: "t2.micro" 190 key_name: "<computed>" 191 placement_group: "<computed>" 192 private_dns: "<computed>" 193 private_ip: "<computed>" 194 public_dns: "<computed>" 195 public_ip: "<computed>" 196 root_block_device.#: "<computed>" 197 security_groups.#: "<computed>" 198 source_dest_check: "true" 199 subnet_id: "<computed>" 200 tenancy: "<computed>" 201 vpc_security_group_ids.#: "<computed>" 202 ``` 203 204 This output shows the _execution plan_, describing which actions Terraform 205 will take in order to change real infrastructure to match the configuration. 206 The output format is similar to the diff format generated by tools 207 such as Git. The output has a `+` next to `aws_instance.example`, 208 meaning that Terraform will create this resource. Beneath that, 209 it shows the attributes that will be set. When the value displayed 210 is `<computed>`, it means that the value won't be known 211 until the resource is created. 212 213 214 If `terraform apply` failed with an error, read the error message 215 and fix the error that occurred. At this stage, it is likely to be a 216 syntax error in the configuration. 217 218 If the plan was created successfully, Terraform will now pause and wait for 219 approval before proceeding. If anything in the plan seems incorrect or 220 dangerous, it is safe to abort here with no changes made to your infrastructure. 221 In this case the plan looks acceptable, so type `yes` at the confirmation 222 prompt to proceed. 223 224 Executing the plan will take a few minutes since Terraform waits for the EC2 225 instance to become available: 226 227 ``` 228 # ... 229 aws_instance.example: Creating... 230 ami: "" => "ami-2757f631" 231 instance_type: "" => "t2.micro" 232 [...] 233 234 aws_instance.example: Still creating... (10s elapsed) 235 aws_instance.example: Creation complete 236 237 Apply complete! Resources: 1 added, 0 changed, 0 destroyed. 238 239 # ... 240 ``` 241 242 After this, Terraform is all done! You can go to the EC2 console to see the 243 created EC2 instance. (Make sure you're looking at the same region that was 244 configured in the provider configuration!) 245 246 Terraform also wrote some data into the `terraform.tfstate` file. This state 247 file is extremely important; it keeps track of the IDs of created resources 248 so that Terraform knows what it is managing. This file must be saved and 249 distributed to anyone who might run Terraform. It is generally recommended to 250 [setup remote state](https://www.terraform.io/docs/state/remote.html) 251 when working with Terraform, to share the state automatically, but this is 252 not necessary for simple situations like this Getting Started guide. 253 254 You can inspect the current state using `terraform show`: 255 256 ``` 257 $ terraform show 258 aws_instance.example: 259 id = i-32cf65a8 260 ami = ami-2757f631 261 availability_zone = us-east-1a 262 instance_state = running 263 instance_type = t2.micro 264 private_ip = 172.31.30.244 265 public_dns = ec2-52-90-212-55.compute-1.amazonaws.com 266 public_ip = 52.90.212.55 267 subnet_id = subnet-1497024d 268 vpc_security_group_ids.# = 1 269 vpc_security_group_ids.3348721628 = sg-67652003 270 ``` 271 272 You can see that by creating our resource, we've also gathered 273 a lot of information about it. These values can actually be referenced 274 to configure other resources or outputs, which will be covered later in 275 the getting started guide. 276 277 ## Provisioning 278 279 The EC2 instance we launched at this point is based on the AMI 280 given, but has no additional software installed. If you're running 281 an image-based infrastructure (perhaps creating images with 282 [Packer](https://www.packer.io)), then this is all you need. 283 284 However, many infrastructures still require some sort of initialization 285 or software provisioning step. Terraform supports provisioners, 286 which we'll cover a little bit later in the getting started guide, 287 in order to do this. 288 289 ## Next 290 291 Congratulations! You've built your first infrastructure with Terraform. 292 You've seen the configuration syntax, an example of a basic execution 293 plan, and understand the state file. 294 295 Next, we're going to move on to [changing and destroying infrastructure](/intro/getting-started/change.html).