Merge branch '321102-terraform-module-registry-iteration-1-docs' into 'master'

Docs for Terraform module registry iteration 1

See merge request gitlab-org/gitlab!58813

doc/user/infrastructure/index.md

@@ -74,6 +74,12 @@ Neither Terraform nor GitLab encrypts the plan file by default. If your Terrafor
 includes sensitive data such as passwords, access tokens, or certificates, GitLab strongly
 recommends encrypting plan output or modifying the project visibility settings.
 
+## Terraform module registry
+
+GitLab can be used as a [Terraform module registry](../packages/terraform_module_registry/index.md)
+to create and publish Terraform modules to a private registry specific to your
+top-level namespace.
+
 ## Terraform integration in Merge Requests
 
 Collaborating around Infrastructure as Code (IaC) changes requires both code changes

doc/user/packages/index.md

@@ -46,7 +46,6 @@ guides you through the process.
 | Puppet    | [#36897](https://gitlab.com/gitlab-org/gitlab/-/issues/36897) |
 | RPM       | [#5932](https://gitlab.com/gitlab-org/gitlab/-/issues/5932) |
 | SBT       | [#36898](https://gitlab.com/gitlab-org/gitlab/-/issues/36898) |
-| Terraform | [Draft: Merge Request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18834) |
 | Vagrant   | [#36899](https://gitlab.com/gitlab-org/gitlab/-/issues/36899) |
 
 <!-- vale gitlab.Spelling = YES -->
@@ -54,6 +53,16 @@ guides you through the process.
 
 The GitLab [Container Registry](container_registry/index.md) is a secure and private registry for container images. It's built on open source software and completely integrated within GitLab. Use GitLab CI/CD to create and publish images. Use the GitLab [API](../../api/container_registry.md) to manage the registry across groups and projects.
 
+## Infrastructure Registry
+
+The GitLab [Infrastructure Registry](infrastructure_registry/index.md) is a secure and private registry for infrastructure packages. You can use GitLab CI/CD to create and publish infrastructure packages.
+
+The Infrastructure Registry supports the following formats:
+
+| Package type | GitLab version |
+| ------------ | -------------- |
+| [Terraform Module](terraform_module_registry/index.md) | 14.0+ |
+
 ## Dependency Proxy
 
 The [Dependency Proxy](dependency_proxy/index.md) is a local proxy for frequently-used upstream images and packages.

doc/user/packages/infrastructure_registry/index.md

+---
+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
+---
+
+# Infrastructure Registry **(FREE)**
+
+> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3221) in GitLab 14.0.
+
+With the GitLab Infrastructure Registry, you can use GitLab projects as a
+private registry for infrastructure packages. You can create and publish
+packages with GitLab CI/CD, which can then be consumed from other private
+projects.
+
+## View packages
+
+To view packages within your project or group:
+
+1. Go to the project or group.
+1. Go to **Packages & Registries > Infrastructure Registry**.
+
+You can search, sort, and filter packages on this page.
+
+When you view packages in a group:
+
+- All packages published to the group and its projects are displayed.
+- Only the projects you can access are displayed.
+- If a project is private, or you are not a member of the project, it is not displayed.
+
+For information on how to create and upload a package, view the GitLab
+documentation for your package type:
+
+- [Terraform modules](../terraform_module_registry/index.md)
+
+## Use GitLab CI/CD to build packages
+
+To use [GitLab CI/CD](../../../ci/README.md) to build packages, you can
+authenticate with the [`CI_JOB_TOKEN` predefined variable](../../../ci/variables/predefined_variables.md).
+
+CI/CD templates, which you can use to get started, are in [this repository](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates).
+
+Learn more about using CI/CD to build:
+
+- [Terraform modules](../terraform_module_registry/index.md#publish-a-terraform-module-by-using-cicd)
+
+If you use CI/CD to build a package, you can find extended activity information
+when you view the package details:
+
+![Package CI/CD activity](../package_registry/img/package_activity_v12_10.png)
+
+You can see the pipeline that published the package as well as the commit and the user who triggered it. However, the history is limited to five updates per package.
+
+## Download a package
+
+To download a package:
+
+1. Go to **Packages & Registries > Infrastructure Registry**.
+1. Select the name of the package you want to download.
+1. In the **Activity** section, select the name of the package you want to download.
+
+## Delete a package
+
+You cannot edit a package after you publish it in the Infrastructure Registry. Instead, you
+must delete and recreate it.
+
+To delete a package, you must have suitable [permissions](../../permissions.md).
+
+You can delete packages by using [the API](../../../api/packages.md#delete-a-project-package) or the UI.
+
+To delete a package in the UI, from your group or project:
+
+1. Go to **Packages & Registries > Infrastructure Registry**.
+1. Find the name of the package you want to delete.
+1. Select **Delete**.
+
+The package is permanently deleted.
+
+## Disable the Infrastructure Registry
+
+The Infrastructure Registry is automatically enabled.
+
+For self-managed instances, a GitLab administrator can
+[disable](../../../administration/packages/index.md) **Packages & Registries**,
+which removes this menu item from the sidebar. **(FREE SELF)**
+
+You can also remove the Infrastructure Registry for a specific project:
+
+1. In your project, go to **Settings > General**.
+1. Expand the **Visibility, project features, permissions** section and toggle **Packages** off (in gray).
+1. Select **Save changes**.
+
+To enable it back, follow the same steps above and toggle it on (in blue).

doc/user/packages/terraform_module_registry/index.md

+---
+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).
+- A [CI/CD job token](../../../api/README.md#gitlab-cicd-job-token).
+- A [deploy token](../../project/deploy_tokens/index.md).
+
+## 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 deploy token, it must be configured with the `read_package_registry` and/or `write_package_registry` scope.
+
+Authentication tokens (Deploy Token, 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"'
+```