gitlab-org--gitlab-foss/doc/user/packages/terraform_module_registry/index.md

stage	group	info
Configure	Configure	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments

Terraform module registry (FREE)

Introduced in GitLab 14.0.

Publish Terraform modules in your project's Infrastructure Registry, then reference them using GitLab as a Terraform module registry.

Authenticate to the Terraform module registry

To authenticate to the Terraform module registry, you need either:

• A personal access token with at least read_api rights.
• A CI/CD job token.

Publish a Terraform Module

When you publish a Terraform Module, if it does not exist, it is created.

If a package with the same name and version already exists, it will not be created. It does not overwrite the existing package.

Prerequisites:

• You need to authenticate with the API. If authenticating with a deploy token, it must be configured with the write_package_registry scope.

PUT /projects/:id/packages/terraform/modules/:module-name/:module-system/:module-version/file

Attribute	Type	Required	Description
id	integer/string	yes	The ID or URL-encoded path of the project.
module-name	string	yes	The package name. It can contain only lowercase letters (a-z), uppercase letter (A-Z), numbers (0-9), or hyphens (-) and cannot exceed 64 characters.
module-system	string	yes	The package system. It can contain only lowercase letters (a-z) and numbers (0-9), and cannot exceed 64 characters.
module-version	string	yes	The package version. It must be valid according to the Semantic Versioning Specification.

Provide the file content in the request body.

Note that, in the following example, the request must end with /file. If you send a request ending with something else, it results in a 404 error {"error":"404 Not Found"}.

Example request using a personal access token:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --upload-file path/to/file.tgz \
     "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/terraform/modules/my-module/my-system/0.0.1/file"

Example response:

{
  "message":"201 Created"
}

Example request using a deploy token:

curl --header "DEPLOY-TOKEN: <deploy_token>" \
     --upload-file path/to/file.tgz \
     "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/terraform/modules/my-module/my-system/0.0.1/file"

Example response:

{
  "message":"201 Created"
}

Reference a Terraform Module

Prerequisites:

• You need to authenticate with the API. If authenticating with a personal access token, it must be configured with the read_api scope.

Authentication tokens (Job Token or Personal Access Token) can be provided for terraform in your ~/.terraformrc file:

credentials "gitlab.com" {
  token = "<TOKEN>"
}

Where gitlab.com can be replaced with the hostname of your self-managed GitLab instance.

You can then reference your Terraform Module from a downstream Terraform project:

module "<module>" {
  source = "gitlab.com/<namespace>/<module-name>/<module-system>"
}

Publish a Terraform module by using CI/CD

To work with Terraform modules in GitLab CI/CD, you can use CI_JOB_TOKEN in place of the personal access token in your commands.

For example:

image: curlimages/curl:latest

stages:
  - upload

upload:
  stage: upload
  script:
    - 'curl --header "JOB-TOKEN: $CI_JOB_TOKEN" --upload-file path/to/file.tgz "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/terraform/modules/my-module/my-system/0.0.1/file"'

Example projects

For examples of the Terraform module registry, check the projects below:

• The GitLab local file project creates a minimal Terraform module and uploads it into the Terraform module registry using GitLab CI/CD.
• The Terraform module test project uses the module from the previous example.