작업

작업 (Tasks)

Consul-Terraform-Sync(CTS)에서 작업은 Consul 카탈로그의 동적 서비스 정보를 네트워크 인프라 변경으로 변환하는 것을 뜻해요. 작업은 네트워크 드라이버를 사용해 자동화를 수행하며, Terraform 드라이버의 경우 작업 범위는 Terraform 모듈이에요.

출처: 문서

본문

작업은 Consul 카탈로그의 동적 서비스 정보를 다운스트림 네트워크 인프라 변경으로 변환하는 것입니다. Consul-Terraform-Sync(CTS)는 네트워크 드라이버를 사용해 작업을 실행하는 자동화를 수행합니다. Terraform 드라이버의 경우 작업 범위는 Terraform 모듈입니다.

다음은 작업 구성의 예시입니다.

task {
  name        = "frontend-firewall-policies"
  description = "Add firewall policy rules for frontend services"
  providers   = ["fake-firewall", "null"]
  module      = "example/firewall-policy/module"
  version     = "1.0.0"
  condition "services" {
    names = ["web", "image"]
  }
}

위의 예시 작업에서는 providers 필드에 나열된 fake-firewall과 null 프로바이더가 사용됩니다. 이 프로바이더들은 각각 별도의 terraform_provider 블록에서 구성해야 합니다. 이 프로바이더들은 module 필드에 구성된 Terraform 모듈 example/firewall-policy/module에서 리소스를 생성, 업데이트, 삭제하는 데 사용됩니다. 이 모듈은 프로바이더를 사용해 IP 주소를 기반으로 방화벽 정책 객체를 생성하고 삭제하는 작업을 수행할 수 있습니다. IP 주소는 condition "services" 블록에 구성된 web 및 image 서비스 인스턴스에서 가져옵니다. 이러한 서비스 수준 정보는 Consul 카탈로그의 변경 사항을 감시하는 CTS가 검색합니다.

작업 구성 방법에 대한 자세한 내용은 작업 구성을 참조하세요.

작업은 task CLI를 사용해 활성화하거나 비활성화할 수 있습니다. 활성화되면 작업은 아래 섹션에서 설명하는 대로 실행되고 자동화됩니다. 그러나 비활성화된 작업은 Consul 카탈로그에서 변경 사항이 감지되어도 실행되지 않습니다. 비활성화된 작업은 실행되지 않으므로 다시 활성화될 때까지 이벤트를 저장하지도 않습니다.

작업 실행 (Task Execution)

활성화된 작업은 서비스 변경(services 조건) 또는 서비스 등록·등록 해제(catalog-services 조건)와 같은 다양한 유형의 조건을 모니터링하고 실행하도록 구성할 수 있습니다.

작업은 작업의 모듈에 추가 정보를 제공하는 다른 변수를 모니터링하되 실행하지는 않을 수도 있습니다. 예를 들어 catalog-services 조건이 있는 작업은 등록 변경이 있을 때 실행되면서 추가로 서비스 인스턴스의 IP 정보를 모니터링할 수 있습니다.

구성된 모든 모니터링 정보는 실행에 사용되는지 여부와 관계없이 모듈 입력으로 작업의 모듈에 전달할 수 있습니다. 아래에는 CTS가 지원하는 실행 조건 유형과 해당 모듈 입력에 대한 세부 정보가 있습니다.

서비스 조건 (Services Condition)

services 조건이 있는 작업은 구성된 서비스 목록의 변경 사항 또는 주어진 정규 표현식(regex)과 일치하는 서비스의 변경 사항 중 하나를 모니터링하고 실행합니다.

services 조건으로 작업을 구성하는 방법은 두 가지입니다. 단일 작업에는 아래 두 옵션 중 하나만 구성할 수 있습니다.

• 작업의 services 필드(권장되지 않음, deprecated)를 구성해 작업을 트리거할 서비스 목록을 지정합니다.
• 작업의 condition 블록을 services 조건 유형으로 구성해 작업을 트리거할 서비스를 지정합니다.

services 조건은 건강 목록 노드 서비스 API(Health List Nodes For Service)를 모니터링하고 구성된 서비스에 대한 정보가 변경되면 작업을 실행하는 방식으로 동작합니다. 이러한 변경에는 IP 주소 같은 서비스 값의 변경, 서비스 인스턴스 추가 또는 제거, 태그 변경 등이 포함됩니다. 작업을 실행하게 만드는 값의 전체 목록은 아래에 정리되어 있습니다.

속성	설명
id	이 서비스의 고유한 Consul ID입니다. Consul 에이전트마다 고유합니다.
name	서비스의 논리적 이름입니다. 여러 서비스 인스턴스가 동일한 논리적 서비스 이름을 공유할 수 있습니다.
address	서비스 호스트의 IP 주소입니다. 비어 있다면 노드 주소를 사용해야 합니다.
port	서비스의 포트 번호입니다.
meta	서비스에 대한 사용자 정의 메타데이터 키/값 쌍 목록입니다.
tags	서비스에 대한 태그 목록입니다.
namespace	서비스 인스턴스의 Consul Enterprise 네임스페이스입니다.
status	건강 검사 목록을 집계한 서비스 인스턴스의 대표 상태입니다.
node	서비스가 등록된 Consul 노드의 이름입니다.
node_id	서비스가 등록된 노드의 ID입니다.
node_address	서비스가 등록된 Consul 노드의 IP 주소입니다.
node_datacenter	서비스가 등록된 Consul 노드의 데이터 센터입니다.
node_tagged_addresses	에이전트에 대한 명시적 LAN 및 WAN IP 주소 목록입니다.
node_meta	노드에 대한 사용자 정의 메타데이터 키/값 쌍 목록입니다.

다음은 정규 표현식과 일치하는 이름의 서비스가 변경될 때 실행되는 작업 구성의 예시입니다.

task {
  name        = "services_condition_task"
  description = "execute on changes to services whose name starts with web"
  providers   = ["my-provider"]
  module      = "path/to/services-condition-module"
  condition "services" {
    regexp              = "^web.*"
    use_as_module_input = false
  }
}

services 조건은 각 CTS 모듈에 필요한 services 입력 변수에 대한 입력을 제공할 수 있습니다. 이는 services 조건의 구성 방식에 따라 제공됩니다.

• 작업의 services 필드(권장되지 않음): services 객체가 자동으로 모듈 입력으로 전달됩니다.
• 작업의 condition "services" 블록: 사용자는 use_as_module_input 필드를 구성해 조건의 services 객체를 선택적으로 모듈 입력으로 사용할 수 있습니다. 이 필드는 이전에는 source_includes_var(권장되지 않음)로 불렸습니다.

카탈로그 서비스 조건 (Catalog-Services Condition)

catalog-services 조건이 있는 작업은 조건 구성에 부합하는 서비스에 대한 서비스 등록 변경 사항을 모니터링하고 실행합니다. '서비스 등록 변경'은 구체적으로 서비스 등록과 등록 해제를 의미하며, 서비스 등록은 첫 번째 서비스 인스턴스가 등록될 때, 서비스 등록 해제는 마지막 서비스 인스턴스가 등록 해제될 때 발생합니다. catalog-services 조건이 있는 작업은 모듈에 따라 추가로 서비스 인스턴스 정보를 모니터링하되 실행하지는 않을 수 있습니다.

catalog-services 조건은 카탈로그 목록 서비스 API(Catalog List Services)를 모니터링하고 등록된 서비스 목록에서 서비스가 추가되거나 제거될 때 작업을 실행하는 방식으로 동작합니다. 참고로 작업은 서비스 목록의 태그 변경에는 실행되지 않습니다. 이는 위에서 언급한 서비스 인스턴스 정보의 변경도 작업을 실행하지 않는 것과 유사합니다.

다음은 데이터센터 dc1에서 web.* 정규 표현식과 일치하는 이름의 서비스에 등록 변경이 있을 때 실행되는 작업 구성의 예시입니다. 또한 데이터센터 dc2에 있는 web-api의 서비스 인스턴스 변경은 추가로 모니터링하되 실행하지는 않습니다.

task {
  name      = "catalog_service_condition_task"
  module    = "path/to/catalog-services-module"
  providers = ["my-provider"]
  condition "catalog-services" {
    datacenter          = "dc1"
    regexp              = "web.*"
    use_as_module_input = false
  }
  module_input "services" {
    names      = ["web-api"]
    datacenter = "dc2"
  }
}

condition 블록의 use_as_module_input 필드를 사용하면 CTS가 catalog_services 입력 변수의 모듈 입력으로 조건의 객체를 사용하도록 구성할 수 있습니다. use_as_module_input 설정 방법은 구성된 모듈의 문서를 참조하세요.

자세한 내용과 추가 구성 옵션은 카탈로그 서비스 조건 구성 섹션을 참조하세요.

Consul KV 조건 (Consul KV Condition)

consul-kv 조건이 있는 작업은 조건 구성에 부합하는 KV 쌍에 대한 Consul KV 변경 사항을 모니터링하고 실행합니다. consul-kv 조건은 Consul KV API를 모니터링하고 구성된 KV 항목이 생성, 삭제 또는 업데이트될 때 작업을 실행하는 방식으로 동작합니다.

recurse 옵션에 따라 조건은 단일 Consul KV 쌍(주어진 경로 기준)을 모니터링하거나 해당 경로를 접두사로 가지는 모든 쌍을 모니터링합니다. 아래 예시에서는 recurse가 true로 설정되어 있으므로 path 옵션이 접두사로 처리됩니다. my-key 키와 my-key/another-key 키 항목의 변경이 모두 작업을 트리거합니다. recurse가 false로 설정되어 있다면 my-key의 변경만 작업을 트리거합니다.

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             = true
    datacenter          = "dc1"
    namespace           = "default"
    use_as_module_input = true
  }
}

condition 블록의 use_as_module_input 필드를 사용하면 CTS가 consul_kv 입력 변수의 모듈 입력으로 조건의 객체를 사용하도록 구성할 수 있습니다. use_as_module_input 설정 방법은 구성된 모듈의 문서를 참조하세요.

자세한 내용과 추가 구성 옵션은 Consul-KV 조건 구성 섹션을 참조하세요.

스케줄 조건 (Schedule Condition)

모든 예약 작업(scheduled task)은 스케줄 조건으로 구성해야 합니다. 스케줄 조건은 cron 구성으로 작업을 트리거하는 주기를 설정합니다. 스케줄 조건 블록은 모듈 입력을 구성하는 매개변수를 지원하지 않습니다. 따라서 입력을 별도로 구성해야 하며, module_input 블록을 구성해 모듈 입력을 정의할 수 있습니다.

다음은 스케줄 조건의 cron 구성으로 설정된 대로 매주 월요일마다 실행되는 작업 구성의 예시입니다. 모듈 입력은 module_input 블록으로 정의됩니다. 작업이 월요일에 트리거되면 Consul에서 web과 db에 대한 최신 정보를 가져와 모듈의 입력 변수에 제공합니다.

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"]
  }
}

다음은 모듈 입력 유형의 사용 가능한 옵션과 구성 방법입니다.

• 서비스 모듈 입력: task.services 필드(권장되지 않음) / module_input "services" 블록. 이 블록은 이전에 source_input "services"(권장되지 않음)로 불렸습니다.
• Consul KV 모듈 입력: module_input "consul-kv". 이 블록은 이전에 source_input "consul-kv"(권장되지 않음)로 불렸습니다.

실행 동작 (Running Behavior)

예약 작업은 일반적으로 스케줄에 따라 실행되지만, 다음 방식으로 CTS를 실행할 때 주문형(on-demand)으로 트리거할 수도 있습니다.

• 장기 실행 모드(Long-running mode): 장기 실행 모드가 시작될 때 CTS는 먼저 모든 작업이 한 번 실행되는 once 모드 단계를 거칩니다. 예약 작업은 이 once 모드 단계에서 한 번 트리거됩니다. 이 동작은 예약되지 않은 작업에도 적용됩니다. once 모드가 완료된 후 예약 작업은 이후 스케줄에 따라 트리거됩니다.
• 검사 모드(Inspect mode): 검사 모드에서 실행하면 터미널에 작업이 해당 시점에 트리거되었을 때 적용할 제안된 변경 사항의 계획(plan)이 출력된 후 종료됩니다. 이 모드에서는 변경 사항이 적용되지 않습니다. 예약 작업에 대한 출력 계획은 스케줄이 아니어도 해당 시점에 작업이 트리거되었을 때 적용될 제안된 업데이트입니다.
• Once 모드: once 모드에서는 모든 작업이 한 번만 트리거됩니다. 예약 작업은 스케줄에 없더라도 once 모드에서 실행됩니다.
• 활성화 CLI(Enable CLI): CLI를 통해 작업이 활성화되면 예약 작업을 포함한 모든 유형의 작업이 그 시점에 트리거됩니다.

버퍼 기간 (Buffer Period)

예약 작업은 구성된 주기에 따라 트리거되므로 예약 작업에는 버퍼 기간이 비활성화됩니다. 전역 수준 또는 작업 수준에서 구성된 모든 buffer_period는 예약되지 않은 동적 작업에만 적용되고 예약 작업에는 적용되지 않습니다.

이벤트 (Events)

작업이 실행될 때마다 이벤트가 저장됩니다. 예약 작업의 경우 Consul 카탈로그에 변경이 있는지 여부와 관계없이 작업이 스케줄에 따라 트리거될 때마다 이벤트가 저장됩니다.

작업 자동화 (Task Automation)

CTS는 시작 시 각 활성화된 작업을 한 번 실행하여 인프라를 Consul의 현재 상태와 동기화하려고 시도합니다. 데몬은 자동화 환경을 준비하거나 작업을 처음으로 실행하는 동안 오류가 발생하면 중지되고 종료됩니다. 이는 서비스 변경 사항이 시간이 지남에 따라 발견됨에 따라 데몬이 전체 자동화로 작업을 실행하기 전에 작업이 올바르게 구성되고 실행 가능한지 확인하는 데 도움이 됩니다. 결과적으로 처음부터 작업을 비활성화된 상태로 구성하는 것은 권장되지 않습니다. 모든 작업이 성공적으로 한 번 실행된 후에는 자동화 중 작업 실패가 기록되고 이후 변경 후 재시도되거나 다시 시도됩니다.

작업은 서비스 변경이 감지되면 거의 실시간으로 실행됩니다. 플래핑(flapping)이 발생하기 쉬운 서비스나 환경의 경우 버퍼 기간(buffer period)을 구성해 작업이 실행되기 전에 변경 사항을 축적하는 것이 유용할 수 있습니다. 버퍼 기간은 짧은 시간 동안 작업에 대한 변경 사항을 일괄 처리하여 인프라에 대한 연속적인 네트워크 호출 수를 줄입니다.

상태 정보 (Status Information)

상태 관련 정보는 상태 API(status API)를 통해 수집되고 제공되어 작업이 어떻게 실행되고 있는지 가시성을 제공합니다. 정보는 세 가지 수준(낮은 것에서 높은 것 순)으로 제공됩니다.

• 이벤트 데이터
• 작업 상태
• 전체 상태

이 세 수준은 계층을 형성하며 각 수준의 데이터가 다음 상위 수준에 정보를 제공합니다. 가장 낮은 수준인 이벤트 데이터는 네트워크 인프라를 업데이트하기 위해 작업이 실행될 때마다 수집됩니다. 이 이벤트 데이터는 집계되어 개별 작업 상태를 알리는 데 사용됩니다. 모든 작업 상태의 개수 분포는 전체 상태의 작업 요약을 알립니다.

이벤트 (Event)

작업이 트리거되면 CTS는 네트워크 인프라를 업데이트하기 위해 일련의 단계를 수행합니다. 이러한 단계는 작업의 모듈 입력에 대한 최신 데이터를 Consul에서 가져온 다음 그에 따라 네트워크 인프라를 업데이트하는 것으로 구성됩니다. 이벤트는 이 과정 전반에 걸친 정보를 포착합니다. 네트워크 인프라 업데이트가 성공했는지 여부와 발생한 오류를 이해하는 데 도움이 되는 정보를 저장합니다.

동적 작업은 Consul에서 변경으로 트리거될 때 이벤트를 저장합니다. 예약 작업은 Consul에 변경이 있는지 여부와 관계없이 스케줄에 따라 트리거될 때 이벤트를 저장합니다. 비활성화된 작업은 네트워크 인프라를 업데이트하지 않으므로 다시 활성화될 때까지 이벤트를 저장하지 않습니다.

샘플 이벤트:

{
  "id"         : "ef202675-502f-431f-b133-ed64d15b0e0e",
  "success"    : false,
  "start_time" : "2020-11-24T12:05:18.651231-05:00",
  "end_time"   : "2020-11-24T12:05:20.900115-05:00",
  "task_name"  : "task_b",
  "error"      : {
    "message" : "example error: error while doing terraform-apply"
  },
  ...
}

이벤트 구조에 대한 전체 정보는 API 문서의 이벤트를 참조하세요. 이벤트 정보는 작업 상태 API와 함께 include=events 매개변수를 사용해 검색할 수 있습니다.

작업 상태 (Task Status)

작업이 네트워크 인프라를 업데이트하기 위해 실행될 때마다 그 실행에 대한 이벤트 데이터가 저장됩니다. 각 작업에는 가장 최근 이벤트 5개가 저장되며, 이 저장된 이벤트를 사용해 작업 상태가 결정됩니다. 예를 들어 가장 최근에 저장된 이벤트가 성공하지 못했지만 나머지가 성공했다면 작업의 건강 상태는 errored입니다.

샘플 작업 상태:

{
  "task_name"  : "task_b",
  "status"     : "errored",
  "providers"  : ["null"],
  "services"   : ["web"],
  "events_url" : "/v1/status/tasks/task_b?include=events"
}

작업 상태 정보는 작업 상태 API로 검색할 수 있습니다. API 문서에는 어떤 건강 상태가 제공되는지와 이벤트의 성공/실패 정보를 기반으로 어떻게 계산되는지에 대한 세부 정보가 포함되어 있습니다.

전체 상태 (Overall Status)

전체 상태는 모든 작업에 걸친 건강 상태의 요약을 반환합니다. 이 요약은 각 건강 상태 범주에 속한 작업 수입니다.

샘플 전체 상태:

{
  "task_summary" : {
    "successful" : 28,
    "errored"    : 5,
    "critical"   : 1
  }
}

전체 상태 정보는 전체 상태 API로 검색할 수 있습니다. API 문서에는 어떤 건강 상태가 제공되는지와 작업 상태의 건강 상태 정보를 기반으로 어떻게 계산되는지에 대한 세부 정보가 포함되어 있습니다.

더 알아보기 (Learn more)

• Consul-Terraform-Sync(CTS) 참조
• CTS 작업 구성
• CTS 이벤트