github.com/bengesoff/terraform@v0.3.1-0.20141018223233-b25a53629922/README.md (about) 1 # Terraform 2 3 * Website: http://www.terraform.io 4 * IRC: `#terraform-tool` on Freenode 5 * Mailing list: [Google Groups](http://groups.google.com/group/terraform-tool) 6 7 ![Terraform](https://raw.githubusercontent.com/hashicorp/terraform/master/website/source/assets/images/readme.png) 8 9 Terraform is a tool for building, changing, and versioning infrastructure 10 safely and efficiently. Terraform can manage existing and popular service 11 providers as well as custom in-house solutions. 12 13 The key features of Terraform are: 14 15 * **Infrastructure as Code**: Infrastructure is described using a high-level 16 configuration syntax. This allows a blueprint of your datacenter to be 17 versioned and treated as you would any other code. Additionally, 18 infrastructure can be shared and re-used. 19 20 * **Execution Plans**: Terraform has a "planning" step where it generates 21 an _execution plan_. The execution plan shows what Terraform will do when 22 you call apply. This lets you avoid any surprises when Terraform 23 manipulates infrastructure. 24 25 * **Resource Graph**: Terraform builds a graph of all your resources, 26 and parallelizes the creation and modification of any non-dependent 27 resources. Because of this, Terraform builds infrastructure as efficiently 28 as possible, and operators get insight into dependencies in their 29 infrastructure. 30 31 * **Change Automation**: Complex changesets can be applied to 32 your infrastructure with minimal human interaction. 33 With the previously mentioned execution 34 plan and resource graph, you know exactly what Terraform will change 35 and in what order, avoiding many possible human errors. 36 37 For more information, see the 38 [introduction section](http://www.terraform.io/intro) 39 of the Terraform website. 40 41 ## Getting Started & Documentation 42 43 All documentation is available on the 44 [Terraform website](http://www.terraform.io). 45 46 ## Developing Terraform 47 48 If you wish to work on Terraform itself or any of its built-in providers, 49 you'll first need [Go](http://www.golang.org) installed (version 1.2+ is 50 _required_). Make sure Go is properly installed, including setting up 51 a [GOPATH](http://golang.org/doc/code.html#GOPATH). 52 53 Next, install the following software packages, which are needed for some dependencies: 54 55 - [Git](http://git-scm.com/) 56 - [Mercurial](http://mercurial.selenic.com/) 57 58 Then, install [Gox](https://github.com/mitchellh/gox), which is used 59 as a compilation tool on top of Go: 60 61 ```sh 62 $ go get -u github.com/mitchellh/gox 63 ``` 64 65 Next, clone this repository into `$GOPATH/src/github.com/hashicorp/terraform`. 66 Install the necessary dependencies by running `make updatedeps` and then just 67 type `make`. This will compile some more dependencies and then run the tests. If 68 this exits with exit status 0, then everything is working! 69 70 ```sh 71 $ make updatedeps 72 ... 73 $ make 74 ... 75 ``` 76 77 To compile a development version of Terraform and the built-in plugins, 78 run `make dev`. This will put Terraform binaries in the `bin` folder: 79 80 ```sh 81 $ make dev 82 ... 83 $ bin/terraform 84 ... 85 ``` 86 87 If you're developing a specific package, you can run tests for just that 88 package by specifying the `TEST` variable. For example below, only 89 `terraform` package tests will be run. 90 91 ```sh 92 $ make test TEST=./terraform 93 ... 94 ``` 95 96 ### Acceptance Tests 97 98 Terraform also has a comprehensive 99 [acceptance test](http://en.wikipedia.org/wiki/Acceptance_testing) 100 suite covering most of the major features of the built-in providers. 101 102 If you're working on a feature of a provider and want to verify it 103 is functioning (and hasn't broken anything else), we recommend running 104 the acceptance tests. Note that we _do not require_ that you run or 105 write acceptance tests to have a PR accepted. The acceptance tests 106 are just here for your convenience. 107 108 **Warning:** The acceptance tests create/destroy/modify _real resources_, 109 which may incur real costs. In the presence of a bug, it is technically 110 possible that broken providers could corrupt existing infrastructure 111 as well. Therefore, please run the acceptance providers at your own 112 risk. At the very least, we recommend running them in their own private 113 account for whatever provider you're testing. 114 115 To run the acceptance tests, invoke `make testacc`: 116 117 ```sh 118 $ make testacc TEST=./builtin/providers/aws TESTARGS='-run=VPC' 119 ... 120 ``` 121 122 The `TEST` variable is required, and you should specify the folder where 123 the provider is. The `TESTARGS` variable is recommended to filter down 124 to a specific resource to test, since testing all of them at once can 125 take a very long time. 126 127 Acceptance tests typically require other environment variables to be 128 set for things such as access keys. The provider itself should error 129 early and tell you what to set, so it is not documented here.