github.com/mapuri/terraform@v0.7.6-0.20161012203214-7e0408293f97/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: Explains the use of the source parameter, which tells Terraform where modules can be found.
     6  ---
     7  
     8  # Module Sources
     9  
    10  As documented in the [Usage section](/docs/modules/usage.html), the only required parameter when using a module is `source`. The `source` parameter tells Terraform where the module can be found and what constraints to put on the module. Constraints can include a specific version or Git branch.
    11  
    12  Terraform manages modules for you: it downloads them, organizes them on disk, checks for updates, etc. Terraform uses this `source` parameter to determine where it should retrieve and update modules from.
    13  
    14  Terraform supports the following sources:
    15  
    16    * Local file paths
    17  
    18    * GitHub
    19  
    20    * BitBucket
    21  
    22    * Generic Git, Mercurial repositories
    23  
    24    * HTTP URLs
    25  
    26  Each is documented further below.
    27  
    28  ## Local File Paths
    29  
    30  The easiest source is the local file path. For maximum portability, this should be a relative file path into a subdirectory. This allows you to organize your Terraform configuration into modules within one repository, for example:
    31  
    32  ```
    33  module "consul" {
    34  	source = "./consul"
    35  }
    36  ```
    37  
    38  Updates for file paths are automatic: when "downloading" the module using the [get command](/docs/commands/get.html), Terraform will create a symbolic link to the original directory. Therefore, any changes are automatically available.
    39  
    40  ## GitHub
    41  
    42  Terraform will automatically recognize GitHub URLs and turn them into a link to the specific Git repository. The syntax is simple:
    43  
    44  ```
    45  module "consul" {
    46  	source = "github.com/hashicorp/example"
    47  }
    48  ```
    49  
    50  Subdirectories within the repository can also be referenced:
    51  
    52  ```
    53  module "consul" {
    54  	source = "github.com/hashicorp/example//subdir"
    55  }
    56  ```
    57  
    58  **Note:** The double-slash, `//`, is important. It is what tells Terraform that that is the separator for a subdirectory, and not part of the repository itself.
    59  
    60  GitHub source URLs require that Git is installed on your system and that you have access to the repository.
    61  
    62  You can use the same parameters to GitHub repositories as you can generic Git repositories (such as tags or branches). See the documentation for generic Git repositories for more information.
    63  
    64  ### Private GitHub Repos
    65  
    66  If you need Terraform to be able to fetch modules from private GitHub repos on a remote machine (like Atlas or a CI server), you'll need to provide Terraform with credentials that can be used to authenticate as a user with read access to the private repo.
    67  
    68  First, create a [machine user](https://developer.github.com/guides/managing-deploy-keys/#machine-users) on GitHub with read access to the private repo in question, then embed this user's credentials into the `source` parameter:
    69  
    70  ```
    71  module "private-infra" {
    72    source = "git::https://MACHINE-USER:MACHINE-PASS@github.com/org/privatemodules//modules/foo"
    73  }
    74  ```
    75  
    76  **Note:** Terraform does not yet support interpolations in the `source` field, so the machine username and password will have to be embedded directly into the `source` string. You can track [GH-1439](https://github.com/hashicorp/terraform/issues/1439) to learn when this limitation is addressed.
    77  
    78  ## BitBucket
    79  
    80  Terraform will automatically recognize BitBucket URLs and turn them into a link to the specific Git or Mercurial repository, for example:
    81  
    82  ```
    83  module "consul" {
    84  	source = "bitbucket.org/hashicorp/consul"
    85  }
    86  ```
    87  
    88  Subdirectories within the repository can also be referenced:
    89  
    90  ```
    91  module "consul" {
    92  	source = "bitbucket.org/hashicorp/consul//subdir"
    93  }
    94  ```
    95  
    96  **Note:** The double-slash, `//`, is important. It is what tells Terraform that this is the separator for a subdirectory, and not part of the repository itself.
    97  
    98  BitBucket URLs will require that Git or Mercurial is installed on your system, depending on the type of repository.
    99  
   100  ## Generic Git Repository
   101  
   102  Generic Git repositories are also supported. The value of `source` in this case should be a complete Git-compatible URL. Using generic Git repositories requires that Git is installed on your system.
   103  
   104  ```
   105  module "consul" {
   106  	source = "git://hashicorp.com/consul.git"
   107  }
   108  ```
   109  
   110  You can also use protocols such as HTTP or SSH to reference a module, but you'll have specify to Terraform that it is a Git module, by prefixing the URL with `git::` like so:
   111  
   112  ```
   113  module "consul" {
   114  	source = "git::https://hashicorp.com/consul.git"
   115  }
   116  
   117  module "ami" {
   118  	source = "git::ssh://git@github.com/owner/repo.git"
   119  }
   120  ```
   121  
   122  If you do not specify the type of `source` then Terraform will attempt to use the closest match, for example assuming `https://hashicorp.com/consul.git` is a HTTP URL.
   123  
   124  The URLs for Git repositories support the following query parameters:
   125  
   126    * `ref` - The ref to checkout. This can be a branch, tag, commit, etc.
   127  
   128  ```
   129  module "consul" {
   130  	source = "git::https://hashicorp.com/consul.git?ref=master"
   131  }
   132  ```
   133  
   134  ## Generic Mercurial Repository
   135  
   136  Generic Mercurial repositories are supported. The value of `source` in this case should be a complete Mercurial-compatible URL. Using generic Mercurial repositories requires that Mercurial is installed on your system. You must tell Terraform that your `source` is a Mercurial repository by prefixing it with `hg::`.
   137  
   138  ```
   139  module "consul" {
   140  	source = "hg::http://hashicorp.com/consul.hg"
   141  }
   142  ```
   143  
   144  URLs for Mercurial repositories support the following query parameters:
   145  
   146    * `rev` - The rev to checkout. This can be a branch, tag, commit, etc.
   147  
   148  ```
   149  module "consul" {
   150  	source = "hg::http://hashicorp.com/consul.hg?ref=master"
   151  }
   152  ```
   153  
   154  ## HTTP URLs
   155  
   156  An HTTP or HTTPS URL can be used to redirect Terraform to get the module source from one of the other sources.  For HTTP URLs, Terraform will make a `GET` request to the given URL. An additional `GET` parameter, `terraform-get=1`, will be appended, allowing
   157  you to optionally render the page differently when Terraform is requesting it.
   158  
   159  Terraform then looks for the resulting module URL in the following order:
   160  
   161  1. Terraform will look to see if the header `X-Terraform-Get` is present. The header should contain the source URL of the actual module.
   162  
   163  2. Terraform will look for a `<meta>` tag with the name of `terraform-get`, for example:
   164  
   165  ```
   166  <meta name=“terraform-get” content="github.com/hashicorp/example" />
   167  ```