선행 조건
GitLab CI/CD를 사용하여 백엔드로 Terraform 상태 초기화
- Terraform 환경 변수 사용자화
로컬 머신에서 상태에 액세스
GitLab으로 관리되는 Terraform 상태로 마이그레이션하기
- 초기 백엔드 설정
- 백엔드 변경
GitLab 백엔드를 원격 데이터 소스로 사용하기
Terraform 상태 파일 관리
관련 주제

GitLab 관리 Terraform 상태

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

기본적으로 비활성화된 상태로 GitLab 15.7에 도입된 마침표가 포함된 상태 이름을 지원하는 기능 플래그인 allow_dots_on_tf_state_names 지원.
마침표가 포함된 상태 이름을 일반 사용 가능하게 한 기능 플래그 allow_dots_on_tf_state_names가 삭제됨.

Terraform은 인프라스트럭처 구성에 관한 세부 정보를 저장하기 위해 상태 파일을 사용합니다. Terraform 원격 백엔드를 사용하여 상태 파일을 원격 및 공유 저장소에 저장할 수 있습니다.

GitLab은 Terraform HTTP 백엔드를 제공하여 상태 파일을 최소한의 구성으로 안전하게 저장할 수 있습니다. Terraform 상태 백엔드는 GitLab 인스턴스에서 관리되는 상태 파일의 자동 버전 관리와 암호화를 제공합니다.

경고: 재해 복구 계획 휴식 중인 상태 파일은 디스크와 오브젝트 저장소에서 lockbox Ruby gem으로 암호화되고, db_key_base 애플리케이션 설정에서 파생된 키로 보호됩니다. 상태 파일을 복호화하려면 GitLab이 사용 가능해야 합니다. GitLab이 오프라인 상태이고 GitLab이 필요로 하는 인프라스트럭처(가상 머신, Kubernetes 클러스터 또는 네트워크 구성 요소)를 배포하려고 하는 경우, 상태 파일에 쉽게 액세스하거나 복호화할 수 없습니다. 또한, GitLab이 부트스트랩을 위해 Terraform 모듈이나 기타 종속성을 제공하는 경우, 이러한 것들은 접근할 수 없습니다. 이 문제를 해결하기 위해, 이러한 종속성을 호스팅하거나 백업할 다른 조치를 취하거나 단일 고장 지점이 없는 별도의 GitLab 인스턴스를 사용하는 것을 고려해야 합니다.

선행 조건

GitLab Self-managed의 경우, Terraform 상태 파일에 GitLab을 사용하기 전에:

관리자가 Terraform 상태 저장소를 설정해야 합니다.
프로젝트의 가시성, 프로젝트 기능, 권한 아래에서 Settings > General로 이동하여, Infrastructure 아래에서 토글을 켜 GitLab 메뉴 Infrastructure를 활성화해야 합니다.

GitLab CI/CD를 사용하여 백엔드로 Terraform 상태 초기화

선행 조건:

terraform apply를 사용하여 상태를 잠그고, 잠금을 해제하고, 상태를 쓰려면 적어도 Maintainer 역할이 있어야합니다.
terraform plan -lock=false를 사용하여 상태를 읽으려면 적어도 Developer 역할이 있어야합니다.

경고: 다른 작업 아티팩트와 마찬가지로, Terraform 계획 데이터는 리포지토리에 대한 Guest 역할이 있는 모든 사람이 볼 수 있습니다. Terraform이나 GitLab은 기본적으로 계획 파일을 암호화하지 않습니다. Terraform plan.json 또는 plan.cache 파일에 암호, 엑세스 토큰 또는 인증서와 같은 중요한 데이터가 포함된 경우 계획 출력을 암호화하거나 프로젝트 가시성 설정을 수정해야 합니다. 또한, public 파이프 라인을 비활성화하고 artifact’s public flag를 false로 설정해야합니다 (public: false). 이 설정은 아티팩트에 대한 접근 권한이 GitLab 관리자 및 적어도 Reporter 역할이 있는 프로젝트 멤버에게만 제공되도록합니다.

GitLab CI/CD를 백엔드로 구성하는 방법:

Terraform 프로젝트에서 .tf 파일(예: backend.tf)에서 HTTP 백엔드를 정의합니다.
```
terraform {
  backend "http" {
  }
}
```
프로젝트 리포지토리의 루트 디렉터리에서 .gitlab-ci.yml 파일을 생성합니다. .gitlab-ci.yml에서 OpenTofu CI/CD 구성요소를 사용합니다. Terraform 대신 OpenTofu 사용을 선호하는 경우 Terraform 템플릿 레시피 문서를 참조하세요.
프로젝트를 GitLab에 푸시합니다. 이 작업은 파이프라인을 트리거하며, gitlab-tofu init, gitlab-tofu validate 및 gitlab-tofu plan 명령을 실행합니다.
이전 파이프라인에서 수동으로 deploy 작업을 트리거합니다. 이는 정의된 인프라를 프로비저닝하기 위해 gitlab-tofu apply 명령을 실행합니다.

위 명령의 출력은 작업 로그에서 볼 수 있어야합니다.

gitlab-tofu/gitlab-terraform CLI는 각각 tofu/terraform CLI를 래핑합니다. 자세한 정보는 GitLab Terraform 도우미를 참조하거나 gitlab-terraform의 소스 코드를 참조하세요.

Terraform 환경 변수 사용자화

설정된 Terraform HTTP 환경 변수를 사용하여 CI/CD 작업을 정의할 수 있습니다.

init를 사용하여 Terraform 구성을 사용자화하고 Terraform 구성을 덮어씌우려면, -backend-config=... 대신 환경 변수를 사용하세요. -backend-config를 사용하면 구성이:

계획 명령의 결과에 캐시됩니다.
일반적으로 apply 명령으로 전달됩니다.

이 구성은 이전 작업의 계획과 함께 Terraform apply에 대한 상태 파일을 잠그지 못하는 문제로 이어질 수 있습니다.

로컬 머신에서 상태에 액세스

로컬 머신에서 GitLab 관리 Terraform 상태에 액세스할 수 있습니다.

경고: GitLab의 클러스터링 배포에서는 로컬 저장소를 사용하지 않아야합니다. 분할된 상태가 발생할 수 있으며 이는 후속 Terraform 실행을 일관성 없게 만들 수 있습니다. 대신 원격 저장소 리소스를 사용하세요.

Terraform 상태가 CI/CD를 위해 초기화되었는지 확인합니다.
미리 채워진 Terraform init 명령을 복사하세요.
1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
2. 주요 작업 > Terraform 상태를 선택합니다.
3. 사용하려는 환경 옆에서 작업()을 선택하고 Terraform 초기화 명령 복사를 선택합니다.
터미널을 열고 로컬 머신에서이 명령을 실행하세요.

GitLab으로 관리되는 Terraform 상태로 마이그레이션하기

Terraform은 백엔드가 변경되거나 재구성될 때 상태를 복사하는 기능을 지원합니다. 다른 백엔드에서 GitLab으로 관리되는 Terraform 상태로 마이그레이션하기 위해 이러한 작업을 사용합니다.

GitLab으로 관리되는 Terraform 상태로 마이그레이션하기 위해 필요한 명령을 로컬 터미널에서 실행해야 합니다.

다음 예제는 상태 이름을 변경하는 방법을 보여줍니다. 동일한 워크플로우가 다른 상태 저장 백엔드에서 GitLab으로 관리되는 Terraform 상태로 마이그레이션하기 위해 필요합니다.

이 명령은 로컬 머신에서 실행해야 합니다.

초기 백엔드 설정

PROJECT_ID="<gitlab-project-id>"
TF_USERNAME="<gitlab-username>"
TF_PASSWORD="<gitlab-personal-access-token>"
TF_ADDRESS="https://gitlab.com/api/v4/projects/${PROJECT_ID}/terraform/state/old-state-name"

terraform init \
  -backend-config=address=${TF_ADDRESS} \
  -backend-config=lock_address=${TF_ADDRESS}/lock \
  -backend-config=unlock_address=${TF_ADDRESS}/lock \
  -backend-config=username=${TF_USERNAME} \
  -backend-config=password=${TF_PASSWORD} \
  -backend-config=lock_method=POST \
  -backend-config=unlock_method=DELETE \
  -backend-config=retry_wait_min=5

백엔드를 초기화하는 중...

백엔드 "http"가 성공적으로 구성되었습니다! 백엔드 구성이 변경되지 않는 한 Terraform은 자동으로
이 백엔드를 사용합니다.

공급자 플러그인을 초기화하는 중...

Terraform이 성공적으로 초기화되었습니다!

이제 Terraform을 사용하여 작업을 시작할 수 있습니다. "terraform plan"을 실행하여
인프라에 필요한 변경 사항을 확인해 보세요. 이제 모든 Terraform 명령이 작동해야 합니다.

만약 Terraform을 위해 모듈 또는 백엔드 구성을 설정하거나 변경한 경우,
작업 디렉터리를 다시 초기화하려면 이 명령을 다시 실행하세요. 잊을 경우, 다른
명령에서 이를 감지하고 필요한 경우 이를 상기시켜줄 것입니다.

백엔드 변경

이제 terraform init가 이전 상태가 있는 위치를 알고 있는 .terraform/ 디렉터리를 만들었으므로 새 위치에 대해 알려줄 수 있습니다.

TF_ADDRESS="https://gitlab.com/api/v4/projects/${PROJECT_ID}/terraform/state/new-state-name"

terraform init \
  -migrate-state \
  -backend-config=address=${TF_ADDRESS} \
  -backend-config=lock_address=${TF_ADDRESS}/lock \
  -backend-config=unlock_address=${TF_ADDRESS}/lock \
  -backend-config=username=${TF_USERNAME} \
  -backend-config=password=${TF_PASSWORD} \
  -backend-config=lock_method=POST \
  -backend-config=unlock_method=DELETE \
  -backend-config=retry_wait_min=5

백엔드를 초기화하는 중...
백엔드 구성이 변경되었습니다!

Terraform이 백엔드의 변경된 구성을 감지했습니다. Terraform은 이제 백엔드에 이미 있는 상태를 확인할 것입니다.

상태 잠금을 획득하는 중. 이 과정은 몇 분 정도 소요될 수 있습니다...
기존 상태를 새 백엔드로 복사하시겠습니까?
  이전 "http" 백엔드에서 새로 구성된 "http" 백엔드로 마이그레이션하는 동안 기존 상태가 발견되었습니다.
  새로 구성된 "http" 백엔드에 기존 상태가 발견되지 않았습니다. 이 상태를 새로 구성된 "http"
  백엔드로 복사하시겠습니까? "yes"를 입력하면 복사하고, "no"를 입력하면 빈 상태로 시작합니다.

  값을 입력하세요: yes


백엔드 "http"가 성공적으로 구성되었습니다! 백엔드 구성이 변경되지 않는 한 Terraform은 자동으로
이 백엔드를 사용합니다.

공급자 플러그인을 초기화하는 중...

Terraform이 성공적으로 초기화되었습니다!

이제 Terraform을 사용하여 작업을 시작할 수 있습니다. "terraform plan"을 실행하여
인프라에 필요한 변경 사항을 확인해 보세요. 이제 모든 Terraform 명령이 작동해야 합니다.

만약 Terraform을 위해 모듈 또는 백엔드 구성을 설정하거나 변경한 경우,
작업 디렉터리를 다시 초기화하려면 이 명령을 다시 실행하세요. 잊을 경우, 다른
명령에서 이를 감지하고 필요한 경우 이를 상기시켜줄 것입니다.

yes를 입력하면 이전 위치에서 새 위치로 상태를 복사합니다. 그런 다음 GitLab CI/CD에서 다시 실행할 수 있습니다.

GitLab 백엔드를 원격 데이터 소스로 사용하기

Terraform 데이터 소스로 GitLab으로 관리되는 Terraform 상태 백엔드를 사용할 수 있습니다.

main.tf 또는 해당 파일에서 변수를 선언하세요. 값은 비워두세요.

variable "example_remote_state_address" {
  type = string
  description = "Gitlab remote state file address"
}

variable "example_username" {
  type = string
  description = "Gitlab username to query remote state"
}

variable "example_access_token" {
  type = string
  description = "GitLab access token to query remote state"
}

이전 단계에서의 값을 덮어쓰려면 example.auto.tfvars라는 파일을 만드세요. 이 파일은 프로젝트 저장소에 버전 관리되어서는 안 됩니다.

example_remote_state_address = "https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME>"
example_username = "<GitLab username>"
example_access_token = "<GitLab personal access token>"

.tf 파일에서 Terraform 입력 변수를 사용하여 데이터 소스를 정의하세요.
```
data "terraform_remote_state" "example" {
  backend = "http"

  config = {
    address = var.example_remote_state_address
    username = var.example_username
    password = var.example_access_token
  }
}
```
- address: 데이터 소스로 사용할 원격 상태 백엔드의 URL입니다. 예: https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME>.
- username: 데이터 소스와 인증하기 위한 사용자 이름입니다. 개인 액세스 토큰을 사용하면 이 값을 GitLab 사용자 이름으로 설정하세요. GitLab CI/CD를 사용하면 이 값은 'gitlab-ci-token'입니다.
- password: 데이터 소스와 인증하기 위한 암호입니다. 개인 액세스 토큰을 사용하면 토큰 값을 (토큰은 API 스코프여야 함) 설정하세요. GitLab CI/CD를 사용하면 ${CI_JOB_TOKEN} CI/CD 변수의 내용입니다.

데이터 소스에서 가져온 출력은 이제 data.terraform_remote_state.example.outputs.<OUTPUT-NAME>을 사용하여 Terraform 리소스에서 참조할 수 있습니다.

대상 프로젝트에서 Terraform 상태를 읽으려면 최소한 Developer 역할이 필요합니다.

Terraform 상태 파일 관리

Terraform 상태 파일을 보려면:

왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
운영 > Terraform 상태를 선택합니다.

이 UI 개선을 추적하는 Epic이 존재합니다.

개별 Terraform 상태 버전 관리

개별 상태 버전은 GitLab REST API를 사용하여 관리할 수 있습니다.

적어도 개발자 역할을 가지고 있다면, 상태 버전을 시리얼 번호를 사용하여 검색할 수 있습니다::

curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<your_project_id>/terraform/state/<your_state_name>/versions/<version-serial>"

최소한 Maintainer 역할을 가지고 있다면, 상태 버전을 시리얼 번호를 사용하여 삭제할 수 있습니다:

curl --header "Private-Token: <your_access_token>" --request DELETE "https://gitlab.example.com/api/v4/projects/<your_project_id>/terraform/state/<your_state_name>/versions/<version-serial>"

상태 파일 제거

최소한 Maintainer 역할을 가지고 있다면, 상태 파일을 제거할 수 있습니다.

왼쪽 사이드바에서 운영 > Terraform 상태를 선택합니다.
작업 열에서 작업 ()을 선택한 다음 상태 파일 및 버전 제거를 선택합니다.

API를 사용하여 상태 파일 제거

개인 엑세스 토큰을 사용하여 REST API에 요청을 보내어 상태 파일을 제거할 수 있습니다:

curl --header "Private-Token: <your_access_token>" --request DELETE "https://gitlab.example.com/api/v4/projects/<your_project_id>/terraform/state/<your_state_name>"

CI/CD 작업 토큰 및 기본 인증을 사용할 수도 있습니다:

curl --user "gitlab-ci-token:$CI_JOB_TOKEN" --request DELETE "https://gitlab.example.com/api/v4/projects/<your_project_id>/terraform/state/<your_state_name>"

GraphQL API도 사용할 수 있습니다.

GitLab 관리 Terraform 상태

선행 조건

GitLab CI/CD를 사용하여 백엔드로 Terraform 상태 초기화

Terraform 환경 변수 사용자화

로컬 머신에서 상태에 액세스

GitLab으로 관리되는 Terraform 상태로 마이그레이션하기

초기 백엔드 설정

백엔드 변경

GitLab 백엔드를 원격 데이터 소스로 사용하기

Terraform 상태 파일 관리

개별 Terraform 상태 버전 관리

상태 파일 제거

API를 사용하여 상태 파일 제거

관련 주제

도움말

기능 사용 가능성과 제품 평가판

도움받기