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.

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.