github.com/handlerbot/terraform@v0.10.0-beta1.0.20180726153736-26b68d98f9cb/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](#local-file-paths)
    18  
    19    * [Terraform Registry](#terraform-registry)
    20  
    21    * [GitHub](#github)
    22  
    23    * [Bitbucket](#bitbucket)
    24  
    25    * Generic [Git](#generic-git-repository), [Mercurial](#generic-mercurial-repository) repositories
    26  
    27    * [HTTP URLs](#http-urls)
    28  
    29    * [S3 buckets](#s3-bucket)
    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.
    51  
    52  The registry is integrated directly into Terraform. You can reference any
    53  registry module with a source string of `<NAMESPACE>/<NAME>/<PROVIDER>`. Each
    54  module's information page on the registry includes its source string.
    55  
    56  ```hcl
    57  module "consul" {
    58    source = "hashicorp/consul/aws"
    59    version = "0.1.0"
    60  }
    61  ```
    62  
    63  The above example would use the
    64  [Consul module for AWS](https://registry.terraform.io/modules/hashicorp/consul/aws)
    65  from the public registry.
    66  
    67  Registry modules support versioning. You can provide a specific version, or use
    68  flexible [version constraints](/docs/modules/usage.html#module-versions).
    69  
    70  You can learn more about the registry at the
    71  [Terraform Registry documentation](/docs/registry/modules/use.html#using-modules).
    72  
    73  ## Private Registries
    74  
    75  [Terraform Enterprise](https://www.hashicorp.com/products/terraform) provides a
    76  [private module registry](/docs/enterprise/registry/index.html), to help
    77  you share code within your organization. Other services can also provide
    78  private registries by implementing [Terraform's registry API](/docs/registry/api.html).
    79  
    80  Source strings for private registry modules are similar to public modules, but
    81  also include a hostname. They should follow the format
    82  `<HOSTNAME>/<NAMESPACE>/<NAME>/<PROVIDER>`.
    83  
    84  ```hcl
    85  module "vpc" {
    86    source = "app.terraform.io/example_corp/vpc/aws"
    87    version = "0.9.3"
    88  }
    89  ```
    90  
    91  Modules from private registries support versioning, just like modules from the
    92  public Terraform Registry.
    93  
    94  ## GitHub
    95  
    96  Terraform will automatically recognize GitHub URLs and turn them into a link to the specific Git repository. The syntax is simple:
    97  
    98  ```hcl
    99  module "consul" {
   100    source = "github.com/hashicorp/example"
   101  }
   102  ```
   103  
   104  Subdirectories within the repository can also be referenced:
   105  
   106  ```hcl
   107  module "consul" {
   108    source = "github.com/hashicorp/example//subdir"
   109  }
   110  ```
   111  
   112  These will fetch the modules using HTTPS.  If you want to use SSH instead:
   113  
   114  ```hcl
   115  module "consul" {
   116    source = "git@github.com:hashicorp/example.git//subdir"
   117  }
   118  ```
   119  
   120  **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.
   121  
   122  GitHub source URLs require that Git is installed on your system and that you have access to the repository.
   123  
   124  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](#parameters) for more information.
   125  
   126  ### Private GitHub Repos
   127  
   128  If you need Terraform to fetch modules from private GitHub repos, you must provide Terraform with credentials to authenticate as a user with read access to those repos.
   129  
   130  - If you run Terraform only on your local machine, you can specify the module source as an SSH URI (like `git@github.com:hashicorp/example.git`) and Terraform will use your default SSH key to authenticate.
   131  - If you use Terraform Enterprise, consider using the private module registry. It makes handling credentials easier, and provides full versioning support. (See [Private Registries](#private-registries) above for more info.)
   132  
   133      If you need to use modules directly from Git, you can use SSH URIs with Terraform Enterprise. You'll need to add an SSH private key to your organization and assign it to any workspace that fetches modules from private repos. [See the Terraform Enterprise docs about SSH keys for cloning modules.](/docs/enterprise/workspaces/ssh-keys.html)
   134  - If you need to run Terraform on a remote machine like a CI worker, you either need to write an SSH key to disk and set the `GIT_SSH_COMMAND` environment variable appropriately during the worker's provisioning process, or create a [GitHub machine user](https://developer.github.com/guides/managing-deploy-keys/#machine-users) with read access to the repos in question and embed its credentials into the modules' `source` parameters:
   135  
   136      ```hcl
   137      module "private-infra" {
   138        source = "git::https://MACHINE-USER:MACHINE-PASS@github.com/org/privatemodules//modules/foo"
   139      }
   140      ```
   141  
   142      Note that Terraform does not support interpolations in the `source` parameter of a module, so you must hardcode the machine username and password if using this method.
   143  
   144  ## Bitbucket
   145  
   146  Terraform will automatically recognize public Bitbucket URLs and turn them into a link to the specific Git or Mercurial repository, for example:
   147  
   148  ```hcl
   149  module "consul" {
   150    source = "bitbucket.org/hashicorp/consul"
   151  }
   152  ```
   153  
   154  Subdirectories within the repository can also be referenced:
   155  
   156  ```hcl
   157  module "consul" {
   158    source = "bitbucket.org/hashicorp/consul//subdir"
   159  }
   160  ```
   161  
   162  **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.
   163  
   164  Bitbucket URLs will require that Git or Mercurial is installed on your system, depending on the type of repository.
   165  
   166  ## Private Bitbucket Repos
   167  Private bitbucket repositories must be specified similar to the [Generic Git Repository](#generic-git-repository) section below.
   168  
   169  ```hcl
   170  module "consul" {
   171    source = "git::https://bitbucket.org/foocompany/module_name.git"
   172  }
   173  ```
   174  
   175  You can also specify branches and version with the `?ref` query, and use HTTPS or SSH:
   176  
   177  ```hcl
   178  module "consul" {
   179    source = "git::https://bitbucket.org/foocompany/module_name.git?ref=hotfix"
   180  }
   181  ```
   182  
   183  ```hcl
   184  module "consul" {
   185    source = "git::ssh://git@bitbucket.org/foocompany/module_name.git"
   186  }
   187  ```
   188  
   189  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.
   190  
   191  ## Generic Git Repository
   192  
   193  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.
   194  
   195  ```hcl
   196  module "consul" {
   197    source = "git://hashicorp.com/consul.git"
   198  }
   199  ```
   200  
   201  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:
   202  
   203  ```hcl
   204  module "consul" {
   205    source = "git::https://hashicorp.com/consul.git"
   206  }
   207  
   208  module "ami" {
   209    source = "git::ssh://git@github.com/owner/repo.git"
   210  }
   211  ```
   212  
   213  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.
   214  
   215  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.
   216  
   217  ### Parameters
   218  
   219  The URLs for Git repositories support the following query parameters:
   220  
   221    * `ref` - The ref to checkout. This can be a branch, tag, commit, etc.
   222  
   223  ```hcl
   224  module "consul" {
   225    source = "git::https://hashicorp.com/consul.git?ref=master"
   226  }
   227  ```
   228  
   229  ## Generic Mercurial Repository
   230  
   231  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::`.
   232  
   233  ```hcl
   234  module "consul" {
   235    source = "hg::http://hashicorp.com/consul.hg"
   236  }
   237  ```
   238  
   239  URLs for Mercurial repositories support the following query parameters:
   240  
   241    * `rev` - The rev to checkout. This can be a branch, tag, commit, etc.
   242  
   243  ```hcl
   244  module "consul" {
   245    source = "hg::http://hashicorp.com/consul.hg?rev=default"
   246  }
   247  ```
   248  
   249  ## HTTP URLs
   250  
   251  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
   252  you to optionally render the page differently when Terraform is requesting it.
   253  
   254  Terraform then looks for the resulting module URL in the following order:
   255  
   256  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.
   257  
   258  2. Terraform will look for a `<meta>` tag with the name of `terraform-get`, for example:
   259  
   260  ```html
   261  <meta name="terraform-get" content="github.com/hashicorp/example" />
   262  ```
   263  
   264  ## S3 Bucket
   265  
   266  Terraform can also store modules in an S3 bucket. To access the bucket
   267  you must have appropriate AWS credentials in your configuration or
   268  available via shared credentials or environment variables.
   269  
   270  There are a variety of S3 bucket addressing schemes, most are
   271  [documented in the S3
   272  configuration](http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html#access-bucket-intro).
   273  Here are a couple of examples.
   274  
   275  Using the `s3` protocol.
   276  
   277  ```hcl
   278  module "consul" {
   279    source = "s3::https://s3-eu-west-1.amazonaws.com/consulbucket/consul.zip"
   280  }
   281  ```
   282  
   283  Or directly using the bucket's URL.
   284  
   285  ```hcl
   286  module "consul" {
   287    source = "consulbucket.s3-eu-west-1.amazonaws.com/consul.zip"
   288  }
   289  ```
   290  
   291  
   292  ## Unarchiving
   293  
   294  Terraform will automatically unarchive files based on the extension of
   295  the file being requested (over any protocol). It supports the following
   296  archive formats:
   297  
   298  * tar.gz and tgz
   299  * tar.bz2 and tbz2
   300  * zip
   301  * gz
   302  * bz2