GitLab 관리형 Terraform 상태

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

Terraform은 인프라 구성에 관한 세부 정보를 저장하는 데 상태 파일을 사용합니다. Terraform 원격 백엔드를 사용하여 상태 파일을 원격 및 공유 리포지터리에 저장할 수 있습니다.

GitLab은 Terraform HTTP 백엔드를 제공하여 최소한의 구성으로 상태 파일을 안전하게 저장할 수 있습니다.

GitLab에서는 다음을 할 수 있습니다.

  • Terraform 상태 파일을 버전 관리할 수 있습니다.
  • 전송 및 정지 상태 파일을 암호화할 수 있습니다.
  • 상태를 잠그거나 해제할 수 있습니다.
  • 원격으로 terraform plan 및 terraform apply 명령을 실행할 수 있습니다.
caution
재해 복구 계획 Terraform 상태 파일은 디스크와 객체 리포지터리에 안정적으로 쉬는 상태로 있을 때 잠금 상자 루비 젬으로 암호화됩니다. 상태 파일을 해독하려면 GitLab이 사용 가능해야 합니다. 오프라인 상태이고 GitLab을 사용하여 GitLab이 요구하는 인프라(가상 머신, Kubernetes 클러스터 또는 네트워크 컴포넌트와 같은)를 배포하면 상태 파일에 쉽게 액세스하거나 해독할 수 없습니다. 또한, GitLab이 GitLab을 부트스트래핑하는 데 필요한 Terraform 모듈이나 기타 의존성을 제공하면 이러한 것들은 액세스할 수 없을 것입니다. 이 문제를 해결하기 위해 이러한 의존성을 호스팅하거나 백업하기 위한 다른 방법을 마련하거나 단일 고장 지점이 없는 별도의 GitLab 인스턴스를 사용하는 것을 고려해보세요.

전제 조건

Self-managed GitLab의 경우, Terraform 상태 파일에 GitLab을 사용하기 전에 다음을 수행해야 합니다.

  • 관리자는 Terraform 상태 리포지터리를 설정해야 합니다.
  • 프로젝트의 Settings > General로 이동하여 Infrastructure 아래에서 토글을 켜고, 프로젝트의 Infrastructure 메뉴를 활성화해야 합니다.

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

terraform init 명령을 실행한 후, GitLab CI/CD를 사용하여 terraform 명령을 실행할 수 있습니다.

전제 조건:

  • terraform apply를 사용하여 상태를 잠그고 잠금을 해제하고 상태에 쓰려면 적어도 Maintainer 역할이 있어야 합니다.
  • terraform plan -lock=false를 사용하여 상태를 읽으려면 적어도 Developer 역할이 있어야 합니다.
caution
기타 작업 결과물과 마찬가지로 Terraform plan 데이터는 리포지터리의 Guest 역할을 가진 모든 사람이 볼 수 있습니다. Terraform이나 GitLab은 기본적으로 계획 파일을 암호화하지 않습니다. Terraform plan.json이나 plan.cache 파일에 암호, 액세스 토큰 또는 인증서와 같은 민감한 데이터가 포함된 경우, 계획 결과물을 암호화하거나 프로젝트 가시성 설정을 수정해야 합니다. 또한 public pipelines를 비활성화하고 artifact’s public flag를 false로 설정해야 합니다 (public: false). 이 설정을 통해 작업 결과물은 GitLab 관리자와 최소한 Reporter 역할을 가진 프로젝트 멤버만 액세스할 수 있게 됩니다.

GitLab CI/CD를 백엔드로 설정하려면:

  1. 프로젝트의 .tf 파일(예: backend.tf)에서 HTTP 백엔드를 정의하세요: 

    terraform {
  backend "http" {
  }
}
  2. 프로젝트 리포지터리의 루트 디렉터리에서 .gitlab-ci.yml 파일을 만들어서 사용하세요. Terraform.gitlab-ci.yml 템플릿을 참고하여 작성하세요.
  3. 프로젝트를 GitLab에 푸시합니다. 이 작업은 gitlab-terraform init, gitlab-terraform validate, gitlab-terraform plan 명령을 실행하는 파이프라인을 트리거합니다.
  4. 이전 파이프라인에서 매뉴얼으로 deploy 작업을 트리거하여 정의된 인프라를 프로비저닝하는 gitlab-terraform apply 명령을 실행합니다.

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

gitlab-terraform CLI는 terraform CLI의 래퍼입니다. 자세한 내용은 GitLab Terraform helpers 또는 gitlab-terraform의 소스 코드를 확인하세요.

명시적으로 terraform 명령을 호출하려면 템플릿을 재정의하고 언급한 내용을 달성할 수 있도록 참고하세요.

Terraform 환경 변수 사용자 정의

Terraform.gitlab-ci.yml 템플릿을 사용할 때 CI/CD 작업을 정의할 때 Terraform HTTP 구성 변수를 사용할 수 있습니다.

terraform init를 사용자 정의하고 Terraform 구성을 재정의하려면, terraform init -backend-config=... 방식 대신 환경 변수를 사용하십시오. -backend-config를 사용하면 구성이 다음과 같이 됩니다:

  • terraform plan 명령어의 출력에 캐시됩니다.
  • 일반적으로 terraform apply 명령어로 전달됩니다.

이 구성은 CI 작업에서 Terraform 상태 파일을 잠글 수 없는 문제와 같은 문제를 야기할 수 있습니다.

로컬 머신에서 상태 접근

GitLab에서 관리되는 Terraform 상태에 로컬 머신에서 접근할 수 있습니다.

caution
GitLab의 클러스터 배포에서는 로컬 스토리지를 사용하지 말아야 합니다. 노드간에 분할된 상태가 발생하여 후속 Terraform 실행이 일관성이 없어질 수 있습니다. 대신 원격 스토리지 리소스를 사용하십시오.
  1. CI/CD를 위해 Terraform 상태가 초기화되었는지 확인하십시오 여기를 참조하십시오.

  2. 미리 채워진 Terraform init 명령을 복사하십시오:

    1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾으십시오.
    2. 운영 > Terraform 상태를 선택하십시오.
    3. 사용하려는 환경 옆에서 작업들(⋯)을 선택하고 Terraform init 명령 복사를 선택하십시오.
  3. 터미널을 열고 로컬 머신에서 이 명령을 실행하십시오.

GitLab에서 관리되는 Terraform 상태로 마이그레이션

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이 백엔드에서 기존 상태를 확인할 것입니다.

상태 잠금을 획득하는 중. 잠시 기다려 주십시오...
기존 상태를 새 백엔드로 복사하시겠습니까?
  이전 "http" 백엔드에서 새로 구성된 "http" 백엔드로 마이그레이션하는 중에 기존 상태가 발견되었습니다. 새로 구성된 "http" 백엔드에서 기존 상태가 발견되지 않았습니다. 이 상태를 새 "http" 백엔드로 복사하시겠습니까? "yes"를 입력하여 복사하고 "no"를 입력하여 비어 있는 상태로 시작하십시오.
  
  값을 입력하십시오: yes


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

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

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

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

Terraform에 모듈 또는 백엔드 구성을 설정하거나 변경하면 작업 디렉터리를 다시 초기화하려면 이 명령을 다시 실행하십시오. 까먹으면 다른 명령이 이를 감지하고 필요할 경우 이를 상기시킬 것입니다.

yes를 입력하면 이전 위치에서 새 위치로 상태가 복사됩니다. 그런 다음 GitLab CI/CD에서 실행하도록 돌아갈 수 있습니다.

GitLab 백엔드를 원격 데이터 원본으로 사용하기

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

  1. main.tf 또는 기타 관련 파일에서 이러한 변수를 선언하세요. 값은 비워둡니다. 

    variable "example_remote_state_address" {
  type = string
  description = "Gitlab 원격 상태 파일 주소"
}
   
variable "example_username" {
  type = string
  description = "Gitlab 원격 상태를 쿼리할 사용자 이름"
}
   
variable "example_access_token" {
  type = string
  description = "GitLab 원격 상태를 쿼리할 액세스 토큰"
}

  2. 이전 단계의 값을 재정의하려면 example.auto.tfvars라는 파일을 만드세요. 이 파일은 프로젝트 리포지터리에 버전 관리되지 않아야 합니다. 

    example_remote_state_address = "https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME>"
example_username = "<GitLab 사용자 이름>"
example_access_token = "<GitLab 개인 액세스 토큰>"

  3. .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 상태 파일을 보려면:

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

이 UI 개선을 추적하는 에픽이 있습니다.

개별 Terraform 상태 버전 관리하기

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

적어도 Developer 역할이 있는 경우, 그들의 일련 번호를 사용하여 상태 버전을 검색할 수 있습니다:: 

curl --header "Private-Token: <your_access_token>" "https://<미리_설정된_주소>/api/v4/projects/<프로젝트_ID>/terraform/state/<상태_이름>/versions/<버전_일련_번호>"

Maintainer 역할 이상을 가진 경우, 그들의 일련 번호를 사용하여 상태 버전을 제거할 수 있습니다: 

curl --header "Private-Token: <your_access_token>" --request DELETE "https://<미리_설정된_주소>/api/v4/projects/<프로젝트_ID>/terraform/state/<상태_이름>/versions/<버전_일련_번호>"

상태 파일 제거하기

Maintainer 역할 이상을 가진 경우, 상태 파일을 제거할 수 있습니다.

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

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

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

curl --header "Private-Token: <your_access_token>" --request DELETE "https://<미리_설정된_주소>/api/v4/projects/<프로젝트_ID>/terraform/state/<상태_이름>"

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

curl --user "gitlab-ci-token:$CI_JOB_TOKEN" --request DELETE "https://<미리_설정된_주소>/api/v4/projects/<프로젝트_ID>/terraform/state/<상태_이름>"

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

관련 주제