github.com/trawler/terraform@v0.10.8-0.20171106022149-4b1c7a1d9b48/website/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`.
    11  
    12  The `source` parameter tells Terraform where the module can be found.
    13  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.
    14  
    15  Terraform supports the following sources:
    16  
    17    * Local file paths
    18  
    19    * [Terraform Registry](/docs/registry/index.html)
    20  
    21    * GitHub
    22  
    23    * Bitbucket
    24  
    25    * Generic Git, Mercurial repositories
    26  
    27    * HTTP URLs
    28  
    29    * S3 buckets
    30  
    31  Each is documented further below.
    32  
    33  ## Local File Paths
    34  
    35  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:
    36  
    37  ```hcl
    38  module "consul" {
    39    source = "./consul"
    40  }
    41  ```
    42  
    43  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.
    44  
    45  ## Terraform Registry
    46  
    47  The [Terraform Registry](https://registry.terraform.io) is an index of modules
    48  written by the Terraform community.
    49  The Terraform Registry is the easiest
    50  way to get started with Terraform and to find modules to start with.
    51  The registry is integrated directly into Terraform:
    52  
    53  ```hcl
    54  module "consul" {
    55    source = "hashicorp/consul/aws"
    56  }
    57  ```
    58  
    59  The above example would use the
    60  [Consul module for AWS](https://registry.terraform.io/modules/hashicorp/consul/aws)
    61  from the public registry.
    62  
    63  You can learn more about the registry at the
    64  [Terraform Registry documentation section](/docs/registry/index.html).
    65  
    66  ## GitHub
    67  
    68  Terraform will automatically recognize GitHub URLs and turn them into a link to the specific Git repository. The syntax is simple:
    69  
    70  ```hcl
    71  module "consul" {
    72    source = "github.com/hashicorp/example"
    73  }
    74  ```
    75  
    76  Subdirectories within the repository can also be referenced:
    77  
    78  ```hcl
    79  module "consul" {
    80    source = "github.com/hashicorp/example//subdir"
    81  }
    82  ```
    83  
    84  These will fetch the modules using HTTPS.  If you want to use SSH instead:
    85  
    86  ```hcl
    87  module "consul" {
    88    source = "git@github.com:hashicorp/example.git//subdir"
    89  }
    90  ```
    91  
    92  **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.
    93  
    94  GitHub source URLs require that Git is installed on your system and that you have access to the repository.
    95  
    96  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.
    97  
    98  ### Private GitHub Repos
    99  
   100  If you need Terraform to be able to fetch modules from private GitHub repos on a remote machine (like Terraform Enterprise 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.
   101  
   102  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:
   103  
   104  ```hcl
   105  module "private-infra" {
   106    source = "git::https://MACHINE-USER:MACHINE-PASS@github.com/org/privatemodules//modules/foo"
   107  }
   108  ```
   109  
   110  **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.
   111  
   112  ## Bitbucket
   113  
   114  Terraform will automatically recognize public Bitbucket URLs and turn them into a link to the specific Git or Mercurial repository, for example:
   115  
   116  ```hcl
   117  module "consul" {
   118    source = "bitbucket.org/hashicorp/consul"
   119  }
   120  ```
   121  
   122  Subdirectories within the repository can also be referenced:
   123  
   124  ```hcl
   125  module "consul" {
   126    source = "bitbucket.org/hashicorp/consul//subdir"
   127  }
   128  ```
   129  
   130  **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.
   131  
   132  Bitbucket URLs will require that Git or Mercurial is installed on your system, depending on the type of repository.
   133  
   134  ## Private Bitbucket Repos
   135  Private bitbucket repositories must be specified similar to the Generic Git Respository section below.
   136  
   137  ```hcl
   138  module "consul" {
   139    source = "git::https://bitbucket.org/foocompany/module_name.git"
   140  }
   141  ```
   142  
   143  You can also specify branches and version withs the ?ref query
   144  
   145  ```hcl
   146  module "consul" {
   147    source = "git::https://bitbucket.org/foocompany/module_name.git?ref=hotfix"
   148  }
   149  ```
   150  
   151  You will need to run a `terraform get -update=true` if you want to pull the latest versions. This can be handy when you are rapidly iterating on a module in development.
   152  
   153  ## Generic Git Repository
   154  
   155  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.
   156  
   157  ```hcl
   158  module "consul" {
   159    source = "git://hashicorp.com/consul.git"
   160  }
   161  ```
   162  
   163  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:
   164  
   165  ```hcl
   166  module "consul" {
   167    source = "git::https://hashicorp.com/consul.git"
   168  }
   169  
   170  module "ami" {
   171    source = "git::ssh://git@github.com/owner/repo.git"
   172  }
   173  ```
   174  
   175  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.
   176  
   177  The URLs for Git repositories support the following query parameters:
   178  
   179    * `ref` - The ref to checkout. This can be a branch, tag, commit, etc.
   180  
   181  ```hcl
   182  module "consul" {
   183    source = "git::https://hashicorp.com/consul.git?ref=master"
   184  }
   185  ```
   186  
   187  Terraform will cache the module locally by default `terraform get` is run, so successive updates to master or a specified branch will not be factored into future plans. Run `terraform get -update=true` to get the latest version of the branch. This is handy in development, but potentially bothersome in production if you don't have control of the repository.
   188  
   189  ## Generic Mercurial Repository
   190  
   191  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::`.
   192  
   193  ```hcl
   194  module "consul" {
   195    source = "hg::http://hashicorp.com/consul.hg"
   196  }
   197  ```
   198  
   199  URLs for Mercurial repositories support the following query parameters:
   200  
   201    * `rev` - The rev to checkout. This can be a branch, tag, commit, etc.
   202  
   203  ```hcl
   204  module "consul" {
   205    source = "hg::http://hashicorp.com/consul.hg?rev=default"
   206  }
   207  ```
   208  
   209  ## HTTP URLs
   210  
   211  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
   212  you to optionally render the page differently when Terraform is requesting it.
   213  
   214  Terraform then looks for the resulting module URL in the following order:
   215  
   216  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.
   217  
   218  2. Terraform will look for a `<meta>` tag with the name of `terraform-get`, for example:
   219  
   220  ```html
   221  <meta name="terraform-get" content="github.com/hashicorp/example" />
   222  ```
   223  
   224  ### S3 Bucket
   225  
   226  Terraform can also store modules in an S3 bucket. To access the bucket
   227  you must have appropriate AWS credentials in your configuration or
   228  available via shared credentials or environment variables.
   229  
   230  There are a variety of S3 bucket addressing schemes, most are
   231  [documented in the S3
   232  configuration](http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html#access-bucket-intro).
   233  Here are a couple of examples.
   234  
   235  Using the `s3` protocol.
   236  
   237  ```hcl
   238  module "consul" {
   239    source = "s3::https://s3-eu-west-1.amazonaws.com/consulbucket/consul.zip"
   240  }
   241  ```
   242  
   243  Or directly using the bucket's URL.
   244  
   245  ```hcl
   246  module "consul" {
   247    source = "consulbucket.s3-eu-west-1.amazonaws.com/consul.zip"
   248  }
   249  ```
   250  
   251  
   252  ## Unarchiving
   253  
   254  Terraform will automatically unarchive files based on the extension of
   255  the file being requested (over any protocol). It supports the following
   256  archive formats:
   257  
   258  * tar.gz and tgz
   259  * tar.bz2 and tbz2
   260  * zip
   261  * gz
   262  * bz2