Terraform 모듈 레지스트리를 사용하면 다음을 수행할 수 있습니다:

• GitLab 프로젝트를 Terraform 모듈의 비공개 레지스트리로 사용합니다.
• GitLab CI/CD로 모듈을 만들고 게시한 다음 다른 비공개 프로젝트에서 사용할 수 있습니다.

Terraform 모듈 레지스트리 인증#

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

• 최소한 read_api 범위를 가진 개인 액세스 토큰.
• CI/CD 작업 토큰.
• read_package_registry 또는 write_package_registry 범위를 가진 배포 토큰.

API를 사용할 때:

• 배포 토큰으로 인증하는 경우 모듈을 게시하려면 write_package_registry 범위를 적용해야 합니다. 모듈을 다운로드하려면 read_package_registry 범위를 적용합니다.
• 개인 액세스 토큰으로 인증하는 경우 최소한 read_api 범위로 구성해야 합니다.

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

사전 요구 사항#

Terraform 모듈을 게시하려면:

• Developer, Maintainer, 또는 Owner 역할이 있어야 합니다.

모듈을 삭제하려면:

• Maintainer 또는 Owner 역할이 있어야 합니다.

Terraform 모듈 게시#

Terraform 모듈을 게시하면 모듈이 없는 경우 생성됩니다.

Terraform 모듈을 게시한 후 Terraform 모듈 레지스트리에서 볼 수 있습니다.

API 사용#

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

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

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

요청은 /file로 끝나야 합니다. 다른 것으로 끝나는 요청을 보내면 404 Not Found 오류가 발생합니다.

curl --fail-with-body --header "PRIVATE-TOKEN: <your_access_token>" \
     --upload-file path/to/file.tgz \
     --url "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/terraform/modules/<your_module>/<your_system>/0.0.1/file"

curl --fail-with-body --header "DEPLOY-TOKEN: <deploy_token>" \
     --upload-file path/to/file.tgz \
     --url "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/terraform/modules/<your_module>/<your_system>/0.0.1/file"

예시 응답:

{
  "message":"201 Created"
}

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

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

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

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

• fmt: Terraform 모듈의 서식을 검증합니다
• kics-iac-sast: Terraform 모듈의 보안 문제를 테스트합니다
• deploy: Terraform 모듈 레지스트리에 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}    # The relative path to the root directory of the Terraform project.
    TERRAFORM_MODULE_NAME: ${CI_PROJECT_NAME}  # The name of your Terraform module, must not have any spaces or underscores (will be translated to hyphens).
    TERRAFORM_MODULE_SYSTEM: local             # The system or provider your Terraform module targets (ex. local, aws, google).
    TERRAFORM_MODULE_VERSION: ${CI_COMMIT_TAG} # The version - it's recommended to follow SemVer for Terraform Module Versioning.
  script:
    - TERRAFORM_MODULE_NAME=$(echo "${TERRAFORM_MODULE_NAME}" | tr " _" -) # module-name must not have spaces or underscores, so translate them to hyphens
    - 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 구문 참조를 참조하세요.

모듈 해결 워크플로우#

새 모듈을 업로드하면 GitLab이 모듈의 경로를 생성합니다. 예를 들어:

• https://gitlab.example.com/parent-group/my-infra-package

이 경로는 Terraform 모듈 레지스트리 프로토콜을 따르며, 여기서:

• gitlab.example.com은 호스트 이름입니다.
• parent-group은 Terraform 모듈 레지스트리의 고유한 최상위 네임스페이스입니다.
• my-infra-package는 모듈의 이름입니다.

중복이 허용되지 않는 경우, 모듈 이름과 버전은 parent-group 아래의 모든 그룹, 하위 그룹 및 프로젝트에서 고유해야 합니다. 그렇지 않으면 다음 오류가 발생합니다:

• {"message":"A module with the same name already exists in the namespace."}

중복이 허용되는 경우, 모듈 해결은 가장 최근에 게시된 모듈을 기반으로 합니다.

예를 들어 다음과 같은 경우:

• 프로젝트는 gitlab.example.com/parent-group/subgroup/my-project입니다.
• Terraform 모듈은 my-infra-package입니다.

중복이 허용되면 my-infra-package는 유효한 모듈입니다. 중복이 허용되지 않으면 모듈 이름은 parent-group 아래의 모든 그룹의 모든 프로젝트에서 고유해야 합니다.

모듈의 이름을 지을 때 다음 명명 규칙을 염두에 두세요:

• 프로젝트 및 그룹 이름에는 점(.)이 포함되어서는 안 됩니다. 예를 들어 source = "gitlab.example.com/my.group/project.name"은 유효하지 않습니다.
• 모듈 버전은 시맨틱 버전 사양을 따라야 합니다.

중복 Terraform 모듈 허용#

기본적으로 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 모듈 보기#

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

1. 상단 표시줄에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
2. 운영 > Terraform 모듈을 선택합니다.

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

모듈의 README 파일을 보려면:

1. Terraform 모듈 레지스트리 페이지에서 Terraform 모듈을 선택합니다.
2. **README**를 선택합니다.

Terraform 모듈 참조#

그룹 또는 프로젝트에서 모듈을 참조합니다.

네임스페이스에서#

작업 토큰, 개인 액세스 토큰 또는 배포 토큰과 같은 인증 토큰을 terraform에 대한 환경 변수로 제공할 수 있습니다.

환경 변수의 도메인 이름에 TF_TOKEN_ 접두사를 추가해야 하며 마침표는 언더스코어로 인코딩됩니다. 자세한 내용은 환경 변수 자격 증명을 참조하세요.

예를 들어 TF_TOKEN_gitlab_com이라는 변수의 값은 CLI가 호스트 이름 gitlab.com에 서비스 요청을 할 때 배포 토큰으로 사용됩니다:

export TF_TOKEN_gitlab_com='glpat-<deploy_token>'

이 방법은 엔터프라이즈 구현에 선호됩니다. 로컬 또는 임시 환경의 경우 ~/.terraformrc 또는 %APPDATA%/terraform.rc 파일을 만들 수 있습니다:

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

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

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

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

프로젝트에서#

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

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

machine <gitlab.com>
login 
password 

여기서 gitlab.com을 GitLab Self-Managed 인스턴스의 호스트 이름으로, 을 토큰 사용자 이름으로 교체할 수 있습니다.

다운스트림 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. 자산 테이블에서 다운로드할 모듈을 선택합니다.

Terraform 모듈 삭제#

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

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

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

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

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

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

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

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

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

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

예시 프로젝트#

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

• GitLab 로컬 파일 프로젝트는 최소 Terraform 모듈을 만들고 GitLab CI/CD를 사용하여 Terraform 모듈 레지스트리에 업로드합니다.
• Terraform 모듈 테스트 프로젝트는 이전 예시의 모듈을 사용합니다.