github.com/armen/terraform@v0.5.2-0.20150529052519-caa8117a08f1/website/source/docs/modules/sources.html.markdown (about)

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