debian-mirror-gitlab/doc/user/packages/terraform_module_registry/index.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

150 lines
7.1 KiB
Markdown
Raw Normal View History

2021-09-04 01:27:46 +05:30
---
2023-01-13 00:05:48 +05:30
stage: Package
group: Package Registry
2022-11-25 23:54:43 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
2021-09-04 01:27:46 +05:30
---
# Terraform module registry **(FREE)**
2021-11-11 11:23:49 +05:30
> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3221) in GitLab 14.0.
2021-09-04 01:27:46 +05:30
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:
2022-03-02 08:16:31 +05:30
- A [personal access token](../../../api/index.md#personalprojectgroup-access-tokens) with at least `read_api` rights.
2021-11-11 11:23:49 +05:30
- A [CI/CD job token](../../../ci/jobs/ci_job_token.md).
2021-09-04 01:27:46 +05:30
## Publish a Terraform Module
When you publish a Terraform Module, if it does not exist, it is created.
Prerequisites:
2023-01-13 00:05:48 +05:30
- The package name and version [must be unique in the top-level namespace](../infrastructure_registry/index.md#how-module-resolution-works).
2022-07-23 23:45:48 +05:30
- Your project and group names must not include a dot (`.`). For example, `source = "gitlab.example.com/my.group/project.name"`.
- You must [authenticate with the API](../../../api/index.md#authentication). If authenticating with a deploy token, it must be configured with the `write_package_registry` scope.
2023-01-13 00:05:48 +05:30
- The name of a module [must be unique within the scope of its group](../infrastructure_registry/index.md#how-module-resolution-works), otherwise an
[error occurs](#troubleshooting).
2021-09-04 01:27:46 +05:30
```plaintext
2022-01-26 12:08:38 +05:30
PUT /projects/:id/packages/terraform/modules/:module-name/:module-system/:module-version/file
2021-09-04 01:27:46 +05:30
```
| Attribute | Type | Required | Description |
| -------------------| --------------- | ---------| -------------------------------------------------------------------------------------------------------------------------------- |
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/index.md#namespaced-path-encoding). |
2022-07-23 23:45:48 +05:30
| `module-name` | string | yes | The package name. **Supported syntax**: One to 64 ASCII characters, including lowercase letters (a-z), digits (0-9), and hyphens (`-`).
| `module-system` | string | yes | The package system. **Supported syntax**: One to 64 ASCII characters, including lowercase letters (a-z), digits (0-9), and hyphens (`-`). More information can be found in the [Terraform Module Registry Protocol documentation](https://www.terraform.io/internals/module-registry-protocol).
2022-01-26 12:08:38 +05:30
| `module-version` | string | yes | The package version. It must be valid according to the [Semantic Versioning Specification](https://semver.org/).
2021-09-04 01:27:46 +05:30
Provide the file content in the request body.
2022-04-04 11:22:00 +05:30
As the following example shows, requests must end with `/file`.
2021-11-11 11:23:49 +05:30
If you send a request ending with something else, it results in a 404
error `{"error":"404 Not Found"}`.
2021-09-04 01:27:46 +05:30
Example request using a personal access token:
```shell
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:
```json
{
"message":"201 Created"
}
```
Example request using a deploy token:
```shell
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:
```json
{
"message":"201 Created"
}
```
## Reference a Terraform Module
Prerequisites:
2021-09-30 23:02:18 +05:30
- You need to [authenticate with the API](../../../api/index.md#authentication). If authenticating with a personal access token, it must be configured with the `read_api` scope.
2021-09-04 01:27:46 +05:30
Authentication tokens (Job Token or Personal Access Token) can be provided for `terraform` in your `~/.terraformrc` file:
```plaintext
credentials "gitlab.com" {
token = "<TOKEN>"
}
```
Where `gitlab.com` can be replaced with the hostname of your self-managed GitLab instance.
2022-05-07 20:08:51 +05:30
You can then refer to your Terraform Module from a downstream Terraform project:
2021-09-04 01:27:46 +05:30
```plaintext
module "<module>" {
2022-01-26 12:08:38 +05:30
source = "gitlab.com/<namespace>/<module-name>/<module-system>"
2021-09-04 01:27:46 +05:30
}
```
2022-08-27 11:52:29 +05:30
Where `<namespace>` is the [namespace](../../../user/namespace/index.md) of the Terraform module registry.
2022-05-07 20:08:51 +05:30
2021-09-04 01:27:46 +05:30
## Publish a Terraform module by using CI/CD
2021-09-30 23:02:18 +05:30
To work with Terraform modules in [GitLab CI/CD](../../../ci/index.md), you can use
2021-09-04 01:27:46 +05:30
`CI_JOB_TOKEN` in place of the personal access token in your commands.
2022-08-13 15:12:31 +05:30
For example, this job uploads a new module for the `local` [system provider](https://registry.terraform.io/browse/providers) and uses the module version from the Git commit tag:
2021-09-04 01:27:46 +05:30
```yaml
stages:
- upload
upload:
stage: upload
2022-07-23 23:45:48 +05:30
image: curlimages/curl:latest
variables:
TERRAFORM_MODULE_DIR: ${CI_PROJECT_DIR} # The path to your Terraform module
TERRAFORM_MODULE_NAME: ${CI_PROJECT_NAME} # The name of your Terraform module
TERRAFORM_MODULE_SYSTEM: local # The system or provider your Terraform module targets (ex. local, aws, google)
2022-08-13 15:12:31 +05:30
TERRAFORM_MODULE_VERSION: ${CI_COMMIT_TAG} # Tag commits with SemVer for the version of your Terraform module to be published
2021-09-04 01:27:46 +05:30
script:
2022-08-13 15:12:31 +05:30
- TERRAFORM_MODULE_NAME=$(echo "${TERRAFORM_MODULE_NAME}" | tr " _" -) # module-name must not have spaces or underscores, so translate them to hyphens
- tar -vczf ${TERRAFORM_MODULE_NAME}-${TERRAFORM_MODULE_SYSTEM}-${TERRAFORM_MODULE_VERSION}.tgz -C ${TERRAFORM_MODULE_DIR} --exclude=./.git .
2022-08-27 11:52:29 +05:30
- 'curl --location --header "JOB-TOKEN: ${CI_JOB_TOKEN}"
2022-08-13 15:12:31 +05:30
--upload-file ${TERRAFORM_MODULE_NAME}-${TERRAFORM_MODULE_SYSTEM}-${TERRAFORM_MODULE_VERSION}.tgz
${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/terraform/modules/${TERRAFORM_MODULE_NAME}/${TERRAFORM_MODULE_SYSTEM}/${TERRAFORM_MODULE_VERSION}/file'
2022-07-23 23:45:48 +05:30
rules:
- if: $CI_COMMIT_TAG
2021-09-04 01:27:46 +05:30
```
2022-08-13 15:12:31 +05:30
To trigger this upload job, add a Git tag to your commit. Ensure the tag follows the [Semantic Versioning Specification](https://semver.org/) that Terraform requires. The `rules:if: $CI_COMMIT_TAG` ensures that only tagged commits to your repo trigger the module upload job.
2022-07-23 23:45:48 +05:30
For other ways to control jobs in your CI/CD pipeline, refer to the [`.gitlab-ci.yml`](../../../ci/yaml/index.md) keyword reference.
2021-09-04 01:27:46 +05:30
## Example projects
For examples of the Terraform module registry, check the projects below:
- The [_GitLab local file_ project](https://gitlab.com/mattkasa/gitlab-local-file) creates a minimal Terraform module and uploads it into the Terraform module registry using GitLab CI/CD.
- The [_Terraform module test_ project](https://gitlab.com/mattkasa/terraform-module-test) uses the module from the previous example.
2023-01-13 00:05:48 +05:30
## Troubleshooting
- Publishing a module with a duplicate name results in a `{"message":"Access Denied"}` error. There's an ongoing discussion about allowing duplicate module names [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/368040).