From 07c3893653a1ced2a9e7f873ce8e95819fdaf7d1 Mon Sep 17 00:00:00 2001 From: Nick Fagerlund Date: Wed, 7 Feb 2018 09:15:55 -0800 Subject: [PATCH] website: private module registry documentation --- .../docs/commands/cli-config.html.markdown | 42 +++++++---- website/docs/modules/sources.html.markdown | 36 +++++++++- website/docs/modules/usage.html.markdown | 28 ++++---- website/docs/registry/index.html.md | 2 +- website/docs/registry/modules/publish.html.md | 24 ++++--- website/docs/registry/modules/use.html.md | 37 ++++++++-- website/docs/registry/private.html.md | 69 ++++++++----------- 7 files changed, 153 insertions(+), 85 deletions(-) diff --git a/website/docs/commands/cli-config.html.markdown b/website/docs/commands/cli-config.html.markdown index f70e04669..e63dec699 100644 --- a/website/docs/commands/cli-config.html.markdown +++ b/website/docs/commands/cli-config.html.markdown @@ -7,17 +7,13 @@ description: |- configuration file. --- -# CLI Configuration File +# CLI Configuration File (`.terraformrc`/`terraform.rc`) -The CLI configuration file allows customization of some behaviors of the -Terraform CLI in general. This is separate from -[your infrastructure configuration](/docs/configuration/index.html), and -provides per-user customization that applies regardless of which working -directory Terraform is being applied to. +The CLI configuration file configures per-user settings for CLI behaviors, +which apply across all Terraform working directories. This is separate from +[your infrastructure configuration](/docs/configuration/index.html). -For example, the CLI configuration file can be used to activate a shared -plugin cache directory that allows provider plugins to be shared between -different working directories, as described in more detail below. +## Location The configuration is placed in a single file whose location depends on the host operating system: @@ -52,18 +48,40 @@ disable_checkpoint = true The following settings can be set in the CLI configuration file: -* `disable_checkpoint` - when set to `true`, disables +- `disable_checkpoint` — when set to `true`, disables [upgrade and security bulletin checks](/docs/commands/index.html#upgrade-and-security-bulletin-checks) that require reaching out to HashiCorp-provided network services. -* `disable_checkpoint_signature` - when set to `true`, allows the upgrade and +- `disable_checkpoint_signature` — when set to `true`, allows the upgrade and security bulletin checks described above but disables the use of an anonymous id used to de-duplicate warning messages. -* `plugin_cache_dir` - enables +- `plugin_cache_dir` — enables [plugin caching](/docs/configuration/providers.html#provider-plugin-cache) and specifies, as a string, the location of the plugin cache directory. +- `credentials` — provides credentials for use with Terraform Enterprise's + [private module registry.](/docs/enterprise/registry/index.html) This is + only necessary when running Terraform on the command line; runs managed by + Terraform Enterprise can access private modules automatically. + + This setting is a repeatable block, where the block label is a hostname + (either `app.terraform.io` or the hostname of your private install) and + the block body contains a `token` attribute. Whenever Terraform requests + module data from that hostname, it will authenticate with that token. + + ``` hcl + credentials "app.terraform.io" { + token = "xxxxxx.atlasv1.zzzzzzzzzzzzz" + } + ``` + + ~> **Note:** The credentials hostname must match the hostname in your module + sources. If your Terraform Enterprise instance is available at multiple + hostnames, use one of them consistently. (The SaaS version of Terraform + Enterprise responds to API calls at both its newer hostname, + app.terraform.io, and its historical hostname, atlas.hashicorp.com.) + ## Deprecated Settings The following settings are supported for backward compatibility but are no diff --git a/website/docs/modules/sources.html.markdown b/website/docs/modules/sources.html.markdown index d759762b1..bad5abed6 100644 --- a/website/docs/modules/sources.html.markdown +++ b/website/docs/modules/sources.html.markdown @@ -47,12 +47,16 @@ Updates for file paths are automatic: when "downloading" the module using the [g The [Terraform Registry](https://registry.terraform.io) is an index of modules written by the Terraform community. The Terraform Registry is the easiest -way to get started with Terraform and to find modules to start with. -The registry is integrated directly into Terraform: +way to get started with Terraform and to find modules. + +The registry is integrated directly into Terraform. You can reference any +registry module with a source string of `//`. Each +module's information page on the registry includes its source string. ```hcl module "consul" { source = "hashicorp/consul/aws" + version = "0.1.0" } ``` @@ -60,9 +64,33 @@ The above example would use the [Consul module for AWS](https://registry.terraform.io/modules/hashicorp/consul/aws) from the public registry. +Registry modules support versioning. You can provide a specific version, or use +flexible [version constraints](/docs/modules/usage.html#module-versions). + You can learn more about the registry at the [Terraform Registry documentation](/docs/registry/modules/use.html#using-modules). +## Private Registries + +[Terraform Enterprise](https://www.hashicorp.com/products/terraform) provides a +[private module registry](/docs/enterprise/registry/index.html), to help +you share code within your organization. Other services can also provide +private registries by implementing [Terraform's registry API](/docs/registry/api.html). + +Source strings for private registry modules are similar to public modules, but +also include a hostname. They should follow the format +`///`. + +```hcl +module "vpc" { + source = "app.terraform.io/example_corp/vpc/aws" + version = "0.9.3" +} +``` + +Modules from private registries support versioning, just like modules from the +public Terraform Registry. + ## GitHub Terraform will automatically recognize GitHub URLs and turn them into a link to the specific Git repository. The syntax is simple: @@ -100,7 +128,9 @@ You can use the same parameters to GitHub repositories as you can generic Git re 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. - 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. -- If you use Terraform Enterprise, you can use SSH URIs. 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) +- 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.) + + 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) - 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: ```hcl diff --git a/website/docs/modules/usage.html.markdown b/website/docs/modules/usage.html.markdown index d49cd776f..64ff092b6 100644 --- a/website/docs/modules/usage.html.markdown +++ b/website/docs/modules/usage.html.markdown @@ -36,9 +36,11 @@ The only required configuration key for a module is the `source` parameter. The value of this tells Terraform where to download the module's source code. Terraform comes with support for a variety of module sources. -The recommended source for external modules is a -[Terraform Registry](/docs/registry/index.html), which provides the full -capabilities of modules such as version constraints. +We recommend using modules from the public [Terraform Registry](/docs/registry/index.html) +or from [Terraform Enterprise's private module registry](/docs/enterprise/registry/index.html). +These sources support version constraints for a more reliable experience, and +provide a searchable marketplace for finding the modules you need. + Registry modules are specified using a simple slash-separated path like the `hashicorp/consul/aws` path used in the above example. The full source string for each registry module can be found from the registry website. @@ -72,11 +74,10 @@ a newer version will be used only if it is within the given constraint. ## Module Versions -It is recommended to explicitly constrain the acceptable version numbers for -each external module so that upstream changes aren't automatically adopted, -since this may result in unexpected or unwanted changes changes. +We recommend explicitly constraining the acceptable version numbers for +each external module to avoid unexpected or unwanted changes. -The `version` attribute within the `module` block is used for this purpose: +Use the `version` attribute in the `module` block to specify versions: ```shell module "consul" { @@ -105,12 +106,13 @@ may be appropriate if a semantic versioning methodology is used consistently or if there is a well-defined release process that avoids unwanted updates. Version constraints are supported only for modules installed from a module -registry, such as the [Terraform Registry](https://registry.terraform.io/). -Other module sources may provide their own versioning mechanisms within the -source string itself, or they may not support versions at all. In particular, -modules whose sources are local file paths do not support `version` because -they are constrained to share the same version as their caller by being -obtained by the same source repository. +registry, such as the [Terraform Registry](https://registry.terraform.io/) or +[Terraform Enterprise's private module registry](/docs/enterprise/registry/index.html). +Other module sources can provide their own versioning mechanisms within the +source string itself, or might not support versions at all. In particular, +modules sourced from local file paths do not support `version`; since +they're loaded from the same source repository, they always share the same +version as their caller. ## Configuration diff --git a/website/docs/registry/index.html.md b/website/docs/registry/index.html.md index 8ae94ad59..ac7e942bd 100644 --- a/website/docs/registry/index.html.md +++ b/website/docs/registry/index.html.md @@ -9,7 +9,7 @@ description: |- # Terraform Registry The [Terraform Registry](https://registry.terraform.io) is a repository -of modules written by the Terraform community. The registry can be used to +of modules written by the Terraform community. The registry can help you get started with Terraform more quickly, see examples of how Terraform is written, and find pre-made modules for infrastructure components you require. diff --git a/website/docs/registry/modules/publish.html.md b/website/docs/registry/modules/publish.html.md index b53e578d0..f7a870fd0 100644 --- a/website/docs/registry/modules/publish.html.md +++ b/website/docs/registry/modules/publish.html.md @@ -29,28 +29,30 @@ Meeting the requirements for publishing a module is extremely easy. The list may appear long only to ensure we're detailed, but adhering to the requirements should happen naturally. -* **GitHub.** The module must be on GitHub and must be a public repo. +- **GitHub.** The module must be on GitHub and must be a public repo. This is only a requirement for the [public registry](https://registry.terraform.io). If you're using a private registry, you may ignore this requirement. -* **Repository name.** The repository name must be `terraform-PROVIDER-NAME` -where PROVIDER is the primary provider to associate with the module and -NAME is a unique name for the module. The name may contain hyphens. Example: -`terraform-aws-consul` or `terraform-google-vault`. +- **Named `terraform--`.** Module repositories must use this +three-part name format, where `` reflects the type of infrastructure the +module manages and `` is the main provider where it creates that +infrastructure. The `` segment can contain additional hyphens. Examples: +`terraform-google-vault` or `terraform-aws-ec2-instance`. -* **Repository description.** The GitHub repository description is used +- **Repository description.** The GitHub repository description is used to populate the short description of the module. This should be a simple one sentence description of the module. -* **Standard Module Structure.** The module must adhere to the +- **Standard module structure.** The module must adhere to the [standard module structure](/docs/modules/create.html#standard-module-structure). This allows the registry to inspect your module and generate documentation, track resource usage, and more. -* **Tags for Releases.** Releases are detected by creating and pushing -tags. The tag name must be a semantic version that can optionally be prefixed -with a `v`. Examples are `v1.0.4` and `0.9.2`. To publish a module initially, -at least one release tag must be present. +- **`x.y.z` tags for releases.** The registry uses tags to identify module +versions. Release tag names must be a [semantic version](http://semver.org), +which can optionally be prefixed with a `v`. For example, `v1.0.4` and `0.9.2`. +To publish a module initially, at least one release tag must be present. Tags +that don't look like version numbers are ignored. ## Publishing a Public Module diff --git a/website/docs/registry/modules/use.html.md b/website/docs/registry/modules/use.html.md index 433095c3d..9623d7fb0 100644 --- a/website/docs/registry/modules/use.html.md +++ b/website/docs/registry/modules/use.html.md @@ -21,20 +21,21 @@ terms. On the results page, filters can be used further refine search results. By default, only [verified modules](/docs/registry/modules/verified.html) are shown in search results. Verified modules are reviewed by HashiCorp to -ensure stability and compatibility. By using the filters, you may view unverified +ensure stability and compatibility. By using the filters, you can view unverified modules as well. ## Using Modules The Terraform Registry is integrated directly into Terraform. This makes it easy to reference any module in the registry. The syntax for referencing -a registry module is `namespace/name/provider`. For example: +a registry module is `//`. For example: `hashicorp/consul/aws`. ~> **Note:** Module registry integration was added in Terraform v0.10.6, and full versioning support in v0.11.0. When viewing a module on the registry on a tablet or desktop, usage instructions -are shown on the right side. You can copy and paste this to get started with any module. Some modules may +are shown on the right side. +You can copy and paste this to get started with any module. Some modules have required inputs you must set before being able to use the module. ```hcl @@ -44,6 +45,30 @@ module "consul" { } ``` +The `terraform init` command will download and cache any modules referenced by +a configuration. + +### Private Registry Module Sources + +You can also use modules from a private registry, like the one provided by +Terraform Enterprise. Private registry modules have source strings of the form +`///`. This is the same format as the +public registry, but with an added hostname prefix. + +```hcl +module "vpc" { + source = "app.terraform.io/example_corp/vpc/aws" + version = "0.9.3" +} +``` + +Depending on the registry you're using, you might also need to configure +credentials to access modules. See your registry's documentation for details. +[Terraform Enterprise's private registry is documented here.](/docs/enterprise/registry/index.html) + +Private registry module sources are supported in Terraform v0.11.0 and +newer. + ## Module Versions Each module in the registry is versioned. These versions syntactically must @@ -54,6 +79,6 @@ Terraform since version 0.11 will resolve any provided [module version constraints](/docs/modules/usage.html#module-versions) and using them is highly recommended to avoid pulling in breaking changes. -Terraform from version 10.6 through to 0.11 had partial support for the registry -protocol, however will not honor version constraints and always download the -latest version. +Terraform versions after 0.10.6 but before 0.11 have partial support for the registry +protocol, but always download the latest version instead of honoring version +constraints. diff --git a/website/docs/registry/private.html.md b/website/docs/registry/private.html.md index 16b63cf80..1d7380bde 100644 --- a/website/docs/registry/private.html.md +++ b/website/docs/registry/private.html.md @@ -3,52 +3,43 @@ layout: "registry" page_title: "Terraform Registry - Private Registry" sidebar_current: "docs-registry-private" description: |- - Terraform is capable of loading modules from private registries for private modules via Terraform Enterprise. + Terraform can load private modules from private registries via Terraform Enterprise. --- -# Private Registry +# Private Registries The registry at [registry.terraform.io](https://registry.terraform.io) -may only host public modules. Terraform is capable of loading modules from -private registries for private modules. +only hosts public modules, but most organizations have some modules that +can't, shouldn't, or don't need to be public. -Official private registries are available via [Terraform Enterprise](https://www.hashicorp.com/products/terraform). -There are two tiers: Pro and Enterprise. The Pro version is only available -as a SaaS service whereas the Enterprise version is available for private -install. Both versions fully support private registries. +You can load private modules [directly from version control and other +sources](/docs/modules/sources.html), but those sources don't support [version +constraints](/docs/modules/usage.html#module-versions) or a browsable +marketplace of modules, both of which are important for enabling a +producers-and-consumers content model in a large organization. -Terraform interacts with module registries using [the registry API](/docs/registry/api.html). +If your organization is specialized enough that teams frequently use modules +created by other teams, you will benefit from a private module registry. + +## Terraform Enterprise's Private Registry + +[Terraform Enterprise](https://www.hashicorp.com/products/terraform) (TFE) +includes a private module registry, available at both Pro and Premium tiers. + +It uses the same VCS-backed tagged release workflow as the Terraform Registry, +but imports modules from your private VCS repos (on any of TFE's supported VCS +providers) instead of requiring public GitHub repos. You can seamlessly +reference private modules in your Terraform configurations (just include a +hostname in the module source), and TFE's UI provides a searchable marketplace +of private modules to help your users find the code they need. + +[Terraform Enterprise's private module registry is documented here.](/docs/enterprise/registry/index.html) + +## Other Private Registries + +Terraform can use versioned modules from any service that implements +[the registry API](/docs/registry/api.html). The Terraform open source project does not provide a server implementation, but we welcome community members to create their own private registries by following the published protocol. -Modules can alternatively be referenced -[directly from version control and other sources](/docs/modules/sources.html), -but only registry modules support certain features such as -[version constraints](/docs/modules/usage.html#module-versions). - -## Private Registry Module Sources - -Public Terraform Registry modules have source strings of the form -`namespace/name/provider`. Private registries -- whether integrated into -Terraform Enterprise or via a third-party implementation -- require an -additional hostname prefix: - -```hcl -module "example" { - source = "example.com/namespace/name/provider" -} -``` - -Private registry module sources are supported in Terraform v0.11.0 and -newer. - -## Coming Soon - -Terraform Enterprise will be publicly available for self service signup -soon. In the mean time, if you're interested in private -registries and being part of the beta, please contact us at -[hello@hashicorp.com](mailto:hello@hashicorp.com). - -When Terraform Enterprise is publicly available, Private Registry documentation -will be available here.