resilien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

website: private module registry documentation

This commit is contained in:
Nick Fagerlund 2018-02-07 09:15:55 -08:00 committed by Martin Atkins
parent 178cca7d01
commit 07c3893653
7 changed files with 153 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
website/docs/commands/cli-config.html.markdown
View File

@ -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

36
website/docs/modules/sources.html.markdown
View File

@ -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 `<NAMESPACE>/<NAME>/<PROVIDER>`. 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
`<HOSTNAME>/<NAMESPACE>/<NAME>/<PROVIDER>`.
```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

28
website/docs/modules/usage.html.markdown
View File

@ -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

2
website/docs/registry/index.html.md
View File

@ -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.

24
website/docs/registry/modules/publish.html.md
View File

@ -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-<PROVIDER>-<NAME>`.** Module repositories must use this
three-part name format, where `<NAME>` reflects the type of infrastructure the
module manages and `<PROVIDER>` is the main provider where it creates that
infrastructure. The `<NAME>` 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

37
website/docs/registry/modules/use.html.md
View File

@ -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 `<NAMESPACE>/<NAME>/<PROVIDER>`. 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
`<HOSTNAME>/<NAMESPACE>/<NAME>/<PROVIDER>`. 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.

69
website/docs/registry/private.html.md
View File

@ -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.