github.com/nalum/terraform@v0.3.2-0.20141223102918-aa2c22ffeff6/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 on your machine (version 
    50  1.2+ is _required_). Alternatively, you can use the Vagrantfile in the root of 
    51  this repo to stand up a virtual machine with the appropriate dev tooling 
    52  already set up for you.
    53  
    54  For local dev first make sure Go is properly installed, including setting up
    55  a [GOPATH](http://golang.org/doc/code.html#GOPATH). Next, install the following 
    56  software packages, which are needed for some dependencies:
    57  
    58  - [Git](http://git-scm.com/)
    59  - [Mercurial](http://mercurial.selenic.com/)
    60  
    61  Then, install [Gox](https://github.com/mitchellh/gox), which is used
    62  as a compilation tool on top of Go:
    63  
    64  ```sh
    65  $ go get -u github.com/mitchellh/gox
    66  ```
    67  
    68  Next, clone this repository into `$GOPATH/src/github.com/hashicorp/terraform`.
    69  Install the necessary dependencies by running `make updatedeps` and then just
    70  type `make`. This will compile some more dependencies and then run the tests. If
    71  this exits with exit status 0, then everything is working!
    72  
    73  ```sh
    74  $ make updatedeps
    75  ...
    76  $ make
    77  ...
    78  ```
    79  
    80  To compile a development version of Terraform and the built-in plugins,
    81  run `make dev`. This will put Terraform binaries in the `bin` folder:
    82  
    83  ```sh
    84  $ make dev
    85  ...
    86  $ bin/terraform
    87  ...
    88  ```
    89  
    90  If you're developing a specific package, you can run tests for just that
    91  package by specifying the `TEST` variable. For example below, only
    92  `terraform` package tests will be run.
    93  
    94  ```sh
    95  $ make test TEST=./terraform
    96  ...
    97  ```
    98  
    99  ### Acceptance Tests
   100  
   101  Terraform also has a comprehensive
   102  [acceptance test](http://en.wikipedia.org/wiki/Acceptance_testing)
   103  suite covering most of the major features of the built-in providers.
   104  
   105  If you're working on a feature of a provider and want to verify it
   106  is functioning (and hasn't broken anything else), we recommend running
   107  the acceptance tests. Note that we _do not require_ that you run or
   108  write acceptance tests to have a PR accepted. The acceptance tests
   109  are just here for your convenience.
   110  
   111  **Warning:** The acceptance tests create/destroy/modify _real resources_,
   112  which may incur real costs. In the presence of a bug, it is technically
   113  possible that broken providers could corrupt existing infrastructure
   114  as well. Therefore, please run the acceptance providers at your own
   115  risk. At the very least, we recommend running them in their own private
   116  account for whatever provider you're testing.
   117  
   118  To run the acceptance tests, invoke `make testacc`:
   119  
   120  ```sh
   121  $ make testacc TEST=./builtin/providers/aws TESTARGS='-run=VPC'
   122  ...
   123  ```
   124  
   125  The `TEST` variable is required, and you should specify the folder where
   126  the provider is. The `TESTARGS` variable is recommended to filter down
   127  to a specific resource to test, since testing all of them at once can
   128  take a very long time.
   129  
   130  Acceptance tests typically require other environment variables to be
   131  set for things such as access keys. The provider itself should error
   132  early and tell you what to set, so it is not documented here.