remote 백엔드

remote 백엔드

HCP Terraform(구 Terraform Cloud)의 CLI 주도 실행 워크플로에서 state 저장과 연산 실행을 모두 수행하는 remote 백엔드를 설명해 드릴게요.

출처: 문서

본문

참고: remote 백엔드는 Terraform v0.11.13과 Terraform Enterprise v201809-1에서 도입했어요. Terraform v1.1.0과 Terraform Enterprise v202201-1부터는 HCP Terraform의 내장 cloud 연동을 대신 사용하는 것을 권장해요. cloud 옵션은 계획과 적용 결과를 사람이 읽을 수 있는 형식으로 표시하는 구조화된 run 출력 모드 같은 개선된 사용자 경험과 더 많은 기능을 지원해요.

remote 백엔드는 모든 다른 Terraform 백엔드 중 유일하게 state 스냅샷 저장과 HCP Terraform의 CLI 주도 run 워크플로를 위한 연산 실행을 모두 수행할 수 있어요. 예전에는 "enhanced" 백엔드라고 불렸어요.

전체 원격 연산을 사용할 때 terraform plan이나 terraform apply 같은 연산은 Terraform Cloud의 run 환경에서 실행될 수 있고, 로그 출력은 로컬 터미널로 스트리밍돼요. 원격 plan과 apply는 연결된 HCP Terraform 워크스페이스의 변수 값을 사용해요. 로컬 연산으로도 HCP Terraform을 사용할 수 있는데, 이 경우 state만 HCP Terraform 백엔드에 저장돼요.

명령 지원 (Command Support)

remote 백엔드는 다음 Terraform 명령을 지원해요: apply, console(v0.11.12 이상), destroy, fmt, get, graph(v0.11.12 이상), import(v0.11.12 이상), init, output, plan, providers, show, state(모든 하위 명령: list, mv, pull, push, rm, show), taint, untaint, validate, version, workspace.

워크스페이스 (Workspaces)

remote 백엔드는 단일 원격 HCP Terraform 워크스페이스 또는 networking-dev와 networking-prod 같은 비슷한 이름의 여러 원격 워크스페이스와 함께 작동할 수 있어요. 백엔드 구성의 workspaces 블록이 어떤 모드를 사용할지 결정해요:

  • 단일 원격 HCP Terraform 워크스페이스를 사용하려면 workspaces.name을 원격 워크스페이스의 전체 이름(networking-prod 같은)으로 설정해요.
  • 여러 원격 워크스페이스를 사용하려면 workspaces.prefix를 원하는 모든 원격 워크스페이스 이름에 사용되는 접두사로 설정해요. 예를 들어 prefix = "networking-"을 설정하면 networking-dev, networking-prod 같은 이름의 HCP Terraform 워크스페이스를 사용해요. 이는 단일 Terraform 구성에서 사용되는 여러 Terraform CLI 워크스페이스를 여러 HCP Terraform 워크스페이스에 매핑할 때 유용해요.

백엔드 구성은 name 또는 prefix 중 하나를 요구해요. 둘 다 생략하거나 둘 다 설정하면 구성 오류가 발생해요. terraform init 실행 시 이전 state가 있고 해당 원격 워크스페이스가 비어 있거나 없으면 Terraform이 워크스페이스를 만들고 원격 state를 그에 맞게 갱신해요. 하지만 워크스페이스가 원격 연산에 변수나 특정 Terraform 버전을 요구한다면, 어떤 원격 연산도 실행하기 전에 HCP Terraform에서 원격 워크스페이스를 먼저 만드는 것을 권장해요.

워크스페이스 이름 (Workspace Names)

Terraform은 명령줄에서 워크스페이스와 상호작용할 때 공통 접두사를 뺀 축약 이름을 사용해요. 예를 들어 prefix = "networking-"이면 terraform workspace select prod를 사용해 현재 구성 안의 Terraform CLI 워크스페이스 prod로 전환해요. 하지만 그 Terraform CLI 워크스페이스에 대한 plan과 apply 같은 원격 Terraform 연산은 HCP Terraform 워크스페이스 networking-prod에서 일어나요.

이 때문에 terraform.workspace 보간 표현식은 원격 워크스페이스가 연산을 로컬로 수행하는지 원격으로 수행하는지에 따라 다른 결과를 만들어요. 예를 들어 prefix = "networking-"으로 만든 networking-prod라는 원격 워크스페이스에서 표현식은 다음을 만들어요:

  • 로컬 연산의 경우 terraform.workspace = prod
  • 원격 연산의 경우 terraform.workspace = networking-prod

Terraform 1.1.0 이전에는 HCP Terraform 워크스페이스가 내부적으로 단일 default Terraform CLI 워크스페이스만 사용했어요. 그래서 구성이 terraform.workspace로 dev나 prod를 반환하도록 사용했다면, HCP Terraform의 원격 run은 terraform workspace select 명령으로 어떤 워크스페이스를 설정했든 항상 default로 평가했어요. 따라서 Terraform 1.0.x 이하를 사용하면서 HCP Terraform 워크스페이스에 대해 원격 연산을 실행하는 구성에서는 terraform.workspace를 사용하지 않는 것을 권장해요.

실행 환경 결정 (Determining Run Environment)

구성에서 run이 로컬인지 원격인지 결정해야 한다면 HCP Terraform run 환경 변수를 사용하는 것을 권장해요. 아래 예시는 HCP_TERRAFORM_RUN_ID를 사용해요:

output "current_workspace_name" {
  value = terraform.workspace
}

variable "HCP_TERRAFORM_RUN_ID" {
  type    = string
  default = ""
}

output "remote_execution_determine" {
  value = "Remote run environment? %{if var.HCP_TERRAFORM_RUN_ID != ""}Yes%{else}No this is local%{endif}!"
}

예시 구성 (Example Configurations)

참고: 구성에서 토큰을 생략하고, 대신 terraform login을 사용하거나 CLI 구성 파일에서 credentials를 수동으로 구성하는 것을 권장해요.

기본 구성 (Basic Configuration)

# 단일 워크스페이스 사용:
terraform {
  backend "remote" {
    hostname = "app.terraform.io"
    organization = "company"

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

# 여러 워크스페이스 사용:
terraform {
  backend "remote" {
    hostname = "app.terraform.io"
    organization = "company"

    workspaces {
      prefix = "my-app-"
    }
  }
}

CLI 입력 사용 (Using CLI Input)

# main.tf
terraform {
  required_version = "~> 0.12.0"

  backend "remote" {}
}

백엔드 구성 파일:

# config.remote.tfbackend
workspaces { name = "workspace" }
hostname     = "app.terraform.io"
organization = "company"

백엔드 파일로 terraform init 실행:

terraform init -backend-config=config.remote.tfbackend

데이터 소스 구성 (Data Source Configuration)

data "terraform_remote_state" "foo" {
  backend = "remote"

  config = {
    organization = "company"

    workspaces = {
      name = "workspace"
    }
  }
}

구성 변수 (Configuration Variables)

경고: 자격 증명과 기타 민감 데이터를 제공할 때는 환경 변수를 사용하는 것을 권장해요. -backend-config를 사용하거나 이런 값을 구성에 직접 하드코딩하면 Terraform이 .terraform 하위 디렉터리와 plan 파일 양쪽에 이 값을 포함해요. 자세한 내용은 Credentials and Sensitive Data를 참고해요.

다음 구성 옵션을 지원해요:

  • hostname - (선택) 연결할 remote 백엔드 호스트 이름. 기본값은 app.terraform.io.
  • organization - (필수) 대상 워크스페이스를 포함하는 조직의 이름.
  • token - (선택) remote 백엔드로 인증하는 데 사용하는 토큰. 구성에서 토큰을 생략하고 terraform login을 사용하거나 CLI 구성 파일에서 credentials를 수동으로 구성하는 것을 권장해요.
  • workspaces - (필수) 사용할 원격 워크스페이스를 지정하는 블록.

workspaces 블록은 다음 키를 지원해요:

  • name - (선택) 하나의 원격 워크스페이스의 전체 이름. 구성되면 기본 워크스페이스만 사용할 수 있어요. 이 옵션은 prefix와 충돌해요.
  • prefix - (선택) 이 구성과 함께 사용할 수 있는 하나 이상의 원격 워크스페이스 이름에 사용되는 접두사. 전체 워크스페이스 이름은 HCP Terraform에서 사용되고, 축약 이름(접두사 제외)은 명령줄에서 Terraform CLI 워크스페이스에 사용돼요. 생략하면 기본 워크스페이스만 사용할 수 있어요. 이 옵션은 name과 충돌해요.

참고: 다른 HCP Terraform 워크스페이스에서 state를 검색하는 terraform_remote_state 데이터 소스를 구성할 때는 반드시 name 키를 사용해야 해요. prefix 키는 remote 백엔드 인스턴스를 구성할 때만 사용하기 위한 것이에요.

명령줄 인자 (Command Line Arguments)

backend "remote" 블록을 포함하는 구성에서 Terraform state를 로컬로 수정한 다음 원격 워크스페이스로 다시 푸시하는 명령은 그 동작을 수정하기 위해 다음 옵션을 받아들여요:

  • -ignore-remote-version - 로컬과 원격 Terraform 버전이 일치하는지 검사하는 것을 재정의해 불일치가 있어도 연산을 진행하게 해요.

보통 state 수정 연산은 원격 워크스페이스의 설정 일부로 선택된 Terraform 버전과 호환되는 로컬 Terraform CLI 버전을 사용해야 해요. 이는 로컬 연산이 워크스페이스의 원격 실행 환경이 디코딩할 수 없는 새 state 스냅샷을 만들지 않도록 하기 위한 것이에요. 이 검사를 재정의하면 HCP Terraform 워크스페이스가 더 이상 원격 연산을 완료하지 못하게 될 수 있으므로 이 옵션을 사용하지 않는 것을 권장해요.

.terraformignore로 업로드에서 파일 제외하기

버전 참고: .terraformignore 지원은 Terraform 0.12.11에서 추가됐어요.

CLI 주도 run에서 원격 plan이나 apply를 실행할 때 구성 디렉터리의 아카이브가 HCP Terraform에 업로드돼요. 구성 디렉터리 루트의 .terraformignore 파일로 업로드에서 무시할 경로를 정의할 수 있어요. 파일이 없으면 아카이브는 기본적으로 다음을 제외해요:

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

.terraformignore 파일은 .gitignore 파일에 포함하듯 규칙을 포함할 수 있어요:

  • 주석(#로 시작)이나 빈 줄은 무시돼요.
  • 디렉터리를 지정하려면 패턴을 슬래시 /로 끝내요.
  • 느낌표 !로 시작하면 패턴을 부정해요.

.gitignore와 달리 구성 디렉터리 루트의 .terraformignore만 고려된다는 점을 주의해요.

더 알아보기 (Learn more)