» Registry Modules API

» Listing and reading modules, providers and versions

The Terraform Enterprise Module Registry implemenets the Registry standard API for consuming the modules. Refer to the Module Registry HTTP API to perform the following:

  • Browse available modules
  • Search modules by keyword
  • List available versions for a specific module
  • Download source code for a specific module version
  • List latest version of a module for all providers
  • Get the latest version for a specific module provider
  • Get a specific module
  • Download the latest version of a module

The TFE Module Registry endpoints differs from the Module Registry endpoints in the following ways:

  • The :namespace parameter should be replaced with the organization name.
  • The module registry discovery endpoints have the path prefix provided in the discovery document which is currently /api/registry/v1.
  • Authentication is handled the same as all other TFE endpoints.

» Sample Request

List available versions for the consul module for the aws provider on the module registry published from the Github organization my-gh-repo-org:

$ curl https://registry.terraform.io/v1/modules/my-gh-repo-org/consul/aws/versions

The same request for the same module and provider on the TFE module registry for my-tfe-org TFE organization:

$ curl \
  --header "Authorization: Bearer $ATLAS_TOKEN" \
  https://app.terraform.io/api/registry/v1/modules/my-tfe-org/consul/aws/versions

» Publish a Module

This endpoint can be used to publish a new module to the registry. The publishing process will fetch all tags in the source repository that look like SemVer versions with optional 'v' prefix. For each version, the tag is cloned and the config parsed to populate module details (input and output variables, readme, submodules, etc.). The Module Registry Requirements define additional requirements on naming, standard module structure and tags for releases.

Method Path
POST /registry-modules

» Parameters

  • linkable-repo-id (string: <required>) - Specifies the repository to be used to ingress the configuration. For Bitbucket server, the format is <PROJECT_KEY>/<REPO>. Bitbucket Server is currently the only supported VCS service.
  • oauth-token-id (string: <requires>) - Specifies the VCS Connection (OAuth Conection + Token) to use as identified. This ID can be obtained from the oauth-tokens endpoint.

» Sample Payload

{
  "data": {
    "attributes": {
      "linkable-repo-id":"SKI/terraform-aws-instance",
      "oauth-token-id":"ot-hmAyP66qk2AMVdbJ"
    },
    "type":"registry-modules"
  }
}

» Sample Request

curl \
  --header "Authorization: Bearer $ATLAS_TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/registry-modules

» Sample Response

{
  "data": {
    "id": "mod-1JqHG3j71bwoukuX",
    "type": "registry-modules",
    "attributes": {
      "name": "instance",
      "provider": "aws",
      "status": "pending",
      "version-statuses": [],
      "created-at": "2017-11-30T00:00:52.386Z",
      "updated-at": "2017-11-30T00:00:52.386Z",
      "permissions": {
        "can-delete": true,
        "can-resync": true,
        "can-retry": true
      }
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "org-QpXoEnULx3r2r1CA",
          "type": "organizations"
        }
      }
    },
    "links": {
      "self": "/api/v2/registry-modules/show/skierkowski-v2/instance/aws"
    }
  }
}

» Delete a module

These endpoints can delete a single version for a provider, a single provider (and all its versions) for a module, or a whole module. If the requested deletion would leave a provider with no versions or a module with no providers, the empty items will be automatically deleted as well.

Method Path
POST /registry-modules/actions/delete/:organization/:module/:provider/:version
POST /registry-modules/actions/delete/:organization/:module/:provider
POST /registry-modules/actions/delete/:organization/:module

» Parameters

  • :organization (string: <required>) - Specifies the organization for the module registry.
  • :module (string: <required>) - Specifies the module name from which to delete all versions from all providers.
  • :provider (string: <optional>) - Specifies the provider for the given module from which to delete all versions.
  • :version (string: <optional>) - Specifies the version for the given module and provider to be deleted.

» Sample Request

curl \
  --header "Authorization: Bearer $ATLAS_TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  https://app.terraform.io/api/v2/registry-modules/actions/delete/skierkowski-v2/instance