website: publishing and private registry docs
This commit is contained in:
parent
de50eeb6b6
commit
e71b271492
|
@ -190,3 +190,24 @@ $ tree complete-module/
|
|||
│ ├── exampleB/
|
||||
│ ├── .../
|
||||
```
|
||||
|
||||
## Publishing Modules
|
||||
|
||||
If you've built a module that you intend to be reused, we recommend
|
||||
[publishing the module](/docs/registry/module/publish.html) on the
|
||||
[Terraform Registry](https://registry.terraform.io). This will version
|
||||
your module, generate documentation, and more.
|
||||
|
||||
Published modules can be easily consumed by Terraform, and in Terraform
|
||||
0.11 you'll also be able to constrain module versions for safe and predictable
|
||||
updates. The following example shows how easy it is to consume a module
|
||||
from the registry:
|
||||
|
||||
```hcl
|
||||
module "consul" {
|
||||
source = "hashicorp/consul/aws"
|
||||
}
|
||||
```
|
||||
|
||||
You can also gain all the benefits of the registry for private modules
|
||||
by signing up for a [private registry](/docs/registry/private.html).
|
||||
|
|
|
@ -3,11 +3,83 @@ layout: "registry"
|
|||
page_title: "Terraform Registry - Publishing Modules"
|
||||
sidebar_current: "docs-registry-publish"
|
||||
description: |-
|
||||
TODO
|
||||
Anyone can publish and share modules on the Terraform Registry.
|
||||
---
|
||||
|
||||
# Publishing Modules
|
||||
|
||||
Anyone can publish and share modules on the [Terraform Registry](https://registry.terraform.io).
|
||||
|
||||
TODO
|
||||
Published modules support versioning, automatically generate documentation,
|
||||
allow browsing version histories, show examples and READMEs, and more. We
|
||||
recommend publishing reusable modules to a registry.
|
||||
|
||||
Public modules are managed via Git and GitHub. Publishing a module takes only
|
||||
a few minutes. Once a module is published, you can release a new version of
|
||||
a module by simply pushing a properly formed Git tag.
|
||||
|
||||
The registry extracts the name of the module, the provider, the documentation,
|
||||
inputs/outputs, and more directly from the source of the module. No manual
|
||||
annotations are required.
|
||||
|
||||
## Requirements
|
||||
|
||||
The list below contains all the requirements for publishing a module.
|
||||
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.
|
||||
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.
|
||||
|
||||
* **Repostory 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`.
|
||||
|
||||
* **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.
|
||||
|
||||
## Publishing a Public Module
|
||||
|
||||
With the requirements met, you can publish a public module by going to
|
||||
the [Terraform Registry](https://registry.terraform.io) and clicking the
|
||||
"Upload" link in the top navigation.
|
||||
|
||||
If you're not signed in, this will ask you to connect with GitHub. We only
|
||||
ask for access to public repositories, since the public registry may only
|
||||
publish public modules. We require access to hooks so we can register a webhook
|
||||
with your repository. We require access to your email address so that we can
|
||||
email you alerts about your module. We will not spam you.
|
||||
|
||||
The upload page will list your available repositories. This is shown in the
|
||||
screenshot below. Select the repository of the module you want to add and
|
||||
click "Create Module."
|
||||
|
||||
In a few seconds, your module will be created.
|
||||
|
||||
## Releasing New Versions
|
||||
|
||||
The Terraform Registry uses tags to detect releases.
|
||||
|
||||
Tag names must be a valid [semantic version](http://semver.org), optionally
|
||||
prefixed with a `v`. Example of valid tags are: `v1.0.1` and `0.9.4`. To publish
|
||||
a new module, you must already have at least one tag created.
|
||||
|
||||
To release a new version, create and push a new tag with the proper format.
|
||||
The webhook will notify the registry of the new version and it will appear
|
||||
on the registry usually in less than a minute.
|
||||
|
||||
If your version doesn't appear properly, you may force a sync with GitHub
|
||||
by viewing your module on the registry and clicking "Force GitHub Sync"
|
||||
under the "Manage Module" dropdown. This process may take a few minutes.
|
||||
Please only do this if you do not see the version appear, since it will
|
||||
cause the registry to resync _all versions_ of your module.
|
||||
|
|
|
@ -0,0 +1,36 @@
|
|||
---
|
||||
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.
|
||||
---
|
||||
|
||||
# Private Registry
|
||||
|
||||
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.
|
||||
|
||||
Official private registries are available via [Terraform Enterprise](#).
|
||||
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.
|
||||
|
||||
The Terraform project does not provide any free or open source solution
|
||||
to have a private registry. Terraform only requires that the
|
||||
[read API](/docs/registry/api.html) to be
|
||||
available to load modules from a registry. We welcome the community to create
|
||||
their own private registries by recreating this API.
|
||||
|
||||
## Coming Soon
|
||||
|
||||
Terraform Enterprise is currently in beta and does not allow open signups.
|
||||
|
||||
Terraform Enterprise will be publicly available for self service signup
|
||||
by the end of 2017. 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, the documentation will
|
||||
be available here.
|
|
@ -28,6 +28,10 @@
|
|||
</ul>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-registry-private") %>>
|
||||
<a href="/docs/registry/private.html">Private Registry</a>
|
||||
</li>
|
||||
|
||||
<hr>
|
||||
|
||||
<li<%= sidebar_current("docs-registry-api") %>>
|
||||
|
|
Loading…
Reference in New Issue