Modules

The ModuleVersion resource

A terraform module’s version in the Private Module Registry.

Key path

Description

type* (string)

Available values: module-versions

id (string)

attributes.created-at (string)

The resource creation timestamp.

attributes.dependencies (object)

The list of modules this version depends on.

attributes.details (string)

README contents.

This file should be named README or README.md. The latter will be processed as CommonMark.

attributes.error-message (string)

This field contains the error description, when this module version’s status is errored.

attributes.inputs (array)

Input Variables.

attributes.is-root-module (boolean)

Module version marked as root will allow the creation of workspaces directly from the registry, as well as standard module usage.

attributes.outputs (array)

Output Values.

attributes.resources (array)

Declared resources.

attributes.status (string)

Available values: not_uploaded, pending, ok, errored, pending_delete

The module version’s current status.

Initial status:

  • not_uploaded - Module version has been created, however the code has not been uploaded.

Transitional statuses:

  • pending - Module version has been created and is currently synchronizing.

  • pending_delete - Module version has been deleted from the repository and pending deletion from the registry.

Ending statuses:

  • ok - Module version has been created and the code has been uploaded.

  • errored - Module version has been created, however its synchronization has failed. Attribute error-message contains the details.

attributes.version* (string)

Semantic Version.

relationships.module* (object)

The module this version belogs to.

relationships.module.data.type* (string)

Available values: modules

relationships.module.data.id* (string)

relationships.vcs-revision (object)

The Git commit information when the module version was uploaded from a VCS.

relationships.vcs-revision.data.type* (string)

Available values: vcs-revisions

relationships.vcs-revision.data.id* (string)

links.download (string)

The URL to download the tar.gz archive with module version source code.

links.self (string)

The Module resource

A terraform module in the Private Module Registry.

Key path

Description

type* (string)

Available values: modules

id (string)

attributes.created-at (string)

The resource creation timestamp.

attributes.description (string)

The description of the module.

By default, this is taken from the VCS repository description. For mono repos you likely want to override this behavior by passing this argument in a Create Module operation.

attributes.error-message (string)

This field contains the error description, when this module’s status is errored.

attributes.name (string)

The module name.

attributes.provider (string)

A name of a system, this module was written for.

For multi-cloud modules this argument should match terraform provider name (ex: aws or google), in other cases the convention is to name it system

attributes.source (string)

The source by which the module should be addressed from a HCL template.

attributes.status (string)

Available values: no_version_tags, pending, setup_complete, errored

The Module’s current status.

Initial status:

  • pending - The initial status of a module once it has been created. Now Scalr will download the code from the VCS, and create a module-version resource for each matching Git tag.

Ending statuses:

  • no_version_tags - a Module has been created, however the Module source repository has no tags.

  • setup_complete - a Module has been created, and at least one ModuleVersion has been successfully uploaded. Scalr assigns this status while some module-versions upload might be still in-progress. If you want to ensure a specific version was uploaded, you can poll List Module Versions for the ok status.

  • errored - Module has been created, however its synchronization has failed. Attribute error-message contains the details.

attributes.vcs-repo.identifier* (string)

A reference to the module’s VCS repository.

For GitHub, GitHub Enterprise and GitLab the format is <org>/<repo>. Azure DevOps Services has the format <org>/<project>/<repo>.

attributes.vcs-repo.path (string)

The repository sub-directory where the module source is located. If omitted or submitted as an empty string, this defaults to the repository’s root.

attributes.vcs-repo.tag-prefix (string)

Specify this attribute when a module’s releases are namespaced within a repository’s Git tags. This is usually the case for a mono repos with individually versioned components. For example if your module is tagged my-module/v1.0.0 it’s tag_prefix is my-module/.

relationships.account (object)

The account this module belongs to.

relationships.account.data.type* (string)

Available values: accounts

relationships.account.data.id* (string)

relationships.created-by (object)

The user who has created the module.

relationships.created-by.data.type* (string)

Available values: users

relationships.created-by.data.id* (string)

relationships.environment (object)

The environment this module belongs to.

relationships.environment.data.type* (string)

Available values: environments

relationships.environment.data.id* (string)

relationships.latest-module-version (object)

The module’s latest version.

relationships.latest-module-version.data.type* (string)

Available values: module-versions

relationships.latest-module-version.data.id* (string)

relationships.module-versions (object)

The IDs of the module versions.

relationships.module-versions.data* (array)

relationships.vcs-provider* (object)

The module’s VCS provider.

relationships.vcs-provider.data.type* (string)

Available values: vcs-providers

relationships.vcs-provider.data.id* (string)

links.self (string)

List Module Versions

GET /api/iacp/v3/module-versions

This endpoint lists versions of a particular module. The query parameter filter[module] with Module ID is required.

Query Parameters
  • page[number] (string) – Page number

  • page[size] (string) – Page size

  • filter[module] (string) – Filter module versions by module (Required)

  • filter[status] (string) – Filter module versions by status

  • filter[version] (string) – Filter module versions by semantic version

  • include (array) – The comma-separated list of relationship paths. (Available values: module, vcs-revision)

Example Request:

GET /api/iacp/v3/module-versions?filter%5Bmodule%5D=string HTTP/1.1
Host: my.scalr.io
Prefer: profile=preview
Status Codes
  • 200 OK

    Success.

    Example Respone:

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    Preference-Applied: profile=preview
    
    {
        "data": [
            {
                "attributes": {
                    "created-at": "2021-03-08T17:17:33Z",
                    "dependencies": null,
                    "details": "Readme",
                    "error-message": null,
                    "inputs": [
                        {
                            "default": "64512",
                            "description": "Description",
                            "name": "input",
                            "type": ""
                        },
                        {
                            "default": false,
                            "description": "Description",
                            "name": "input_bool",
                            "type": "bool"
                        },
                    ],
                    "outputs": [
                        {
                            "name": "output",
                            "sensitive": false,
                            "description": "description",
                            "value": "value"
                        },
                        {
                            "name": "output_hash",
                            "sensitive": false,
                            "description": "",
                            "value": "value"
                        }
                    ],
                    "resources": [
                        {
                            "address": "this",
                            "type": "resource"
                        }
                    ],
                    "source": "vcs",
                    "status": "ok",
                    "updated-at": "2021-03-08T17:17:34Z",
                    "version": "2.33.0"
                },
                "id": "modver-tc5se25e31ope30",
                "links": {
                    "download": "https://my.scalr.io/api/tfe/v1/blobs/eyJhbGciOiJQQkVTMi1IUzUxMitBMjU2S1ciLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwicDJjIjo4MTkyLCJwMnMiOiJBVEU5cmdvYnZhOE1fY3BURGh1V05BIn0.rD4n_R9uD6Ft6I744CpsR6wryQfE87I6ZhjzJYulPiVCZ6fvg5w-ZkpsxT2UAEtH-d-IkwpZ7dpDwakt1tR83FPo3XgCvXd0.3npxoRR9AtHnkN9r9alqfA.x9IfrsqIVgLeggswY1NsWIX6JtuvZNAmHHsBwfWbKVyL2T015z4ov9Xwr-cJjSQ3Wm86ptKuuyA9AAe0OpmndRmN1cs1NjySB3LCtX2pxdquL6AsoRS-QL9NiVQ-P0rV.7kOsXKrbKCI8LQQX7KVGKPc4xWo1XrYeljXwVisrRgU",
                    "self": "https://my.scalr.io/api/iacp/v3/module-versions/modver-tc5se25e31ope30",
                    "upload": "https://my.scalr.io/api/tfe/v1/blobs/eyJhbGciOiJQQkVTMi1IUzUxMitBMjU2S1ciLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwicDJjIjo4MTkyLCJwMnMiOiIxdHVNVmEzbGo2RjMyNGE4UnhQdlpBIn0.7k5G1a9x8dWfmjsbUZ6okpwaX84Pp_GwR_orrLsENBw8IMTAwhqX0hgLKTWRDNcuYLX9I8gLt6fvO1EX1ctyaeRQg-l4fwCS.qBHmtESZD3lw7oPwmcFEgQ.uMaq6n4HQ7XbX3swiHzAmqhPGutn0HoTxkO-AOOXwHdKwulr5yht9XdG-weHQmP0OzaKSW9QCH__4maIuEmPt0cHxZKbm7lGdeOfB5NxS8lZpPJ_1wZDF9PwjdMtz_Ct.AJeQzbFdN0dYKZg1gWejyakKCdqhhN2_mV10AWpTwU4"
                },
                "relationships": {
                    "registry-module": {
                        "data": {
                            "id": "mod-tc5se0n0dirb90o",
                            "type": "modules"
                        }
                    },
                    "submodules": null,
                    "vcs-revision": {
                        "data": {
                            "id": "vrb-tc5se25juq2h92o",
                            "type": "vcs-revisions"
                        }
                    }
                },
                "type": "module-versions"
            },
            {
                "attributes": {
                    "created-at": "2021-03-08T17:17:33Z",
                    "dependencies": null,
                    "details": "Readme",
                    "error-message": null,
                    "inputs": [
                        {
                            "default": "64512",
                            "description": "Description",
                            "name": "input",
                            "type": ""
                        },
                        {
                            "default": false,
                            "description": "Description",
                            "name": "input_bool",
                            "type": "bool"
                        },
                    ],
                    "outputs": [
                        {
                            "name": "output",
                            "sensitive": false,
                            "description": "description",
                            "value": "value"
                        },
                        {
                            "name": "output_hash",
                            "sensitive": false,
                            "description": "",
                            "value": "value"
                        }
                    ],
                    "resources": [
                        {
                            "address": "this",
                            "type": "resource"
                        }
                    ],
                    "source": "vcs",
                    "status": "ok",
                    "updated-at": "2021-03-08T17:17:34Z",
                    "version": "2.32.0"
                },
                "id": "modver-tc5se2g5a5kno2o",
                "links": {
                    "download": "https://my.scalr.io/api/tfe/v1/blobs/eyJhbGciOiJQQkVTMi1IUzUxMitBMjU2S1ciLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwicDJjIjo4MTkyLCJwMnMiOiJtM2s4bC1YQW4yYmJVZVhkN3dQeTNRIn0.oFjsZVp2LfT-qY-C7pNGRLYJlBJXADFeJQQdTBmYiFhO1CFpM_lVrN5ZUpxFBYlnmIX7tQquo4PWS_GcN0Pf3B37560Mf11K.BGkWFwUmrHiKn0OCFLJyNQ.ln7PLZsRXSYy9M0ZciJnTdOOfRWi-Ngtlrwyf5lesgj9mTmKnmVCxfUx4D4H5zRU7cYzSxnY3NpglB9xXScXiJfp1uYWLqkP4u8b3rMRiMeOkZliI83Ht-w0VowrIdr-.HsK9BmK8XgE8SCiGQhTlJHnSe_zJGMULiBfXnyORLoE",
                    "self": "https://my.scalr.io/api/iacp/v3/module-versions/modver-tc5se2g5a5kno2o",
                    "upload": "https://my.scalr.io/api/tfe/v1/blobs/eyJhbGciOiJQQkVTMi1IUzUxMitBMjU2S1ciLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwicDJjIjo4MTkyLCJwMnMiOiJnUkFiNm94RTh2dVhYSVZCaDRKYlRRIn0.ZhZJzNENRdYHbPg3Omf8gam2C739LimHO1HUWWvEgz1plI0vtrdEEb43CArkxRFIhObukU708DF8yjjVcWA1IzFhDfVj7dcZ.d1kePjxrwP_sqnhHOhTVAg.pROMF18dUKxui5T0AE4b3TcK9_85Ij0FbyPQDRNxSrCMvx2c4JqRp0rMxD4qRh3_lNTqNkP8Dd0CGqdhSeGDs1b6YS1a9FOU3qLf8jcNhyHn5oRxllPA2hPVyN3F4dA3.VgZHkqsc6L6gfNK3I_9vyW6ZnddulbeI8SXi2jN-Mvc"
                },
                "relationships": {
                    "registry-module": {
                        "data": {
                            "id": "mod-tc5se0n0dirb90o",
                            "type": "modules"
                        }
                    },
                    "submodules": null,
                    "vcs-revision": {
                        "data": {
                            "id": "vrb-tc5se2gg1jf9fd0",
                            "type": "vcs-revisions"
                        }
                    }
                },
                "type": "module-versions"
            }
        ],
        "included": null,
        "links": {
            "first": "https://my.scalr.io/api/iacp/v3/module-versions?filter%5Bmodule%5D=mod-tc5se0n0dirb90o&page%5Bnumber%5D=1&page%5Bsize%5D=20",
            "last": "https://my.scalr.io/api/iacp/v3/module-versions?filter%5Bmodule%5D=mod-tc5se0n0dirb90o&page%5Bnumber%5D=1&page%5Bsize%5D=20",
            "next": null,
            "prev": null,
            "self": "https://my.scalr.io/api/iacp/v3/module-versions?filter%5Bmodule%5D=mod-tc5se0n0dirb90o&page%5Bnumber%5D=1&page%5Bsize%5D=20"
        },
        "meta": {
            "pagination": {
                "current-page": 1,
                "next-page": null,
                "prev-page": null,
                "total-count": 2,
                "total-pages": 1
            }
        }
    }
    

  • 404 Not Found – Module versions not found, or user unauthorized to perform action.

  • 4XX – Client error.

  • 5XX – Server error.

Get a Module Version

GET /api/iacp/v3/module-versions/{module_version}

Show details of a specific terraform module version.

Parameters
  • module_version (string) – The ID of the module version to show.

Query Parameters
  • include (array) – The comma-separated list of relationship paths. (Available values: module, vcs-revision)

Example Request:

GET /api/iacp/v3/module-versions/{module_version} HTTP/1.1
Host: my.scalr.io
Prefer: profile=preview
Status Codes
  • 200 OK

    Success.

    Example Respone:

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    Preference-Applied: profile=preview
    
    {
      "data": {
          "attributes": {
              "created-at": "2021-03-08T17:17:33Z",
              "dependencies": null,
              "details": "Readme",
              "error-message": null,
              "inputs": [
              {
                "default": "64512",
                "description": "Description",
                "name": "input",
                "type": ""
              },
              {
                "default": false,
                "description": "Description",
                "name": "input_bool",
                "type": "bool"
              },
              ],
              "outputs": [
              {
                "name": "output",
                "sensitive": false,
                "description": "description",
                "value": "value"
              },
              {
                "name": "output_hash",
                "sensitive": false,
                "description": "",
                "value": "value"
              }
              ],
              "resources": [
              {
                "address": "this",
                "type": "resource"
              }
              ],
              "source": "vcs",
              "status": "ok",
              "updated-at": "2021-03-08T17:17:34Z",
              "version": "2.32.0"
          },
          "id": "modver-tc5se2g5a5kno2o",
          "links": {
              "download": "https://my.scalr.io/api/tfe/v1/blobs/eyJhbGciOiJQQkVTMi1IUzUxMitBMjU2S1ciLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwicDJjIjo4MTkyLCJwMnMiOiJCMkFBYTFYZjVXSzFCZGJmdnROQ0ZRIn0.lGSbcUuzclL9gQBupjKtHLRehXBXEYAvgrKaqlfyccpC1LeaXdM7svZ2uEpc1sDf1r9CwqmqFARbEZnhX-X-ea-HZZimjfC1.S5GAd9YGP63jEXMCQ6cRZA.npYma_A0XT4LNAewjDiq30v8EGnsgdwJkOFc73yxmhMgooNyLw_hunu1m0GVpzZPPHnpCaaJ450CpibEfD7Xu_vt_J8fhO793H1wuQ7M-ktQIDqVDrfwYdo8Ut_cSJkD.fyEC1qOkZKESUu0NTY154iDdH5Xc47FSMP0R1JUQKIA",
              "self": "https://my.scalr.io/api/iacp/v3/module-versions/modver-tc5se2g5a5kno2o",
              "upload": "https://my.scalr.io/api/tfe/v1/blobs/eyJhbGciOiJQQkVTMi1IUzUxMitBMjU2S1ciLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwicDJjIjo4MTkyLCJwMnMiOiJiN0h1Y1JGdFlscllaNnpKdTU0YmRRIn0.wPdnUSplk9Nx9lzCL4uSe5MSzQojy5QYYlClka8O5pux3L_NZPWwGNxgiUacF_tW_1ksnnAQJ54pVWaXUG1gnQxoyEG-HF_B.yPKNcD8rwt93FdNBJo17yg.mquU8exgiv2__lPJO8MdqiOODTLU12q_jauUGtNt1SKjtj4YDn8MRCwPpChKGsLHpQc9_u8x4A4WWIzBMjs2TsoezFNkSjDiSexhw2IzUbUjr6pAsoYiOPbRlBxRbD7k.eRBOLhRO8qjJX_rhJm6riFcqB2C4ygkm_pG7UlC-bqg"
          },
          "relationships": {
              "registry-module": {
                  "data": {
                      "id": "mod-tc5se0n0dirb90o",
                      "type": "modules"
                  }
              },
              "submodules": null,
              "vcs-revision": {
                  "data": {
                      "id": "vrb-tc5se2gg1jf9fd0",
                      "type": "vcs-revisions"
                  }
              }
          },
          "type": "module-versions"
      },
      "included": null,
      "meta": null
    }
    

  • 404 Not Found – Module version not found or user unauthorized to perform action.

  • 422 Unprocessable Entity – Malformed request body (missing attributes, wrong types, etc.).

  • 4XX – Client error.

  • 5XX – Server error.

Resync a Module Version

POST /api/iacp/v3/module-versions/{module_version}/actions/resync

Trigger resync of the Module Version associated with the relationships.vcs-revision. Only modules associated with a VCS can be resynchronized.

Parameters
  • module_version (string) –

Status Codes
  • 204 No Content – Successfully triggered resync of the module version

  • 422 Unprocessable Entity – Malformed request body (missing attributes, wrong types, etc.).

  • 4XX – Client error.

  • 5XX – Server error.

List Modules

GET /api/iacp/v3/modules

This endpoint lists modules by various filters.

To list modules accessible from a certain environment, filter[environment] has to be specified. Modules from the account which this environment belongs as well as globally published modules will be listed as well.

To list modules accessible from a certain account, filter[account] has to be specified. Modules published globally will be listed as well.

To list modules accessible globally, both filter[account]=null and filter[environment]=null have to be specified.

If no filters were specified, all modules which the user has read access to will be listed.

Query Parameters
  • page[number] (string) – Page number

  • page[size] (string) – Page size

  • filter[name] (string) – Filter modules by name

  • filter[provider] (string) – Filter modules by provider

  • filter[source] (string) – Filter modules by source

  • filter[status] (string) – Filter modules by status

  • filter[environment] (string) – Filter modules by environment

  • filter[account] (string) – Filter modules by account

  • filter[module-versions][status] (string) – Filter modules by module-version status

  • filter[module-versions][is-root-module] (string) – Filter modules by module-version is-root-module

  • query (string) – Query string, search by id, name, provider, and submodules recursively

  • include (array) – The comma-separated list of relationship paths. (Available values: latest-module-version, module-versions, vcs-provider)

  • sort (array) – The comma-separated list of attributes. (Available values: created-at, name)

Example Request:

GET /api/iacp/v3/modules HTTP/1.1
Host: my.scalr.io
Prefer: profile=preview
Status Codes
  • 200 OK

    Success.

    Example Respone:

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    Preference-Applied: profile=preview
    
    {
        "data": [
            {
                "attributes": {
                    "created-at": "2021-03-08T17:17:10Z",
                    "description": "Terraform module for ec2-instance on provider aws.",
                    "error-message": null,
                    "name": "ec2-instance",
                    "path": null,
                    "permissions": {
                        "can-delete": true,
                        "can-resync": true,
                        "can-retry": true
                    },
                    "provider": "aws",
                    "source": "https://github.com/Perepyolka/terraform-aws-ec2-instance",
                    "status": "setup_complete",
                    "tag-prefix": null,
                    "updated-at": "2021-03-08T17:17:10Z",
                    "vcs-repo": {
                        "display-identifier": null,
                        "identifier": "Perepyolka/terraform-aws-ec2-instance",
                        "path": null,
                        "tag-prefix": null
                    }
                },
                "id": "mod-tc5sdkmf8ij7sqo",
                "links": {
                    "self": "https://my.scalr.io/api/iacp/v3/modules/mod-tc5sdkmf8ij7sqo"
                },
                "relationships": {
                    "account": null,
                    "created-by": {
                        "data": {
                            "id": "user-suh84u6vhn64l0o",
                            "type": "users"
                        }
                    },
                    "environment": null,
                    "last-active-version": {
                        "data": {
                            "id": "modver-tc5sdlvtsuh01so",
                            "type": "module-versions"
                        }
                    },
                    "last-version": {
                        "data": {
                            "id": "modver-tc5sdlml3umv77g",
                            "type": "module-versions"
                        }
                    },
                    "module-versions": {
                        "data": [
                            {
                                "id": "modver-tc5sdlml3umv77g",
                                "type": "module-versions"
                            },
                            {
                                "id": "modver-tc5sdlvtsuh01so",
                                "type": "module-versions"
                            }
                        ]
                    },
                    "organization": null,
                    "vcs-provider": {
                        "data": {
                            "id": "vcs-tc5scfesq268838",
                            "type": "vcs-providers"
                        }
                    }
                },
                "type": "modules"
            },
            {
                "attributes": {
                    "created-at": "2021-03-08T17:17:30Z",
                    "description": "Terraform module for vpc on provider aws.",
                    "error-message": null,
                    "name": "vpc",
                    "path": null,
                    "permissions": {
                        "can-delete": true,
                        "can-resync": true,
                        "can-retry": true
                    },
                    "provider": "aws",
                    "source": "https://github.com/Perepyolka/terraform-aws-vpc",
                    "status": "setup_complete",
                    "tag-prefix": null,
                    "updated-at": "2021-03-08T17:17:30Z",
                    "vcs-repo": {
                        "display-identifier": null,
                        "identifier": "Perepyolka/terraform-aws-vpc",
                        "path": null,
                        "tag-prefix": null
                    }
                },
                "id": "mod-tc5se0n0dirb90o",
                "links": {
                    "self": "https://my.scalr.io/api/iacp/v3/modules/mod-tc5se0n0dirb90o"
                },
                "relationships": {
                    "account": {
                        "data": {
                            "id": "acc-svrcncgh453bi8g",
                            "type": "accounts"
                        }
                    },
                    "created-by": {
                        "data": {
                            "id": "user-svrcmmpcrkmit1g",
                            "type": "users"
                        }
                    },
                    "environment": null,
                    "last-active-version": {
                        "data": {
                            "id": "modver-tc5se25e31ope30",
                            "type": "module-versions"
                        }
                    },
                    "last-version": {
                        "data": {
                            "id": "modver-tc5se25e31ope30",
                            "type": "module-versions"
                        }
                    },
                    "module-versions": {
                        "data": [
                            {
                                "id": "modver-tc5se25e31ope30",
                                "type": "module-versions"
                            },
                            {
                                "id": "modver-tc5se2g5a5kno2o",
                                "type": "module-versions"
                            }
                        ]
                    },
                    "organization": null,
                    "vcs-provider": {
                        "data": {
                            "id": "vcs-tc5scfesq268838",
                            "type": "vcs-providers"
                        }
                    }
                },
                "type": "modules"
            },
            {
                "attributes": {
                    "created-at": "2021-03-08T17:17:50Z",
                    "description": "Terraform module for module on provider scalr.",
                    "error-message": null,
                    "name": "module",
                    "path": null,
                    "permissions": {
                        "can-delete": true,
                        "can-resync": true,
                        "can-retry": true
                    },
                    "provider": "scalr",
                    "source": "https://github.com/Perepyolka/terraform-scalr-module",
                    "status": "setup_complete",
                    "tag-prefix": null,
                    "updated-at": "2021-03-08T17:17:50Z",
                    "vcs-repo": {
                        "display-identifier": null,
                        "identifier": "Perepyolka/terraform-scalr-module",
                        "path": null,
                        "tag-prefix": null
                    }
                },
                "id": "mod-tc5seck22g8nrgg",
                "links": {
                    "self": "https://my.scalr.io/api/iacp/v3/modules/mod-tc5seck22g8nrgg"
                },
                "relationships": {
                    "account": {
                        "data": {
                            "id": "acc-svrcncgh453bi8g",
                            "type": "accounts"
                        }
                    },
                    "created-by": {
                        "data": {
                            "id": "user-svrcmmpcrkmit1g",
                            "type": "users"
                        }
                    },
                    "environment": {
                        "data": {
                            "id": "env-svrcnchebt61e30",
                            "type": "environments"
                        }
                    },
                    "last-active-version": {
                        "data": {
                            "id": "modver-tc5seeb91o5nvio",
                            "type": "module-versions"
                        }
                    },
                    "last-version": {
                        "data": {
                            "id": "modver-tc5seeb91o5nvio",
                            "type": "module-versions"
                        }
                    },
                    "module-versions": {
                        "data": [
                            {
                                "id": "modver-tc5seeb91o5nvio",
                                "type": "module-versions"
                            }
                        ]
                    },
                    "organization": {
                        "data": {
                            "id": "env-svrcnchebt61e30",
                            "type": "organizations"
                        }
                    },
                    "vcs-provider": {
                        "data": {
                            "id": "vcs-tburi8v8tjct4e0",
                            "type": "vcs-providers"
                        }
                    }
                },
                "type": "modules"
            }
        ],
        "included": null,
        "links": {
            "first": "https://my.scalr.io/api/iacp/v3/modules?filter%5Benvironment%5D=env-svrcnchebt61e30&page%5Bnumber%5D=1&page%5Bsize%5D=20",
            "last": "https://my.scalr.io/api/iacp/v3/modules?filter%5Benvironment%5D=env-svrcnchebt61e30&page%5Bnumber%5D=1&page%5Bsize%5D=20",
            "next": null,
            "prev": null,
            "self": "https://my.scalr.io/api/iacp/v3/modules?filter%5Benvironment%5D=env-svrcnchebt61e30&page%5Bnumber%5D=1&page%5Bsize%5D=20"
        },
        "meta": {
            "pagination": {
                "current-page": 1,
                "next-page": null,
                "prev-page": null,
                "total-count": 3,
                "total-pages": 1
            }
        }
    }
    

  • 404 Not Found – Modules not found, or user unauthorized to perform action.

  • 4XX – Client error.

  • 5XX – Server error.

Publish a Module

POST /api/iacp/v3/modules

This endpoint creates a Module from a VCS repository.

The module’s source code directory should follow the standard module structure.

Scalr extracts various meta information from the module’s source:

  • It’s important to provide each variable and output blocks with a meaninful descriptions, as they will be displayed in a Module and Workspace Variables pages for your internal users.

  • README or README.md file will be displayed on a Module page.

  • Nested modules from modules/ directory will be searchable and available though the Registry just like top-level modules.

Modules can be published on both account and environment scopes. If neither scope is specified in the request body, the module will be published in the same scope that the related vcs-provider is published.

Request body:

Key path

Description

data.type* (string)

Available values: modules

data.id (string)

data.attributes.vcs-repo.identifier* (string)

A reference to the module’s VCS repository.

For GitHub, GitHub Enterprise and GitLab the format is <org>/<repo>. Azure DevOps Services has the format <org>/<project>/<repo>.

data.attributes.vcs-repo.path (string)

The repository sub-directory where the module source is located. If omitted or submitted as an empty string, this defaults to the repository’s root.

data.attributes.vcs-repo.tag-prefix (string)

Specify this attribute when a module’s releases are namespaced within a repository’s Git tags. This is usually the case for a mono repos with individually versioned components. For example if your module is tagged my-module/v1.0.0 it’s tag_prefix is my-module/.

data.relationships.account (object)

The account this module belongs to.

data.relationships.account.data.type* (string)

Available values: accounts

data.relationships.account.data.id* (string)

data.relationships.environment (object)

The environment this module belongs to.

data.relationships.environment.data.type* (string)

Available values: environments

data.relationships.environment.data.id* (string)

data.relationships.vcs-provider* (object)

The module’s VCS provider.

data.relationships.vcs-provider.data.type* (string)

Available values: vcs-providers

data.relationships.vcs-provider.data.id* (string)

Publish a Module from a VCS:

In the case where a module is developed in a dedicated repository, the module’s repository name should follow terraform-<PROVIDER>-<NAME> pattern. Module name and provider attributes will be extracted from the repository name. Module description copied the VCS repository description.

The repository Git tags are expected to be semantically versioned and named v<SEMVER> or <SEMVER>. Each matching tag will be processed and will produce a ModuleVersion resource.

After module module registration Scalr will listen for repository events, and automatically synchronize changes

POST /api/iacp/v3/modules HTTP/1.1
Host: my.scalr.io
Content-Type: application/vnd.api+json
Prefer: profile=preview

{
    "data": {
      "type": "modules",
      "attributes": {
        "vcs-repo": {
          "identifier": "Scalr/terraform-aws-vpc",
        }
      },
      "relationships": {
        "account": {
          "data": {
            "type": "accounts",
            "id": "acc-svrcncgh453bi8g"
          }
        },
        "vcs-provider": {
          "data": {
            "type": "vcs-providers",
            "id": "vcs-t745mjlp46208k0"
          }
        }
      }
    }
  }

Publish a Module From a Subdirectory:

Sometimes your module might be located in a repository subdirectory.

For example you’re keeping infrastructure configuration together with an application code. And your repository files structure is looking like:

$ tree Scalr/scalr-io
.
├── ...
└── infra
    ├── ...
    └── terraform
        └── terraform-google-scalr-io
            ├── main.tf
            ├── providers.tf
            ├── variables.tf
            ├── outputs.tf
            └── README.md

In this case, the module publication requires a path and attribute to be set and an optional description attribute:

POST /api/iacp/v3/modules HTTP/1.1
Host: my.scalr.io
Content-Type: application/vnd.api+json
Prefer: profile=preview

{
    "data": {
      "type": "modules",
      "description": "Terraform module which creates Scalr.IO application infrastructure on Google Cloud",
      "attributes": {
        "vcs-repo": {
          "identifier": "Scalr/scalr-io",
          "path": "infra/terraform/terraform-google-scalr-io"
        }
      },
      "relationships": {
        "account": {
          "data": {
            "type": "accounts",
            "id": "acc-svrcncgh453bi8g"
          }
        },
        "vcs-provider": {
          "data": {
            "type": "vcs-providers",
            "id": "vcs-t745mjlp46208k0"
          }
        }
      }
    }
  }

Publish a Module From a Mono Repo:

The easiest way to model a mono repo of terraform modules, is placing all modules into a nested modules/ folder, and wrap them up into a top-level “package” module.

$ tree terraform-system-infra
.
├── modules/
│   ├── primitives/        # private module
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   └── outputs.tf
│   ├── networking/        # depends from ../primitives
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   ├── outputs.tf
|   |   ├── README.md
│   │   └── ...
|   ├── mongo-cluster/     # depends from ../primitives and ../networking
│   │   ├── variables.tf
│   │   ├── outputs.tf
|   |   ├── README.md
│   │   └── ...
│   └── ...
|   # Package module
├── main.tf
└── README.md

The top-level main.tf can have only a single null_resource to satisfy minimum requirements of the terraform module structure.

resource null_resource "package" {
  triggers = {
    always = timestamp()
  }
  provisioner "local-exec" {
    command = "echo 'This Terraform module is a package of nested modules. You should not use the top-level module directly'; exit 1"
  }
}

The README.md should have a table of contents with the links to nested modules READMEs.

The networking module usage:

module "networking" {
  source = "<scalr-registry-uri>/infra/system//modules/networking"
  version = "1.7.1"
}
POST /api/iacp/v3/modules HTTP/1.1
Host: my.scalr.io
Content-Type: application/vnd.api+json
Prefer: profile=preview

{
    "data": {
      "type": "modules",
      "attributes": {
        "vcs-repo": {
          "identifier": "Scalr/terraform-system-infra",
        }
      },
      "relationships": {
        "account": {
          "data": {
            "type": "accounts",
            "id": "acc-svrcncgh453bi8g"
          }
        },
        "vcs-provider": {
          "data": {
            "type": "vcs-providers",
            "id": "vcs-t745mjlp46208k0"
          }
        }
      }
    }
  }

Publish a Module from a Mono Repo with Individually Versioned Components:

If your development approach is to keep many (say shared library) modules in a mono repo, but release each module individually versioned, you should consider the following example.

Each module should have in a repository it’s own Git tag namespace, e.g. <TAG-PREFIX>v<SEMVER> and a subdirectory: path/to/terraform-<PROVIDER>-<NAME>.

POST /api/iacp/v3/modules HTTP/1.1
Host: my.scalr.io
Content-Type: application/vnd.api+json
Prefer: profile=preview

{
    "data": {
      "type": "modules",
      "attributes": {
        "description": "Terraform module which creates infrastructure on AWS",
        "vcs-repo": {
          "identifier": "Scalr/infra",
          "path": "library/terraform-aws-my-module",
          "tag-prefix": "my-module/"
        }
      },
      "relationships": {
        "account": {
          "data": {
            "type": "accounts",
            "id": "acc-svrcncgh453bi8g"
          }
        },
        "vcs-provider": {
          "data": {
            "type": "vcs-providers",
            "id": "vcs-t745mjlp46208k0"
          }
        }
      }
    }
  }
Status Codes
  • 201 Created

    Successfully created module.

    Example Respone:

    HTTP/1.1 201 Created
    Content-Type: application/vnd.api+json
    Preference-Applied: profile=preview
    
    {
        "data": {
            "attributes": {
                "created-at": "2021-02-16T07:35:31Z",
                "description": "Terraform module which creates VPC resources on AWS",
                "error-message": null,
                "name": "vpc",
                "permissions": {
                    "can-delete": true,
                    "can-resync": true,
                    "can-retry": true
                },
                "provider": "aws",
                "source": "https://github.com/Scalr/terraform-aws-vpc",
                "status": "pending",
                "updated-at": "2021-02-16T07:35:31Z",
                "vcs-repo": {
                    "display-identifier": null,
                    "identifier": "Scalr/terraform-aws-vpc",
                    "path": null,
                    "provider-type": "github",
                    "tag-prefix": null
                }
            },
            "id": "mod-tb51l0r15hfeh38",
            "links": {
                "self": "https://my.scalr.io/api/iacp/v3/modules/mod-tb51l0r15hfeh38"
            },
            "relationships": {
                "account": {
                   "data": {
                      "type": "accounts",
                      "id": "acc-svrcncgh453bi8g"
                   }
                },
                "created-by": {
                    "data": {
                        "id": "user-suh84u6vhn64l0o",
                        "type": "users"
                    }
                },
                "environment": null,
                "latest-version": null,
                "module-versions": null,
                "vcs-provider": {
                    "data": {
                       "type": "vcs-providers",
                       "id": "vcs-t745mjlp46208k0"
                    }
                },
            },
            "type": "modules"
        },
        "included": null,
        "meta": null
    }
    

  • 403 Forbidden – User unauthorized to perform action.

  • 404 Not Found – Relationship resource not found, or user unauthorized to perform action.

  • 422 Unprocessable Entity – Malformed request body (missing attributes, wrong types, etc.).

  • 4XX – Client error.

  • 5XX – Server error.

Unpublish a Module

DELETE /api/iacp/v3/modules/{module}

This endpoint removes the module from the registry.

Parameters
  • module (string) – The ID of the module.

Status Codes

Get a Module

GET /api/iacp/v3/modules/{module}

Show details of a specific terraform module.

Parameters
  • module (string) – The ID of the module to show.

Query Parameters
  • include (array) – The comma-separated list of relationship paths. (Available values: latest-module-version, module-versions, vcs-provider)

Example Request:

GET /api/iacp/v3/modules/{module} HTTP/1.1
Host: my.scalr.io
Prefer: profile=preview
Status Codes
  • 200 OK

    Success.

    Example Respone:

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    Preference-Applied: profile=preview
    
    {
        "data": {
            "attributes": {
                "created-at": "2021-03-08T17:17:30Z",
                "description": "Terraform module for vpc on provider aws.",
                "error-message": null,
                "name": "vpc",
                "path": null,
                "permissions": {
                    "can-delete": true,
                    "can-resync": true,
                    "can-retry": true
                },
                "provider": "aws",
                "source": "https://github.com/Scalr/terraform-aws-vpc",
                "status": "setup_complete",
                "tag-prefix": null,
                "updated-at": "2021-03-08T17:17:30Z",
                "vcs-repo": {
                    "display-identifier": null,
                    "identifier": "Perepyolka/terraform-aws-vpc",
                    "path": null,
                    "tag-prefix": null
                }
            },
            "id": "mod-tc5se0n0dirb90o",
            "links": {
                "self": "https://my.scalr.io/api/iacp/v3/modules/mod-tc5se0n0dirb90o"
            },
            "relationships": {
                "account": {
                    "data": {
                        "id": "acc-svrcncgh453bi8g",
                        "type": "accounts"
                    }
                },
                "created-by": {
                    "data": {
                        "id": "user-svrcmmpcrkmit1g",
                        "type": "users"
                    }
                },
                "environment": null,
                "last-active-version": {
                    "data": {
                        "id": "modver-tc5se25e31ope30",
                        "type": "module-versions"
                    }
                },
                "last-version": {
                    "data": {
                        "id": "modver-tc5se25e31ope30",
                        "type": "module-versions"
                    }
                },
                "module-versions": {
                    "data": [
                        {
                            "id": "modver-tc5se25e31ope30",
                            "type": "module-versions"
                        },
                        {
                            "id": "modver-tc5se2g5a5kno2o",
                            "type": "module-versions"
                        }
                    ]
                },
                "organization": null,
                "vcs-provider": {
                    "data": {
                        "id": "vcs-tc5scfesq268838",
                        "type": "vcs-providers"
                    }
                }
            },
            "type": "modules"
        },
        "included": null,
        "meta": null
    }
    

  • 404 Not Found – Module not found or user unauthorized to perform action.

  • 422 Unprocessable Entity – Malformed request body (missing attributes, wrong types, etc.).

  • 4XX – Client error.

  • 5XX – Server error.

Resync a Module

POST /api/iacp/v3/modules/{module}/actions/resync

Trigger resync of the Module associated with the VCS repository.

Parameters
  • module (string) – The ID of the module to resync.

Example Request:

POST /api/iacp/v3/modules/{module}/actions/resync HTTP/1.1
Host: my.scalr.io
Content-Type: application/json
Prefer: profile=preview

{
    "force": true
}
Status Codes