Terraform 상태 관리
Offering: GitLab Self-Managed
GitLab은 Terraform 상태 파일의 백엔드로 사용될 수 있습니다. 이 파일의 저장 위치 기본값은 다음과 같습니다: 이 위치는 아래 설명된 옵션을 사용하여 구성할 수 있습니다. GitLab Helm 차트 설치의 경우 외부 오브젝트 스토리지 구성을 사용하세요.
GitLab은 Terraform 상태 파일의 백엔드로 사용될 수 있습니다. 파일은 저장되기 전에 암호화됩니다. 이 기능은 기본적으로 활성화되어 있습니다.
이 파일의 저장 위치 기본값은 다음과 같습니다:
- Linux 패키지 설치의 경우
/var/opt/gitlab/gitlab-rails/shared/terraform_state - 직접 컴파일 설치의 경우
/home/git/gitlab/shared/terraform_state
이 위치는 아래 설명된 옵션을 사용하여 구성할 수 있습니다.
GitLab Helm 차트 설치의 경우 외부 오브젝트 스토리지 구성을 사용하세요.
Terraform 상태 비활성화#
인스턴스 전체에서 Terraform 상태를 비활성화할 수 있습니다. 디스크 공간을 줄이거나 인스턴스에서 Terraform을 사용하지 않는 경우 Terraform을 비활성화할 수 있습니다.
Terraform 상태 관리가 비활성화되면:
-
왼쪽 사이드바에서 운영 > Terraform 상태를 선택할 수 없습니다.
-
Terraform 상태에 액세스하는 CI/CD 작업이 다음 오류로 실패합니다:
Error refreshing state: HTTP remote state endpoint invalid auth
Terraform 관리를 비활성화하려면 설치 방법에 따라 아래 단계를 따르세요.
사전 요구 사항:
- 관리자여야 합니다.
Linux 패키지 설치의 경우:
-
/etc/gitlab/gitlab.rb를 편집하고 다음 줄을 추가합니다:gitlab_rails['terraform_state_enabled'] = false -
파일을 저장하고 변경 사항이 적용되도록 GitLab을 재구성합니다.
직접 컴파일 설치의 경우:
-
/home/git/gitlab/config/gitlab.yml을 편집하고 다음 줄을 추가하거나 수정합니다:terraform_state: enabled: false -
파일을 저장하고 변경 사항이 적용되도록 GitLab을 재시작합니다.
로컬 스토리지 사용#
기본 구성은 로컬 스토리지를 사용합니다. Terraform 상태 파일이 로컬에 저장되는 위치를 변경하려면 아래 단계를 따르세요.
Linux 패키지 설치의 경우:
-
저장 경로를 예를 들어
/mnt/storage/terraform_state로 변경하려면/etc/gitlab/gitlab.rb를 편집하고 다음 줄을 추가합니다:gitlab_rails['terraform_state_storage_path'] = "/mnt/storage/terraform_state" -
파일을 저장하고 변경 사항이 적용되도록 GitLab을 재구성합니다.
직접 컴파일 설치의 경우:
-
저장 경로를 예를 들어
/mnt/storage/terraform_state로 변경하려면/home/git/gitlab/config/gitlab.yml을 편집하고 다음 줄을 추가하거나 수정합니다:terraform_state: enabled: true storage_path: /mnt/storage/terraform_state -
파일을 저장하고 변경 사항이 적용되도록 GitLab을 재시작합니다.
오브젝트 스토리지 사용#
Terraform 상태 파일을 디스크에 저장하는 대신, 지원되는 오브젝트 스토리지 옵션 중 하나를 사용하는 것을 권장합니다. 이 구성은 이미 유효한 자격 증명이 구성되어 있어야 합니다.
GitLab에서 오브젝트 스토리지 사용에 대해 자세히 알아보세요.
오브젝트 스토리지 설정#
다음 설정은:
- Linux 패키지 설치에서
terraform_state_object_store_접두사가 붙습니다. - 직접 컴파일 설치에서
terraform_state:아래에object_store:로 중첩됩니다.
| 설정 | 설명 | 기본값 |
|---|---|---|
enabled |
오브젝트 스토리지 활성화/비활성화 | false |
remote_directory |
Terraform 상태 파일이 저장되는 버킷 이름 | |
connection |
아래 설명된 다양한 연결 옵션 |
오브젝트 스토리지로 마이그레이션#
오브젝트 스토리지에서 로컬 스토리지로 Terraform 상태 파일을 다시 마이그레이션하는 것은 불가능하므로 주의하여 진행하세요. 이 동작을 변경하기 위한 이슈가 존재합니다.
Terraform 상태 파일을 오브젝트 스토리지로 마이그레이션하려면:
-
Linux 패키지 설치의 경우:
gitlab-rake gitlab:terraform_states:migrate -
직접 컴파일 설치의 경우:
sudo -u git -H bundle exec rake gitlab:terraform_states:migrate RAILS_ENV=production
PostgreSQL 콘솔을 사용하여 선택적으로 진행 상황을 추적하고 모든 Terraform 상태 파일이 성공적으로 마이그레이션되었는지 확인할 수 있습니다:
- Linux 패키지 설치의 경우
sudo gitlab-rails dbconsole --database main - 직접 컴파일 설치의 경우
sudo -u git -H psql -d gitlabhq_production
아래의 objectstg(file_store=2인 경우)가 모든 상태 수를 갖는지 확인합니다:
gitlabhq_production=# SELECT count(*) AS total, sum(case when file_store = '1' then 1 else 0 end) AS filesystem, sum(case when file_store = '2' then 1 else 0 end) AS objectstg FROM terraform_state_versions;
total | filesystem | objectstg
------+------------+-----------
15 | 0 | 15
terraform_state 폴더의 디스크에 파일이 없는지 확인합니다:
sudo find /var/opt/gitlab/gitlab-rails/shared/terraform_state -type f | grep -v tmp | wc -l
S3 호환 연결 설정#
통합 오브젝트 스토리지 설정을 사용하는 것을 권장합니다. 이 섹션은 이전 구성 형식을 설명합니다.
다양한 프로바이더의 사용 가능한 연결 설정을 참조하세요.
-
/etc/gitlab/gitlab.rb를 편집하고 원하는 값으로 교체하여 다음 줄을 추가합니다:gitlab_rails['terraform_state_object_store_enabled'] = true gitlab_rails['terraform_state_object_store_remote_directory'] = "terraform" gitlab_rails['terraform_state_object_store_connection'] = { 'provider' => 'AWS', 'region' => 'eu-central-1', 'aws_access_key_id' => 'AWS_ACCESS_KEY_ID', 'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY' }[!note] AWS IAM 프로파일을 사용하는 경우 AWS 액세스 키와 시크릿 액세스 키/값 쌍을 생략해야 합니다.
gitlab_rails['terraform_state_object_store_connection'] = { 'provider' => 'AWS', 'region' => 'eu-central-1', 'use_iam_profile' => true } -
파일을 저장하고 변경 사항이 적용되도록 GitLab을 재구성합니다.
-
/home/git/gitlab/config/gitlab.yml을 편집하고 다음 줄을 추가하거나 수정합니다:terraform_state: enabled: true object_store: enabled: true remote_directory: "terraform" # 버킷 이름 connection: provider: AWS # 현재 AWS만 지원됩니다 aws_access_key_id: AWS_ACCESS_KEY_ID aws_secret_access_key: AWS_SECRET_ACCESS_KEY region: eu-central-1 -
파일을 저장하고 변경 사항이 적용되도록 GitLab을 재시작합니다.
Terraform 상태 파일 경로 찾기#
Terraform 상태 파일은 관련 프로젝트의 해시된 디렉터리 경로에 저장됩니다.
경로 형식은 /var/opt/gitlab/gitlab-rails/shared/terraform_state/<path>/<to>/<projectHashDirectory>//0.tfstate이며, UUID는 무작위로 정의됩니다.
상태 파일 경로를 찾으려면:
-
쉘에
get-terraform-path를 추가합니다:get-terraform-path() { PROJECT_HASH=$(echo -n $1 | openssl dgst -sha256 | sed 's/^.* //') echo "${PROJECT_HASH:0:2}/${PROJECT_HASH:2:2}/${PROJECT_HASH}" } -
get-terraform-path <project_id>를 실행합니다.$ get-terraform-path 650 20/99/2099a9b5f777e242d1f9e19d27e232cc71e2fa7964fc988a319fce5671ca7f73
상대 경로가 표시됩니다.
백업에서 Terraform 상태 파일 복원#
백업에서 Terraform 상태 파일을 복원하려면 암호화된 상태 파일과 GitLab 데이터베이스에 액세스할 수 있어야 합니다.
데이터베이스 테이블#
다음 데이터베이스 테이블은 S3 경로를 특정 프로젝트로 추적하는 데 도움이 됩니다:
terraform_states: 각 상태의 범용 고유 식별자(UUID)를 포함한 기본 상태 정보를 포함합니다.
파일 구조 및 경로 구성#
상태 파일은 특정 디렉터리 구조에 저장되며:
- 경로의 처음 세 세그먼트는 프로젝트 ID의 SHA-256 해시 값에서 파생됩니다.
- 각 상태는 경로의 일부를 형성하는
terraform_states데이터베이스 테이블에 저장된 UUID를 가집니다.
예를 들어, 다음과 같은 프로젝트의 경우:
- 프로젝트 ID가
12345 - 상태 UUID가
example-uuid
12345의 SHA-256 해시 값이 5994471abb01112afcc18159f6cc74b4f511b99806da59b3caf5a9c173cacfc5라면, 폴더 구조는 다음과 같습니다:
terraform/ <- 구성된 Terraform 저장 디렉터리
├─ 59/ <- 프로젝트 ID 해시의 첫 번째와 두 번째 문자
| ├─ 94/ <- 프로젝트 ID 해시의 세 번째와 네 번째 문자
| | ├─ 5994471abb01112afcc18159f6cc74b4f511b99806da59b3caf5a9c173cacfc5/ <- 전체 프로젝트 ID 해시
| | | ├─ example-uuid/ <- 상태 UUID
| | | | ├─ 1.tf <- 개별 상태 버전
| | | | ├─ 2.tf
| | | | ├─ 3.tf
복호화 프로세스#
상태 파일은 Lockbox를 사용하여 암호화되며 복호화를 위해 다음 정보가 필요합니다:
db_key_base애플리케이션 시크릿- 프로젝트 ID
암호화 키는 db_key_base와 프로젝트 ID 모두에서 파생됩니다. db_key_base에 액세스할 수 없으면 복호화가 불가능합니다.
파일을 수동으로 복호화하는 방법은 Lockbox 문서를 참조하세요.
암호화 키 생성 프로세스를 보려면 상태 업로더 코드를 참조하세요.