HCP Terraform에 연결하기

HCP Terraform에 연결하기 (Connect to HCP Terraform)

이 주제는 Terraform CLI를 HCP Terraform에 연결하는 방법을 설명해요. CLI를 HCP Terraform과 통합하면 CLI가 CLI 기반 워크플로우(CLI-driven workflow)의 클라이언트로 동작할 수 있어요. 추가 정보는 CLI 기반 실행 워크플로우를 참고하세요.

출처: 문서

본문

실습: HCP Terraform으로 상태 마이그레이션하기 튜토리얼을 완료해서 CLI와 HCP Terraform 통합을 더 배워 보세요.

개요 (Overview)

Terraform CLI를 HCP Terraform에 연결하면 Terraform 구성을 담은 작업 디렉터리를 하나 이상의 HCP Terraform 워크스페이스에 연결해요. 이렇게 하면 워크스페이스에 접근 권한이 있는 팀 구성원이 HCP Terraform을 사용해 인프라를 프로비저닝하고 관리할 수 있어요. 또한 HCP Terraform이 상태 데이터를 관리하므로 원격 상태 객체를 직접 유지할 필요가 없어요. 추가 정보는 다음 주제를 참고하세요.

Terraform 구성 언어 레퍼런스의 상태 개요
HCP Terraform 문서의 HCP Terraform의 Terraform 상태

HCP Terraform에 연결하려면 다음 단계를 완료해요.

HCP Terraform에 자격 증명을 제공해요.
Terraform 구성에 연결 설정을 정의해요.
작업 디렉터리를 초기화해요.
상태 데이터를 마이그레이션해요. 이 단계는 선택 사항이에요.

요구사항 (Requirements)

워크스페이스를 만들 권한이 있는 HCP Terraform 사용자 프로필이 있어야 해요. 추가 정보는 HCP Terraform 문서의 워크스페이스 권한을 참고하세요.

자격 증명 제공하기 (Provide credentials)

HCP Terraform에 접근하기 위한 자격 증명을 제공해야 해요. Terraform에 로그인하려면 terraform login 명령을 사용할 것을 권장해요. Terraform 구성에 사용자 토큰을 제공할 수도 있어요. 추가 정보는 Terraform 구성 레퍼런스의 token 속성을 참고하세요.

연결 설정 정의하기 (Define connection settings)

Terraform 구성에 cloud 블록을 추가하고 연결 설정을 구성해 작업 디렉터리를 HCP Terraform 워크스페이스에 연결해요. cloud 블록은 terraform 블록의 멤버예요. 추가 정보는 terraform 블록 레퍼런스를 참고하세요.

cloud 블록에서 다음 설정을 지정해요.

organization: 연결할 HCP Terraform 조직의 이름을 지정해요.
workspaces.tags: 태그 문자열 맵 또는 키만 있는 문자열 태그 목록(레거시 스타일)을 지정해요. Terraform은 일치하는 태그가 있는 조직 내 기존 워크스페이스에 작업 디렉터리를 연결해요. 일치하는 태그가 있는 기존 워크스페이스가 없으면, 구성을 초기화할 때 Terraform CLI가 이 필드에 지정한 태그를 적용하는 새 워크스페이스를 만들도록 안내해요.
workspaces.name: 태그를 사용하는 대신 Terraform 구성과 연결할 기존 워크스페이스의 이름을 지정할 수 있어요. name을 구성하면 tags 구성을 사용할 수 없어요.
workspaces.project: 기존 프로젝트의 이름을 지정할 수 있어요. Terraform은 name 또는 tags와 일치하는 프로젝트 내 워크스페이스에 구성을 연결해요.

cloud 블록 구성에 대한 자세한 내용은 cloud 블록 레퍼런스를 참고하세요.

다음 예시에서 구성은 networking-development 프로젝트에서 networking과 source:cli로 태그된 모든 워크스페이스에 작업 디렉터리를 연결해요.

terraform {
  cloud {
    organization = "my-org"
    hostname = "app.terraform.io" # Optional; defaults to app.terraform.io

    workspaces {
      project = "networking-development"

      tags = {
        layer = "networking"
        source = "cli"
      }
    }
  }
}

작업 디렉터리 초기화하기 (Initialize the working directory)

cloud 블록을 추가하거나 변경한 후에는 terraform init 명령을 실행해 설정을 완료해요.

기본적으로 Terraform은 terraform plan 또는 terraform apply 명령을 실행할 때 작업 디렉터리에 저장된 Terraform 구성의 복사본을 업로드해요. 하지만 디렉터리에 .terraformignore 파일을 추가해 HCP Terraform에 업로드하고 싶지 않은 파일을 지정할 수 있어요. 자세한 내용은 파일 제외하기를 참고하세요.

작업 디렉터리에 기존 Terraform 상태 파일이 없다면, 즉시 HCP Terraform과 함께 Terraform을 사용하기 시작할 수 있어요. 자세한 내용은 CLI 기반 실행 워크플로우를 참고하세요.

디렉터리에 backend 구성과 연결된 기존 상태 파일이 있다면, Terraform은 기존 워크스페이스에서 상태를 마이그레이션하도록 안내해요. 다음 단계는 상태 데이터 마이그레이션을 참고하세요.

상태 데이터 마이그레이션 (Migrate state data)

다음 시나리오 중 하나에 따라 안내가 표시되면 데이터 마이그레이션 과정을 완료해요.

상태가 로컬 또는 상태 백엔드에 저장된 경우: 작업 디렉터리에 이미 하나 이상의 워크스페이스에 상태 데이터가 있다면, Terraform은 상태를 새 HCP Terraform 워크스페이스로 마이그레이션하도록 안내해요.
상태가 원격 백엔드에 저장된 경우: 작업 디렉터리가 이미 원격 백엔드로 HCP Terraform에 연결되어 있다면 Terraform은 같은 HCP Terraform 워크스페이스를 계속 사용할 수 있어요. 이 시나리오에서는 backend "remote" 구성을 cloud 블록으로 바꿔요.

로컬 상태 마이그레이션 (Migrate local state)

terraform init 명령을 실행하고 CLI 안내를 따라 로컬 또는 상태 백엔드에 저장된 상태 데이터를 마이그레이션해요.

HCP Terraform은 모든 워크스페이스가 이름을 가져야 하므로, 마이그레이션 중에 Terraform이 워크스페이스 이름을 바꾸도록 안내할 수도 있어요.

Terraform CLI 전용 워크스페이스는 같은 구성과 연관된 여러 환경(예: production, staging, development)을 나타내지만, HCP Terraform 워크스페이스는 완전히 독립적인 구성을 나타낼 수 있고 HCP Terraform 조직 안에서 고유한 이름을 가져야 해요.

그 결과 Terraform은 기존 이름을 기준으로 한 패턴에 따라 워크스페이스 이름을 바꾸도록 안내해요. 그 패턴은 워크스페이스가 구성을 공유한다는 것을 나타내기 위한 것이에요. 일반적인 전략은 <COMPONENT>-<ENVIRONMENT>-<REGION>으로, 예를 들어 networking-prod-us-east와 networking-staging-us-east가 있어요. 추가 정보는 HCP Terraform 문서의 워크스페이스 명명을 참고하세요.

원격 백엔드 마이그레이션 (Migrate remote backend)

terraform 블록 또는 terraform.tf 파일에서 backend "remote"를 cloud로 바꿔요. Terraform은 동일한 HCP Terraform 워크스페이스 집합을 계속 사용해요.

다음 예시는 my-app-prod라는 단일 워크스페이스의 상태 데이터를 my-org라는 HCP Terraform 조직으로 마이그레이션해요.

terraform {
-  backend "remote" {
+    cloud {
       organization = "my-org"

       workspaces {
          name = "my-app-prod"
       }
     }
   }
}

terraform 블록 또는 terraform.tf 파일이 prefix 인자를 사용해 여러 워크스페이스에 연결한다면, name 인자 대신 tags 인자에 키-값 문자열 태그 목록을 지정할 수 있어요. terraform plan 또는 terraform apply 작업 중 Terraform은 지정된 태그와 일치하는 워크스페이스에 구성을 연결해요.

다음 예시는 my-app- 접두사를 app=mine 태그로 바꿔요.

terraform {
-  backend "remote" {
+  cloud {
     organization = "my-org"

    workspaces {
-      prefix = "my-app-"
+      tags = {
+        app = "mine"
+      }
    }
   }
 }

cloud 블록은 prefix 인자를 지원하지 않으므로, 워크스페이스를 HCP Terraform으로 마이그레이션한 후에는 Terraform CLI를 사용할 때 전체 이름으로 참조해야 해요. 예를 들어 terraform workspace select prod 명령 대신 terraform workspace select my-app-prod를 실행해야 해요.

파일 제외하기 (Exclude files)

CLI 기반 실행에서 원격 plan 또는 apply를 실행할 때 구성 디렉터리의 복사본이 HCP Terraform에 업로드돼요. 구성 디렉터리 루트에 .terraformignore 파일을 추가해 업로드에서 제외할 경로를 정의할 수 있어요. 이 파일이 없어도 Terraform은 기본적으로 다음 디렉터리를 제외해요.

.git/ 디렉터리
.terraform/ 디렉터리(.terraform/modules 제외)

.terraformignore 정의 규칙은 .gitignore 파일에 기반해요.

Terraform은 #로 시작하는 주석을 무시해요.
Terraform은 빈 줄을 무시해요.
패턴을 슬래시 /로 끝내면 디렉터리를 지정해요.
느낌표 !로 패턴을 시작하면 부정(negate)해요. 큰 디렉터리를 무시할 때 부정 패턴은 성능에 영향을 줄 수 있어요. .terraformignore 안에서 가능한 한 앞부분에 부정 규칙을 배치하거나, 가능하면 사용을 피하세요.

Terraform은 구성 디렉터리의 루트에 있는 .terraformignore를 파싱해요.

HCP Terraform에 연결하기