Terraform 모듈 레지스트리

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated
  • 인프라 레지스트리와 Terraform 모듈 레지스트리가 GitLab 15.11에서 하나의 Terraform 모듈 레지스트리 기능으로 병합됨.
  • GitLab 16.9에서 그룹에 대한 지원이 도입됨.

Terraform 모듈 레지스트리를 사용하면 GitLab 프로젝트를 Terraform 모듈의 비공식 레지스트리로 사용할 수 있습니다. GitLab CI/CD를 사용하여 모듈을 생성하고 게시할 수 있으며, 그런 다음 다른 비공식 프로젝트에서 사용할 수 있습니다.

Terraform 모듈 보기

  • Readme 파일에 대한 지원이 GitLab 17.2에서 도입됨.

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

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

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

모듈을 선택한 다음 Readme를 선택하여 모듈의 Readme 파일도 볼 수 있습니다.

Terraform 모듈 레지스트리에 인증

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

여기 문서화된 방법 외의 인증 방법을 사용하지 마세요. 문서화되지 않은 인증 방법은 향후 제거될 수 있습니다.

Terraform 모듈 게시

Terraform 모듈을 게시할 때, 만약 그것이 존재하지 않으면 생성됩니다.

API 사용

Terraform 모듈 레지스트리 API를 사용하여 Terraform 모듈을 게시할 수 있습니다.

사전 요구 사항:

PUT /projects/:id/packages/terraform/modules/:module-name/:module-system/:module-version/file
속성 유형 필수 설명
id 정수/문자열 예 프로젝트의 ID 또는 URL 인코딩된 경로.
module-name 문자열 예 모듈 이름. 지원되는 문법: 소문자(a-z) 및 숫자(0-9)를 포함하여 1~64개의 ASCII 문자. 모듈 이름은 64자를 초과할 수 없습니다.
module-system 문자열 예 모듈 시스템. 지원되는 문법: 소문자(a-z) 및 숫자(0-9)를 포함하여 1~64개의 ASCII 문자. 모듈 시스템은 64자를 초과할 수 없습니다. 더 많은 정보는 Terraform 모듈 레지스트리 프로토콜 문서에서 찾을 수 있습니다.
module-version 문자열 예 모듈 버전. 의미적 버전 명세에 따라 유효해야 합니다.

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

다음 예와 같이 요청은 /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 템플릿 사용하기 (권장)

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 모듈 레지스트리에 배포합니다.

파이프라인 변수

다음 변수를 사용하여 파이프라인을 구성할 수 있습니다:

Variable Default Description
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 시스템 제공자를 위해 새로운 모듈을 업로드하고 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 태그를 추가하세요. 태그가 Terraform이 요구하는 의미 체계 버전 관리 사양을 따르는지 확인하세요. rules:if: $CI_COMMIT_TAG는 레포지토리에 태그가 있는 커밋만 모듈 업로드 작업을 트리거하도록 보장합니다.

CI/CD 파이프라인에서 작업을 제어하는 다른 방법에 대해서는 CI/CD YAML 구문 참조를 참조하세요.

Terraform 모듈 중복 허용

  • GitLab 16.8에서 도입됨.
  • GitLab 17.0에서 필요한 역할이 변경됨 - Maintainer에서 Owner로.

기본적으로 Terraform 모듈 레지스트리는 동일한 네임스페이스 내에서 모듈 이름의 고유성을 강제합니다.

중복 모듈 이름을 게시할 수 있도록 하려면:

  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에 대한 인증 토큰(작업 토큰, 개인 액세스 토큰 또는 배포 토큰)을 제공할 수 있습니다:

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

여기서 gitlab.com은 자가 호스팅하는 GitLab 인스턴스의 호스트 이름으로 대체할 수 있습니다.

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

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

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

프로젝트에서

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

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

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

여기서 gitlab.com은 자가 호스팅하는 GitLab 인스턴스의 호스트 이름으로 대체할 수 있고, <USERNAME>은 귀하의 토큰 사용자 이름입니다.

하위 Terraform 프로젝트에서 Terraform 모듈을 참조할 수 있습니다:

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

모듈의 최신 버전을 참조해야 하는 경우 <module-version>을 소스 URL에서 생략할 수 있습니다. 향후 문제를 방지하려면 가능하면 특정 버전을 참조하는 것이 좋습니다.

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

Terraform 모듈 다운로드

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

  1. 왼쪽 사이드바에서 Operate > Terraform modules를 선택합니다.
  2. 다운로드할 모듈의 이름을 선택합니다.
  3. 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 Module Registry에 게시한 후에는 수정할 수 없습니다. 대신, 모듈을 삭제하고 다시 생성해야 합니다.

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

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

UI에서 모듈을 삭제하려면, 프로젝트에서:

  1. 왼쪽 사이드바에서 Operate > Terraform modules를 선택합니다.
  2. 삭제할 패키지의 이름을 찾습니다.
  3. Delete를 선택합니다.

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

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

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

셀프 관리 인스턴스의 경우, GitLab 관리자가 Packages and registries를 비활성화하면, 사이드바에서 이 메뉴 항목이 제거됩니다.

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

  1. 프로젝트에서 Settings > General로 이동합니다.
  2. Visibility, project features, permissions 섹션을 확장하고 Packages를 꺼짐(회색)으로 전환합니다.
  3. Save changes를 선택합니다.

다시 활성화하려면 위의 단계를 따라 껐다가 켭니다(파란색).

예제 프로젝트

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

문제 해결

  • 중복 이름을 가진 모듈을 게시하면 {"message":"A package with the same name already exists in the namespace"} 오류가 발생합니다.