Terraform 모듈 보기
Terraform Module Registry에 인증
Terraform 모듈 게시
Terraform 모듈 참조
- 네임스페이스로부터
- 프로젝트로부터
Terraform 모듈 다운로드
모듈 해상도 작동 방식
Terraform 모듈 삭제
Terraform 모듈 레지스트리 비활성화
예제 프로젝트
문제 해결

Terraform 모듈 레지스트리

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

GitLab 14.0에서 소개되었습니다.
인프라 레지스트리 및 Terraform 모듈 레지스트리가 GitLab 15.11에서 단일 Terraform 모듈 레지스트리 기능으로 Merge되었습니다.
그룹 지원이 GitLab 16.9에서 소개되었습니다.

Terraform Module Registry를 사용하면 GitLab 프로젝트를 Terraform 모듈의 개인 레지스트리로 사용할 수 있습니다. GitLab CI/CD를 사용하여 모듈을 생성하고 게시한 후 다른 개인 프로젝트에서 사용할 수 있습니다.

Terraform 모듈 보기

프로젝트 또는 그룹에서 Terraform 모듈을 보려면:

왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
운영 > Terraform 모듈을 선택합니다.

이 페이지에서 모듈을 검색하고 정렬, 필터링할 수 있습니다.

Terraform Module Registry에 인증

Terraform Module Registry에 인증하려면 다음 중 하나가 필요합니다.

적어도 read_api 권한이 있는 개인 액세스 토큰.
CI/CD 작업 토큰.
read_package_registry 또는 write_package_registry 범위가 있는 배포 토큰 또는 둘 다.

여기에 문서화되지 않은 인증 방법을 사용하지 마십시오. 문서화되지 않은 인증 방법은 나중에 제거될 수 있습니다.

Terraform 모듈 게시

Terraform 모듈을 게시하면 존재하지 않는 경우 생성됩니다.

API 사용

Terraform Module Registry API를 사용하여 Terraform 모듈을 게시할 수 있습니다.

전제 조건:

중복이 허용된 경우가 아니면 패키지 이름과 버전은 상위 수준 네임스페이스에서 고유해야 합니다.
프로젝트 및 그룹 이름에는 점(.)이 포함되어서는 안 됩니다. 예: source = "gitlab.example.com/my.group/project.name".
API로 인증해야 합니다. 배포 토큰으로 인증하는 경우 write_package_registry 범위로 구성해야 합니다.
중복이 허용된 경우가 아니면 모듈의 이름은 그룹의 범위에서 고유해야 합니다. 그렇지 않으면 오류가 발생합니다.

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

속성	유형	필수	설명
`id`	integer/string	예	프로젝트의 ID 또는 URL-인코딩된 경로.
`module-name`	string	예	모듈 이름. 지원되는 구문: 소문자 알파벳 (a-z) 및 숫자 (0-9)를 포함한 1~64자 ASCII 문자. 모듈 이름은 64자를 초과할 수 없습니다.
`module-system`	string	예	모듈 시스템. 지원되는 구문: 소문자 알파벳 (a-z) 및 숫자 (0-9)를 포함한 1~64자 ASCII 문자. 모듈 시스템은 64자를 초과할 수 없습니다. 자세한 정보는 Terraform 모듈 레지스트리 프로토콜 문서에서 확인할 수 있습니다.
`module-version`	string	예	모듈 버전. 의미론적 버전 지정 규칙에 따라 유효해야 합니다.

요청 본문에 파일 내용을 제공합니다.

다음 예시에서 요청은 /file로 끝나야 합니다. 다른 값으로 끝나는 요청을 보내면 404 오류( {"error":"404 Not Found"} )가 발생합니다.

개인 액세스 토큰을 사용한 예시 요청:

curl --fail-with-body --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"

배포 토큰을 사용한 요청의 예시:

curl --fail-with-body --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"

응답 예시:

{
  "message":"201 Created"
}

CI/CD 템플릿 사용(권장됨)

GitLab 15.9에서 소개되었습니다.

Terraform-Module.gitlab-ci.yml 또는 고급 Terraform/Module-Base.gitlab-ci.yml CI/CD 템플릿을 사용하여 Terraform 모듈을 GitLab terraform 레지스트리에 게시할 수 있습니다:

include:
  template: Terraform-Module.gitlab-ci.yml

파이프라인에는 다음 작업이 포함되어 있습니다:

fmt - Terraform 모듈의 포맷을 유효성 검사합니다.
kics-iac-sast - Terraform 모듈을 보안 문제에 대해 테스트합니다.
deploy - 태그 파이프라인 전용. Terraform 모듈을 Terraform 모듈 레지스트리에 배포합니다.

파이프라인 변수

다음 변수로 파이프라인을 구성할 수 있습니다:

변수	기본값	설명
`TERRAFORM_MODULE_DIR`	`${CI_PROJECT_DIR}`	Terraform 프로젝트의 루트 디렉터리의 상대 경로.
`TERRAFORM_MODULE_NAME`	`${CI_PROJECT_NAME}`	Terraform 모듈의 이름. 공백이나 밑줄을 포함해서는 안 됩니다.
`TERRAFORM_MODULE_SYSTEM`	`local`	Terraform 모듈 대상의 시스템 또는 제공자. 예: `local`, `aws`, `google`.
`TERRAFORM_MODULE_VERSION`	`${CI_COMMIT_TAG}`	Terraform 모듈 버전. 의미론적 버전 지정 규칙을 따라야 합니다.

매뉴얼으로 CI/CD 사용하기

GitLab CI/CD에서 Terraform 모듈을 사용하려면, 명령어에서 개인 접근 토큰 대신에 CI_JOB_TOKEN을 사용할 수 있습니다.

예를 들어, 다음 작업은 local system provider를 위한 새로운 모듈을 업로드하고, Git 커밋 태그에서 모듈 버전을 사용합니다:

stages:
  - deploy

upload:
  stage: deploy
  image: curlimages/curl:latest
  variables:
    TERRAFORM_MODULE_DIR: ${CI_PROJECT_DIR}    # Terraform 프로젝트의 루트 디렉터리로의 상대 경로.
    TERRAFORM_MODULE_NAME: ${CI_PROJECT_NAME}  # Terraform 모듈의 이름으로, 공백이나 밑줄이 없어야 합니다(하이픈으로 변환됩니다).
    TERRAFORM_MODULE_SYSTEM: local             # Terraform 모듈이 타겟으로 하는 시스템 또는 프로바이더 (예: local, aws, google).
    TERRAFORM_MODULE_VERSION: ${CI_COMMIT_TAG} # 버전 - Terraform 모듈 버전 관리를 위해 SemVer를 따르는 것이 좋습니다.
  script:
    - TERRAFORM_MODULE_NAME=$(echo "${TERRAFORM_MODULE_NAME}" | tr " _" -) # 모듈 이름에 공백이나 밑줄이 있으면 하이픈으로 변환
    - tar -vczf /tmp/${TERRAFORM_MODULE_NAME}-${TERRAFORM_MODULE_SYSTEM}-${TERRAFORM_MODULE_VERSION}.tgz -C ${TERRAFORM_MODULE_DIR} --exclude=./.git .
    - 'curl --fail-with-body --location --header "JOB-TOKEN: ${CI_JOB_TOKEN}"
         --upload-file /tmp/${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'
  rules:
    - if: $CI_COMMIT_TAG

이 업로드 작업을 트리거하려면 커밋에 Git 태그를 추가하세요. rules:if: $CI_COMMIT_TAG는 리포지터리에 태그가 달린 커밋만 모듈 업로드 작업을 트리거하도록 보장합니다. CI/CD 파이프라인에서 작업을 제어하는 다른 방법은 CI/CD YAML 구문 참조를 참조하십시오.

중복된 Terraform 모듈 허용하기

GitLab 16.8에서 도입됨.

기본적으로, Terraform 모듈 레지스트리는 동일한 네임스페이스 내 모듈 이름에 대해 유일성을 요구합니다.

중복 모듈 이름을 발행하도록 허용하려면:

왼쪽 사이드바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
설정 > 패키지 및 레지스트리를 선택합니다.
Duplicate packages 테이블의 Terraform module 행에서 Allow duplicates 토글을 끄십시오.
선택사항. Exeptions 텍스트 상자에 허용할 패키지 이름과 일치하는 정규 표현식을 입력합니다.

변경 사항이 자동으로 저장됩니다.

또한 GraphQL API에서 terraform_module_duplicates_allowed를 활성화하여 중복된 이름을 발행할 수도 있습니다.

특정 이름으로 중복을 허용하려면:

terraform_module_duplicates_allowed가 비활성화되어 있는지 확인하세요.
중복을 허용하려는 모듈 이름에 대한 정규 표현식 패턴을 정의하기 위해 terraform_module_duplicate_exception_regex를 사용합니다.

상위 네임스페이스 설정이 하위 네임스페이스 설정보다 우선합니다. 예를 들어, 그룹에 terraform_module_duplicates_allowed를 활성화하고 서브그룹에 비활성화하면, 중복은 그룹 및 서브그룹의 모든 프로젝트에 대해 허용됩니다.

Terraform 모듈 참조

전제 조건:

API로 인증해야 합니다. 개인 접근 토큰을 사용하여 인증하는 경우 read_api 범위로 구성되어야 합니다.

네임스페이스로부터

~/.terraformrc 또는 %APPDATA%/terraform.rc 파일에 terraform의 작업 토큰, 개인 접근 토큰 또는 배포 토큰을 제공할 수 있습니다:

credentials "gitlab.com" {
  token = "<토큰>"
}

여기서 gitlab.com은 Self-managed GitLab 인스턴스의 호스트 이름으로 대체할 수 있습니다.

그런 다음 downstream Terraform 프로젝트에서 Terraform 모듈을 참조할 수 있습니다:

module "<module>" {
  source = "gitlab.com/<네임스페이스>/<모듈-이름>/<모듈-시스템>"
}

여기서 <namespace>은 Terraform 모듈 레지스트리의 namespace입니다.

프로젝트로부터

프로젝트 수준 소스를 사용하여 Terraform 모듈을 참조하려면, Terraform에서 제공하는 fetching archives over HTTP 소스 유형을 사용합니다.

~/.netrc 파일에 terraform의 작업 토큰, 개인 접근 토큰 또는 배포 토큰을 제공할 수 있습니다:

machine gitlab.com
login <사용자이름>
password <토큰>

여기서 gitlab.com은 Self-managed GitLab 인스턴스의 호스트 이름으로 대체할 수 있으며, <USERNAME>은 토큰 사용자명입니다.

다음으로 downstream Terraform 프로젝트에서 Terraform 모듈을 참조할 수 있습니다:

module "<module>" {
  source = "https://gitlab.com/api/v4/projects/<프로젝트-id>/packages/terraform/modules/<모듈-이름>/<모듈-시스템>/<모듈-버전>"
}

모듈의 최신 버전을 참조해야 하는 경우, 소스 URL에서 <모듈-버전>을 생략할 수 있습니다. 가능하다면 특정 버전을 참조하는 것이 좋습니다.

동일한 네임스페이스 내에서 중복 모듈 이름이 있는 경우, 네임스페이스 레벨에서 모듈을 참조하면 최근에 발행된 모듈이 설치됩니다. 중복 모듈의 특정 버전을 참조하려면 프로젝트 수준 소스 유형을 사용하세요.

Terraform 모듈 다운로드

Terraform 모듈을 다운로드하려면:

왼쪽 사이드바에서 운영 > Terraform modules를 선택합니다.
다운로드하려는 모듈의 이름을 선택합니다.
Activity 섹션에서 모듈의 이름을 선택합니다.

모듈 해상도 작동 방식

새 모듈을 업로드하면 GitLab은 모듈을 위한 경로를 생성합니다. 예를 들어 https://gitlab.example.com/parent-group/my-infra-package와 같습니다.

이 경로는 Terraform 사양과 일치합니다.
경로의 이름은 해당 네임스페이스에서 고유해야 합니다.

하위 그룹의 프로젝트의 경우 GitLab은 부모 그룹을 포함하여 해당 네임스페이스 전체에서 모듈의 이름이 이미 존재하지 않는지 확인합니다.

예를 들어:

프로젝트가 gitlab.example.com/parent-group/sub-group/my-project라면,
Terraform 모듈이 my-infra-package이라면,

해당하는 모듈의 이름은 parent-group 하위 모든 그룹 안에 있는 모든 프로젝트에서 고유해야 합니다.

Terraform 모듈 삭제

Terraform 모듈을 Terraform 모듈 레지스트리에 게시한 후에는 해당 모듈을 편집할 수 없습니다. 대신 삭제한 후 다시 만들어야 합니다.

모듈을 삭제하려면 권한을 갖고 있어야 합니다.

모듈은 패키지 API 또는 UI를 사용하여 삭제할 수 있습니다.

UI에서 모듈을 삭제하려면 프로젝트에서 다음을 수행합니다:

왼쪽 사이드바에서 운영 > Terraform 모듈을 선택합니다.
삭제하려는 패키지의 이름을 찾습니다.
삭제를 선택합니다.

패키지가 영구적으로 삭제됩니다.