From 1c098ce4ec6efe532a83be4ec8e1f12f5d37d6b9 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Mon, 14 Aug 2017 17:19:00 -0700 Subject: [PATCH 01/16] website: trivial change to make branch --- website/layouts/docs.erb | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/website/layouts/docs.erb b/website/layouts/docs.erb index 5457337f99..4aa9ca890e 100644 --- a/website/layouts/docs.erb +++ b/website/layouts/docs.erb @@ -510,6 +510,10 @@ Sources + > + Registry + + > Creating Modules From bf7f4d243db0b83a47efbf7dd912bdbbc5b39389 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Mon, 14 Aug 2017 23:35:33 -0700 Subject: [PATCH 02/16] website: working on registry docs --- website/docs/modules/create.html.markdown | 9 +++++ website/docs/modules/sources.html.markdown | 26 +++++++++++++- website/docs/modules/usage.html.markdown | 21 +++++++++--- website/docs/registry/index.html.md | 35 +++++++++++++++++++ website/layouts/docs.erb | 4 +-- website/layouts/registry.erb | 40 ++++++++++++++++++++++ 6 files changed, 127 insertions(+), 8 deletions(-) create mode 100644 website/docs/registry/index.html.md create mode 100644 website/layouts/registry.erb diff --git a/website/docs/modules/create.html.markdown b/website/docs/modules/create.html.markdown index 860c56564f..a3a25d4a7d 100644 --- a/website/docs/modules/create.html.markdown +++ b/website/docs/modules/create.html.markdown @@ -14,6 +14,11 @@ the Terraform files you're applying comprise what is called the _root module_. T Therefore, you can enter the source of any module, satisfy any required variables, run `terraform apply`, and expect it to work. +Modules that are created for reuse should follow the +[standard structure](#standard-structure). This structure enables tooling +such as the [Terraform Registry](/docs/registry/index.html) to inspect and +generate documentation, read examples, and more. + ## An Example Module Within a folder containing Terraform configurations, create a subfolder called `child`. In this subfolder, make one empty `main.tf` file. Then, back in the root folder containing the `child` folder, add this to one of your Terraform configuration files: @@ -89,3 +94,7 @@ variables and outputs you require. The [get command](/docs/commands/get.html) will automatically get all nested modules. You don't have to worry about conflicting versions of modules, since Terraform builds isolated subtrees of all dependencies. For example, one module might use version 1.0 of module `foo` and another module might use version 2.0, and this will all work fine within Terraform since the modules are created separately. + +## Standard Structure + +TODO diff --git a/website/docs/modules/sources.html.markdown b/website/docs/modules/sources.html.markdown index e5b1a971a7..441bdc29fe 100644 --- a/website/docs/modules/sources.html.markdown +++ b/website/docs/modules/sources.html.markdown @@ -7,14 +7,17 @@ description: Explains the use of the source parameter, which tells Terraform whe # Module Sources -As documented in the [Usage section](/docs/modules/usage.html), the only required parameter when using a module is `source`. The `source` parameter tells Terraform where the module can be found and what constraints to put on the module. Constraints can include a specific version or Git branch. +As documented in the [Usage section](/docs/modules/usage.html), the only required parameter when using a module is `source`. +The `source` parameter tells Terraform where the module can be found. 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. Terraform supports the following sources: * Local file paths + * [Terraform Registry](/docs/registry/index.html) + * GitHub * Bitbucket @@ -39,6 +42,27 @@ module "consul" { 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. +## Terraform Registry + +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: + +```hcl +module "consul" { + source = "hashicorp/consul/aws" +} +``` + +The above example would use the +[Consul module for AWS](https://registry.terraform.io/modules/hashicorp/consul/aws) +from the public registry. + +You can learn more about the registry at the +[Terraform Registry documentation section](/docs/registry/index.html). + ## GitHub Terraform will automatically recognize GitHub URLs and turn them into a link to the specific Git repository. The syntax is simple: diff --git a/website/docs/modules/usage.html.markdown b/website/docs/modules/usage.html.markdown index 79782a746f..3ba349e57a 100644 --- a/website/docs/modules/usage.html.markdown +++ b/website/docs/modules/usage.html.markdown @@ -11,16 +11,21 @@ Using modules in Terraform is very similar to defining resources: ```shell module "consul" { - source = "github.com/hashicorp/consul/terraform/aws" + source = "hashicorp/consul/aws" servers = 3 } ``` You can view the full documentation for configuring modules in the [Module Configuration](/docs/configuration/modules.html) section. -In modules we only specify a name rather than a name and a type (as in resources). This name can be used elsewhere in the configuration to reference the module and its variables. +In modules we only specify a name rather than a name and a type (as in resources). This name can be used elsewhere in the configuration to reference the module and its outputs. -The existence of the above configuration will tell Terraform to create the resources in the `consul` module which can be found on GitHub at the given URL. Just like a resource, the module configuration can be deleted to remove the module. +The source tells Terraform what to create. In this example, we create +the [Consul module for AWS](https://registry.terraform.io/modules/hashicorp/consul/aws) +from the [Terraform Registry](https://registry.terraform.io). You can learn +more about the [source configuration below](#source). + +Just like a resource, the module configuration can be deleted to remove the module. ## Multiple instances of a module @@ -62,8 +67,14 @@ The resource names in your module get prefixed by `module.Sources - > - Registry + > + Registry > diff --git a/website/layouts/registry.erb b/website/layouts/registry.erb new file mode 100644 index 0000000000..83abe4bc53 --- /dev/null +++ b/website/layouts/registry.erb @@ -0,0 +1,40 @@ +<% wrap_layout :inner do %> + <% content_for :sidebar do %> + + <% end %> + + <%= yield %> +<% end %> From 0718e9ce3f4fc70df507308102d85c567abf744d Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Tue, 15 Aug 2017 09:03:53 -0700 Subject: [PATCH 03/16] website: standard module structure --- website/docs/modules/create.html.markdown | 96 ++++++++++++++++++++++- 1 file changed, 94 insertions(+), 2 deletions(-) diff --git a/website/docs/modules/create.html.markdown b/website/docs/modules/create.html.markdown index a3a25d4a7d..a94595b066 100644 --- a/website/docs/modules/create.html.markdown +++ b/website/docs/modules/create.html.markdown @@ -95,6 +95,98 @@ The [get command](/docs/commands/get.html) will automatically get all nested mod You don't have to worry about conflicting versions of modules, since Terraform builds isolated subtrees of all dependencies. For example, one module might use version 1.0 of module `foo` and another module might use version 2.0, and this will all work fine within Terraform since the modules are created separately. -## Standard Structure +## Standard Module Structure + +The standard module structure is a file and folder layout we recommend for +reusable modules. Terraform tooling is built to understand the standard +module structure and use that structure to generate documentation, index +modules for the registry, and more. + +The standard module expects the structure documented below. The list may appear +long, but everything is optional except for the root module. All items are +documented in detail. Most modules don't need to do any work to follow the +standard structure. + +* **Root module**. This is the **only required element** for the standard + module structure. Terraform files must exist in the root directory of + the module. This should be the primary entrypoint for the module and is + expected to be opinionated. For the + [Consul module](#) + the root module sets up a complete Consul cluster. A lot of assumptions + are made, however, and it is fully expected that advanced users will use + specific nested modules to more carefully control what they want. + +* **README**. The root module and any nested modules should have README + files. This file should be named `README` or `README.md`. The latter will + be treated as markdown. The README doesn't need to document inputs or + outputs of the module because tooling will automatically generate this. + + +* **main.tf, variables.tf, outputs.tf**. These are the recommended filenames for + a minimal module, even if they're empty. `main.tf` should be the primary + entrypoint. For a simple module, this may be where all the resources are + created. For a complex module, resource creation may be split into multiple + files but all nested module usage should be in the main file. `variables.tf` + and `outputs.tf` should contain the declarations for variables and outputs, + respectively. + +* **Variables and outputs should have descriptions.** All variables and + outputs should have one or two sentence descriptions that explain their + purpose. This is used for documentation. See the documentation for + [variable configuration](/docs/configuration/variables.html) and + [output configuration](/docs/configuration/outputs.html) for more details. + +* **Nested modules**. Nested modules should exist under the `modules/` + subdirectory. Any nested module with a `README.md` is considered usable + by an external user. If a README doesn't exist, it is considered for internal + use only. These are purely advisory; Terraform will not actively deny usage + of internal modules. Nested modules should be used to split complex behavior + into multiple small modules that advanced users can carefully pick and + choose. For example, the + [Consul module](#) + has a nested module for creating the Cluster that is separate from the + module to setup necessary IAM policies. This allows a user to bring in their + own IAM policy choices. + +* **Examples**. Examples of using the module should exist under the + `examples/` subdirectory. Each example may have a README to explain the + goal and usage of the example. + +A minimal recommended module following the standard structure is shown below. +While the root module is the only required element, we recommend below as +a minimum structure: + +```sh +$ tree minimal-module/ +. +├── README.md +├── main.tf +├── variables.tf +├── outputs.tf +``` -TODO +A complete example of a module following the standard structure is shown below. +This example includes all optional elements and is therefore the most +complex a module can become: + +```sh +$ tree complete-module/ +. +├── README.md +├── main.tf +├── variables.tf +├── outputs.tf +├── ... +├── modules/ +│   ├── nestedA/ +│   │   ├── variables.tf +│   │   ├── main.tf +│   │   ├── outputs.tf +│   ├── nestedB/ +│   ├── .../ +├── examples/ +│   ├── exampleA/ +│   │   ├── main.tf +│   ├── exampleB/ +│   ├── .../ +``` From 331b6f339a40dc4964f33191de60028b8281d1cf Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Tue, 15 Aug 2017 09:27:34 -0700 Subject: [PATCH 04/16] website: finding and using registry modules --- website/docs/registry/modules/use.html.md | 54 +++++++++++++++++++++++ website/layouts/registry.erb | 8 +++- 2 files changed, 60 insertions(+), 2 deletions(-) create mode 100644 website/docs/registry/modules/use.html.md diff --git a/website/docs/registry/modules/use.html.md b/website/docs/registry/modules/use.html.md new file mode 100644 index 0000000000..4e690f0e17 --- /dev/null +++ b/website/docs/registry/modules/use.html.md @@ -0,0 +1,54 @@ +--- +layout: "registry" +page_title: "Finding and Using Modules from the Terraform Registry" +sidebar_current: "docs-registry-use" +description: |- + The Terraform Registry is a repository of modules written by the Terraform community. +--- + +# Finding and Using Modules + +The [Terraform Registry](https://registry.terraform.io) makes it simple to +find and use modules. + +## Finding Modules + +Every page on the registry has a search field for finding +modules. Enter any type of module you're looking for (examples: "vault", +"vpc", "database") and resulting modules will be listed. The search query +will look at module name, provider, and description to match your search +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 +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: +`hashicorp/consul/aws`. + +When viewing a module on the registry on a tablet or desktop, usage instructions +are shown on the right side. The screenshot below shows where to find these. +You can copy and paste this to get started with any module. Some modules may +have required inputs you must set before being able to use the module. + +```hcl +module "consul" { + source = "hashicorp/consul/aws" +} +``` + +## Module Versions + +Each module in the registry is versioned. These versions syntactically must +follow [semantic versioning](http://semver.org/). In addition to pure syntax, +we encourge all modules to follow the full guidelines of semantic versioning. + +Terraform currently only downloads the latest version of each module. The +next release of Terraform (0.11) will bring full support for constraining +module versions. The registry has required semantic versions since launch +to prepare for this transition shortly after. diff --git a/website/layouts/registry.erb b/website/layouts/registry.erb index 83abe4bc53..730015543d 100644 --- a/website/layouts/registry.erb +++ b/website/layouts/registry.erb @@ -18,8 +18,12 @@ Finding and Using Modules - > - Publishing Modules + > + Publishing Modules + + + > + Verified Modules From b4f2fae0a659566cdcd5a4f80ee3ed40aca079b3 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Tue, 15 Aug 2017 13:13:31 -0700 Subject: [PATCH 05/16] website: api docs for the registry --- website/docs/registry/api.html.md | 186 ++++++++++++++++++++++ website/docs/registry/modules/use.html.md | 2 +- 2 files changed, 187 insertions(+), 1 deletion(-) create mode 100644 website/docs/registry/api.html.md diff --git a/website/docs/registry/api.html.md b/website/docs/registry/api.html.md new file mode 100644 index 0000000000..dd516a50f1 --- /dev/null +++ b/website/docs/registry/api.html.md @@ -0,0 +1,186 @@ +--- +layout: "registry" +page_title: "Terraform Registry - HTTP API" +sidebar_current: "docs-registry-api" +description: |- + The /acl endpoints create, update, destroy, and query ACL tokens in Consul. +--- + +# HTTP API + +The [Terraform Registry](https://registry.terraform.io) has an HTTP API for +reading and downloading registry modules. + +Terraform interacts with the registry only as read-only. Therefore, the +documented API is only read-only. +Any endpoints that aren't documented on this +page can and will likely change over time. This allows differing methods +for getting modules into a registry while keeping a consistent API for +reading modules in a registry. + +## List Latest Version of Module for All Providers + +This endpoint returns the latest version of each provider for a module. + +| Method | Path | Produces | +| ------ | ---------------------------- | -------------------------- | +| `GET` | `/v1/modules/:namespace/:name` | `application/json` | + +### Parameters + +- `namespace` `(string: )` - The user the module is owned by. + This is required and is specified as part of the URL path. + +- `name` `(string: )` - The name of the module. + This is required and is specified as part of the URL path. + +### Sample Request + +```text +$ curl \ + https://registry.terraform.io/v1/modules/hashicorp/consul +``` + +### Sample Response + +```json +TODO +``` + +## Latest Module for a Single Provider + +This endpoint returns the latest version of a module for a single provider. + +| Method | Path | Produces | +| ------ | ---------------------------- | -------------------------- | +| `GET` | `/v1/modules/:namespace/:name/:provider` | `application/json` | + +### Parameters + +- `namespace` `(string: )` - The user the module is owned by. + This is required and is specified as part of the URL path. + +- `name` `(string: )` - The name of the module. + This is required and is specified as part of the URL path. + +- `provider` `(string: )` - The name of the provider. + This is required and is specified as part of the URL path. + +### Sample Request + +```text +$ curl \ + https://registry.terraform.io/v1/modules/hashicorp/consul/aws +``` + +### Sample Response + +```json +TODO +``` + +## Get a Specific Module + +This endpoint returns the specified version of a module for a single provider. + +| Method | Path | Produces | +| ------ | ---------------------------- | -------------------------- | +| `GET` | `/v1/modules/:namespace/:name/:provider/:version` | `application/json` | + +### Parameters + +- `namespace` `(string: )` - The user the module is owned by. + This is required and is specified as part of the URL path. + +- `name` `(string: )` - The name of the module. + This is required and is specified as part of the URL path. + +- `provider` `(string: )` - The name of the provider. + This is required and is specified as part of the URL path. + +- `version` `(string: )` - The version of the module. + This is required and is specified as part of the URL path. + +### Sample Request + +```text +$ curl \ + https://registry.terraform.io/v1/modules/hashicorp/consul/aws/1.0.0 +``` + +### Sample Response + +```json +TODO +``` + +## Download a Specific Module + +This endpoint downloads the specified version of a module for a single provider. + +| Method | Path | Produces | +| ------ | ---------------------------- | -------------------------- | +| `GET` | `/v1/modules/:namespace/:name/:provider/:version/download` | `application/json` | + +### Parameters + +- `namespace` `(string: )` - The user the module is owned by. + This is required and is specified as part of the URL path. + +- `name` `(string: )` - The name of the module. + This is required and is specified as part of the URL path. + +- `provider` `(string: )` - The name of the provider. + This is required and is specified as part of the URL path. + +- `version` `(string: )` - The version of the module. + This is required and is specified as part of the URL path. + +### Sample Request + +```text +$ curl \ + https://registry.terraform.io/v1/modules/hashicorp/consul/aws/1.0.0/download +``` + +### Sample Response + +```json +TODO +``` + +## Download the Latest Version of a Module + +This endpoint downloads the latest version of a module for a single provider. + +| Method | Path | Produces | +| ------ | ---------------------------- | -------------------------- | +| `GET` | `/v1/modules/:namespace/:name/:provider/download` | `application/json` | + +### Parameters + +- `namespace` `(string: )` - The user the module is owned by. + This is required and is specified as part of the URL path. + +- `name` `(string: )` - The name of the module. + This is required and is specified as part of the URL path. + +- `provider` `(string: )` - The name of the provider. + This is required and is specified as part of the URL path. + +- `version` `(string: )` - The version of the module. + This is required and is specified as part of the URL path. + +### Sample Request + +```text +$ curl \ + https://registry.terraform.io/v1/modules/hashicorp/consul/aws/download +``` + +### Sample Response + +```json +TODO +``` + diff --git a/website/docs/registry/modules/use.html.md b/website/docs/registry/modules/use.html.md index 4e690f0e17..836adf5332 100644 --- a/website/docs/registry/modules/use.html.md +++ b/website/docs/registry/modules/use.html.md @@ -3,7 +3,7 @@ layout: "registry" page_title: "Finding and Using Modules from the Terraform Registry" sidebar_current: "docs-registry-use" description: |- - The Terraform Registry is a repository of modules written by the Terraform community. + The Terraform Registry makes it simple to find and use modules. --- # Finding and Using Modules From de50eeb6b69964cda7fbd4d17af83003d3a29dc9 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Tue, 15 Aug 2017 13:36:32 -0700 Subject: [PATCH 06/16] website: more registry docs --- website/docs/registry/modules/publish.html.md | 13 ++++++++ .../docs/registry/modules/verified.html.md | 32 +++++++++++++++++++ 2 files changed, 45 insertions(+) create mode 100644 website/docs/registry/modules/publish.html.md create mode 100644 website/docs/registry/modules/verified.html.md diff --git a/website/docs/registry/modules/publish.html.md b/website/docs/registry/modules/publish.html.md new file mode 100644 index 0000000000..946081583b --- /dev/null +++ b/website/docs/registry/modules/publish.html.md @@ -0,0 +1,13 @@ +--- +layout: "registry" +page_title: "Terraform Registry - Publishing Modules" +sidebar_current: "docs-registry-publish" +description: |- + TODO +--- + +# Publishing Modules + +Anyone can publish and share modules on the [Terraform Registry](https://registry.terraform.io). + +TODO diff --git a/website/docs/registry/modules/verified.html.md b/website/docs/registry/modules/verified.html.md new file mode 100644 index 0000000000..f133354d05 --- /dev/null +++ b/website/docs/registry/modules/verified.html.md @@ -0,0 +1,32 @@ +--- +layout: "registry" +page_title: "Terraform Registry - Verified Modules" +sidebar_current: "docs-registry-verified" +description: |- + Verified modules are reviewed by HashiCorp and actively maintained by contributors to stay up-to-date and compatible with both Terraform and their respective providers. +--- + +# Verified Modules + +Verified modules are reviewed by HashiCorp and actively maintained by +contributors to stay up-to-date and compatible with both Terraform and +their respective providers. + +The blue verification badge appears next to modules that are verified. + +TODO: Screenshot + +If a module is verified, it is promised to be actively maintained and of +high quality. It isn't indicative of flexibility or feature support; very +simple modules can be verified just because they're great examples of modules. +Likewise, an unverified module could be extremely high quality and actively +maintained. An unverified module shouldn't be assumed to be poor quality, it +only means it hasn't been created by a HashiCorp partner. + +Module verification is currently a manual process restricted to a small group +of trusted HashiCorp partners. In the coming months, we'll be expanding +verification to enable the broader community to verify their modules. + +When [using registry modules](/docs/registry/modules/use.html), there is no +difference between a verified and unverified module; they are used the same +way. From e71b2714921a67e0b3cd263a169f5bb22fa9dc81 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Thu, 17 Aug 2017 21:19:49 -0700 Subject: [PATCH 07/16] website: publishing and private registry docs --- website/docs/modules/create.html.markdown | 21 +++++ website/docs/registry/modules/publish.html.md | 76 ++++++++++++++++++- website/docs/registry/private.html.md | 36 +++++++++ website/layouts/registry.erb | 4 + 4 files changed, 135 insertions(+), 2 deletions(-) create mode 100644 website/docs/registry/private.html.md diff --git a/website/docs/modules/create.html.markdown b/website/docs/modules/create.html.markdown index a94595b066..c5ef846d6b 100644 --- a/website/docs/modules/create.html.markdown +++ b/website/docs/modules/create.html.markdown @@ -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). diff --git a/website/docs/registry/modules/publish.html.md b/website/docs/registry/modules/publish.html.md index 946081583b..07087f98d1 100644 --- a/website/docs/registry/modules/publish.html.md +++ b/website/docs/registry/modules/publish.html.md @@ -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. diff --git a/website/docs/registry/private.html.md b/website/docs/registry/private.html.md new file mode 100644 index 0000000000..4355cd2d64 --- /dev/null +++ b/website/docs/registry/private.html.md @@ -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. diff --git a/website/layouts/registry.erb b/website/layouts/registry.erb index 730015543d..76f4c300ad 100644 --- a/website/layouts/registry.erb +++ b/website/layouts/registry.erb @@ -28,6 +28,10 @@ + > + Private Registry + +
> From 9b363cd7d41ad5f2d55b2787b9da6db05c3481f2 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Wed, 23 Aug 2017 10:56:59 -0700 Subject: [PATCH 08/16] website: add LICENSE to standard module structure --- website/docs/modules/create.html.markdown | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/website/docs/modules/create.html.markdown b/website/docs/modules/create.html.markdown index c5ef846d6b..ca5b8901e4 100644 --- a/website/docs/modules/create.html.markdown +++ b/website/docs/modules/create.html.markdown @@ -121,6 +121,10 @@ standard structure. be treated as markdown. The README doesn't need to document inputs or outputs of the module because tooling will automatically generate this. +* **LICENSE**. The license under which this module is available. If you are + publishing a module publicly, many organizations will not adopt a module + unless a clear license is present. We recommend always having a license + file, even if the license is non-public. * **main.tf, variables.tf, outputs.tf**. These are the recommended filenames for a minimal module, even if they're empty. `main.tf` should be the primary From 3bb89e89d633ab4a6b47453052d0287aa734c7e2 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Mon, 28 Aug 2017 10:41:57 -0700 Subject: [PATCH 09/16] website: note repo desc for publishing, fix broken link --- website/docs/modules/create.html.markdown | 2 +- website/docs/registry/modules/publish.html.md | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/website/docs/modules/create.html.markdown b/website/docs/modules/create.html.markdown index ca5b8901e4..b26c3c69e2 100644 --- a/website/docs/modules/create.html.markdown +++ b/website/docs/modules/create.html.markdown @@ -198,7 +198,7 @@ $ tree complete-module/ ## 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 +[publishing the module](/docs/registry/modules/publish.html) on the [Terraform Registry](https://registry.terraform.io). This will version your module, generate documentation, and more. diff --git a/website/docs/registry/modules/publish.html.md b/website/docs/registry/modules/publish.html.md index 07087f98d1..44fc66f7d0 100644 --- a/website/docs/registry/modules/publish.html.md +++ b/website/docs/registry/modules/publish.html.md @@ -38,6 +38,10 @@ 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`. +* **Repostory 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](/docs/modules/create.html#standard-module-structure). This allows the registry to inspect your module and generate documentation, From 71b58abf9b9e2179d2fd7a1a1386e672c4498ce7 Mon Sep 17 00:00:00 2001 From: Paul Banks Date: Mon, 11 Sep 2017 20:11:02 +0100 Subject: [PATCH 10/16] Filling out API docs. Some TODOs remain --- website/docs/modules/create.html.markdown | 9 +- website/docs/registry/api.html.md | 365 +++++++++++++++++- website/docs/registry/modules/publish.html.md | 11 +- website/docs/registry/modules/use.html.md | 2 +- website/docs/registry/private.html.md | 11 +- 5 files changed, 366 insertions(+), 32 deletions(-) diff --git a/website/docs/modules/create.html.markdown b/website/docs/modules/create.html.markdown index b26c3c69e2..cd537cb48b 100644 --- a/website/docs/modules/create.html.markdown +++ b/website/docs/modules/create.html.markdown @@ -111,7 +111,7 @@ standard structure. module structure. Terraform files must exist in the root directory of the module. This should be the primary entrypoint for the module and is expected to be opinionated. For the - [Consul module](#) + [Consul module](https://registry.terraform.io/modules/hashicorp/consul) the root module sets up a complete Consul cluster. A lot of assumptions are made, however, and it is fully expected that advanced users will use specific nested modules to more carefully control what they want. @@ -147,7 +147,7 @@ standard structure. of internal modules. Nested modules should be used to split complex behavior into multiple small modules that advanced users can carefully pick and choose. For example, the - [Consul module](#) + [Consul module](https://registry.terraform.io/modules/hashicorp/consul) has a nested module for creating the Cluster that is separate from the module to setup necessary IAM policies. This allows a user to bring in their own IAM policy choices. @@ -157,8 +157,8 @@ standard structure. goal and usage of the example. A minimal recommended module following the standard structure is shown below. -While the root module is the only required element, we recommend below as -a minimum structure: +While the root module is the only required element, we recommend the structure +below as the minimum: ```sh $ tree minimal-module/ @@ -183,6 +183,7 @@ $ tree complete-module/ ├── ... ├── modules/ │   ├── nestedA/ +│   │   ├── README.md │   │   ├── variables.tf │   │   ├── main.tf │   │   ├── outputs.tf diff --git a/website/docs/registry/api.html.md b/website/docs/registry/api.html.md index dd516a50f1..50003e128d 100644 --- a/website/docs/registry/api.html.md +++ b/website/docs/registry/api.html.md @@ -11,12 +11,54 @@ description: |- The [Terraform Registry](https://registry.terraform.io) has an HTTP API for reading and downloading registry modules. -Terraform interacts with the registry only as read-only. Therefore, the -documented API is only read-only. -Any endpoints that aren't documented on this -page can and will likely change over time. This allows differing methods -for getting modules into a registry while keeping a consistent API for -reading modules in a registry. +Terraform interacts with the registry as read-only. Therefore, the documented +API is read-only. Any endpoints that aren't documented on this page can and will +likely change over time. This allows differing methods for getting modules into +the registry while keeping a consistent API for reading modules in the registry. + +## HTTP Status Codes + +The API follows regular HTTP status semantics. To make implementing a complete +client easier, some details on our policy and potential future status codes are +listed below. A robust client should consider how to handle all of the +following. + + - **Success:** Return status is `200` on success with a body or `204` if there + is no body data to return. + - **Redirects:** Moved or aliased endpoints redirect with a `301`. Endpoints + redirecting to the latest version of a module may redirect with `302` or + `307` to indicate that they logically point to different resources over time. + - **Client Errors:** Invalid requests will receive the relevant `4xx` status. + Except where noted below, the request should not be retried. + - **Rate Limiting:** Clients placing excessive load on the service might be + rate-limited and receive a `429` code. This should be interpreted as a sign + to slow down, and wait some time before retrying the request. + - **Service Errors:** The usual `5xx` errors will be returned for service + failures. In all cases it is safe to retry the request after receiving a + `5xx` response. + - **Load Shedding:** A `503` response indicates that the service is under load + and can't process your request immediately. As with other `5xx` errors you + may retry after some delay, although clients should consider being more + lenient with retry schedule in this case. + +## Error Responses + +When a `4xx` or `5xx` status code is returned. The response payload will look +like the following example: + +```json +{ + "errors": [ + "something bad happened" + ] +} +``` + +The `errors` key is a list containing one or more strings where each string +describes an error that has occurred. + +Note that it is possible that some `5xx` errors might result in a response that +is not in JSON format above due to being returned by an intermediate proxy. ## List Latest Version of Module for All Providers @@ -28,8 +70,8 @@ This endpoint returns the latest version of each provider for a module. ### Parameters -- `namespace` `(string: )` - The user the module is owned by. - This is required and is specified as part of the URL path. +- `namespace` `(string: )` - The user or organization the module is + owned by. This is required and is specified as part of the URL path. - `name` `(string: )` - The name of the module. This is required and is specified as part of the URL path. @@ -38,13 +80,40 @@ This endpoint returns the latest version of each provider for a module. ```text $ curl \ - https://registry.terraform.io/v1/modules/hashicorp/consul + https://registry.terraform.io/v1/modules/examplecorp/vapordb ``` ### Sample Response ```json -TODO +[ + { + "id": "examplecorp/vapordb/aws/1.0.0", + "owner": "wispy", + "namespace": "examplecorp", + "name": "vapordb", + "version": "1.0.0", + "provider": "aws", + "description": "Terraform Module for running VaporDB on AWS", + "source": "https://github.com/examplecorp/terraform-aws-vapordb", + "published_at": "2017-09-01T22:30:19.181077Z", + "downloads": 2, + "verified": true + }, + { + "id": "examplecorp/vapordb/azurerm/1.0.0", + "owner": "wispy", + "namespace": "examplecorp", + "name": "vapordb", + "version": "1.0.0", + "provider": "azurerm", + "description": "Terraform Module for running VaporDB on Azure", + "source": "https://github.com/examplecorp/terraform-azurerm-vapordb", + "published_at": "2017-09-01T22:30:19.181077Z", + "downloads": 2, + "verified": true + } +] ``` ## Latest Module for a Single Provider @@ -70,13 +139,142 @@ This endpoint returns the latest version of a module for a single provider. ```text $ curl \ - https://registry.terraform.io/v1/modules/hashicorp/consul/aws + https://registry.terraform.io/v1/modules/Azure/network/azurerm ``` ### Sample Response ```json -TODO +{ + "id": "Azure/network/azurerm/0.9.3", + "owner": "echuvyrov", + "namespace": "Azure", + "name": "network", + "version": "0.9.3", + "provider": "azurerm", + "description": "Terraform Azure RM Module for Network", + "source": "https://github.com/Azure/terraform-azurerm-network", + "published_at": "2017-09-01T22:30:19.181077Z", + "downloads": 0, + "verified": false, + "root": { + "path": "", + "readme": "Create a basic network in Azure\n==============================================================================\n\nThis Terraform module deploys a Virtual Network in Azure with the following characteristics: ...", + "empty": false, + "inputs": [ + { + "name": "resource_group_name", + "description": "Default resource group name that the network will be created in.", + "default": "\"myapp-rg\"" + }, + { + "name": "location", + "description": "The location/region where the core network will be created. The full list of Azure regions can be found at https://azure.microsoft.com/regions", + "default": "" + }, + { + "name": "address_space", + "description": "The address space that is used by the virtual network.", + "default": "\"10.0.0.0/16\"" + }, + { + "name": "dns_servers", + "description": "The DNS servers to be used with vNet.", + "default": "[]" + }, + { + "name": "subnet_prefixes", + "description": "The address prefix to use for the subnet.", + "default": "[\n \"10.0.1.0/24\"\n]" + }, + { + "name": "subnet_names", + "description": "A list of public subnets inside the vNet.", + "default": "[\n \"subnet1\"\n]" + }, + { + "name": "tags", + "description": "The tags to associate with your network and subnets.", + "default": "{\n \"tag1\": \"\",\n \"tag2\": \"\"\n}" + }, + { + "name": "allow_rdp_traffic", + "description": "This optional variable, when set to true, adds a security rule allowing RDP traffic to flow through to the newly created network. The default value is false.", + "default": "false" + }, + { + "name": "allow_ssh_traffic", + "description": "This optional variable, when set to true, adds a security rule allowing SSH traffic to flow through to the newly created network. The default value is false.", + "default": "false" + } + ], + "outputs": [ + { + "name": "vnet_id", + "description": "The id of the newly created vNet" + }, + { + "name": "vnet_name", + "description": "The Name of the newly created vNet" + }, + { + "name": "vnet_location", + "description": "The location of the newly created vNet" + }, + { + "name": "vnet_address_space", + "description": "The address space of the newly created vNet" + }, + { + "name": "vnet_dns_servers", + "description": "The DNS servers of the newly created vNet" + }, + { + "name": "vnet_subnets", + "description": "The ids of subnets created inside the newl vNet" + }, + { + "name": "security_group_id", + "description": "The id of the security group attached to subnets inside the newly created vNet. Use this id to associate additional network security rules to subnets." + } + ], + "dependencies": [], + "resources": [ + { + "name": "network", + "type": "azurerm_resource_group" + }, + { + "name": "vnet", + "type": "azurerm_virtual_network" + }, + { + "name": "subnet", + "type": "azurerm_subnet" + }, + { + "name": "security_group", + "type": "azurerm_network_security_group" + }, + { + "name": "security_rule_rdp", + "type": "azurerm_network_security_rule" + }, + { + "name": "security_rule_ssh", + "type": "azurerm_network_security_rule" + } + ] + }, + "submodules": null, + "providers": [ + "azurerm" + ], + "versions": [ + "0.9.2", + "0.9.3" + ] +} ``` ## Get a Specific Module @@ -105,19 +303,144 @@ This endpoint returns the specified version of a module for a single provider. ```text $ curl \ - https://registry.terraform.io/v1/modules/hashicorp/consul/aws/1.0.0 + https://registry.terraform.io/v1/modules/Azure/network/azurerm/0.9.2 ``` ### Sample Response ```json -TODO +{ + "id": "Azure/network/azurerm/0.9.2", + "owner": "echuvyrov", + "namespace": "Azure", + "name": "network", + "version": "0.9.2", + "provider": "azurerm", + "description": "Terraform Azure RM Module for Network", + "source": "https://github.com/Azure/terraform-azurerm-network", + "published_at": "2017-08-30T22:22:12.222113Z", + "downloads": 0, + "verified": false, + "root": { + "path": "", + "readme": "Create a basic network in Azure\n==============================================================================\n\nThis Terraform module deploys a Virtual Network in Azure with the following characteristics: ...", + "empty": false, + "inputs": [ + { + "name": "tags", + "description": "The tags to associate with your network and subnets.", + "default": "{\n \"tag1\": \"\",\n \"tag2\": \"\"\n}" + }, + { + "name": "subnet_names", + "description": "A list of public subnets inside the vNet.", + "default": "[\n \"subnet1\"\n]" + }, + { + "name": "subnet_prefixes", + "description": "The address prefix to use for the subnet.", + "default": "[\n \"10.0.1.0/24\"\n]" + }, + { + "name": "dns_servers", + "description": "The DNS servers to be used with vNet.", + "default": "[]" + }, + { + "name": "address_space", + "description": "The address space that is used by the virtual network.", + "default": "\"10.0.0.0/16\"" + }, + { + "name": "location", + "description": "The location/region where the core network will be created. The full list of Azure regions can be found at https://azure.microsoft.com/regions", + "default": "" + }, + { + "name": "prefix", + "description": "Default prefix to use with your resource names.", + "default": "\"myapp\"" + } + ], + "outputs": [ + { + "name": "vnet_id", + "description": "The id of the newly created vNet" + }, + { + "name": "vnet_name", + "description": "The Name of the newly created vNet" + }, + { + "name": "vnet_location", + "description": "The location of the newly created vNet" + }, + { + "name": "vnet_address_space", + "description": "The address space of the newly created vNet" + }, + { + "name": "vnet_dns_servers", + "description": "The DNS servers of the newly created vNet" + }, + { + "name": "vnet_subnets", + "description": "The ids of subnets created inside the newl vNet" + }, + { + "name": "security_group_id", + "description": "The id of the security group attached to subnets inside the newly created vNet. Use this id to associate additional network security rules to subnets." + } + ], + "dependencies": [], + "resources": [ + { + "name": "security_rule_ssh", + "type": "azurerm_network_security_rule" + }, + { + "name": "security_rule_rdp", + "type": "azurerm_network_security_rule" + }, + { + "name": "security_group", + "type": "azurerm_network_security_group" + }, + { + "name": "subnet", + "type": "azurerm_subnet" + }, + { + "name": "vnet", + "type": "azurerm_virtual_network" + }, + { + "name": "rg", + "type": "azurerm_resource_group" + } + ] + }, + "submodules": null, + "providers": [ + "azurerm" + ], + "versions": [ + "0.9.2", + "0.9.3" + ] +} ``` ## Download a Specific Module This endpoint downloads the specified version of a module for a single provider. +A successful response has no body, and includes the URL from which the module +version's source can be downloaded in the `X-Terraform-Get` header. Note that +this URL may contain special syntax interpreted by Terraform via +[`go-getter`](https://github.com/hashicorp/go-getter). See the [`go-getter` +documentation](https://github.com/hashicorp/go-getter#url-format) for details. + | Method | Path | Produces | | ------ | ---------------------------- | -------------------------- | | `GET` | `/v1/modules/:namespace/:name/:provider/:version/download` | `application/json` | @@ -145,14 +468,19 @@ $ curl \ ### Sample Response -```json -TODO +```text +HTTP/1.1 204 No Content +Content-Length: 0 +X-Terraform-Get: https://api.github.com/repos/Azure/terraform-azurerm-network/tarball/v0.9.2//*?archive=tar.gz ``` ## Download the Latest Version of a Module This endpoint downloads the latest version of a module for a single provider. +It returns a 302 redirect whose `Location` header redirects the client to the +download endpoint (above) for the latest version. + | Method | Path | Produces | | ------ | ---------------------------- | -------------------------- | | `GET` | `/v1/modules/:namespace/:name/:provider/download` | `application/json` | @@ -180,7 +508,8 @@ $ curl \ ### Sample Response -```json -TODO +```text +HTTP/1.1 302 Found +Location: /v1/modules/Azure/network/azurerm/0.9.3/download ``` diff --git a/website/docs/registry/modules/publish.html.md b/website/docs/registry/modules/publish.html.md index 44fc66f7d0..cea80125c3 100644 --- a/website/docs/registry/modules/publish.html.md +++ b/website/docs/registry/modules/publish.html.md @@ -33,12 +33,12 @@ requirements should happen naturally. 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` +* **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`. -* **Repostory 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. @@ -64,10 +64,13 @@ 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 +The upload page will list your available repositories, filtered to those that +match the [naming convention described above](#Requirements). This is shown in +the screenshot below. Select the repository of the module you want to add and click "Create Module." +TODO: screenshot + In a few seconds, your module will be created. ## Releasing New Versions diff --git a/website/docs/registry/modules/use.html.md b/website/docs/registry/modules/use.html.md index 836adf5332..556e53bd3b 100644 --- a/website/docs/registry/modules/use.html.md +++ b/website/docs/registry/modules/use.html.md @@ -50,5 +50,5 @@ we encourge all modules to follow the full guidelines of semantic versioning. Terraform currently only downloads the latest version of each module. The next release of Terraform (0.11) will bring full support for constraining -module versions. The registry has required semantic versions since launch +module versions. The registry has the required semantic versions since launch to prepare for this transition shortly after. diff --git a/website/docs/registry/private.html.md b/website/docs/registry/private.html.md index 4355cd2d64..d867a03790 100644 --- a/website/docs/registry/private.html.md +++ b/website/docs/registry/private.html.md @@ -17,11 +17,12 @@ 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. +The Terraform project does not provide any free or open source solution to have +a private registry. Terraform only requires the [read API](/docs/registry/api.html) +to be available to load modules from a registry. +Support for specifying an alternative to the public registry will be available +in Terraform 0.11. We welcome the community to create their own private +registries by recreating this API. ## Coming Soon From 722b3c6708e1cdd57214dd886d85e69a5cb5ac42 Mon Sep 17 00:00:00 2001 From: Paul Banks Date: Fri, 15 Sep 2017 16:26:37 +0100 Subject: [PATCH 11/16] API examples updated to use Consul modules --- website/docs/registry/api.html.md | 397 +++++++++++++----------------- 1 file changed, 167 insertions(+), 230 deletions(-) diff --git a/website/docs/registry/api.html.md b/website/docs/registry/api.html.md index 50003e128d..8ba7482b94 100644 --- a/website/docs/registry/api.html.md +++ b/website/docs/registry/api.html.md @@ -80,7 +80,7 @@ This endpoint returns the latest version of each provider for a module. ```text $ curl \ - https://registry.terraform.io/v1/modules/examplecorp/vapordb + https://registry.terraform.io/v1/modules/hashicorp/consul ``` ### Sample Response @@ -88,30 +88,30 @@ $ curl \ ```json [ { - "id": "examplecorp/vapordb/aws/1.0.0", - "owner": "wispy", - "namespace": "examplecorp", - "name": "vapordb", - "version": "1.0.0", - "provider": "aws", - "description": "Terraform Module for running VaporDB on AWS", - "source": "https://github.com/examplecorp/terraform-aws-vapordb", - "published_at": "2017-09-01T22:30:19.181077Z", - "downloads": 2, - "verified": true + "id": "hashicorp/consul/azurerm/0.0.1", + "owner": "gruntwork-team", + "namespace": "hashicorp", + "name": "consul", + "version": "0.0.1", + "provider": "azurerm", + "description": "A Terraform Module for how to run Consul on AzureRM using Terraform and Packer", + "source": "https://github.com/hashicorp/terraform-azurerm-consul", + "published_at": "2017-09-14T23:22:59.923047Z", + "downloads": 100, + "verified": false }, { - "id": "examplecorp/vapordb/azurerm/1.0.0", - "owner": "wispy", - "namespace": "examplecorp", - "name": "vapordb", - "version": "1.0.0", - "provider": "azurerm", - "description": "Terraform Module for running VaporDB on Azure", - "source": "https://github.com/examplecorp/terraform-azurerm-vapordb", - "published_at": "2017-09-01T22:30:19.181077Z", - "downloads": 2, - "verified": true + "id": "hashicorp/consul/aws/0.0.1", + "owner": "gruntwork-team", + "namespace": "hashicorp", + "name": "consul", + "version": "0.0.1", + "provider": "aws", + "description": "A Terraform Module for how to run Consul on AWS using Terraform and Packer", + "source": "https://github.com/hashicorp/terraform-aws-consul", + "published_at": "2017-09-14T23:22:44.793647Z", + "downloads": 113, + "verified": false } ] ``` @@ -139,140 +139,101 @@ This endpoint returns the latest version of a module for a single provider. ```text $ curl \ - https://registry.terraform.io/v1/modules/Azure/network/azurerm + https://registry.terraform.io/v1/modules/hashicorp/consul/aws ``` ### Sample Response +Note this response has has some fields trimmed for clarity. + ```json { - "id": "Azure/network/azurerm/0.9.3", - "owner": "echuvyrov", - "namespace": "Azure", - "name": "network", - "version": "0.9.3", - "provider": "azurerm", - "description": "Terraform Azure RM Module for Network", - "source": "https://github.com/Azure/terraform-azurerm-network", - "published_at": "2017-09-01T22:30:19.181077Z", - "downloads": 0, + "id": "hashicorp/consul/aws/0.0.1", + "owner": "gruntwork-team", + "namespace": "hashicorp", + "name": "consul", + "version": "0.0.1", + "provider": "aws", + "description": "A Terraform Module for how to run Consul on AWS using Terraform and Packer", + "source": "https://github.com/hashicorp/terraform-aws-consul", + "published_at": "2017-09-14T23:22:44.793647Z", + "downloads": 113, "verified": false, "root": { "path": "", - "readme": "Create a basic network in Azure\n==============================================================================\n\nThis Terraform module deploys a Virtual Network in Azure with the following characteristics: ...", + "readme": "# Consul AWS Module\n\nThis repo contains a Module for how to deploy a [Consul]...", "empty": false, "inputs": [ { - "name": "resource_group_name", - "description": "Default resource group name that the network will be created in.", - "default": "\"myapp-rg\"" - }, - { - "name": "location", - "description": "The location/region where the core network will be created. The full list of Azure regions can be found at https://azure.microsoft.com/regions", - "default": "" - }, - { - "name": "address_space", - "description": "The address space that is used by the virtual network.", - "default": "\"10.0.0.0/16\"" - }, - { - "name": "dns_servers", - "description": "The DNS servers to be used with vNet.", - "default": "[]" - }, - { - "name": "subnet_prefixes", - "description": "The address prefix to use for the subnet.", - "default": "[\n \"10.0.1.0/24\"\n]" - }, - { - "name": "subnet_names", - "description": "A list of public subnets inside the vNet.", - "default": "[\n \"subnet1\"\n]" + "name": "ami_id", + "description": "The ID of the AMI to run in the cluster. ...", + "default": "\"\"" }, { - "name": "tags", - "description": "The tags to associate with your network and subnets.", - "default": "{\n \"tag1\": \"\",\n \"tag2\": \"\"\n}" - }, - { - "name": "allow_rdp_traffic", - "description": "This optional variable, when set to true, adds a security rule allowing RDP traffic to flow through to the newly created network. The default value is false.", - "default": "false" - }, - { - "name": "allow_ssh_traffic", - "description": "This optional variable, when set to true, adds a security rule allowing SSH traffic to flow through to the newly created network. The default value is false.", - "default": "false" + "name": "aws_region", + "description": "The AWS region to deploy into (e.g. us-east-1).", + "default": "\"us-east-1\"" } ], "outputs": [ { - "name": "vnet_id", - "description": "The id of the newly created vNet" - }, - { - "name": "vnet_name", - "description": "The Name of the newly created vNet" - }, - { - "name": "vnet_location", - "description": "The location of the newly created vNet" - }, - { - "name": "vnet_address_space", - "description": "The address space of the newly created vNet" + "name": "num_servers", + "description": "" }, { - "name": "vnet_dns_servers", - "description": "The DNS servers of the newly created vNet" - }, - { - "name": "vnet_subnets", - "description": "The ids of subnets created inside the newl vNet" - }, - { - "name": "security_group_id", - "description": "The id of the security group attached to subnets inside the newly created vNet. Use this id to associate additional network security rules to subnets." + "name": "asg_name_servers", + "description": "" } ], "dependencies": [], - "resources": [ - { - "name": "network", - "type": "azurerm_resource_group" - }, - { - "name": "vnet", - "type": "azurerm_virtual_network" - }, - { - "name": "subnet", - "type": "azurerm_subnet" - }, - { - "name": "security_group", - "type": "azurerm_network_security_group" - }, - { - "name": "security_rule_rdp", - "type": "azurerm_network_security_rule" - }, - { - "name": "security_rule_ssh", - "type": "azurerm_network_security_rule" - } - ] + "resources": [] }, - "submodules": null, + "submodules": [ + { + "path": "modules/consul-cluster", + "readme": "# Consul Cluster\n\nThis folder contains a [Terraform](https://www.terraform.io/) ...", + "empty": false, + "inputs": [ + { + "name": "cluster_name", + "description": "The name of the Consul cluster (e.g. consul-stage). This variable is used to namespace all resources created by this module.", + "default": "" + }, + { + "name": "ami_id", + "description": "The ID of the AMI to run in this cluster. Should be an AMI that had Consul installed and configured by the install-consul module.", + "default": "" + } + ], + "outputs": [ + { + "name": "asg_name", + "description": "" + }, + { + "name": "cluster_size", + "description": "" + } + ], + "dependencies": [], + "resources": [ + { + "name": "autoscaling_group", + "type": "aws_autoscaling_group" + }, + { + "name": "launch_configuration", + "type": "aws_launch_configuration" + } + ] + } + ], "providers": [ + "aws", "azurerm" ], "versions": [ - "0.9.2", - "0.9.3" + "0.0.1" ] } ``` @@ -303,130 +264,102 @@ This endpoint returns the specified version of a module for a single provider. ```text $ curl \ - https://registry.terraform.io/v1/modules/Azure/network/azurerm/0.9.2 + https://registry.terraform.io/v1/modules/hashicorp/consul/aws/0.0.1 ``` ### Sample Response +Note this response has has some fields trimmed for clarity. + + ```json { - "id": "Azure/network/azurerm/0.9.2", - "owner": "echuvyrov", - "namespace": "Azure", - "name": "network", - "version": "0.9.2", - "provider": "azurerm", - "description": "Terraform Azure RM Module for Network", - "source": "https://github.com/Azure/terraform-azurerm-network", - "published_at": "2017-08-30T22:22:12.222113Z", - "downloads": 0, + "id": "hashicorp/consul/aws/0.0.1", + "owner": "gruntwork-team", + "namespace": "hashicorp", + "name": "consul", + "version": "0.0.1", + "provider": "aws", + "description": "A Terraform Module for how to run Consul on AWS using Terraform and Packer", + "source": "https://github.com/hashicorp/terraform-aws-consul", + "published_at": "2017-09-14T23:22:44.793647Z", + "downloads": 113, "verified": false, "root": { "path": "", - "readme": "Create a basic network in Azure\n==============================================================================\n\nThis Terraform module deploys a Virtual Network in Azure with the following characteristics: ...", + "readme": "# Consul AWS Module\n\nThis repo contains a Module for how to deploy a [Consul]...", "empty": false, "inputs": [ { - "name": "tags", - "description": "The tags to associate with your network and subnets.", - "default": "{\n \"tag1\": \"\",\n \"tag2\": \"\"\n}" - }, - { - "name": "subnet_names", - "description": "A list of public subnets inside the vNet.", - "default": "[\n \"subnet1\"\n]" - }, - { - "name": "subnet_prefixes", - "description": "The address prefix to use for the subnet.", - "default": "[\n \"10.0.1.0/24\"\n]" - }, - { - "name": "dns_servers", - "description": "The DNS servers to be used with vNet.", - "default": "[]" + "name": "ami_id", + "description": "The ID of the AMI to run in the cluster. ...", + "default": "\"\"" }, { - "name": "address_space", - "description": "The address space that is used by the virtual network.", - "default": "\"10.0.0.0/16\"" - }, - { - "name": "location", - "description": "The location/region where the core network will be created. The full list of Azure regions can be found at https://azure.microsoft.com/regions", - "default": "" - }, - { - "name": "prefix", - "description": "Default prefix to use with your resource names.", - "default": "\"myapp\"" + "name": "aws_region", + "description": "The AWS region to deploy into (e.g. us-east-1).", + "default": "\"us-east-1\"" } ], "outputs": [ { - "name": "vnet_id", - "description": "The id of the newly created vNet" - }, - { - "name": "vnet_name", - "description": "The Name of the newly created vNet" - }, - { - "name": "vnet_location", - "description": "The location of the newly created vNet" - }, - { - "name": "vnet_address_space", - "description": "The address space of the newly created vNet" + "name": "num_servers", + "description": "" }, { - "name": "vnet_dns_servers", - "description": "The DNS servers of the newly created vNet" - }, - { - "name": "vnet_subnets", - "description": "The ids of subnets created inside the newl vNet" - }, - { - "name": "security_group_id", - "description": "The id of the security group attached to subnets inside the newly created vNet. Use this id to associate additional network security rules to subnets." + "name": "asg_name_servers", + "description": "" } ], "dependencies": [], - "resources": [ - { - "name": "security_rule_ssh", - "type": "azurerm_network_security_rule" - }, - { - "name": "security_rule_rdp", - "type": "azurerm_network_security_rule" - }, - { - "name": "security_group", - "type": "azurerm_network_security_group" - }, - { - "name": "subnet", - "type": "azurerm_subnet" - }, - { - "name": "vnet", - "type": "azurerm_virtual_network" - }, - { - "name": "rg", - "type": "azurerm_resource_group" - } - ] + "resources": [] }, - "submodules": null, + "submodules": [ + { + "path": "modules/consul-cluster", + "readme": "# Consul Cluster\n\nThis folder contains a [Terraform](https://www.terraform.io/) ...", + "empty": false, + "inputs": [ + { + "name": "cluster_name", + "description": "The name of the Consul cluster (e.g. consul-stage). This variable is used to namespace all resources created by this module.", + "default": "" + }, + { + "name": "ami_id", + "description": "The ID of the AMI to run in this cluster. Should be an AMI that had Consul installed and configured by the install-consul module.", + "default": "" + } + ], + "outputs": [ + { + "name": "asg_name", + "description": "" + }, + { + "name": "cluster_size", + "description": "" + } + ], + "dependencies": [], + "resources": [ + { + "name": "autoscaling_group", + "type": "aws_autoscaling_group" + }, + { + "name": "launch_configuration", + "type": "aws_launch_configuration" + } + ] + } + ], "providers": [ + "aws", "azurerm" ], "versions": [ - "0.9.2", - "0.9.3" + "0.0.1" ] } ``` @@ -462,8 +395,8 @@ documentation](https://github.com/hashicorp/go-getter#url-format) for details. ### Sample Request ```text -$ curl \ - https://registry.terraform.io/v1/modules/hashicorp/consul/aws/1.0.0/download +$ curl -i \ + https://registry.terraform.io/v1/modules/hashicorp/consul/aws/0.0.1/download ``` ### Sample Response @@ -471,7 +404,7 @@ $ curl \ ```text HTTP/1.1 204 No Content Content-Length: 0 -X-Terraform-Get: https://api.github.com/repos/Azure/terraform-azurerm-network/tarball/v0.9.2//*?archive=tar.gz +X-Terraform-Get: https://api.github.com/repos/hashicorp/terraform-aws-consul/tarball/v0.0.1//*?archive=tar.gz ``` ## Download the Latest Version of a Module @@ -502,7 +435,7 @@ download endpoint (above) for the latest version. ### Sample Request ```text -$ curl \ +$ curl -i \ https://registry.terraform.io/v1/modules/hashicorp/consul/aws/download ``` @@ -510,6 +443,10 @@ $ curl \ ```text HTTP/1.1 302 Found -Location: /v1/modules/Azure/network/azurerm/0.9.3/download +Location: /v1/modules/hashicorp/consul/aws/0.0.1/download +Content-Length: 70 +Content-Type: text/html; charset=utf-8 + +Found. ``` From 197bbc61148f8580705967ce4034a2d46b7c2705 Mon Sep 17 00:00:00 2001 From: Paul Banks Date: Fri, 15 Sep 2017 17:50:22 +0100 Subject: [PATCH 12/16] Add screenshots, make registry the default module source example, remove dead support link in registry submenu --- website/docs/configuration/modules.html.md | 2 +- website/docs/registry/modules/publish.html.md | 4 ++-- website/docs/registry/modules/verified.html.md | 2 +- website/layouts/registry.erb | 4 ---- 4 files changed, 4 insertions(+), 8 deletions(-) diff --git a/website/docs/configuration/modules.html.md b/website/docs/configuration/modules.html.md index 18d513a49a..7c6353b071 100644 --- a/website/docs/configuration/modules.html.md +++ b/website/docs/configuration/modules.html.md @@ -23,7 +23,7 @@ Module configuration looks like the following: ```hcl module "consul" { - source = "github.com/hashicorp/consul/terraform/aws" + source = "hashicorp/consul/aws" servers = 5 } ``` diff --git a/website/docs/registry/modules/publish.html.md b/website/docs/registry/modules/publish.html.md index cea80125c3..895aa10fed 100644 --- a/website/docs/registry/modules/publish.html.md +++ b/website/docs/registry/modules/publish.html.md @@ -69,10 +69,10 @@ match the [naming convention described above](#Requirements). This is shown in the screenshot below. Select the repository of the module you want to add and click "Create Module." -TODO: screenshot - In a few seconds, your module will be created. +![Create Module flow animation](/assets/images/docs/registry-upload.gif) + ## Releasing New Versions The Terraform Registry uses tags to detect releases. diff --git a/website/docs/registry/modules/verified.html.md b/website/docs/registry/modules/verified.html.md index f133354d05..d7ff853ac9 100644 --- a/website/docs/registry/modules/verified.html.md +++ b/website/docs/registry/modules/verified.html.md @@ -14,7 +14,7 @@ their respective providers. The blue verification badge appears next to modules that are verified. -TODO: Screenshot +![Verified module listing](/assets/images/docs/registry-verified.png) If a module is verified, it is promised to be actively maintained and of high quality. It isn't indicative of flexibility or feature support; very diff --git a/website/layouts/registry.erb b/website/layouts/registry.erb index 76f4c300ad..89ebb9cd2d 100644 --- a/website/layouts/registry.erb +++ b/website/layouts/registry.erb @@ -37,10 +37,6 @@ > API - - > - Support - <% end %> From e6b7490ed8c2f595179ab69e67e7d47f39389d47 Mon Sep 17 00:00:00 2001 From: Paul Banks Date: Fri, 15 Sep 2017 22:42:38 +0100 Subject: [PATCH 13/16] Fix broken links and update publish gif --- website/docs/modules/create.html.markdown | 2 +- website/docs/registry/modules/publish.html.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/website/docs/modules/create.html.markdown b/website/docs/modules/create.html.markdown index cd537cb48b..02927984cc 100644 --- a/website/docs/modules/create.html.markdown +++ b/website/docs/modules/create.html.markdown @@ -15,7 +15,7 @@ the Terraform files you're applying comprise what is called the _root module_. T Therefore, you can enter the source of any module, satisfy any required variables, run `terraform apply`, and expect it to work. Modules that are created for reuse should follow the -[standard structure](#standard-structure). This structure enables tooling +[standard structure](#standard-module-structure). This structure enables tooling such as the [Terraform Registry](/docs/registry/index.html) to inspect and generate documentation, read examples, and more. diff --git a/website/docs/registry/modules/publish.html.md b/website/docs/registry/modules/publish.html.md index 895aa10fed..b53e578d09 100644 --- a/website/docs/registry/modules/publish.html.md +++ b/website/docs/registry/modules/publish.html.md @@ -67,11 +67,11 @@ email you alerts about your module. We will not spam you. The upload page will list your available repositories, filtered to those that match the [naming convention described above](#Requirements). This is shown in the screenshot below. Select the repository of the module you want to add and -click "Create Module." +click "Publish Module." In a few seconds, your module will be created. -![Create Module flow animation](/assets/images/docs/registry-upload.gif) +![Publish Module flow animation](/assets/images/docs/registry-publish.gif) ## Releasing New Versions From d52dbae2a01f36e7a4d8a9ccd0923165259d22de Mon Sep 17 00:00:00 2001 From: Paul Banks Date: Fri, 15 Sep 2017 22:58:47 +0100 Subject: [PATCH 14/16] Add back Support page with info about getting help. --- website/docs/registry/support.html.md | 16 ++++++++++++++++ website/layouts/registry.erb | 4 ++++ 2 files changed, 20 insertions(+) create mode 100644 website/docs/registry/support.html.md diff --git a/website/docs/registry/support.html.md b/website/docs/registry/support.html.md new file mode 100644 index 0000000000..7436bff27c --- /dev/null +++ b/website/docs/registry/support.html.md @@ -0,0 +1,16 @@ +--- +layout: "registry" +page_title: "Terraform Registry - Support" +sidebar_current: "docs-registry-support" +description: |- + Where to go for help with modules found in the Terraform Registry. +--- + +# Getting Help + +The modules in The Terraform Registry are provided and maintained by trusted +HashiCorp partners and the Terraform Community. If you run into issues using a +module or have additional contributions to make, you can find a link to the +Module's GitHub issues on the module page. + +![Module report issue link](/assets/images/docs/registry-support.png) \ No newline at end of file diff --git a/website/layouts/registry.erb b/website/layouts/registry.erb index 89ebb9cd2d..76f4c300ad 100644 --- a/website/layouts/registry.erb +++ b/website/layouts/registry.erb @@ -37,6 +37,10 @@ > API + + > + Support + <% end %> From 89ac68808aa97e7b9fd9e866552360a90dd16de4 Mon Sep 17 00:00:00 2001 From: Paul Banks Date: Mon, 18 Sep 2017 12:00:34 -0500 Subject: [PATCH 15/16] Fix docs to use pagniated response format and document pagination meta --- website/docs/registry/api.html.md | 176 ++++++++++++++++++------------ 1 file changed, 105 insertions(+), 71 deletions(-) diff --git a/website/docs/registry/api.html.md b/website/docs/registry/api.html.md index 8ba7482b94..7edb66b250 100644 --- a/website/docs/registry/api.html.md +++ b/website/docs/registry/api.html.md @@ -16,50 +16,6 @@ API is read-only. Any endpoints that aren't documented on this page can and will likely change over time. This allows differing methods for getting modules into the registry while keeping a consistent API for reading modules in the registry. -## HTTP Status Codes - -The API follows regular HTTP status semantics. To make implementing a complete -client easier, some details on our policy and potential future status codes are -listed below. A robust client should consider how to handle all of the -following. - - - **Success:** Return status is `200` on success with a body or `204` if there - is no body data to return. - - **Redirects:** Moved or aliased endpoints redirect with a `301`. Endpoints - redirecting to the latest version of a module may redirect with `302` or - `307` to indicate that they logically point to different resources over time. - - **Client Errors:** Invalid requests will receive the relevant `4xx` status. - Except where noted below, the request should not be retried. - - **Rate Limiting:** Clients placing excessive load on the service might be - rate-limited and receive a `429` code. This should be interpreted as a sign - to slow down, and wait some time before retrying the request. - - **Service Errors:** The usual `5xx` errors will be returned for service - failures. In all cases it is safe to retry the request after receiving a - `5xx` response. - - **Load Shedding:** A `503` response indicates that the service is under load - and can't process your request immediately. As with other `5xx` errors you - may retry after some delay, although clients should consider being more - lenient with retry schedule in this case. - -## Error Responses - -When a `4xx` or `5xx` status code is returned. The response payload will look -like the following example: - -```json -{ - "errors": [ - "something bad happened" - ] -} -``` - -The `errors` key is a list containing one or more strings where each string -describes an error that has occurred. - -Note that it is possible that some `5xx` errors might result in a response that -is not in JSON format above due to being returned by an intermediate proxy. - ## List Latest Version of Module for All Providers This endpoint returns the latest version of each provider for a module. @@ -86,34 +42,40 @@ $ curl \ ### Sample Response ```json -[ - { - "id": "hashicorp/consul/azurerm/0.0.1", - "owner": "gruntwork-team", - "namespace": "hashicorp", - "name": "consul", - "version": "0.0.1", - "provider": "azurerm", - "description": "A Terraform Module for how to run Consul on AzureRM using Terraform and Packer", - "source": "https://github.com/hashicorp/terraform-azurerm-consul", - "published_at": "2017-09-14T23:22:59.923047Z", - "downloads": 100, - "verified": false +{ + "meta": { + "limit": 15, + "current_offset": 0 }, - { - "id": "hashicorp/consul/aws/0.0.1", - "owner": "gruntwork-team", - "namespace": "hashicorp", - "name": "consul", - "version": "0.0.1", - "provider": "aws", - "description": "A Terraform Module for how to run Consul on AWS using Terraform and Packer", - "source": "https://github.com/hashicorp/terraform-aws-consul", - "published_at": "2017-09-14T23:22:44.793647Z", - "downloads": 113, - "verified": false - } -] + "modules": [ + { + "id": "hashicorp/consul/azurerm/0.0.1", + "owner": "gruntwork-team", + "namespace": "hashicorp", + "name": "consul", + "version": "0.0.1", + "provider": "azurerm", + "description": "A Terraform Module for how to run Consul on AzureRM using Terraform and Packer", + "source": "https://github.com/hashicorp/terraform-azurerm-consul", + "published_at": "2017-09-14T23:22:59.923047Z", + "downloads": 100, + "verified": false + }, + { + "id": "hashicorp/consul/aws/0.0.1", + "owner": "gruntwork-team", + "namespace": "hashicorp", + "name": "consul", + "version": "0.0.1", + "provider": "aws", + "description": "A Terraform Module for how to run Consul on AWS using Terraform and Packer", + "source": "https://github.com/hashicorp/terraform-aws-consul", + "published_at": "2017-09-14T23:22:44.793647Z", + "downloads": 113, + "verified": false + } + ] +} ``` ## Latest Module for a Single Provider @@ -450,3 +412,75 @@ Content-Type: text/html; charset=utf-8 Found. ``` +## HTTP Status Codes + +The API follows regular HTTP status semantics. To make implementing a complete +client easier, some details on our policy and potential future status codes are +listed below. A robust client should consider how to handle all of the +following. + + - **Success:** Return status is `200` on success with a body or `204` if there + is no body data to return. + - **Redirects:** Moved or aliased endpoints redirect with a `301`. Endpoints + redirecting to the latest version of a module may redirect with `302` or + `307` to indicate that they logically point to different resources over time. + - **Client Errors:** Invalid requests will receive the relevant `4xx` status. + Except where noted below, the request should not be retried. + - **Rate Limiting:** Clients placing excessive load on the service might be + rate-limited and receive a `429` code. This should be interpreted as a sign + to slow down, and wait some time before retrying the request. + - **Service Errors:** The usual `5xx` errors will be returned for service + failures. In all cases it is safe to retry the request after receiving a + `5xx` response. + - **Load Shedding:** A `503` response indicates that the service is under load + and can't process your request immediately. As with other `5xx` errors you + may retry after some delay, although clients should consider being more + lenient with retry schedule in this case. + +## Error Responses + +When a `4xx` or `5xx` status code is returned. The response payload will look +like the following example: + +```json +{ + "errors": [ + "something bad happened" + ] +} +``` + +The `errors` key is a list containing one or more strings where each string +describes an error that has occurred. + +Note that it is possible that some `5xx` errors might result in a response that +is not in JSON format above due to being returned by an intermediate proxy. + +## Pagination + +Endpoints that return lists of results use a common pagination format. + +They accept positive integer query variables `offset` and `limit` which have the +usual SQL-like semantics. Each endpoint will have a sane default limit and a +default offset of `0`. Each endpoint will also apply a sane maximum limit, +requesting more results will just result in the maximum limit being used. + +The response for a paginated result set will look like: + +```json +{ + "meta": { + "limit": 15, + "current_offset": 15, + "next_offset": 30, + "prev_offset": 0, + }, + "": [] +} +``` +Note that: + - `next_offset` will only be present if there are more results available. + - `prev_offset` will only be present if not at `offset = 0`. + - `limit` is the actual limit that was applied, it may be lower than the requested limit param. + - The key for the result array varies based on the endpoint and will be the + type of result pluralized, for example `modules`. \ No newline at end of file From dadb8be289890c67ea4d0b2804da7e69d1a15a13 Mon Sep 17 00:00:00 2001 From: Paul Banks Date: Mon, 18 Sep 2017 12:06:25 -0500 Subject: [PATCH 16/16] Add query params to endpoint docs --- website/docs/registry/api.html.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/website/docs/registry/api.html.md b/website/docs/registry/api.html.md index 7edb66b250..6f228f53c5 100644 --- a/website/docs/registry/api.html.md +++ b/website/docs/registry/api.html.md @@ -32,6 +32,10 @@ This endpoint returns the latest version of each provider for a module. - `name` `(string: )` - The name of the module. This is required and is specified as part of the URL path. +### Query Parameters + +- `offset`, `limit` `(int: )` - See [Pagination](#Pagination) for details. + ### Sample Request ```text