16 KiB
layout | page_title | sidebar_current | description |
---|---|---|---|
registry | Terraform Registry - HTTP API | docs-registry-api | The /acl endpoints create, update, destroy, and query ACL tokens in Consul. |
HTTP API
The Terraform Registry has an HTTP API for reading and downloading registry modules.
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 or204
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 with302
or307
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 a5xx
response. - Load Shedding: A
503
response indicates that the service is under load and can't process your request immediately. As with other5xx
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:
{
"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.
Method | Path | Produces |
---|---|---|
GET |
/v1/modules/:namespace/:name |
application/json |
Parameters
-
namespace
(string: <required>)
- The user or organization the module is owned by. This is required and is specified as part of the URL path. -
name
(string: <required>)
- The name of the module. This is required and is specified as part of the URL path.
Sample Request
$ curl \
https://registry.terraform.io/v1/modules/examplecorp/vapordb
Sample Response
[
{
"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
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: <required>)
- The user the module is owned by. This is required and is specified as part of the URL path. -
name
(string: <required>)
- The name of the module. This is required and is specified as part of the URL path. -
provider
(string: <required>)
- The name of the provider. This is required and is specified as part of the URL path.
Sample Request
$ curl \
https://registry.terraform.io/v1/modules/Azure/network/azurerm
Sample Response
{
"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
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: <required>)
- The user the module is owned by. This is required and is specified as part of the URL path. -
name
(string: <required>)
- The name of the module. This is required and is specified as part of the URL path. -
provider
(string: <required>)
- The name of the provider. This is required and is specified as part of the URL path. -
version
(string: <required>)
- The version of the module. This is required and is specified as part of the URL path.
Sample Request
$ curl \
https://registry.terraform.io/v1/modules/Azure/network/azurerm/0.9.2
Sample Response
{
"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
. See the go-getter
documentation for details.
Method | Path | Produces |
---|---|---|
GET |
/v1/modules/:namespace/:name/:provider/:version/download |
application/json |
Parameters
-
namespace
(string: <required>)
- The user the module is owned by. This is required and is specified as part of the URL path. -
name
(string: <required>)
- The name of the module. This is required and is specified as part of the URL path. -
provider
(string: <required>)
- The name of the provider. This is required and is specified as part of the URL path. -
version
(string: <required>)
- The version of the module. This is required and is specified as part of the URL path.
Sample Request
$ curl \
https://registry.terraform.io/v1/modules/hashicorp/consul/aws/1.0.0/download
Sample Response
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 |
Parameters
-
namespace
(string: <required>)
- The user the module is owned by. This is required and is specified as part of the URL path. -
name
(string: <required>)
- The name of the module. This is required and is specified as part of the URL path. -
provider
(string: <required>)
- The name of the provider. This is required and is specified as part of the URL path. -
version
(string: <required>)
- The version of the module. This is required and is specified as part of the URL path.
Sample Request
$ curl \
https://registry.terraform.io/v1/modules/hashicorp/consul/aws/download
Sample Response
HTTP/1.1 302 Found
Location: /v1/modules/Azure/network/azurerm/0.9.3/download