- Terraform 모듈 보기
- Terraform 모듈 레지스트리에 인증
- Terraform 모듈 게시
- 테라폼 모듈 참조
- Terraform 모듈 다운로드하기
- 모듈 해상도 작동 방식
- Terraform 모듈 삭제하기
- Terraform 모듈 레지스트리 비활성화
- 예제 프로젝트
- 문제 해결
Terraform 모듈 레지스트리
Terraform 모듈 레지스트리를 사용하면 GitLab 프로젝트를 테라폼 모듈의 개인 레지스트리로 사용할 수 있습니다. GitLab CI/CD로 모듈을 만들고 게시하면 다른 개인 프로젝트에서 사용할 수 있습니다.
Terraform 모듈 보기
- Readme 파일 지원이 GitLab 17.2에서 도입되었습니다.
프로젝트나 그룹에서 Terraform 모듈을 보려면 다음을 수행하세요:
- 왼쪽 사이드바에서 검색 또는 가기를 선택하고 프로젝트나 그룹을 찾습니다.
- 운영 > Terraform 모듈을 선택합니다.
이 페이지에서 모듈을 검색, 정렬, 필터링할 수 있습니다.
또한 모듈을 선택한 후 Readme를 선택하여 모듈의 Readme 파일을 볼 수 있습니다.
Terraform 모듈 레지스트리에 인증
Terraform 모듈 레지스트리에 인증하려면 다음 중 하나가 필요합니다:
- 적어도
read_api권한이 있는 개인 엑세스 토큰. - CI/CD 작업 토큰.
-
read_package_registry또는write_package_registry범위가 있는 배포 토큰.
여기에 문서화되지 않은 인증 방법을 사용하지 마십시오. 문서화되지 않은 인증 방법은 향후 제거될 수 있습니다.
Terraform 모듈 게시
Terraform 모듈을 게시할 때, 해당 모듈이 존재하지 않는 경우에는 생성됩니다.
API 사용
Terraform 모듈 레지스트리 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 | yes | 프로젝트의 ID 또는 URL 인코딩된 경로. |
module-name
| string | yes | 모듈 이름. 지원되는 구문: 소문자(영어)와 숫자(0-9)를 포함한 1자부터 64자까지의 ASCII 문자. 모듈 이름은 64자를 초과할 수 없습니다. |
module-system
| string | yes | 모듈 시스템. 지원되는 구문: 소문자(영어)와 숫자(0-9)를 포함한 1자부터 64자까지의 ASCII 문자. 모듈 시스템은 64자를 초과할 수 없습니다. 자세한 정보는 Terraform Module Registry 프로토콜 문서에서 찾을 수 있습니다. |
module-version
| string | yes | 모듈 버전. 의미론적 버전 규격에 따라 유효해야 합니다. |
요청 본문에 파일 콘텐츠를 제공합니다.
다음 예시에서 보여지듯이, 요청은 반드시 /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에서 도입되었습니다.
GitLab 테라폼 레지스트리에 Terraform 모듈을 게시하는 데 Terraform-Module.gitlab-ci.yml
또는 고급 Terraform/Module-Base.gitlab-ci.yml
CI/CD 템플릿을 사용할 수 있습니다:
include:
template: Terraform-Module.gitlab-ci.yml
파이프라인에는 다음 작업이 포함되어 있습니다:
-
fmt- Terraform 모듈의 서식을 유효성 검사합니다. -
kics-iac-sast- Terraform 모듈을 보안 문제에 대해 테스트합니다. -
deploy- 태그 파이프라인 전용. Terraform 모듈을 Terraform 모듈 레지스트리에 배포합니다.
파이프라인 변수
다음 변수로 파이프라인을 구성할 수 있습니다.
| 변수 | 기본값 | 설명 |
|---|---|---|
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}
| 테라폼 모듈 버전입니다. 의미 있는 버전 명세를 따라야 합니다. |
CI/CD 수동 사용
GitLab CI/CD에서 테라폼 모듈을 사용하려면 개인 액세스 토큰 대신 CI_JOB_TOKEN을 명령어에 사용할 수 있습니다.
예를 들어, 다음 작업은 local 시스템 프로바이더에 대한 새 모듈을 업로드하고 Git 커밋 태그에서 모듈 버전을 사용합니다.
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 # 테라폼 모듈이 대상으로 하는 시스템이나 프로바이더입니다 (예: local, aws, google).
TERRAFORM_MODULE_VERSION: ${CI_COMMIT_TAG} # 버전 - 테라폼 모듈 버전 관리를 위해 의미 있는 버전 명세를 따르는 것이 좋습니다.
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 모듈 행에서 중복 허용 토글을 끕니다.
- 선택 사항. 예외 텍스트 상자에 중복을 허용할 패키지 이름과 일치하는 정규 표현식을 입력합니다.
변경 내용은 자동으로 저장됩니다.
또한 GraphQL API에서 terraform_module_duplicates_allowed을 활성화하여 중복된 이름을 게시할 수도 있습니다.
특정 이름에 대해 중복을 허용하려면:
-
terraform_module_duplicates_allowed가 비활성화되었는지 확인합니다. - 중복을 허용할 모듈 이름에 대한 정규 표현식 패턴을 정의하기 위해
terraform_module_duplicate_exception_regex을 사용합니다.
최상위 네임스페이스 설정이 하위 네임스페이스 설정보다 우선합니다.
예를 들어, 그룹에 대해 terraform_module_duplicates_allowed를 활성화하고 서브그룹에 대해 비활성화하면 그룹과 서브그룹의 모든 프로젝트에 대해 중복이 허용됩니다.
테라폼 모듈 참조
전제 조건:
-
API와 인증을 수행해야 합니다. 개인 액세스 토큰으로 인증하는 경우에는
read_api스코프로 구성되어야 합니다.
네임스페이스로부터
~/.terraformrc 또는 %APPDATA%/terraform.rc 파일에서 terraform의 인증 토큰(작업 토큰, 개인 액세스 토큰 또는 배포 토큰)을 제공할 수 있습니다.
credentials "gitlab.com" {
token = "<토큰>"
}
여기서 gitlab.com은 자체 관리형 GitLab 인스턴스의 호스트명으로 대체할 수 있습니다.
그런 다음 다음과 같이 하위 테라폼 프로젝트에서 테라폼 모듈을 참조할 수 있습니다:
module "<module>" {
source = "gitlab.com/<namespace>/<module-name>/<module-system>"
}
여기서 <namespace>는 테라폼 모듈 레지스트리의 네임스페이스입니다.
프로젝트로부터
프로젝트 수준 소스를 사용하여 테라폼 모듈을 참조하려면 Terraform이 제공하는 HTTP로 아카이브 가져오기 소스 유형을 사용하세요.
~/.netrc 파일에서 terraform의 인증 토큰(작업 토큰, 개인 액세스 토큰 또는 배포 토큰)을 제공할 수 있습니다.
machine gitlab.com
login <사용자명>
password <토큰>여기서 gitlab.com은 자체 관리형 GitLab 인스턴스의 호스트명으로 대체할 수 있으며, <사용자명>은 토큰 사용자명입니다.
다음과 같이 하위 테라폼 프로젝트에서 테라폼 모듈을 참조할 수 있습니다:
module "<module>" {
source = "https://gitlab.com/api/v4/projects/<프로젝트-ID>/packages/terraform/modules/<module-name>/<module-system>/<module-version>"
}
모듈의 최신 버전을 참조해야 하는 경우 소스 URL에서 <module-version>을 생략할 수 있습니다. 가능한 경우 특정 버전을 참조하는 것이 좋습니다.
같은 네임스페이스 내에서 중복 모듈 이름이 있는 경우 네임스페이스 수준에서 모듈을 참조하면 최근에 발행된 모듈이 설치됩니다. 중복 모듈의 특정 버전을 참조하려면 프로젝트 수준 소스 유형을 사용하세요.
Terraform 모듈 다운로드하기
Terraform 모듈을 다운로드하려면:
- 왼쪽 사이드바에서 운영 > Terraform 모듈을 선택합니다.
- 다운로드하려는 모듈의 이름을 선택합니다.
- 활동 섹션에서 다운로드하려는 모듈의 이름을 선택합니다.
모듈 해상도 작동 방식
새 모듈을 업로드하면 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 모듈을 선택합니다.
- 삭제하려는 패키지의 이름을 찾습니다.
- 삭제를 선택합니다.
패키지는 영구적으로 삭제됩니다.
Terraform 모듈 레지스트리 비활성화
Terraform 모듈 레지스트리는 자동으로 활성화됩니다.
자체 관리 인스턴스의 경우, GitLab 관리자는 패키지 및 레지스트리를 비활성화하여 이 사이드바 메뉴 항목을 제거할 수 있습니다.
특정 프로젝트에서 Terraform 모듈 레지스트리를 제거할 수도 있습니다.
- 프로젝트에서 설정 > 일반으로 이동합니다.
- 가시성, 프로젝트 기능, 권한 섹션을 확장하고 패키지를 끕니다(회색).
- 변경 사항 저장을 선택합니다.
되돌리려면 위와 동일한 단계를 따라가고 켜기(on, 파란색)로 변경합니다.
예제 프로젝트
Terraform 모듈 레지스트리의 예제를 확인하려면 아래 프로젝트를 확인하세요:
- GitLab local file 프로젝트는 GitLab CI/CD를 사용하여 최소한의 Terraform 모듈을 작성하고 Terraform 모듈 레지스트리에 업로드합니다.
- Terraform module test 프로젝트는 이전 예제의 모듈을 사용합니다.
문제 해결
중복된 이름으로 모듈을 게시하면 {"message":"A package with the same name already exists in the namespace"} 오류가 발생합니다.
도움말