diff options
Diffstat (limited to 'doc/user/packages/terraform_module_registry')
-rw-r--r-- | doc/user/packages/terraform_module_registry/index.md | 124 |
1 files changed, 124 insertions, 0 deletions
diff --git a/doc/user/packages/terraform_module_registry/index.md b/doc/user/packages/terraform_module_registry/index.md new file mode 100644 index 00000000000..efb2b8ddf8e --- /dev/null +++ b/doc/user/packages/terraform_module_registry/index.md @@ -0,0 +1,124 @@ +--- +stage: Configure +group: Configure +info: 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](https://gitlab.com/groups/gitlab-org/-/epics/3221) 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](../../../api/README.md#personalproject-access-tokens) with at least `read_api` rights. +- A [CI/CD job token](../../../api/README.md#gitlab-cicd-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](../../../api/README.md#authentication). If authenticating with a deploy token, it must be configured with the `write_package_registry` scope. + +```plaintext +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](../../../api/README.md#namespaced-path-encoding). | +| `module_name` | string | yes | The package name. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), or hyphens (`-`). +| `module_system` | string | yes | The package name. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), or hyphens (`-`). +| `module_version` | string | yes | The package version. It must be valid according to the [Semantic Versioning Specification](https://semver.org/). + +Provide the file content in the request body. + +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: + +- You need to [authenticate with the API](../../../api/README.md#authentication). 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: + +```plaintext +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: + +```plaintext +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](../../../ci/README.md), you can use +`CI_JOB_TOKEN` in place of the personal access token in your commands. + +For example: + +```yaml +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](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. |