github.com/bengesoff/terraform@v0.3.1-0.20141018223233-b25a53629922/website/source/docs/modules/sources.html.markdown (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Module Sources"
     4  sidebar_current: "docs-modules-sources"
     5  ---
     6  
     7  # Module Sources
     8  
     9  As documented in [usage](/docs/modules/usage.html), the only required
    10  parameter when using a module is the `source` paramter which tells Terraform
    11  where the module can be found and what constraints to put on the module
    12  if any (such as branches for git, versions, etc.).
    13  
    14  Terraform manages modules for you: it downloads them, organizes them
    15  on disk, checks for updates, etc. Terraform uses this source parameter for
    16  the download/update of modules.
    17  
    18  Terraform supports the following sources:
    19  
    20    * Local file paths
    21  
    22    * GitHub
    23  
    24    * BitBucket
    25  
    26    * Generic Git, Mercurial repositories
    27  
    28    * HTTP URLs
    29  
    30  Each is documented further below.
    31  
    32  ## Local File Paths
    33  
    34  The easiest source is the local file path. For maximum portability, this
    35  should be a relative file path into a subdirectory. This allows you to
    36  organize your Terraform configuration into modules within one repository,
    37  for example.
    38  
    39  An example is shown below:
    40  
    41  ```
    42  module "consul" {
    43  	source = "./consul"
    44  }
    45  ```
    46  
    47  Updates for file paths are automatic: when "downloading" the module
    48  using the [get command](/docs/commands/get.html), Terraform will create
    49  a symbolic link to the original directory. Therefore, any changes are
    50  automatically instantly available.
    51  
    52  ## GitHub
    53  
    54  Terraform will automatically recognize GitHub URLs and turn them into
    55  the proper Git repository. The syntax is simple:
    56  
    57  ```
    58  module "consul" {
    59  	source = "github.com/hashicorp/example"
    60  }
    61  ```
    62  
    63  Subdirectories within the repository can also be referenced:
    64  
    65  ```
    66  module "consul" {
    67  	source = "github.com/hashicorp/example//subdir"
    68  }
    69  ```
    70  
    71  **Note:** The double-slash is important. It is what tells Terraform that
    72  that is the separator for a subdirectory, and not part of the repository
    73  itself.
    74  
    75  GitHub source URLs will require that Git is installed on your system
    76  and that you have the proper access to the repository.
    77  
    78  You can use the same parameters to GitHub repositories as you can generic
    79  Git repositories (such as tags or branches). See the documentation for generic
    80  Git repositories for more information.
    81  
    82  ## BitBucket
    83  
    84  Terraform will automatically recognize BitBucket URLs and turn them into
    85  the proper Git or Mercurial repository. An example:
    86  
    87  ```
    88  module "consul" {
    89  	source = "bitbucket.org/hashicorp/example"
    90  }
    91  ```
    92  
    93  Subdirectories within the repository can also be referenced:
    94  
    95  ```
    96  module "consul" {
    97  	source = "bitbucket.org/hashicorp/example//subdir"
    98  }
    99  ```
   100  
   101  **Note:** The double-slash is important. It is what tells Terraform that
   102  that is the separator for a subdirectory, and not part of the repository
   103  itself.
   104  
   105  BitBucket URLs will require that Git or Mercurial is installed on your
   106  system, depending on the source URL.
   107  
   108  ## Generic Git Repository
   109  
   110  Generic Git repositories are also supported. The value of `source` in this
   111  case should be a complete Git-compatible URL. Using Git requires that
   112  Git is installed on your system. Example:
   113  
   114  ```
   115  module "consul" {
   116  	source = "git://hashicorp.com/module.git"
   117  }
   118  ```
   119  
   120  You can also use protocols such as HTTP or SSH, but you'll have to hint
   121  to Terraform (using the forced source type syntax documented below) to use
   122  Git:
   123  
   124  ```
   125  module "consul" {
   126  	source = "git::https://hashicorp.com/module.git"
   127  }
   128  ```
   129  
   130  URLs for Git repositories (of any protocol) support the following query
   131  parameters:
   132  
   133    * `ref` - The ref to checkout. This can be a branch, tag, commit, etc.
   134  
   135  An example of using these parameters is shown below:
   136  
   137  ```
   138  module "consul" {
   139  	source = "git::https://hashicorp.com/module.git?ref=master"
   140  }
   141  ```
   142  
   143  ## Generic Mercurial Repository
   144  
   145  Generic Mercurial repositories are supported. The value of `source` in this
   146  case should be a complete Mercurial-compatible URL. Using Mercurial requires that
   147  Mercurial is installed on your system. Example:
   148  
   149  ```
   150  module "consul" {
   151  	source = "hg::http://hashicorp.com/module.hg"
   152  }
   153  ```
   154  
   155  In the case of above, we used the forced source type syntax documented below.
   156  Mercurial repositories require this.
   157  
   158  URLs for Mercurial repositories (of any protocol) support the following query
   159  parameters:
   160  
   161    * `rev` - The rev to checkout. This can be a branch, tag, commit, etc.
   162  
   163  ## HTTP URLs
   164  
   165  Any HTTP endpoint can serve up Terraform modules. For HTTP URLs (SSL is
   166  supported, as well), Terraform will make a GET request to the given URL.
   167  An additional GET parameter `terraform-get=1` will be appended, allowing
   168  you to optionally render the page differently when Terraform is requesting it.
   169  
   170  Terraform then looks for the resulting module URL in the following order.
   171  
   172  First, if a header `X-Terraform-Get` is present, then it should contain
   173  the source URL of the actual module. This will be used.
   174  
   175  If the header isn't present, Terraform will look for a `<meta>` tag
   176  with the name of "terraform-get". The value will be used as the source
   177  URL.
   178  
   179  ## Forced Source Type
   180  
   181  In a couple places above, we've referenced "forced source type." Forced
   182  source type is a syntax added to URLs that allow you to force a specific
   183  method for download/updating the module. It is used to disambiguate URLs.
   184  
   185  For example, the source "http://hashicorp.com/foo.git" could just as
   186  easily be a plain HTTP URL as it might be a Git repository speaking the
   187  HTTP protocol. The forced source type syntax is used to force Terraform
   188  one way or the other.
   189  
   190  Example:
   191  
   192  ```
   193  module "consul" {
   194  	source = "git::http://hashicorp.com/foo.git"
   195  }
   196  ```
   197  
   198  The above will force Terraform to get the module using Git, despite it
   199  being an HTTP URL.
   200  
   201  If a forced source type isn't specified, Terraform will match the exact
   202  protocol if it supports it. It will not try multiple methods. In the case
   203  above, it would've used the HTTP method.