테라폼 모듈 레지스트리

Tier: Free, Premium, Ultimate
Offering: GitLab.com, Self-Managed, GitLab Dedicated
  • 인프라 레지스트리 및 테라폼 모듈 레지스트리가 GitLab 15.11에서 단일 테라폼 모듈 레지스트리 기능으로 통합되었습니다.
  • 그룹 지원이 GitLab 16.9에 도입되었습니다.

테라폼 모듈 레지스트리를 사용하면 GitLab 프로젝트를 테라폼 모듈용 개인 레지스트리로 사용할 수 있습니다. GitLab CI/CD를 사용하여 모듈을 생성하고 게시할 수 있으며, 이후 다른 개인 프로젝트에서 사용할 수 있습니다.

테라폼 모듈 보기

프로젝트 또는 그룹에서 테라폼 모듈을 보려면 다음을 수행합니다:

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

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

테라폼 모듈 레지스트리 인증

테라폼 모듈 레지스트리에 인증하려면 다음 중 하나가 필요합니다:

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

테라폼 모듈 게시

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

API 사용

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

전제 조건: 

PUT /projects/:id/packages/terraform/modules/:module-name/:module-system/:module-version/file
속성 유형 필수 설명
id integer/string 예 프로젝트의 ID 또는 URL 인코딩된 경로.
module-name 문자열 예 모듈 이름. 지원되는 구문: 소문자 알파벳(a-z) 및 숫자(0-9)을 포함한 최대 64자의 ASCII 문자. 모듈 이름은 64자를 초과할 수 없습니다.
module-system 문자열 예 모듈 시스템. 지원되는 구문: 소문자 알파벳(a-z) 및 숫자(0-9)을 포함한 최대 64자의 ASCII 문자. 모듈 시스템은 64자를 초과할 수 없습니다. 추가 정보는 테라폼 모듈 레지스트리 프로토콜 문서에서 찾을 수 있습니다.
module-version 문자열 예 모듈 버전. Semantic versioning specification에 따라 유효해야 합니다.

요청 본문에 파일 콘텐츠를 제공합니다.

다음 예에서 보여지는대로 요청은 반드시 /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 Terraform 레지스트리에 Terraform 모듈을 게시하는 Terraform-Module.gitlab-ci.yml 또는 고급 Terraform/Module-Base.gitlab-ci.yml CI/CD 템플릿을 사용할 수 있습니다. 

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

파이프라인에는 다음 작업이 포함됩니다:

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

파이프라인 변수

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

변수 기본값 설명
TERRAFORM_MODULE_DIR ${CI_PROJECT_DIR} 테라폼 프로젝트의 루트 디렉터리의 상대 경로.
TERRAFORM_MODULE_NAME ${CI_PROJECT_NAME} 테라폼 모듈의 이름. 공백이나 밑줄이 없어야 합니다.
TERRAFORM_MODULE_SYSTEM local 테라폼 모듈이 대상이 되는 시스템 또는 프로바이더. 예: local, aws, google.
TERRAFORM_MODULE_VERSION ${CI_COMMIT_TAG} 테라폼 모듈 버전. Semantic versioning specification을 따르는 것이 좋습니다.

CI/CD 매뉴얼 사용

GitLab CI/CD에서 테라폼 모듈을 다루기 위해 명령어에 개인 액세스 토큰 대신 CI_JOB_TOKEN을 사용할 수 있습니다.

다음은 이 작업이 Git 커밋 태그에서 local 시스템 프로바이더에 대한 새 모듈을 업로드하는 예시입니다: 

stages:
  - deploy

upload:
  stage: deploy
  image: curlimages/curl:latest
  variables:
    TERRAFORM_MODULE_DIR: ${CI_PROJECT_DIR}    # 테라폼 프로젝트의 루트 디렉터리의 상대 경로.
    TERRAFORM_MODULE_NAME: ${CI_PROJECT_NAME}  # 테라폼 모듈의 이름. 공백이나 밑줄이 없어야 합니다(하이픈으로 변환될 것입니다).
    TERRAFORM_MODULE_SYSTEM: local             # 테라폼 모듈이 대상이 되는 시스템 또는 프로바이더(ex. local, aws, google).
    TERRAFORM_MODULE_VERSION: ${CI_COMMIT_TAG} # 버전 - 테라폼 모듈 버전 관리를 위해서는 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 태그를 추가하세요. 테그가 Semantic versioning specification을 따라야 합니다. rules:if: $CI_COMMIT_TAG는 리포지터리의 태그 커밋인 경우에만 모듈 업로드 작업이 트리거되도록 보장합니다. CI/CD 파이프라인에서 작업을 제어하는 다른 방법에 대해서는 CI/CD YAML 구문 참조를 참조하십시오.

중복된 Terraform 모듈 허용

  • GitLab 16.8에서 도입되었습니다.
  • GitLab 17.0에서 필수 역할이 Maintainer에서 Owner로 변경되었습니다.

기본적으로 Terraform Module Registry는 동일한 네임스페이스 내의 모듈 이름에 대해 고유성을 강제합니다.

중복된 모듈 이름을 발행하려면 다음을 수행하세요:

  1. 왼쪽 사이드바에서 검색 또는 이동하여 이동을 선택하고 그룹을 찾습니다.
  2. 설정 > 패키지 및 레지스트리를 선택합니다.
  3. 중복 패키지 테이블의 Terraform 모듈 행에서 중복 허용 토글을 끕니다.
  4. 선택 사항: 예외 텍스트 상자에 중복을 허용할 패키지 이름과 일치하는 정규 표현식을 입력합니다.

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

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

특정 이름에 대해 중복을 허용하려면:

  1. terraform_module_duplicates_allowed가 비활성화되어 있는지 확인하세요.
  2. terraform_module_duplicate_exception_regex를 사용하여 중복을 허용하려는 모듈 이름의 정규식 패턴을 정의하세요.

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

Terraform 모듈 참조

전제 조건:

  • API로 인증해야 합니다. 개인 액세스 토큰으로 인증하는 경우 read_api 스코프로 구성되어야 합니다.

네임스페이스에서

~/.terraformrc 또는 %APPDATA%/terraform.rc 파일에 terraform의 인증 토큰(Job 토큰, 개인 액세스 토큰 또는 배포 토큰)을 제공할 수 있습니다: 

credentials "gitlab.com" {
  token = "<TOKEN>"
}

여기서 gitlab.com은 Self-Managed형 GitLab 인스턴스의 호스트 이름으로 바꿀 수 있습니다.

그런 다음 다음과 같이 하류 Terraform 프로젝트에서 Terraform 모듈을 참조할 수 있습니다: 

module "<module>" {
  source = "gitlab.com/<namespace>/<module-name>/<module-system>"
}

여기서 <namespace>는 Terraform 모듈 레지스트리의 네임스페이스입니다.

프로젝트에서

프로젝트 수준의 소스를 사용하여 Terraform 모듈을 참조하려면 Terraform이 제공하는 HTTP를 통한 아카이브 가져오기 소스 유형을 사용합니다.

~/.netrc 파일에 terraform의 인증 토큰(Job 토큰, 개인 액세스 토큰 또는 배포 토큰)을 제공할 수 있습니다: 

machine gitlab.com
login <USERNAME>
password <TOKEN>

여기서 gitlab.com은 Self-Managed형 GitLab 인스턴스의 호스트 이름으로 바꿀 수 있으며, <USERNAME>은 귀하의 토큰 사용자 이름입니다.

그런 다음 다음과 같이 하류 Terraform 프로젝트에서 Terraform 모듈을 참조할 수 있습니다: 

module "<module>" {
  source = "https://gitlab.com/api/v4/projects/<project-id>/packages/terraform/modules/<module-name>/<module-system>/<module-version>"
}

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

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

Terraform 모듈 다운로드

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

  1. 왼쪽 사이드바에서 운영 > Terraform 모듈을 선택합니다.
  2. 다운로드하려는 모듈의 이름을 선택합니다.
  3. 활동 섹션에서 원하는 모듈의 이름을 선택합니다.

모듈 분해 작업 방식

새 모듈을 업로드하면 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 모듈을 게시한 후에는 해당 모듈을 편집할 수 없습니다. 대신, 삭제하고 다시 만들어야 합니다.

모듈을 삭제하려면 권한이 적절해야 합니다.

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

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

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

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

Terraform 모듈 레지스트리 비활성화

Terraform 모듈 레지스트리는 자동으로 활성화됩니다.

Self-Managed형 인스턴스의 경우 GitLab 관리자는 패키지 및 레지스트리를 비활성화할 수 있습니다. 이렇게 하면 사이드바의 이 메뉴 항목이 제거됩니다.

특정 프로젝트에서도 Terraform 모듈 레지스트리를 제거할 수 있습니다:

  1. 프로젝트에서 설정 > 일반으로 이동합니다.
  2. 가시성, 프로젝트 기능, 권한 섹션을 확장하고 패키지를 꺼냅니다(회색).
  3. 변경 사항 저장을 선택합니다.

이를 다시 사용하려면 동일한 단계를 따르고 켭니다(파란색).

예제 프로젝트

Terraform 모듈 레지스트리의 예제를 확인하려면 아래 프로젝트를 확인하세요:

문제 해결

  • 동일한 네임스페이스에 중복된 이름으로 모듈을 게시하면 {"message":"A package with the same name already exists in the namespace"} 오류가 발생합니다.