github.com/pgray/terraform@v0.5.4-0.20170822184730-b6a464c5214d/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 it's 
   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  ## Execution Plan
   169  
   170  Next, let's see what Terraform would do if we asked it to
   171  apply this configuration. In the same directory as the
   172  `example.tf` file you created, run `terraform plan`. You
   173  should see output similar to what is copied below. We've
   174  truncated some of the output to save space.
   175  
   176  ```
   177  $ terraform plan
   178  # ...
   179  
   180  + aws_instance.example
   181      ami:                      "ami-2757f631"
   182      availability_zone:        "<computed>"
   183      ebs_block_device.#:       "<computed>"
   184      ephemeral_block_device.#: "<computed>"
   185      instance_state:           "<computed>"
   186      instance_type:            "t2.micro"
   187      key_name:                 "<computed>"
   188      placement_group:          "<computed>"
   189      private_dns:              "<computed>"
   190      private_ip:               "<computed>"
   191      public_dns:               "<computed>"
   192      public_ip:                "<computed>"
   193      root_block_device.#:      "<computed>"
   194      security_groups.#:        "<computed>"
   195      source_dest_check:        "true"
   196      subnet_id:                "<computed>"
   197      tenancy:                  "<computed>"
   198      vpc_security_group_ids.#: "<computed>"
   199  ```
   200  
   201  `terraform plan` shows what changes Terraform will apply to
   202  your infrastructure given the current state of your infrastructure
   203  as well as the current contents of your configuration.
   204  
   205  If `terraform plan` failed with an error, read the error message
   206  and fix the error that occurred. At this stage, it is probably a
   207  syntax error in the configuration.
   208  
   209  The output format is similar to the diff format generated by tools
   210  such as Git. The output has a "+" next to "aws\_instance.example",
   211  meaning that Terraform will create this resource. Beneath that,
   212  it shows the attributes that will be set. When the value displayed
   213  is `<computed>`, it means that the value won't be known
   214  until the resource is created.
   215  
   216  ## Apply
   217  
   218  The plan looks good, our configuration appears valid, so it's time to
   219  create real resources. Run `terraform apply` in the same directory
   220  as your `example.tf`, and watch it go! It will take a few minutes
   221  since Terraform waits for the EC2 instance to become available.
   222  
   223  ```
   224  $ terraform apply
   225  aws_instance.example: Creating...
   226    ami:                      "" => "ami-2757f631"
   227    instance_type:            "" => "t2.micro"
   228    [...]
   229  
   230  aws_instance.example: Still creating... (10s elapsed)
   231  aws_instance.example: Creation complete
   232  
   233  Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
   234  
   235  # ...
   236  ```
   237  
   238  Done! You can go to the AWS console to prove to yourself that the
   239  EC2 instance has been created.
   240  
   241  Terraform also puts some state into the `terraform.tfstate` file
   242  by default. This state file is extremely important; it maps various
   243  resource metadata to actual resource IDs so that Terraform knows
   244  what it is managing. This file must be saved and distributed
   245  to anyone who might run Terraform. It is generally recommended to
   246  [setup remote state](https://www.terraform.io/docs/state/remote.html)
   247  when working with Terraform. This will mean that any potential secrets
   248  stored in the state file, will not be checked into version control
   249  
   250  
   251  You can inspect the state using `terraform show`:
   252  
   253  ```
   254  $ terraform show
   255  aws_instance.example:
   256    id = i-32cf65a8
   257    ami = ami-2757f631
   258    availability_zone = us-east-1a
   259    instance_state = running
   260    instance_type = t2.micro
   261    private_ip = 172.31.30.244
   262    public_dns = ec2-52-90-212-55.compute-1.amazonaws.com
   263    public_ip = 52.90.212.55
   264    subnet_id = subnet-1497024d
   265    vpc_security_group_ids.# = 1
   266    vpc_security_group_ids.3348721628 = sg-67652003
   267  ```
   268  
   269  You can see that by creating our resource, we've also gathered
   270  a lot more metadata about it. This metadata can actually be referenced
   271  for other resources or outputs, which will be covered later in
   272  the getting started guide.
   273  
   274  ## Provisioning
   275  
   276  The EC2 instance we launched at this point is based on the AMI
   277  given, but has no additional software installed. If you're running
   278  an image-based infrastructure (perhaps creating images with
   279  [Packer](https://www.packer.io)), then this is all you need.
   280  
   281  However, many infrastructures still require some sort of initialization
   282  or software provisioning step. Terraform supports
   283  provisioners,
   284  which we'll cover a little bit later in the getting started guide,
   285  in order to do this.
   286  
   287  ## Next
   288  
   289  Congratulations! You've built your first infrastructure with Terraform.
   290  You've seen the configuration syntax, an example of a basic execution
   291  plan, and understand the state file.
   292  
   293  Next, we're going to move on to [changing and destroying infrastructure](/intro/getting-started/change.html).