Consul 에이전트 구성 파일 참조

Consul 에이전트 구성 파일 참조 (Consul Agents Configuration File Reference)

이 주제는 Consul 에이전트를 구성하는 매개변수를 설명해요.

출처: 문서

본문

이 주제는 Consul 에이전트를 구성하는 매개변수를 설명해요.

다음 사항에 대한 정보는 Consul 에이전트 구성 가이드를 참고해요:

구성 파일 위치
일반 구성 설정
리로드 가능한 구성
Consul 에이전트 시작 및 중지

개요 (Overview)

시작 시 Consul 에이전트를 구성하려면 하나 이상의 파일을 생성해요. ACL 매개변수 같은 유사한 구성을 별도의 파일로 그룹화해 구성 변경을 더 잘 관리할 것을 권장해요.

구성 파일을 HCL 또는 JSON로 작성해요. 사람과 컴퓨터 모두 JSON 구성 파일을 읽고 편집할 수 있어요. JSON 구성은 그 안에 여러 구성 키가 지정된 단일 JSON 객체로 구성돼요.

예시 구성 파일:

HCL:

datacenter = "east-aws"
data_dir = "/opt/consul"
log_level = "INFO"
node_name = "foobar"
server = true
watches = [
  {
    type = "checks"
    handler = "/usr/bin/health-check-handler.sh"
  }
]

telemetry {
  statsite_address = "127.0.0.1:2180"
}

JSON:

{
  "datacenter": "east-aws",
  "data_dir": "/opt/consul",
  "log_level": "INFO",
  "node_name": "foobar",
  "server": true,
  "watches": [
    {
      "type": "checks",
      "handler": "/usr/bin/health-check-handler.sh"
    }
  ],
  "telemetry": {
    "statsite_address": "127.0.0.1:2180"
  }
}

TTL 값 (Time-to-live values)

Consul은 Go time 패키지를 사용해 Consul 에이전트 구성 파일에 사용된 모든 time-to-live(TTL) 값을 파싱해요. 정수 및 부동 소수점 값을 문자열로 지정하고 다음 시간 단위 중 하나 이상을 포함해요:

예시:

추가 정보는 형식 지정 사양을 참고해요.

기간 형식 검증 (Duration formatting validation)

타임아웃 및 기간 값을 구성할 때 Consul은 형식을 검증하고 해당되는 곳에 최소 값을 적용해요. 잘못된 기간 문자열을 사용하면 에이전트가 시작에 실패하고 출력에 설명적인 오류 메시지가 포함돼요.

유효한 기간 형식 예시:

"10s" — 10초
"1.5m" — 1.5분, 90초(90s)와 동일
"2h30m45s" — 시, 분, 초가 있는 복합 기간
"0s" — 0 기간이지만 모든 필드가 이 값을 지원하는 것은 아님

오류를 생성하는 잘못된 형식 예시:

"10" — 단위 지정 누락
"10x" — 잘못된 단위, x는 인식되는 기간이 아님
"" — 빈 문자열
"abc" — 숫자가 아닌 문자열
"-5s" — 타임아웃 구성에 음수 기간은 허용되지 않음

일부 타임아웃 구성은 연결 문제나 보안 취약점을 방지하기 위해 최소 값을 적용해요. 예를 들어 핸드셰이크 타임아웃은 일반적으로 최소 1초를 요구해요. 구성된 값이 최소 값보다 낮으면 Consul은 시작 중에 검증 오류를 보고해요.

예시 (Examples)

다음 구성 예시는 서버 및 클라이언트 에이전트 구성 파일의 시나리오를 보여줘요.

암호화가 활성화된 서버 노드 (Server node with encryption enabled)

다음 예시는 암호화가 활성화된 서버 노드를 보여줘요. Consul의 보안 옵션을 구성하는 방법에 대한 추가 정보는 보안(Security) 챕터를 참고해요.

HCL:

node_name = "consul-server"
server = true
ui_config {
  enabled = true
}
data_dir = "consul/data"
addresses {
  http = "0.0.0.0"
}
retry_join = [
  "consul-server2",
  "consul-server3"
]
encrypt = "aPuGh+5UDskRAbkLaXRzFoSOcSM+5vAK+NEYOWHJH7w="

tls {
  defaults {
    verify_incoming = true
    verify_outgoing = true
    ca_file = "/consul/config/certs/consul-agent-ca.pem"
    cert_file = "/consul/config/certs/dc1-server-consul-0.pem"
    key_file = "/consul/config/certs/dc1-server-consul-0-key.pem"
    verify_server_hostname = true
  }
}

JSON:

{
  "node_name": "consul-server",
  "server": true,
  "ui_config": {
    "enabled": true
  },
  "data_dir": "consul/data",
  "addresses": {
    "http": "0.0.0.0"
  },
  "retry_join": ["consul-server1", "consul-server2"],
  "encrypt": "aPuGh+5UDskRAbkLaXRzFoSOcSM+5vAK+NEYOWHJH7w=",
  "tls": {
    "defaults": {
      "verify_incoming": true,
      "verify_outgoing": true,
      "ca_file": "/consul/config/certs/consul-agent-ca.pem",
      "cert_file": "/consul/config/certs/dc1-server-consul-0.pem",
      "key_file": "/consul/config/certs/dc1-server-consul-0-key.pem"
    },
    "internal_rpc": {
      "verify_server_hostname": true
    }
  }
}

서비스 메시의 서버 노드 (Server node in a service mesh)

다음 예시 구성은 "consul-server"라는 서버 에이전트를 위한 것이에요. 서버는 부트스트랩되고 Consul GUI가 활성화돼요. 이 서버 에이전트가 서비스 메시용으로 구성된 이유는 connect 구성이 활성화되어 있기 때문이에요. connect 하위 시스템은 서비스 간 연결 인가와 상호 전송 계층 보안(TLS)을 사용한 암호화를 포함한 Consul의 서비스 메시 기능을 제공해요. 애플리케이션은 서비스 메시 구성의 사이드카 프록시를 사용해 Consul 서비스 메시를 전혀 인지하지 않고 인바운드 및 아웃바운드 연결에 대한 TLS 연결을 수립할 수 있어요. 자세한 내용은 Consul 서비스 메시를 참고해요.

HCL:

node_name = "consul-server"
server    = true
bootstrap = true
ui_config {
  enabled = true
}
datacenter = "dc1"
data_dir   = "consul/data"
log_level  = "INFO"
addresses {
  http = "0.0.0.0"
}
connect {
  enabled = true
}

JSON:

{
  "node_name": "consul-server",
  "server": true,
  "bootstrap": true,
  "ui_config": {
    "enabled": true
  },
  "datacenter": "dc1",
  "data_dir": "consul/data",
  "log_level": "INFO",
  "addresses": {
    "http": "0.0.0.0"
  },
  "connect": {
    "enabled": true
  }
}

여러 인터페이스 또는 IP 주소를 가진 클라이언트 노드 (Client node with multiple interfaces or IP addresses)

다음 예시는 [go-sockaddr 템플릿]을 사용해 여러 인터페이스 또는 IP 주소에서 수신하도록 Consul을 구성하는 방법을 보여줘요.

bind_addr은 내부 RPC 및 Serf 통신에 사용돼요(자세한 내용은 에이전트 구성 읽기).

client_addr 구성은 HTTP, HTTPS, DNS 및 gRPC 서버에 사용되는 IP 주소를 지정해요. 자세한 내용은 에이전트 구성 읽기를 참고해요.

HCL:

node_name = "consul-client"
server    = false
bootstrap = true
ui_config {
  enabled = true
}
datacenter = "dc1"
data_dir   = "consul/data"
log_level  = "INFO"

# used for internal RPC and Serf
bind_addr = "0.0.0.0"

# Used for HTTP, HTTPS, DNS, and gRPC addresses.
# loopback is not included in GetPrivateInterfaces because it is not routable.
client_addr = "{{ GetPrivateInterfaces | exclude \"type\" \"ipv6\" | join \"address\" \" \" }} {{ GetAllInterfaces | include \"flags\" \"loopback\" | join \"address\" \" \" }}"

# advertises gossip and RPC interface to other nodes
advertise_addr = "{{ GetInterfaceIP \"en0\" }}"

JSON:

{
  "node_name": "consul-client",
  "server": false,
  "bootstrap": true,
  "ui_config": {
    "enabled": true
  },
  "datacenter": "dc1",
  "data_dir": "consul/data",
  "log_level": "INFO",
  "bind_addr": "{{ GetPrivateIP }}",
  "client_addr": "{{ GetPrivateInterfaces | exclude \"type\" \"ipv6\" | join \"address\" \" \" }} {{ GetAllInterfaces | include \"flags\" \"loopback\" | join \"address\" \" \" }}",
  "advertise_addr": "{{ GetInterfaceIP \"en0\"}}"
}

서비스를 등록하는 클라이언트 노드 (Client node registering a service)

중앙 서비스 레지스트리로 Consul을 사용하는 것은 일반적인 사용 사례예요. 다음 예시 구성은 Consul 에이전트에 서비스를 등록하고 헬스 체크를 활성화하는 일반적인 설정을 포함해요. 헬스 체크에 대해 더 알아보려면 헬스 체크 정의를 참고해요.

HCL:

node_name  = "consul-client"
server     = false
datacenter = "dc1"
data_dir   = "consul/data"
log_level  = "INFO"
retry_join = ["consul-server"]
service {
  id      = "dns"
  name    = "dns"
  tags    = ["primary"]
  address = "localhost"
  port    = 8600
  check {
    id       = "dns"
    name     = "Consul DNS TCP on port 8600"
    tcp      = "localhost:8600"
    interval = "10s"
    timeout  = "1s"
  }
}

JSON:

{
  "node_name": "consul-client",
  "server": false,
  "datacenter": "dc1",
  "data_dir": "consul/data",
  "log_level": "INFO",
  "retry_join": ["consul-server"],
  "service": {
    "id": "dns",
    "name": "dns",
    "tags": ["primary"],
    "address": "localhost",
    "port": 8600,
    "check": {
      "id": "dns",
      "name": "Consul DNS TCP on port 8600",
      "tcp": "localhost:8600",
      "interval": "10s",
      "timeout": "1s"
    }
  }
}

Consul 에이전트 구성 파일 참조