github.com/hobbeswalsh/terraform@v0.3.7-0.20150619183303-ad17cf55a0fa/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  // force https source
   128  module "consul" {
   129  	source = "git::https://hashicorp.com/module.git"
   130  }
   131  
   132  // force ssh source
   133  module "ami" {
   134  	source = "git::ssh://git@github.com/owner/repo.git"
   135  }
   136  ```
   137  
   138  URLs for Git repositories (of any protocol) support the following query
   139  parameters:
   140  
   141    * `ref` - The ref to checkout. This can be a branch, tag, commit, etc.
   142  
   143  An example of using these parameters is shown below:
   144  
   145  ```
   146  module "consul" {
   147  	source = "git::https://hashicorp.com/module.git?ref=master"
   148  }
   149  ```
   150  
   151  ## Generic Mercurial Repository
   152  
   153  Generic Mercurial repositories are supported. The value of `source` in this
   154  case should be a complete Mercurial-compatible URL. Using Mercurial requires that
   155  Mercurial is installed on your system. Example:
   156  
   157  ```
   158  module "consul" {
   159  	source = "hg::http://hashicorp.com/module.hg"
   160  }
   161  ```
   162  
   163  In the case of above, we used the forced source type syntax documented below.
   164  Mercurial repositories require this.
   165  
   166  URLs for Mercurial repositories (of any protocol) support the following query
   167  parameters:
   168  
   169    * `rev` - The rev to checkout. This can be a branch, tag, commit, etc.
   170  
   171  ## HTTP URLs
   172  
   173  Any HTTP endpoint can serve up Terraform modules. For HTTP URLs (SSL is
   174  supported, as well), Terraform will make a GET request to the given URL.
   175  An additional GET parameter `terraform-get=1` will be appended, allowing
   176  you to optionally render the page differently when Terraform is requesting it.
   177  
   178  Terraform then looks for the resulting module URL in the following order.
   179  
   180  First, if a header `X-Terraform-Get` is present, then it should contain
   181  the source URL of the actual module. This will be used.
   182  
   183  If the header isn't present, Terraform will look for a `<meta>` tag
   184  with the name of "terraform-get". The value will be used as the source
   185  URL.
   186  
   187  ## Forced Source Type
   188  
   189  In a couple places above, we've referenced "forced source type." Forced
   190  source type is a syntax added to URLs that allow you to force a specific
   191  method for download/updating the module. It is used to disambiguate URLs.
   192  
   193  For example, the source "http://hashicorp.com/foo.git" could just as
   194  easily be a plain HTTP URL as it might be a Git repository speaking the
   195  HTTP protocol. The forced source type syntax is used to force Terraform
   196  one way or the other.
   197  
   198  Example:
   199  
   200  ```
   201  module "consul" {
   202  	source = "git::http://hashicorp.com/foo.git"
   203  }
   204  ```
   205  
   206  The above will force Terraform to get the module using Git, despite it
   207  being an HTTP URL.
   208  
   209  If a forced source type isn't specified, Terraform will match the exact
   210  protocol if it supports it. It will not try multiple methods. In the case
   211  above, it would've used the HTTP method.