github.com/lamielle/terraform@v0.3.2-0.20141121070651-81f008ba53d5/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.