- 테라폼 모듈 보기
- 테라폼 모듈 레지스트리에 인증
- 테라폼 모듈 발행
- 테라폼 모듈 참조
- 테라폼 모듈 다운로드
- 모듈 해결 작업 방식
- 테라폼 모듈 삭제
- 테라폼 모듈 레지스트리 비활성화
- 예제 프로젝트
- 문제 해결
Terraform 모듈 레지스트리
테라폼 모듈 레지스트리를 사용하면 GitLab 프로젝트를 테라폼 모듈의 개인 레지스트리로 사용할 수 있습니다. GitLab CI/CD로 모듈을 생성하고 게시할 수 있으며, 이후에 다른 개인 프로젝트에서 사용할 수 있습니다.
테라폼 모듈 보기
프로젝트나 그룹에서 테라폼 모듈을 보려면:
- 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
- 조작 > 테라폼 모듈을 선택합니다.
이 페이지에서 모듈을 검색, 정렬 및 필터링할 수 있습니다.
테라폼 모듈 레지스트리에 인증
테라폼 모듈 레지스트리에 인증하려면 다음 중 하나가 필요합니다:
- 적어도
read_api권한이 있는 개인 액세스 토큰 - CI/CD 작업 토큰
-
read_package_registry또는write_package_registry범위가 있는 배포 토큰
여기에 문서화되어 있지 않은 인증 방법을 사용하지 마십시오. 문서화되지 않은 인증 방법은 향후 제거될 수 있습니다.
테라폼 모듈 발행
테라폼 모듈을 발행할 때 해당 모듈이 없으면 생성됩니다.
API 사용
Terraform 모듈 레지스트리 API를 사용하여 테라폼 모듈을 게시할 수 있습니다.
전제 조건:
- 중복이 허용되는 경우를 제외하고는 패키지 이름과 버전은 상위 수준 네임스페이스에서 고유해야 합니다.
- 프로젝트 및 그룹 이름에는 점(
.)이 포함되어서는 안 됩니다. 예: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 템플릿을 사용하여 GitLab terraform 레지스트리에 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 모듈 버전입니다. Semantic Versioning 사양을 따르는 것이 좋습니다. |
수동으로 CI/CD 사용
Terraform 모듈에서 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 모듈 버전 지정에는 Semantic Versioning을 따르는 것이 좋습니다.
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 사양을 따르는지 확인하십시오. rules:if: $CI_COMMIT_TAG는 레포지토리에서 태그가 붙은 커밋만 모듈 업로드 작업을 트리거하도록 보장합니다.
CI/CD 파이프라인에서 작업을 제어하는 다른 방법에 대해서는 CI/CD YAML 구문 참조를 참조하십시오.
중복 Terraform 모듈 허용
- GitLab 16.8에서 소개됨.
기본적으로, Terraform 모듈 레지스트리는 동일한 이름의 모듈에 대해 네임스페이스에 고유성을 요구합니다.
중복 모듈 이름을 발행하려면 다음을 수행하십시오:
- 왼쪽 사이드바에서 검색 또는 이동을 선택하여 그룹을 찾습니다.
- 설정 > 패키지 및 레지스트리를 선택합니다.
- Duplicate packages 테이블의 Terraform module 행에서 Allow duplicates 토글을 끕니다.
- 옵션. Exceptions 텍스트 상자에 중복된 패키지 이름과 일치하는 정규 표현식을 입력하십시오.
변경 사항이 자동으로 저장됩니다.
또한 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 인스턴스의 호스트 이름으로 대체할 수 있습니다.
그런 다음 다음과 같이 하류 Terraform 프로젝트에서 Terraform 모듈을 참조할 수 있습니다.
module "<module>" {
source = "gitlab.com/<namespace>/<module-name>/<module-system>"
}
여기서 <namespace>는 Terraform 모듈 레지스트리의 네임 스페이스입니다.
프로젝트에서
프로젝트 수준의 소스를 사용하여 Terraform 모듈을 참조하려면 Terraform이 제공하는 HTTP를 통한 아카이브 가져오기 소스 유형을 사용하십시오.
~/.netrc 파일에 terraform의 인증 토큰(작업 토큰, 개인 액세스 토큰 또는 배포 토큰)을 제공할 수 있습니다.
machine gitlab.com
login <사용자명>
password <토큰>여기서 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>"
}
모듈의 최신 버전을 참조해야 하는 경우, 소스 URL에서 <module-version>을 생략할 수 있습니다. 가능하면 특정 버전을 참조하여 미래 문제를 예방해야 합니다.
같은 네임 스페이스 내에서 중복 모듈 이름이 있는 경우, 네임 스페이스 수준에서 모듈을 참조하면 최근에 출시된 모듈이 설치됩니다. 중복 모듈의 특정 버전을 참조하려면 프로젝트 수준 소스 유형을 사용하십시오.
테라폼 모듈 다운로드
테라폼 모듈을 다운로드하려면 다음 작업을 수행합니다.
- 왼쪽 사이드바에서 운영 > 테라폼 모듈을 선택합니다.
- 다운로드하려는 모듈의 이름을 선택합니다.
- 활동 섹션에서 다운로드하려는 모듈의 이름을 선택합니다.
모듈 해결 작업 방식
새 모듈을 업로드하면 GitLab이 모듈에 대한 경로를 생성합니다. 예를 들어 https://gitlab.example.com/parent-group/my-infra-package입니다.
- 이 경로는 테라폼 사양과 일치합니다.
- 경로의 이름은 네임 스페이스 내에서 고유해야 합니다.
하위 그룹의 프로젝트의 경우 GitLab은 모듈 이름이 부모 그룹을 포함하여 네임 스페이스의 모든 하위 그룹 및 상위 그룹에 이미 존재하지 않는지 확인합니다.
예를 들어:
- 프로젝트가
gitlab.example.com/parent-group/sub-group/my-project이고, - 테라폼 모듈이
my-infra-package인 경우,
모든 하위 그룹과 상위 그룹을 포함하여 parent-group 아래의 모든 프로젝트에서 모듈 이름은 고유해야 합니다.
테라폼 모듈 삭제
테라폼 모듈을 Terraform 모듈 레지스트리에 게시한 후에는 편집할 수 없습니다. 대신 삭제하고 다시 만들어야 합니다.
모듈을 삭제하려면 권한이 필요합니다.
모듈을 삭제하려면 패키지 API 또는 UI를 사용할 수 있습니다.
UI에서 모듈을 삭제하려면 프로젝트에서 다음을 수행합니다.
- 왼쪽 사이드바에서 운영 > 테라폼 모듈을 선택합니다.
- 삭제하려는 패키지의 이름을 찾습니다.
- 삭제를 선택합니다.
패키지가 영구적으로 삭제됩니다.
테라폼 모듈 레지스트리 비활성화
Terraform 모듈 레지스트리는 자동으로 활성화됩니다.
자체 관리형 인스턴스의 경우 GitLab 관리자는 패키지 및 레지스트리를 비활성화하여 사이드바에서 이 메뉴 항목을 제거할 수 있습니다.
특정 프로젝트에서도 Terraform 모듈 레지스트리를 제거할 수 있습니다.
- 프로젝트에서 설정 > 일반으로 이동합니다.
- 가시성, 프로젝트 기능, 권한 섹션을 확장하고 패키지를 해제합니다(회색).
- 변경 사항 저장을 선택합니다.
다시 활성화하려면 동일한 단계를 따라가서 활성화합니다(파란색).
예제 프로젝트
테라폼 모듈 레지스트리의 예제는 아래의 프로젝트에서 확인할 수 있습니다.
- GitLab local file 프로젝트는 최소한의 테라폼 모듈을 생성하고 GitLab CI/CD를 사용하여 테라폼 모듈 레지스트리에 업로드합니다.
- Terraform module test 프로젝트는 앞의 예제에서 모듈을 사용합니다.
문제 해결
- 중복된 이름으로 모듈을 게시하면
{"message":"A package with the same name already exists in the namespace"}오류가 발생합니다.
도움말