Consul-Terraform-Sync 구성

Consul-Terraform-Sync 구성 (Consul-Terraform-Sync configuration)

Consul-Terraform-Sync(CTS)에 대한 구성 참조 정보를 담고 있어요. HCL 또는 JSON 구성 파일로 구성 설정을 전달해 CTS 데몬을 구성해요. HCL 구문은 HashiCorp 구성 언어(HashiCorp Configuration Language)에서 배울 수 있어요.

출처: 문서

본문

이 항목은 Consul-Terraform-Sync(CTS)에 대한 구성 참조 정보를 포함합니다. HCL 또는 JSON 구성 파일로 구성 설정을 전달해 CTS 데몬을 구성하세요. HCL 구문을 배우려면 HashiCorp 구성 언어(HashiCorp Configuration Language)를 참조하세요.

전역 구성 (Global configurations)

최상위 옵션은 CTS를 구성하기 위해 예약되어 있습니다.

log_level   = "INFO"
working_dir = "sync-tasks"
port        = 8558
id          = "cts-01"

syslog {
  facility = "local2"
}

buffer_period {
  enabled = true
  min     = "5s"
  max     = "20s"
}

tls {
  enabled         = true
  cert            = "/path/to/cert.pem"
  key             = "/path/to/key.pem"
  verify_incoming = true
  ca_cert         = "/path/to/ca.pem"
}
  • buffer_period — 모든 동적 작업에 대한 기본 버퍼 기간을 구성하여 플래핑(flapping) 서비스가 다운스트림 네트워크 장치에 미치는 영향을 완화합니다. 작업 실행을 트리거하기 전에 클러스터가 일관된 상태에 도달하고 변경 사항을 축적할 때까지 기다리는 최소 및 최대 시간을 정의합니다. 기본값은 활성화되어 있으며, 짧은 시간 내에 다운스트림 인프라가 업데이트되는 횟수를 줄입니다. 플래핑이 많은 시스템에서 활성화하면 유용합니다. 버퍼 기간은 예약 작업에는 적용되지 않습니다.
    • enabled - (bool: true) 버퍼 기간을 전역적으로 활성화하거나 비활성화합니다. min을 지정하면 이것도 활성화됩니다.
    • min - (string: "5s") 변경 사항이 감지된 후 관련 작업을 트리거하기 전에 기다리는 최소 시간입니다.
    • max - (string: "20s") 변경 사항이 감지된 후 관련 작업을 트리거하기 전에 기다리는 최대 시간입니다. min이 설정되면 max의 기본 기간은 min 값의 4배입니다.
  • log_level - (string: "INFO") CTS 로깅에 사용할 로그 수준입니다. 기본값은 "INFO"입니다. 사용 가능한 로그 수준은 "TRACE", "DEBUG", "INFO", "WARN", "ERR"입니다.
  • port - (int: 8558) CTS가 API 요청을 제공하는 데 사용할 포트입니다.
  • id - (string: cts-<hostname> 형식의 생성된 ID) CTS 인스턴스의 ID입니다. CTS는 서비스 등록이 활성화된 경우 ID를 CTS의 서비스 ID로 사용합니다. CTS는 또한 고가용성 클러스터에서 인스턴스를 식별하는 데 ID를 사용합니다.
  • syslog — 로깅을 위한 syslog 서버를 지정합니다.
    • enabled - (bool) syslog 로깅을 활성화합니다. 다른 옵션을 지정해도 syslog 로깅이 활성화됩니다.
    • facility - (string: "local0") 로깅할 syslog facility의 이름입니다.
    • name - (string: "consul-terraform-sync") syslog에 로깅할 때 데몬 프로세스에 사용할 이름입니다.
  • working_dir - (string: "sync-tasks") Terraform 구성 파일을 포함해 CTS가 각 작업에 대해 생성하는 아티팩트를 관리하기 위한 기본 작업 디렉터리를 지정합니다. CTS는 또한 각 작업에 대한 하위 디렉터리를 생성합니다(예: ./sync-tasks/task-name). 하위 디렉터리가 작업의 작업 디렉터리입니다. 작업 수준 작업 디렉터리를 재정의하려면 task.working_dir 옵션을 사용하세요.
  • tls — CTS API에 TLS를 구성합니다.
    • enabled - (bool: false) TLS를 활성화합니다. TLS 옵션 중 하나에 값을 제공하면 이 매개변수가 암시적으로 활성화됩니다.
    • cert - (string) CTS API에 대한 TLS 연결에 사용되는 PEM 인코딩 인증서 파일의 경로입니다.
    • key - (string) cert가 구성한 인증서와 함께 사용되는 PEM 인코딩 프라이빗 키 파일의 경로입니다.
    • verify_incoming - (bool: false) 상호 TLS(mTLS)를 활성화합니다. CTS API에 대한 모든 수신 연결이 TLS 연결을 사용하고 ca_cert 또는 ca_path가 지정한 인증 기관이 서명한 인증서를 제공하도록 요구합니다.
    • ca_cert - (string) verify_incoming이 true로 설정될 때 CTS API에 대한 수신 클라이언트 연결의 진위를 검증하는 데 사용되는 PEM 인코딩 인증 기관 파일의 경로입니다. 둘 다 구성되면 ca_path보다 우선합니다.
    • ca_path - (string) verify_incoming이 true로 설정될 때 CTS API에 대한 수신 클라이언트 연결의 진위를 검증하는 데 사용되는 PEM 인코딩 인증 기관 파일 디렉터리의 경로입니다.
  • license_path Enterprise - (string) CTS 0.6.0에서 권장되지 않으며 향후 릴리스에서 제거될 예정입니다. 대신 license 블록을 사용하세요. 라이선스가 포함된 파일의 경로를 구성합니다. 엔터프라이즈 기능을 사용하려면 라이선스를 지정해야 합니다. CONSUL_LICENSE 및 CONSUL_LICENSE_PATH 환경 변수를 정의해 라이선스를 설정할 수도 있습니다. 자세한 내용은 라이선스 설정(Setting the License)을 참조하세요.

라이선스 (License) Enterprise

license 블록은 다음 옵션으로 CTS가 라이선스를 로드하는 방법을 구성합니다.

  • Consul에서 라이선스를 자동으로 검색하도록 CTS를 구성합니다.
  • 라이선스 파일의 경로를 제공합니다.

license 블록이 구성되지 않으면 CTS는 자동 라이선스 검색을 사용합니다.

license {
  path = "path/to/license.lic"
  auto_retrieval {
    enabled = true
  }
}
매개변수 필수 유형 설명 기본값
path 선택 string 라이선스가 포함된 파일의 경로를 구성합니다. 라이선스 경로가 구성되면 자동 라이선스 검색을 활성화할 때까지 이 라이선스가 사용됩니다. CONSUL_LICENSE 및 CONSUL_LICENSE_PATH 환경 변수를 정의해 라이선스를 설정할 수도 있습니다. 자세한 내용은 라이선스 설정을 검토하세요. none
auto_retrieval 선택 object CTS가 사용하는 라이선스 자동 검색을 구성합니다. 자세한 내용은 자동 검색(Auto-Retrieval)을 검토하세요. 자동 검색에서 기본값 검토

자동 검색 (Auto-retrieval)

auto_retrieval 블록을 사용해 CTS의 자동 라이선스 검색을 구성할 수 있습니다. 활성화되면 CTS는 구성된 Consul Enterprise 백엔드에서 하루에 한 번 새 라이선스를 검색하려고 시도합니다. CTS가 라이선스를 검색할 수 없고 현재 라이선스가 만료일에 가까워지면 라이선스 만료일 처리(License Expiration Date Handling)에 정의된 대로 증가된 빈도로 라이선스 검색을 시도합니다.

매개변수 필수 유형 설명 기본값
enabled 선택 string true로 설정하면 라이선스 자동 검색을 활성화합니다. true

Consul 연결 (Consul connection)

consul 블록은 CTS가 작업 실행을 위해 쿼리를 수행할 수 있도록 Consul 에이전트와의 CTS 연결을 구성합니다. 또한 CTS를 콘솔에 서비스로 자동 등록하는 것도 구성합니다.

참고 로컬 Consul 프로세스와 통신할 때 HTTP/2를 사용하면 Consul-Terraform-Sync 성능을 개선할 수 있습니다. cert_file 및 key_file 매개변수를 설정해 로컬 Consul에 대해 TLS/HTTPS를 구성해야 합니다. Consul-Terraform-Sync 구성의 경우 tls.enabled = true로 설정하고 address 매개변수를 HTTPS URL로 설정하세요(예: address = example.consul.com:8501). Consul에 자체 서명 인증서를 사용한다면 tls.verify = false로 설정하거나 인증서를 ca_cert 또는 ca_path에 추가해야 합니다.

Consul 에이전트 구성에 대한 제안 사항에 대해 자세히 알아보려면 에이전트 실행(run an agent)을 참조하세요.

consul {
  address = "localhost:8500"
  auth {}
  tls {}
  token = null
  transport {}
  service_registration {
    service_name = "cts"
    address = "172.22.0.2"
    default_check {
      address = "http://172.22.0.2:8558"
    }
  }
}
매개변수 필수 유형 설명 기본값
address 선택 string Consul 에이전트의 주소입니다. IP 또는 FQDN일 수 있습니다. localhost:8500
token 선택 string 로컬 Consul 에이전트와의 클라이언트 통신에 사용할 ACL 토큰입니다. 필요한 권한은 ACL 요구 사항을 참조하세요. 토큰은 CONSUL_TOKEN 또는 CONSUL_HTTP_TOKEN 환경 변수로도 제공할 수 있습니다. none
auth 선택 auth Consul과 통신하기 위한 HTTP 기본 인증
tls 선택 tls Consul과의 보안 클라이언트 연결
transport 선택 transport 저수준 네트워크 연결 세부 정보
service_registration 선택 service_registration CTS가 건강 검사와 함께 서비스로 Consul에 자체 등록하는 방법에 대한 옵션.

ACL 요구 사항 (ACL requirements)

다음 표는 CTS에 필요한 ACL 정책을 설명합니다. 자세한 내용은 프로덕션용 Secure Consul-Terraform-Sync 자습서를 참조하세요.

정책 리소스
service:read 작업이 모니터링하는 모든 서비스
node:read 작업이 모니터링하는 서비스를 호스팅하는 모든 노드
keys:read 작업이 모니터링하는 모든 Consul KV 쌍
namespace:read Enterprise 작업이 모니터링하는 리소스에 대한 모든 네임스페이스
service:write 서비스 등록이 활성화된 CTS 서비스
keys:write consul-terraform-sync/ Consul을 Terraform 백엔드로 사용할 때만 필요

Auth

Consul과 통신하기 위한 HTTP 기본 인증을 구성합니다.

매개변수 필수 유형 설명 기본값
enabled 선택 boolean HTTP 기본 인증 사용을 활성화합니다. false
username 선택 string 인증용 사용자 이름 none
password 선택 string 인증용 비밀번호 none

TLS

Consul과의 보안 클라이언트 연결을 위해 TLS를 구성합니다. HTTP/2를 사용하면 Consul의 최대 연결 한도에 도달하는 문제를 해결하고 많은 블로킹 쿼리를 처리할 때 효율성을 개선할 수 있습니다. 이 옵션은 HTTPS 연결에 TLS 검증을 활성화한 Consul 에이전트에 연결할 때 Consul-Terraform-Sync에 필요합니다.

Consul이 전역 CA 체인에 추가하지 않은 자체 서명 인증서를 사용한다면 ca_cert 또는 ca_path로 이 인증서를 설정할 수 있습니다. 또는 verify를 false로 설정해 SSL 검증을 비활성화할 수 있습니다. 그러나 검증을 비활성화하는 것은 잠재적인 보안 취약점입니다.

매개변수 필수 유형 설명 기본값
enabled 선택 boolean TLS를 활성화합니다. TLS 옵션 중 하나에 값을 제공하면 이 매개변수가 암시적으로 활성화됩니다. false
verify 선택 boolean Consul이 반환한 인증서가 유효한지 확인하기 위해 전역 인증 기관(CA) 체인을 검사하는 TLS 피어 검증을 활성화합니다. true
ca_cert 선택 string TLS를 통한 Consul 연결의 진위를 검증하는 데 사용되는 PEM 인코딩 인증 기관 파일의 경로입니다. CONSUL_CACERT 환경 변수로도 제공할 수 있습니다. none
ca_path 선택 string TLS를 통한 Consul 연결의 진위를 검증하는 데 사용되는 PEM 인코딩 인증 기관 파일 디렉터리의 경로입니다. CONSUL_CAPATH 환경 변수로도 제공할 수 있습니다. none
cert 선택 string Consul이 CTS의 연결 진위를 검증할 수 있도록 TLS를 통해 Consul에 제공되는 PEM 인코딩 클라이언트 인증서 파일의 경로입니다. Consul이 verify_incoming을 true로 설정한 경우 필요합니다. CONSUL_CLIENT_CERT 환경 변수로도 제공할 수 있습니다. none
key 선택 string cert가 구성한 클라이언트 인증서와 함께 사용되는 PEM 인코딩 프라이빗 키 파일의 경로입니다. Consul이 verify_incoming을 true로 설정한 경우 필요합니다. CONSUL_CLIENT_KEY 환경 변수로도 제공할 수 있습니다. none
server_name 선택 string TLS로 연결할 때 Consul의 SNI(Server Name Indication)로 사용할 서버 이름입니다. CONSUL_TLS_SERVER_NAME 환경 변수로도 제공할 수 있습니다. none

Transport

Consul에 대한 저수준 네트워크 연결 세부 정보를 구성합니다.

Consul 서비스 업데이트에서 작업 실행까지 가장 짧은 지연 시간을 달성하려면 max_idle_conns_per_host를 모든 작업에 걸쳐 자동화에 있는 서비스 수와 같거나 크게 구성하세요. 이 값은 Consul 에이전트에 대해 구성된 http_max_conns_per_client보다 낮아야 합니다.

max_idle_conns_per_host와 자동화의 서비스 수가 Consul 에이전트 한도보다 크면 CTS가 연결 한도(상태 코드 429)로 인해 오류가 발생할 수 있습니다. 에이전트 한도를 주의해서 늘릴 수 있습니다. Terraform 하위 프로세스 또는 CTS와 같은 호스트의 다른 프로세스가 Consul 에이전트에 하는 요청이 Consul 에이전트 연결 한도에 기여합니다.

매개변수 필수 유형 설명 기본값
dial_keep_alive 선택 string keep-alive의 시간입니다. 30s
dial_timeout 선택 string 연결을 설정할 때까지 기다리는 시간입니다. 30s
disable_keep_alives 선택 boolean keep-alive를 사용해야 하는지 결정합니다. 비활성화하면 성능이 크게 저하됩니다. false
idle_conn_timeout 선택 string 유휴 연결의 시간 초과입니다. 5s
max_idle_conns 선택 integer 모든 호스트에 걸친 총 유휴 연결의 최대 수입니다. 기본적으로 제한은 비활성화되어 있습니다. 0
max_idle_conns_per_host 선택 integer 원격 호스트당 유휴 연결의 최대 수입니다. 대부분의 연결은 Consul 에이전트라는 한 호스트로 설정됩니다. 100
tls_handshake_timeout 선택 string TLS 핸드셰이크를 완료할 때까지 기다리는 시간입니다. 10s

서비스 등록 (Service registration)

CTS는 id 구성을 서비스 ID로 사용해 건강 검사와 함께 서비스로 Consul에 자동으로 등록됩니다. CTS가 정상적으로 중지되면 Consul에서 자체 등록을 해제합니다. CTS가 Consul에 등록할 수 없으면 오류를 기록하고 종료하지 않고 계속 진행합니다.

서비스 등록에는 Consul 토큰이 CTS 서비스에 대한 service:write ACL 정책이 있어야 합니다.

매개변수 필수 유형 설명 기본값
enabled 선택 boolean CTS가 서비스로 Consul에 자체 등록할 수 있게 합니다. 고가용성을 위해 구성된 CTS 인스턴스에 서비스 등록이 활성화되면 인스턴스는 cts-cluster:<cluster-name> 형식을 사용하는 새 태그로 자체 등록합니다. true
service_name 선택 string CTS의 서비스 이름입니다. CTS가 고가용성을 위해 구성된 경우 high_availability.cluster.name 값과 같은 이름을 지정하는 것이 좋습니다. consul-terraform-sync
address 선택 string CTS의 IP 주소 또는 호스트 이름입니다. Consul 에이전트 노드의 IP 주소
namespace 선택 string Enterprise CTS를 등록할 네임스페이스입니다. 우선 순위 순: 1. CTS ACL 토큰에서 추론 2. 기본 네임스페이스
default_check.enabled 선택 boolean CTS가 기본 건강 검사를 만들 수 있게 합니다. true
default_check.address 선택 string 기본 HTTP 건강 검사에 사용할 주소입니다. 해당되는 경우 체계(http/https)와 포트를 포함해야 합니다. http://localhost:<port> 또는 https://localhost:<port>. port 구성과 CTS API에 TLS가 활성화되어 있는지 여부로 결정됩니다.

기본 건강 검사는 Health API를 호출하는 HTTP 검사입니다. 다음 표는 Consul register check API에 해당하는 이 기본 검사에 대해 CTS가 설정하는 값을 설명합니다. 이 표에 나열되지 않은 옵션은 CTS가 기본값을 사용합니다.

매개변수 값
Name CTS Health Status
ID <id>-health
Namespace service_registration.namespace
Notes Check created by Consul-Terraform-Sync
DeregisterCriticalServiceAfter 30m
ServiceID id
Status critical
HTTP <default_check.address>/v1/health
Method GET
Interval 10s
Timeout 2s
TLSSkipVerify false

고가용성 (High availability)

CTS를 고가용성 모드로 실행할 수 있게 하려면 구성에 high_availability 블록을 추가하세요. 추가 정보는 고가용성으로 Consul-Terraform-Sync 실행(Run Consul-Terraform-Sync with High Availability)을 참조하세요. high_availability 블록에는 다음 구성 항목이 포함됩니다.

고가용성 클러스터 (High availability cluster)

cluster 매개변수에는 고가용성이 활성화된 상태로 운영하려는 클러스터에 대한 구성이 포함됩니다. 다음 옵션을 구성할 수 있습니다.

매개변수 설명 필수 유형
name 고가용성이 활성화된 상태로 운영되는 클러스터의 이름을 지정합니다. 필수 String
storage CTS가 상태 정보를 저장하는 방법을 구성합니다. 추가 정보는 상태 저장 및 지속성(State storage and persistence)을 참조하세요. "consul" 리소스에 대한 storage를 정의할 수 있습니다. 추가 정보는 고가용성 클러스터 저장(High availability cluster storage)을 참조하세요. 선택 Object

고가용성 클러스터 저장 (High availability cluster storage)

high_availability.cluster.storage 객체에는 다음 구성이 포함됩니다.

매개변수 설명 필수 유형
parent_path CTS가 상태 정보를 저장할 Consul KV의 상위 경로를 정의합니다. 기본값은 consul-terraform-sync/입니다. CTS는 상위 경로에 클러스터 이름을 자동으로 추가하므로 상태 정보의 실질적인 기본 디렉터리는 consul-terraform-sync/<cluster-name>입니다. 선택 String
namespace Consul KV에 상태를 저장할 때 사용할 네임스페이스를 지정합니다. 기본값은 CTS ACL 토큰에서 추론됩니다. 대체 기본값은 default입니다. 선택 String
session_ttl 리더 선거를 위한 세션 TTL(Time-To-Live)을 지정합니다. Consul에 대해 구성된 session_ttl_min보다 큰 값을 지정해야 합니다. session_ttl이 길수록 장애 조치 후 리더 선거가 길어집니다. 기본값은 15s입니다. 선택 String

고가용성 인스턴스 (High availability instance)

instance 매개변수는 CTS 인스턴스에 고유한 구성을 포함하는 객체입니다. 다음 구성을 지정합니다.

  • address : (선택) 다른 인스턴스에 알릴 CTS 인스턴스의 IP 주소를 지정하는 String 값입니다. 이 매개변수에는 기본값이 없습니다.

서비스 (Service)

참고 CTS 0.5.0에서 권장되지 않으며 향후 주요 릴리스에서 제거될 예정입니다. service 블록은 작업 블록의 services 필드를 정의하는 데 사용되며, 이 필드도 권장되지 않고 서비스 조건(Services Condition) 및 서비스 모듈 입력(Services Module Input)으로 대체되었습니다. service 블록 구성은 해당 서비스 조건(Services Condition)과 서비스 모듈 입력(Services Module Input)의 동등한 필드를 구성해 대체할 수 있습니다. 예시는 0.5.0 릴리스 노트를 참조하세요.

service 블록은 작업 블록의 services 필드(권장되지 않음)에 구성된 서비스를 명시적으로 정의하는 선택적 블록입니다. service 블록은 작업 블록의 condition "services" 또는 module_input "services" 블록에 구성된 서비스를 정의하지 않습니다.

service 블록은 사용자 정의 데이터센터와 같이 기본값이 아닌 값이 있는 서비스에만 필요합니다. service 블록이 구성되지 않은 서비스는 기본값을 가정합니다. 여러 서비스를 구성하려면 여러 service 블록을 지정하세요. service 블록이 구성되면 서비스는 task.services에서 서비스 이름 또는 ID로 참조할 수 있습니다. service 블록이 구성되지 않으면 서비스 이름으로만 참조할 수 있습니다.

service {
  name        = "web"
  datacenter  = "dc1"
  description = "all instances of the service web in datacenter dc1"
}
매개변수 필수 유형 설명 기본값
name 필수 string 서비스의 Consul 논리적 이름입니다. none
id 선택 string CTS의 서비스 ID입니다. 작업이 사용할 서비스 구성을 명시적으로 식별하는 데 사용됩니다. ID가 제공되지 않으면 서비스는 작업 정의 내에서 서비스 이름으로 식별됩니다. none
description 선택 string 서비스를 설명하는 사람이 읽을 수 있는 텍스트 none
datacenter 선택 string 작업을 위해 쿼리할 데이터센터의 이름입니다. CTS가 쿼리하는 에이전트의 데이터센터
namespace 선택 string Enterprise 작업을 위해 쿼리할 서비스의 네임스페이스입니다. 우선 순위 순: 1. CTS ACL 토큰에서 추론 2. 기본 네임스페이스
filter 선택 string 모니터링할 서비스를 추가로 필터링하는 데 사용되는 표현식입니다. 추가 정보는 서비스 필터링 문서와 필터 표현식 작성 방법에 대한 섹션을 참조하세요. none
cts_user_defined_meta 선택 map [string] 호환되는 Terraform 모듈의 서비스 입력 변수에 추가되는 사용자 정의 메타데이터입니다. 일부 모듈은 구성된 메타데이터를 사용하지 않습니다. 메타데이터 사용과 예상 키 및 형식에 대한 정보는 작업을 위해 구성된 모듈을 참조하세요. 여러 작업이 같은 서비스에 의존하지만 다른 메타데이터가 필요하다면 같은 서비스에 대해 다른 메타데이터 세트를 선언할 수 있습니다. 해당 블록에 대해 고유한 ID(그리고 동일한 이름)를 가진 여러 service 블록을 정의하세요. 그러면 메타데이터를 서비스 ID를 기반으로 작업별로 분리할 수 있습니다. none

작업 (Task)

task 블록은 자동화에서 실행할 작업을 구성합니다. condition 블록을 사용해 작업이 실행되는 시점을 지정하세요. 여러 작업을 구성하려면 task 블록을 여러 번 지정할 수 있으며, 완전히 생략할 수도 있습니다. 초기 구성에 작업 블록이 지정되지 않은 경우 /tasks API 엔드포인트 또는 CLI의 task 명령을 사용해 실행 중인 CTS 인스턴스에 추가할 수 있습니다.

task {
  name           = "taskA"
  description    = ""
  enabled        = true
  providers      = []
  module         = "org/example/module"
  version        = "1.0.0"
  variable_files = []
  condition "services" {
    names = ["web", "api"]
  }
}
  • description - (string) 작업을 설명하는 사람이 읽을 수 있는 텍스트입니다.
  • name - (string: 필수) 작업의 고유 이름(필수)입니다. 작업 이름은 문자 또는 밑줄로 시작해야 하며 문자, 숫자, 밑줄, 대시만 포함할 수 있습니다.
  • enabled - (bool: true) 작업이 실행되고 리소스를 관리하지 못하도록 활성화하거나 비활성화합니다.
  • providers - (list [string]) 작업이 의존하는 프로바이더 이름 목록입니다. Terraform 프로바이더 구성을 작업에 매핑하는 데 사용됩니다.
  • services - (list [string]) CTS 0.5.0에서 권장되지 않으며 향후 주요 릴리스에서 제거될 예정입니다. 대신 서비스 조건(Services Condition) 또는 서비스 모듈 입력(Services Module Input)을 사용하세요. 예시는 0.5.0 릴리스 노트를 참조하세요. 작업이 Consul 카탈로그에서 변경 사항을 모니터링하는 논리적 서비스 이름 또는 서비스 ID의 선택적 목록을 지정합니다. 서비스는 작업의 조건 블록 구성에 따라 다르게 작동할 수 있습니다.
    • 조건 블록이 구성되지 않은 경우: 서비스는 작업의 조건으로 작동하며 모듈 입력으로 서비스 정보를 제공합니다.
    • services 유형의 조건 블록이 구성된 경우: 두 가지 모두 서비스 모듈 입력을 구성하므로 services는 이 조건 유형과 호환되지 않습니다. CTS가 오류를 반환합니다.
    • 다른 모든 유형의 조건 블록이 구성된 경우: 서비스는 서비스 모듈 입력을 제공하는 것만 작동합니다. service 블록으로 명시적으로 정의되지 않았고 일치하는 ID가 있는 서비스 값은 기본 네임스페이스의 논리적 서비스 이름으로 간주됩니다.
  • source - (string: 필수) CTS 0.5.0에서 권장되지 않으며 향후 주요 릴리스에서 제거될 예정입니다. 대신 module 필드를 참조하세요.
  • module - (string: 필수) 드라이버가 자동화에 사용되는 Terraform 모듈을 발견하는 데 사용하는 위치입니다. 모듈 소스는 로컬이거나 Terraform Registry 또는 프라이빗 모듈 레지스트리의 원격일 수 있습니다. Terraform 모듈 소스와 지원되는 다른 유형에 대한 자세한 내용은 여기를 참조하세요. terraform 드라이버와 함께 프라이빗 모듈을 사용하려면 CTS를 시작하기 전에 terraform login [hostname] 명령을 실행해 로컬 Terraform CLI를 인증하세요. terraform_cloud 드라이버와 함께 프라이빗 모듈을 사용하려면 추가 단계가 필요 없습니다. 
    // local module example: "./terraform-cts-hello"
module = "<PATH>"
// public module example: "mkam/hello/cts"
module = "<NAMESPACE>/<MODULE NAME>/<PROVIDER>"
// private module example: "my.tfe.hostname.io/my-org/hello/cts"
module = "<HOSTNAME>/<ORGANIZATION>/<MODULE NAME>/<PROVIDER>"
  • variable_files - (list [string]) Terraform 변수 정의 파일(.tfvars)의 경로 목록을 지정합니다. 이 파일의 내용은 변수 이름 할당으로만 구성되어야 합니다. 변수 할당은 작업의 Terraform 모듈이 제공하는 해당 변수 선언과 일치해야 합니다. 변수는 파일에 나타나는 순서대로 로드됩니다. 중복 변수는 더 나중의 값으로 덮어씁니다. 모듈에 의해 지정되지 않는 한 Terraform 프로바이더에 대한 인수는 terraform_provider 블록을 사용해 구성하세요. 
    example.tfvars
address_group = "consul-services"
tags = [ "consul-terraform-sync" ]
  • version - (string) 작업이 사용할 제공된 모듈의 버전입니다. 생략하면 최신 버전이 기본값으로 사용됩니다.
  • working_dir - (string) Terraform 구성 파일을 포함해 CTS가 이 작업에 대해 생성하는 아티팩트를 관리하기 위한 작업 디렉터리입니다. 기본적으로 각 작업에 대한 작업 디렉터리가 기본 working_dir의 하위 디렉터리로 생성됩니다(예: sync-tasks/task-name).
  • buffer_period — 플래핑 서비스가 다운스트림 네트워크 장치에 미치는 영향을 완화하기 위한 동적 작업의 버퍼 기간을 구성합니다. 작업 실행을 트리거하기 전에 클러스터가 일관된 상태에 도달하고 변경 사항을 축적할 때까지 기다리는 최소 및 최대 시간을 정의합니다. 기본값은 최상위 buffer_period 블록에서 상속됩니다. 구성되면 이러한 값이 전역 버퍼 기간보다 우선합니다. 플래핑이 많은 서비스에 의존하는 작업에 대해 활성화하면 유용합니다. 버퍼 기간은 예약 작업에는 적용되지 않습니다.
    • enabled - (bool) 이 작업에 대한 버퍼 기간을 활성화하거나 비활성화합니다. min을 지정하면 이것도 활성화됩니다.
    • min - (string: "5s") 변경 사항이 감지된 후 관련 작업을 트리거하기 전에 기다리는 최소 시간입니다.
    • max - (string: "20s") 변경 사항이 감지된 후 관련 작업을 트리거하기 전에 기다리는 최대 시간입니다. min이 설정되면 max의 기본 기간은 min 값의 4배입니다.
  • condition - (obj: 필수) 충족되면 CTS가 작업을 실행하도록 트리거하는 요구 사항입니다. 작업당 하나의 조건만 구성할 수 있습니다. CTS는 각각 자체 구성 옵션이 있는 다양한 유형의 조건을 지원합니다. 각 조건 유형의 구성 옵션에 대한 자세한 내용은 작업 조건 구성(Task Condition configuration)을 참조하세요.
  • source_input - (obj) CTS 0.5.0에서 권장되지 않으며 0.8.0에서 제거될 예정입니다. 대신 module_input 블록을 참조하세요.
  • module_input - (obj) Terraform 모듈에 제공할 값 또는 메타데이터를 포함하는 Consul 객체를 지정합니다. module_input 블록은 작업 실행에 필요한 추가 모듈 입력을 정의합니다. 이는 조건 블록 또는 services 필드(권장되지 않음)가 제공하는 모듈 입력에 더해집니다. 작업당 여러 module_input 블록을 구성할 수 있습니다. 사용 및 제한 사항에 대한 자세한 내용은 작업 모듈 입력 구성(Task Module Input configuration)을 참조하세요.
  • terraform_version - (string) Enterprise CTS 0.6.0에서 권장되지 않으며 0.8.0에서 제거되었습니다. 대신 terraform_cloud_workspace.terraform_version을 사용하세요. 작업과 연결된 Terraform Cloud 작업 공간에 사용할 Terraform 버전입니다. 이 옵션은 Terraform Cloud 드라이버와 함께 사용할 때만 사용할 수 있습니다. 그렇지 않으면 Terraform 드라이버 내에서 버전을 설정하세요.
  • terraform_cloud_workspace - (obj) Enterprise 작업과 연결된 Terraform Cloud 작업 공간의 속성을 구성합니다. 이 옵션은 Terraform Cloud 드라이버와 함께 사용할 때만 사용할 수 있습니다. 모든 작업 공간의 전역 구성은 driver.workspaces를 검토하세요.
    • execution_mode - (string: "remote") Terraform Cloud를 Terraform 실행 플랫폼으로 사용할지 결정하는 실행 모드입니다. "remote" 또는 "agent"만 지원합니다.
    • agent_pool_id - (string) execution_mode가 "agent"로 설정된 경우에만 지원됩니다. Terraform 워크로드를 실행해야 하는 에이전트 풀의 ID입니다. execution_mode가 "agent"로 설정된 경우 agent_pool_id 또는 agent_pool_name이 필요합니다. 둘 다 제공되면 agent_pool_id가 agent_pool_name보다 우선합니다.
    • agent_pool_name - (string) execution_mode가 "agent"로 설정된 경우에만 지원됩니다. Terraform 워크로드를 실행해야 하는 에이전트 풀의 이름입니다. agent_pool_id 또는 agent_pool_name이 필요합니다. 둘 다 제공되면 agent_pool_id가 agent_pool_name보다 우선합니다.
    • terraform_version - (string) 작업과 연결된 Terraform Cloud 작업 공간에 사용할 Terraform 버전입니다. v0.9.0부터 이 구성을 생략할 수 있으며 CTS는 기존 작업 공간 버전이 호환되면 사용하거나 작업 공간 버전을 호환 버전으로 업그레이드합니다. 이전 버전에서 이 매개변수는 조직이 지원하는 최신 호환 버전이 기본값입니다.
    • auto_upgrade_tf_version - (bool: true) CTS v0.9.0 이상에서 사용할 수 있습니다. true로 설정하면 CTS가 작업 공간의 호환되지 않는 Terraform 버전을 가장 가까운 호환 버전으로 자동 업그레이드합니다. false로 설정하면 CTS가 자동으로 업그레이드하지 않고 작업 공간 Terraform 버전이 호환되지 않으면 오류와 함께 실패합니다. 지정하지 않으면 이 매개변수는 역호환성을 위해 기본적으로 true입니다.

작업 조건 (Task condition)

task 블록은 해당 특정 작업을 실행하기 위해 충족해야 하는 조건을 설정하는 condition 블록으로 구성됩니다. 아래는 CTS가 지원하는 다양한 유형의 조건입니다.

서비스 조건 (Services condition)

이 조건은 regexp에 구성된 정규 표현식과 일치하는 서비스 또는 names에 이름으로 나열된 서비스에서 작업을 트리거합니다. regexp 또는 names 중 하나를 구성해야 하며 둘 다는 안 됩니다.

작업에 condition "services" 블록이 구성되면 다음 제한 사항이 적용됩니다.

  • 작업을 services 필드(권장되지 않음)로 구성할 수 없습니다.
  • 작업을 module_input "services" 또는 source_input "services"(권장되지 않음) 블록으로 구성할 수 없습니다.

CTS가 이러한 제한을 두는 이유는 작업의 모니터링되는 서비스 정보가 하나의 구성 옵션으로만 설정될 수 있기 때문입니다. 작업에 필요한 서비스 모듈 입력은 조건 블록을 통해서만 구성해야 합니다.

서비스 조건으로 작업이 트리거되는 방법에 대한 자세한 내용은 작업 실행: 서비스 조건(Task Execution: Services Condition)을 참조하세요.

task {
  name        = "services_condition_regexp_task"
  description = "execute on changes to services with names starting with web"
  providers   = ["my-provider"]
  module      = "path/to/services-condition-module"

  condition "services" {
    regexp     = "^web.*"
    datacenter = "dc1"
    namespace  = "default"
    filter     = "Service.Tags not contains \"prod\""
    cts_user_defined_meta {
      key = "value"
    }
  }
}

task {
  name        = "services_condition_names_task"
  description = "execute on changes to services with names api or web"
  module      = "path/to/services-condition-module"

  condition "services" {
    names = ["api", "web"]
    datacenter = "dc1"
    namespace  = "default"
    filter     = "Service.Tags not contains \"prod\""
    cts_user_defined_meta {
      key = "value"
    }
  }
}
매개변수 필수 유형 설명 기본값
regexp names가 구성되지 않은 경우 필수 string 모니터링할 Consul 서비스의 이름을 일치시키는 정규 표현식입니다. 정규 표현식과 일치하는 이름을 가진 서비스만 작업이 사용합니다. 목록과 정규 표현식이 모두 필요하다면 목록을 정규 표현식의 일부로 포함하거나 별도의 작업을 만드는 것을 고려하세요. none
names regexp가 구성되지 않은 경우 필수 list [string] 모니터링할 Consul 서비스의 이름입니다. names에 이름이 나열된 서비스만 작업이 사용합니다. none
datacenter 선택 string 작업을 위해 쿼리할 데이터센터의 이름입니다. CTS가 쿼리하는 에이전트의 데이터센터
namespace 선택 string Enterprise 작업을 위해 쿼리할 서비스의 네임스페이스입니다. 우선 순위 순: 1. CTS ACL 토큰에서 추론 2. 기본 네임스페이스
filter 선택 string 모니터링할 서비스를 추가로 필터링하는 데 사용되는 표현식입니다. 추가 정보는 서비스 필터링 문서와 필터 표현식 작성 방법에 대한 섹션을 참조하세요. none
cts_user_defined_meta 선택 map [string] 호환되는 Terraform 모듈의 서비스 입력 변수에 추가되는 사용자 정의 메타데이터입니다. 일부 모듈은 구성된 메타데이터를 사용하지 않습니다. 메타데이터 사용과 예상 키 및 형식에 대한 정보는 작업을 위해 구성된 모듈을 참조하세요. none
source_includes_var 선택 boolean CTS 0.5.0에서 권장되지 않으며 0.8.0에서 제거될 예정입니다. 대신 use_as_module_input 필드를 참조하세요. true
use_as_module_input 선택 boolean 조건 객체의 값이 Terraform 모듈의 services 변수 입력으로도 사용되어야 하는지 여부입니다. 이 필드 구성 방법에 대한 지침은 선택한 모듈의 문서를 참조하세요. 모듈과 일치하지 않게 구성하면 CTS가 오류를 내고 종료합니다. true

카탈로그 서비스 조건 (Catalog-services condition)

catalog-services 조건 블록은 작업이 서비스 등록 및 등록 해제 시에만 실행되도록 구성하며, 더 구체적으로는 각각 첫 번째 서비스 인스턴스 등록 시와 마지막 서비스 인스턴스 등록 해제 시에 실행되도록 구성합니다. catalog-services 조건에는 등록 및 등록 해제 시 작업을 트리거할 수 있는 서비스를 지정하는 추가 구성 옵션이 있습니다.

catalog-services 조건으로 작업이 트리거되는 방법에 대한 자세한 내용은 작업 실행: 카탈로그 서비스 조건(Task Execution: Catalog Services Condition)을 참조하세요.

task {
  name        = "catalog_service_condition_task"
  description = "execute on service de/registrations with name matching 'web.*'"
  module      = "path/to/catalog-services-module"
  providers   = ["my-provider"]

  condition "catalog-services" {
    datacenter          = "dc1"
    namespace           = "default"
    regexp              = "web.*"
    use_as_module_input = true
    node_meta {
      key = "value"
    }
  }
}
매개변수 필수 유형 설명 기본값
regexp 필수 string 등록 및 등록 해제를 모니터링할 Consul 서비스의 이름을 일치시키는 정규 표현식입니다. 정규 표현식과 일치하는 이름을 가진 서비스만 작업이 사용합니다. 추가 정보는 정규 표현식 구문 문서와 정규 표현식 문자열 일치를 참조하세요. none
datacenter 선택 string 작업을 위해 쿼리할 데이터센터의 이름입니다. CTS가 쿼리하는 에이전트의 데이터센터
namespace 선택 string Enterprise 작업을 위해 쿼리할 서비스의 네임스페이스입니다. 우선 순위 순: 1. CTS ACL 토큰에서 추론 2. 기본 네임스페이스
node_meta 선택 map [string] 서비스를 필터링하는 데 사용할 노드 메타데이터 키/값 쌍입니다. 지정된 키/값 쌍이 있는 노드에 등록된 서비스만 작업이 사용합니다. none
source_includes_var 선택 boolean CTS 0.5.0에서 권장되지 않으며 0.8.0에서 제거될 예정입니다. 대신 use_as_module_input 필드를 참조하세요. true
use_as_module_input 선택 boolean 조건 객체의 값이 Terraform 모듈의 catalog_services 변수 입력으로도 사용되어야 하는지 여부입니다. 이 필드 구성 방법에 대한 지침은 선택한 모듈의 문서를 참조하세요. 모듈과 일치하지 않게 구성하면 CTS가 오류를 내고 종료합니다. true

Consul KV 조건 (Consul KV condition)

condition "consul-kv" 블록은 작업이 Consul KV 항목의 변경 시에만 실행되도록 구성합니다. 조건은 단일 Consul KV 항목 또는 주어진 경로를 접두사로 가지는 모든 Consul KV 항목에 대해 구성할 수 있습니다.

작업에 condition "consul-kv" 블록이 구성되면 작업을 module_input "consul-kv" 또는 source_input "consul-kv"(권장되지 않음) 블록으로 구성할 수 없습니다. 작업의 모니터링되는 consul-kv 정보는 하나의 구성 옵션으로만 설정할 수 있습니다. 작업에 필요한 consul-kv 모듈 입력은 조건 블록을 통해서만 구성해야 합니다.

consul-kv 조건으로 작업이 트리거되는 방법에 대한 자세한 내용은 작업 실행: Consul KV 조건(Task Execution: Consul KV Condition)을 참조하세요.

task {
  name        = "consul_kv_condition_task"
  description = "execute on changes to Consul KV entry"
  module      = "path/to/consul-kv-module"
  providers   = ["my-provider"]

  condition "consul-kv" {
    path                = "my-key"
    recurse             = false
    datacenter          = "dc1"
    namespace           = "default"
    use_as_module_input = true
  }
}
매개변수 필수 유형 설명 기본값
path 필수 string 작업이 사용하는 키의 경로입니다. 경로는 단일 Consul KV 항목 또는 경로 내의 여러 항목을 가리킬 수 있습니다. none
recurse 선택 boolean CTS가 경로를 접두사로 처리할 수 있게 합니다. false로 설정하면 경로가 리터럴 일치로 처리됩니다. false
datacenter 선택 string 작업을 위해 쿼리할 데이터센터의 이름입니다. CTS가 쿼리하는 에이전트의 데이터센터
namespace 선택 string Enterprise 작업을 위해 쿼리할 서비스의 네임스페이스입니다. 우선 순위 순: 1. CTS ACL 토큰에서 추론 2. 기본 네임스페이스
source_includes_var 선택 boolean CTS 0.5.0에서 권장되지 않으며 0.8.0에서 제거될 예정입니다. 대신 use_as_module_input 필드를 참조하세요. true
use_as_module_input 선택 boolean 조건 객체의 값이 Terraform 모듈의 consul_kv 변수 입력으로도 사용되어야 하는지 여부입니다. 이 필드 구성 방법에 대한 지침은 선택한 모듈의 문서를 참조하세요. 모듈과 일치하지 않게 구성하면 CTS가 오류를 내고 종료합니다. true

스케줄 조건 (Schedule condition)

예약 작업에는 작업 실행을 위한 스케줄을 정의하는 schedule 조건 블록이 있습니다. 동적 작업과 달리 예약 작업은 Consul의 변경 사항에 따라 동적으로 트리거되지 않습니다.

예약 작업은 또한 작업 모듈에 제공할 모듈 입력 정보를 결정하기 위해 조건 블록과 별개인 추가 작업 구성에 의존합니다. 모듈 입력 구성 방법에 대한 자세한 내용은 module_input 블록 구성을 참조하세요.

스케줄 조건으로 작업이 트리거되는 방법에 대한 자세한 내용은 작업 실행: 스케줄 조건(Task Execution: Schedule Condition)을 참조하세요.

예약 작업의 모듈 입력 옵션에 대한 자세한 내용은 Terraform 모듈: 모듈 입력(Terraform Module: Module Input)을 참조하세요.

task {
  name        = "scheduled_task"
  description = "execute every Monday using service information from web and db"
  module      = "path/to/module"

  condition "schedule" {
    cron = "* * * * Mon"
  }

  module_input "services" {
    names = ["web", "db"]
  }
}
매개변수 필수 유형 설명 기본값
cron 필수 string 작업을 트리거하는 스케줄을 결정하는 CRON 표현식입니다. CRON 표현식에 대한 자세한 내용은 cronexpr 파싱 라이브러리를 참조하세요. none

작업 모듈 입력 (Task Module Input)

참고 module_input은 CTS 0.5.0에서 source_input에서 이름이 바뀌었습니다. module_input 블록에 대한 문서는 source_input 블록에도 적용됩니다.

task 블록에 하나 이상의 module_input 블록을 선택적으로 추가할 수 있습니다. module_input 블록은 Terraform 모듈에 제공할 값 또는 메타데이터를 포함하는 Consul 객체를 지정합니다. 예약 작업과 동적 작업 모두 module_input 블록으로 구성할 수 있습니다.

아래 예시는 작업 구성 내의 module_input에 대한 개요를 보여줍니다.

task {
  name     = "task_a"
  module   = "path/to/module"
  services = ["api"] // (deprecated)

  condition "<condition-type>" {
    // ...
  }

  module_input "<input-type>" {
    // ...
  }
}

구성할 수 있는 module_input 블록의 유형은 조건 블록 유형과 services 필드(권장되지 않음)에 따라 달라집니다. 자세한 내용은 작업 모듈 입력 제한 사항을 참조하세요.

다음 섹션은 CTS가 지원하는 모듈 입력 유형을 설명합니다.

서비스 모듈 입력 (Services module input)

이 services 모듈 입력 객체는 Terraform 모듈에 services 모듈 입력으로 사용될 메타데이터를 가진 Consul에 등록된 서비스를 정의합니다. 다음 매개변수가 지원됩니다.

매개변수 필수 유형 설명 기본값
regexp names가 구성되지 않은 경우 필수 string 모니터링할 Consul 서비스의 이름을 일치시키는 정규 표현식입니다. 정규 표현식과 일치하는 이름을 가진 서비스만 작업이 사용합니다. 목록과 정규 표현식이 모두 필요하다면 목록을 정규 표현식의 일부로 포함하거나 별도의 작업을 만드는 것을 고려하세요. none
names regexp가 구성되지 않은 경우 필수 list [string] 모니터링할 Consul 서비스의 이름입니다. names에 이름이 나열된 서비스만 작업이 사용합니다. none
datacenter 선택 string 작업을 위해 쿼리할 데이터센터의 이름입니다. CTS가 쿼리하는 에이전트의 데이터센터
namespace 선택 string Enterprise 작업을 위해 쿼리할 서비스의 네임스페이스를 나타내는 String 값입니다. 우선 순위 순: 1. CTS ACL 토큰에서 추론 2. 기본 네임스페이스
filter 선택 string 모니터링할 서비스를 추가로 필터링하는 데 사용되는 표현식입니다. 추가 정보는 서비스 필터링 문서와 필터 표현식 작성 방법에 대한 섹션을 참조하세요. none
cts_user_defined_meta 선택 map [string] 호환되는 Terraform 모듈의 서비스 입력 변수에 추가되는 사용자 정의 메타데이터입니다. 일부 모듈은 구성된 메타데이터를 사용하지 않습니다. 메타데이터 사용과 예상 키 및 형식에 대한 정보는 작업을 위해 구성된 모듈을 참조하세요. none

다음 예시에서 예약 작업은 web을 접미사로 가진 모든 Consul 서비스를 쿼리합니다. 일치하는 서비스의 메타데이터가 Terraform 모듈에 제공됩니다.

task {
  name        = "schedule_condition_task"
  description = "execute every Monday using information from service names starting with web"
  module      = "path/to/module"

  condition "schedule" {
    cron = "* * * * Mon"
  }

  module_input "services" {
    regexp = "^web.*"
    datacenter = "dc1"
    namespace  = "default"
    filter     = "Service.Tags not contains \"prod\""
    cts_user_defined_meta {
      key = "value"
    }
  }
}

Consul KV 모듈 입력 (Consul KV module input)

consul-kv 모듈 입력 블록은 모니터링할 Consul KV 변경 사항을 정의합니다. 이러한 변경 사항은 Terraform 모듈에 consul-kv 모듈 입력으로 제공됩니다. 모듈 입력은 단일 Consul KV 항목 또는 주어진 경로를 접두사로 가지는 모든 Consul KV 항목에 대해 구성할 수 있습니다. 다음 매개변수가 지원됩니다.

매개변수 필수 유형 설명 기본값
path 필수 string 작업이 사용하는 키의 경로입니다. 경로는 단일 Consul KV 항목 또는 경로 내의 여러 항목을 가리킬 수 있습니다. none
recurse 선택 boolean CTS가 경로를 접두사로 처리할 수 있게 합니다. false로 설정하면 경로가 리터럴 일치로 처리됩니다. false
datacenter 선택 string 작업을 위해 쿼리할 데이터센터의 이름입니다. CTS가 쿼리하는 에이전트의 데이터센터
namespace 선택 string Enterprise 작업을 위해 쿼리할 서비스의 네임스페이스입니다. 우선 순위 순: 1. CTS ACL 토큰에서 추론 2. 기본 네임스페이스

다음 예시에서 예약 작업은 기본 네임스페이스의 dc1 데이터센터에서 my-key 키가 보유한 값의 변경 사항을 쿼리합니다.

task {
  name        = "schedule_condition_task_kv"
  description = "execute every Monday using information from Consul KV entry my-key"
  module      =  "path/to/module"

  condition "schedule" {
    cron = "* * * * Mon"
  }

  module_input "consul-kv" {
    path       = "my-key"
    recurse    = false
    datacenter = "dc1"
    namespace  = "default"
  }
}

작업 모듈 입력 제한 사항 (Task module input restrictions)

작업의 조건 블록과 services 필드(권장되지 않음)가 주어졌을 때 작업에 대해 구성할 수 있는 module_input 블록의 유형에는 몇 가지 제한이 있습니다. 이는 작업이 동일한 유형의 모니터링되는 변수를 정의하는 여러 구성을 가질 수 없기 때문입니다.

  • 작업을 동일한 유형의 조건과 module_input 블록으로 구성할 수 없습니다. 예를 들어 condition "consul-kv"와 module_input "consul-kv"를 구성하면 둘 다 consul_kv 변수를 구성하므로 오류가 발생합니다.
  • 작업을 두 개 이상의 동일한 유형의 module_input 블록으로 구성할 수 없습니다. 예를 들어 작업 내에서 두 개의 module_input "catalog-services"를 구성하면 catalog_services 변수에 대해 여러 구성을 정의하므로 오류가 반환됩니다.
  • 서비스를 모니터링하는 작업은 다음 구성 중 하나만 포함할 수 있습니다. condition "services" 블록, module_input "services" 블록(이전에는 source_input "services"(권장되지 않음)로 불림), services 필드(권장되지 않음). 나열된 모든 구성은 services 변수를 정의하므로 둘 이상을 포함하면 오류가 반환됩니다.

네트워크 드라이버 (Network drivers)

CTS가 네트워크 인프라 변경을 전파하려면 드라이버가 필요합니다. driver 블록은 CTS가 자동화에서 실행하는 하위 프로세스를 구성합니다. 기본 드라이버는 Terraform CLI의 로컬 설치로 Terraform을 자동화하는 Terraform 드라이버입니다.

CTS 배포당 하나의 네트워크 드라이버만 구성할 수 있습니다.

Terraform 드라이버 (Terraform driver)

driver "terraform" 블록은 Terraform을 로컬에 설치하고 자동화하도록 CTS를 구성하는 데 사용됩니다. 드라이버 블록은 상태 관리를 위해 사용되는 백엔드를 지정하는 Terraform 구성과 프로바이더 발견을 위해 사용되는 required_providers 구성을 지원합니다.

driver "terraform" {
  log         = false
  persist_log = false
  path        = ""

  backend "consul" {
    gzip = true
  }

  required_providers {
    myprovider = {
      source  = "namespace/myprovider"
      version = "1.3.0"
    }
  }
}
  • backend - (obj) 백엔드는 각 작업에 대한 Terraform 상태 파일을 저장합니다. 이 옵션은 Terraform 백엔드 구성과 유사합니다. CTS는 상태 저장소로 사용되는 Terraform 백엔드를 지원합니다. 지원되는 백엔드 옵션: azurerm, consul, cos, gcs, kubernetes, local, manta, pg(Terraform v0.14+), s3. 백엔드 구성 옵션에 대한 자세한 내용은 Terraform 문서 링크를 방문하세요. 생략하면 CTS가 기본값을 생성하고 consul 블록의 구성을 사용해 Consul을 백엔드로 구성하며, 이는 Consul KV에 Terraform 상태 파일을 저장합니다. Consul 인증을 위해 제공된 ACL 토큰은 KV 저장소에 읽고 쓰는 데 사용되며 Consul KV 권한이 필요합니다. Consul KV 경로는 작업의 상태 파일을 저장하는 기본 경로입니다. 각 상태 파일의 전체 경로는 경로 끝에 작업 식별자가 추가됩니다(예: consul-terraform-sync/terraform-env:task-name). 원격 강화 백엔드(remote enhanced backend)는 Terraform Cloud에서 작업을 실행하는 Terraform 드라이버에서 지원되지 않습니다. 원격 작업 공간과 원격 작업을 위해 CTS를 Terraform Cloud와 통합하려면 Terraform Cloud 드라이버를 사용하세요. local 백엔드 유형은 고가용성을 위해 구성된 CTS 인스턴스에서 지원되지 않습니다. 고가용성이 구성되고 Terraform 백엔드 유형이 local이면 CTS는 오류를 기록하고 종료합니다.
  • log - (bool) 모든 Terraform 출력(stderr 및 stdout)이 CTS 로그에 포함되도록 활성화합니다. 디버깅 및 개발 목적으로 유용합니다. 균일한 로그 형식을 기대하는 로그 집계기와 함께 사용하기 어려울 수 있습니다.
  • path - (string) Terraform을 설치하거나 기존 Terraform 바이너리를 발견할 파일 경로입니다. 생략하면 Terraform이 CTS 데몬과 같은 디렉터리에 설치됩니다. 호환되지 않는 Terraform 버전을 해결하거나 버전을 변경하려면 기존 바이너리를 제거하거나 다른 경로로 변경해야 합니다.
  • persist_log - (bool) 각 Terraform 클라이언트에 대해 작업별로 디스크에 trace 로깅을 활성화합니다. 이는 TF_LOG_PATH=<work_dir>/terraform.log를 설정하는 것과 같습니다. trace 로그 수준은 자세한 로깅을 생성하며 디버깅 및 개발 목적으로 유용할 수 있습니다. 프로덕션에서는 이를 활성화하는 것을 권장하지 않습니다. 로그 회전이 없어 파일이 빠르게 커질 수 있습니다.
  • required_providers - (obj: 필수) 모든 작업에 걸쳐 사용되는 각 Terraform 프로바이더를 선언합니다. 이는 각 프로바이더의 소스와 버전을 지정하도록 Terraform terraform.required_providers 필드를 구성하는 것과 동일하게 구성할 수 있습니다. CTS는 이 프로바이더를 사용하는 각 작업을 준비할 때 이러한 요구 사항을 처리합니다.
  • version - (string) 작업 실행을 위해 자동화에서 설치하고 실행할 Terraform 버전입니다. 생략하면 드라이버가 Terraform의 최신 호환 릴리스를 설치합니다. 버전을 변경하려면 기존 바이너리를 제거하거나 원하는 버전을 설치할 경로를 변경하세요. 원하는 Terraform 버전이 CTS 자동화에 사용되는 모든 Terraform 모듈에서 호환되는지 확인하세요.

Terraform Cloud 드라이버 (Terraform Cloud driver)

Enterprise

이 기능은 Consul Enterprise에서 사용할 수 있는 Consul-Terraform-Sync Enterprise가 필요합니다.

Terraform Cloud 드라이버는 CTS Enterprise가 자체 호스팅 배포와 관리형 서비스를 모두 포함하는 Terraform Cloud와 통합할 수 있게 합니다. 이 드라이버를 사용하면 CTS가 작업 공간에 대한 Terraform 실행(run)과 원격 작업을 자동화합니다.

Terraform Cloud로 활성화되는 기능의 개요는 네트워크 드라이버(Network Drivers) 문서에서 볼 수 있습니다.

CTS 배포당 하나의 네트워크 드라이버만 구성할 수 있습니다.

driver "terraform-cloud" {
  hostname     = "https://app.terraform.io"
  organization = "my-org"
  token        = "<TEAM_TOKEN>"
  // Optionally set the token to be securely queried from Vault instead of
  // written directly to the configuration file.
  // token = "{{ with secret \"secret/my/path\" }}{{ .Data.data.foo }}{{ end }}"

  workspaces {
    tags           = ["source:cts"]
    tags_allowlist = []
    tags_denylist  = []
  }

  required_providers {
    myprovider = {
      source  = "namespace/myprovider"
      version = "1.3.0"
    }
  }
}
  • hostname - (string) 연결할 Terraform Cloud 호스트 이름입니다. TFC_HOSTNAME 환경 변수로 재정의할 수 있습니다.
  • organization - (string) CTS가 관리하는 작업 공간을 호스팅하는 Terraform Cloud 조직입니다. TFC_ORGANIZATION 환경 변수로 재정의할 수 있습니다.
  • token - (string) Terraform Cloud 및 작업 공간 관리와 인증하는 데 사용되는 필수 팀 API 토큰입니다. CTS에는 작업 공간 권한만 필요합니다. 토큰은 TFC_TOKEN 환경 변수로도 제공할 수 있습니다. CTS의 자동화를 다른 Terraform Cloud 작업과 격리하려면 전용 팀과 팀 API 토큰을 만드는 것이 좋습니다.
  • workspace_prefix - (string) CTS 0.5.0에서 권장되지 않으며 대신 workspaces.prefix 옵션을 사용하세요. 자동화에 사용되는 자동 생성된 작업 공간 이름 앞에 추가할 접두사를 지정합니다. 이 접두사는 이 드라이버를 사용하는 모든 작업에 사용됩니다. 기본적으로 접두사가 구성되지 않으면 작업 공간 이름은 작업 이름입니다. 접두사가 구성되면 작업 공간 이름은 <workspace_prefix 값>-<task name>이며, 작업 공간 접두사와 작업 이름 사이에 - 문자가 있습니다. 예를 들어 접두사를 "cts"로 구성하면 "task-firewall"이라는 작업의 작업 공간 이름은 "cts-task-firewall"입니다.
  • workspaces — CTS의 Terraform Cloud 작업 공간 관리를 구성합니다.
    • prefix - (string) CTS 작업 자동화에 사용되는 작업 공간 이름 앞에 추가할 접두사를 지정합니다. 이 접두사는 이 드라이버를 사용하는 모든 작업에 사용됩니다. 기본적으로 접두사가 구성되지 않으면 작업 공간 이름은 작업 이름입니다. 접두사가 구성되면 작업 공간 이름은 <prefix><task name>입니다. 예를 들어 접두사를 "cts_"로 구성하면 "task_firewall"이라는 작업의 작업 공간 이름은 "cts_task_firewall"입니다.
    • tags - (list [string]) 작업 공간이 처음 생성되거나 발견될 때 CTS가 모든 자동화된 작업 공간에 추가할 태그입니다. 태그는 작업 공간이 자동화 요구 사항을 충족하고 허용 목록 및 거부 목록 태그 옵션을 충족하는 경우에만 발견된 작업 공간에 추가됩니다. 이 옵션은 기존 태그에 영향을 주지 않습니다. 런타임 중에 수동으로 제거된 태그는 CTS가 다시 시작될 때 다시 태그가 지정됩니다. Terraform Cloud 및 Terraform Enterprise v202108-1+와 호환.
    • tags_allowlist - (list [string]) CTS의 작업 공간 자동화 프로비저닝 검사로 사용할 태그 요구 사항입니다. 구성되면 Terraform Cloud 작업 공간이 CTS가 작업 공간과 실행을 자동화하려면 허용 목록의 태그 중 하나 이상을 가져야 합니다. Terraform Cloud 및 Terraform Enterprise v202108-1+와 호환.
    • tags_denylist - (list [string]) CTS의 작업 공간 자동화 프로비저닝 검사로 사용할 태그 제한입니다. 구성되면 Terraform Cloud 작업 공간이 CTS가 작업 공간과 실행을 자동화하지 않도록 거부 목록의 태그를 가져서는 안 됩니다. 거부된 태그는 tags_allowlist 옵션에 설정된 태그보다 우선순위가 높습니다. Terraform Cloud 및 Terraform Enterprise v202108-1+와 호환.
  • required_providers - (obj: 필수) 모든 작업에 걸쳐 사용되는 각 Terraform 프로바이더를 선언합니다. 이는 각 프로바이더의 소스와 버전을 지정하도록 Terraform terraform.required_providers 필드를 구성하는 것과 동일하게 구성할 수 있습니다. CTS는 이 프로바이더를 사용하는 각 작업을 준비할 때 이러한 요구 사항을 처리합니다.
  • tls — Terraform Enterprise에 대한 HTTPS 연결을 허용하도록 TLS를 구성합니다.
    • enabled - (bool) TLS를 활성화합니다. TLS 옵션 중 하나에 값을 제공하면 이 매개변수가 암시적으로 활성화됩니다.
    • ca_cert - (string) TLS를 통한 Terraform Enterprise 연결의 진위를 검증하는 데 사용되는 PEM 인코딩 인증 기관 파일의 경로입니다.
    • ca_path - (string) TLS를 통한 Terraform Enterprise 연결의 진위를 검증하는 데 사용되는 PEM 인코딩 인증 기관 파일 디렉터리의 경로입니다.
    • cert - (string) Terraform Enterprise가 CTS의 연결 진위를 검증할 수 있도록 TLS를 통해 Terraform Enterprise에 제공되는 PEM 인코딩 클라이언트 인증서 파일의 경로입니다.
    • key - (string) TLS를 통한 Terraform Enterprise와 통신하기 위해 cert가 구성한 클라이언트 인증서와 함께 사용되는 PEM 인코딩 프라이빗 키 파일의 경로입니다.
    • server_name - (string) TLS로 연결할 때 Terraform Enterprise의 SNI(Server Name Indication)로 사용할 서버 이름입니다.
    • verify - (bool: true) TLS 피어 검증을 활성화합니다. 기본값은 활성화되어 있으며, Terraform Enterprise가 반환한 인증서가 유효한지 확인하기 위해 전역 인증 기관(CA) 체인을 검사합니다. Terraform Enterprise가 전역 CA 체인에 추가하지 않은 자체 서명 인증서를 사용한다면 ca_cert 또는 ca_path로 이 인증서를 설정할 수 있습니다. 또는 verify를 false로 설정해 SSL 검증을 비활성화할 수 있습니다. 그러나 검증을 비활성화하는 것은 잠재적인 보안 취약점입니다.
    tls {
  verify = false
}

CTS는 작업 공간 실행에 사용되는 구성 버전을 준비하기 위해 로컬 아티팩트를 생성합니다. 생성된 파일의 위치는 working_dir 옵션으로 또는 작업별로 구성할 수 있습니다. 작업이 로컬 모듈로 구성되고 Terraform Cloud 드라이버로 실행될 때 로컬 모듈이 복사되어 구성 버전의 일부로 업로드됩니다.

각 작업 공간에 사용할 Terraform 버전도 작업 구성 내에서 설정할 수 있습니다.

Terraform 프로바이더 (Terraform provider)

terraform_provider 블록은 네트워크 인프라와 인터페이스하기 위한 옵션을 구성합니다. 모든 작업에 걸친 Terraform 모듈 세트가 필요로 하는 각 프로바이더에 대한 블록을 정의하세요. 이 블록은 Terraform 구성의 provider 블록과 유사합니다. 프로바이더 구성 방법에 대한 세부 정보를 찾으려면 Terraform 프로바이더의 해당 문서를 참조하세요. 공개적으로 사용 가능한 프로바이더의 주요 디렉터리는 Terraform Registry에서 호스팅됩니다.

아래 구성은 AWS Terraform 프로바이더를 예시로 사용해 프로바이더를 정의하는 일반적인 설계를 보여줍니다.

driver "terraform" {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "3.33.0"
    }
  }
}

terraform_provider "aws" {
  // Configuration options
  region = "us-east-1"
}

task {
  module    = "path/to/module"
  providers = ["aws"]
  condition "services" {
    names = ["web", "api"]
  }
}

참고 CTS 구성 파일에 구성된 프로바이더 인수는 프로바이더를 참조하는 각 Terraform 작업 공간에 대해 생성된 terraform.tfvars 파일에 일반 텍스트로 기록됩니다. 인수 또는 동적 값을 로컬 파일에 일반 텍스트로 렌더링하지 않으려면 동적 구성(dynamic configuration)과 함께 task_env를 사용하세요.

Terraform 프로바이더 안전하게 구성 (Securely configure Terraform providers)

terraform_provider 블록은 다른 소스에서 동적으로 인수와 로컬 환경을 로드하는 것을 지원합니다. 이는 셸 환경, Consul KV 또는 Vault에서 Terraform 프로바이더를 안전하게 구성하는 데 사용할 수 있습니다. 아래의 task_env 메타 인수와 템플릿 구문을 사용하면 CTS 구성 파일 내의 일반 텍스트로 민감한 값이나 자격 증명을 노출하지 않을 수 있습니다.

task_env와 동적 값에 대한 템플릿 구문은 terraform_provider 블록 내에서만 지원됩니다.

프로바이더 환경 변수 (Provider environment variables)

Terraform 프로바이더는 일부 인수의 값으로 셸 환경 변수를 지원할 수 있습니다. 사용 가능할 때 일반 텍스트 구성 파일에서 자격 증명을 보호하는 방법으로 환경 변수를 사용하는 것이 좋습니다. 프로바이더의 지원 환경 변수를 찾으려면 Terraform Registry에서 호스팅되는 공식 프로바이더 문서를 참조하세요. 기본적으로 CTS는 모든 Terraform 작업 공간이 자체 환경에서 상속하도록 활성화합니다.

task_env 블록은 terraform_provider 블록에 사용 가능한 메타 인수로, 사용 가능한 환경을 선택된 변수 집합으로 이름을 바꾸거나 범위를 지정하는 데 사용할 수 있습니다. 민감한 값을 환경 변수로 전달하면 값이 프로바이더가 필요한 작업에만 범위가 지정됩니다.

terraform_provider "foo" {
  // Direct assignment of provider arguments are rendered in plain-text within
  // the CTS configuration and the generated terraform.tfvars
  // file for the corresponding Terraform workspaces.
  // token = "<token value>"

  // Instead of configuring the token argument directly for the provider,
  // use the provider's supported environment variable for the token argument.
  // For example,
  // $ export FOO_TOKEN = "<token value>"

  // Dynamically assign the task's environment from the shell env, Consul KV,
  // Vault.
  task_env {
    "FOO_TOKEN" = "{{ env \"CTS_FOO_TOKEN\" }}"
  }
}

보안 경고 CTS는 민감한 값이 Terraform 상태 파일에 기록되는 것을 방지하지 않습니다. Terraform 프로바이더를 안전하게 구성하는 것에 더해 상태 파일을 보호하는 것이 좋습니다. 상태 파일 보호 옵션은 사용된 백엔드에 따라 driver.backend 내에서 설정할 수 있습니다. 예를 들어 Consul KV는 기본 백엔드이며 KV 경로에 대한 ACL로 보호할 수 있습니다. 다른 백엔드의 경우 해당되는 경우 암호화를 활성화하는 것이 좋습니다.

동적 값 로드 (Load dynamic values)

통합 템플릿 구문으로 Terraform 프로바이더에 대한 동적 값을 로드합니다.

Env

env는 CTS에 액세스할 수 있는 주어진 환경 변수를 읽습니다.

terraform_provider "example" {
  address = "{{ env \"EXAMPLE_HOSTNAME\" }}"
}
Consul

key는 필수 consul 블록에 구성된 Consul 서버의 KV 저장소에서 키의 값을 쿼리합니다.

terraform_provider "example" {
  value = "{{ key \"path/example/key\" }}"
}
Vault

with secret는 Vault KV 시크릿 엔진을 쿼리합니다. Vault는 운영자가 vault 블록으로 Vault 클라이언트를 구성하도록 요구하는 선택적 소스입니다. 템플릿 점 표기법 Data.data.<secret_key>를 사용해 시크릿에 액세스하세요.

vault {
  address = "vault.example.com"
}

terraform_provider "example" {
  token = "{{ with secret \"secret/my/path\" }}{{ .Data.data.foo }}{{ end }}"
}
Vault 구성 (Vault configuration)
  • address - (string) Vault 서버의 URI입니다. VAULT_ADDR 환경 변수로도 설정할 수 있습니다.
  • enabled - (bool) Vault 통합이 활성 상태인지 제어합니다.
  • namespace - (string) 시크릿을 읽는 데 사용할 Vault 네임스페이스입니다. VAULT_NAMESPACE 환경 변수로도 설정할 수 있습니다.
  • renew_token - (bool) Vault 토큰을 갱신합니다. VAULT_RENEW_TOKEN 환경 변수로도 설정할 수 있습니다.
  • tls - (tls 블록) Vault와 통신하는 동안 클라이언트가 보안 연결을 사용해야 함을 나타냅니다. 환경 변수: VAULT_CACERT, VAULT_CAPATH, VAULT_CLIENT_CERT, VAULT_CLIENT_KEY, VAULT_SKIP_VERIFY, VAULT_TLS_SERVER_NAME을 지원합니다.
  • token - (string) 요청을 위해 통신할 Vault 토큰입니다. 래핑된 토큰 또는 실제 토큰일 수 있습니다. VAULT_TOKEN 환경 변수 또는 VaultAgentTokenFile로도 설정할 수 있습니다.
  • vault_agent_token_file - (string) Vault Agent 토큰이 포함된 파일의 경로입니다. 지정되면 CTS가 Vault 토큰을 갱신하지 않습니다.
  • transport - (transport 블록) 저수준 네트워크 연결 세부 정보를 구성합니다.
  • unwrap_token - (bool) 제공된 Vault 토큰을 래핑된 토큰으로 언래핑합니다.

참고 Vault 자격 증명은 자동화된 Terraform 모듈을 포함한 작업과 관련 Terraform 구성에서 액세스할 수 없습니다. 작업이 Vault를 필요로 한다면 Vault 프로바이더를 별도로 구성하고 작업의 task.providers 목록에 명시적으로 포함해야 합니다.

여러 프로바이더 구성 (Multiple provider configurations)

CTS는 alias 메타 인수를 활용해 동일한 프로바이더에 대한 여러 구성을 정의하는 Terraform 기능을 지원합니다. 동일한 프로바이더 이름으로 여러 provider 블록을 정의하고 주어진 프로바이더에 걸쳐 alias를 고유한 값으로 설정하세요. task.provider 매개변수의 프로바이더 목록 내에서 프로바이더 이름과 별칭(<name>.<alias>)으로 구성을 지정해 작업에 사용할 프로바이더 구성을 선택하세요. 작업은 여러 프로바이더를 사용할 수 있지만 작업당 프로바이더의 인스턴스는 하나만 허용됩니다.

아래 CTS 구성 예시는 AWS 프로바이더의 다른 인스턴스로 동일한 모듈을 실행하는 두 개의 유사한 작업을 정의합니다.

terraform_provider "aws" {
  alias   = "a"
  profile = "team-a"
  task_env {
    "AWS_ACCESS_KEY_ID" = "{{ env \"CTS_AWS_ACCESS_KEY_ID_A\" }}"
  }
}

terraform_provider "aws" {
  alias   = "b"
  profile = "team-b"
  task_env {
    "AWS_ACCESS_KEY_ID" = "{{ env \"CTS_AWS_ACCESS_KEY_ID_B\" }}"
  }
}

terraform_provider "dns" {
  // ...
}

task {
  name      = "task-a"
  module    = "org/module"
  providers = ["aws.a", "dns"]
  // ...
}

task {
  name      = "task-b"
  module    = "org/module"
  providers = ["aws.b", "dns"]
  // ...
}

더 알아보기 (Learn more)