website: publishing and private registry docs

This commit is contained in:
Mitchell Hashimoto 2017-08-17 21:19:49 -07:00 committed by Paul Banks
parent de50eeb6b6
commit e71b271492
4 changed files with 135 additions and 2 deletions

View File

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

View File

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

View File

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

View File

@ -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") %>>