Consul 에이전트

Consul 에이전트 (Consul Agent)

Consul 에이전트는 노드에서 동작하는 장기 실행 데몬으로, Consul 운영의 핵심 단위예요. 이 문서에서 에이전트의 수명 주기, 요구 사항, 시작·중지 방법, 그리고 구성 방식을 자세히 설명할게요.

출처: 문서

본문

Consul 에이전트는 노드에서 동작하는 장기 실행 데몬입니다. Consul 운영의 핵심 단위입니다. 에이전트는 확장성이 뛰어나 어떤 인프라에도 Consul을 배포할 수 있게 해 줍니다.

에이전트는 서버 모드(server mode) 또는 클라이언트 모드(client mode) 로 실행할 수 있습니다. 서버 노드는 컨트롤 플레인의 서버 클러스터를 구성하며, 클러스터의 상태를 유지하는 역할을 담당합니다. 클라이언트 노드는 클러스터의 대부분을 구성하는 가벼운 프로세스입니다. 대부분의 작업을 서버 노드와 인터페이스하며 자체 상태는 거의 유지하지 않습니다. 클라이언트는 서비스가 실행되는 모든 노드에서 실행됩니다.

핵심 에이전트 작업 외에도 서버 노드는 합의 쿼럼 (consensus quorum)에 참여합니다. 쿼럼은 장애 상황에서 강력한 일관성과 가용성을 제공하는 Raft 프로토콜을 기반으로 합니다. 서버 노드는 클라이언트 노드보다 리소스를 많이 소모하므로 전용 인스턴스에서 실행해야 합니다.

에이전트 수명 주기 (Agent lifecycle)

다음 프로세스는 기존 클러스터의 맥락에서 에이전트 수명 주기를 설명합니다:

에이전트를 시작합니다. 수동으로 또는 자동화·프로그래밍 방식의 프로세스를 통해 시작합니다. 새로 시작된 에이전트는 클러스터의 다른 노드를 알지 못합니다.
에이전트가 클러스터에 조인합니다. 이를 통해 에이전트가 피어 에이전트를 발견할 수 있습니다. 에이전트는 시작 시 join 명령이 발행되거나 auto-join 구성에 따라 클러스터에 조인합니다.
에이전트가 전체 클러스터에 가십(gossip)합니다. 결과적으로 모든 노드는 결국 서로를 알게 됩니다.
기존 서버가 에이전트가 서버라면 새 노드에 복제를 시작합니다.

노드 장애와 충돌 (Node failures and crashes)

네트워크 장애가 발생하면 일부 노드는 다른 노드에 도달하지 못할 수 있습니다. 도달할 수 없는 노드는 failed 로 표시됩니다.

네트워크 장애와 에이전트 충돌을 구분하는 것은 불가능합니다. 결과적으로 에이전트 충돌은 네트워크 장애와 같은 방식으로 처리됩니다.

노드가 failed로 표시되면 이 정보가 서비스 카탈로그에 업데이트됩니다.

노드 종료 (Node exits)

노드가 클러스터를 정상적으로(gracefully) 종료하면 departure 알림을 보내고, 클러스터는 그 상태를 left로 표시합니다. 이 경우 클러스터는 그 노드와 연결된 모든 서비스를 즉시 등록 해제합니다. 이 동작은 일시적 중단을 허용하기 위해 서비스가 등록된 상태로 유지되는 노드 장애와는 다릅니다.

서버 에이전트가 떠나면 종료되는 서버로의 복제가 중지됩니다.

failed 또는 left 상태의 "죽은(dead)" 노드가 누적되는 것을 방지하기 위해 Consul은 카탈로그에서 죽은 노드를 자동으로 제거합니다. 이 프로세스를 reaping 이라고 합니다.

Reaping은 구성 가능한 72시간 간격으로 발생합니다. 중단 상황에서의 영향 때문에 reap 간격을 변경하는 것은 권장하지 않습니다. failed 노드의 경우 reaping은 노드의 모든 서비스를 등록 해제합니다.

에이전트 요구 사항 (Agent requirements)

서버 또는 호스트당 Consul 에이전트 하나를 실행해야 합니다. Consul 인스턴스는 별도의 VM에서 또는 별도의 컨테이너로 실행할 수 있습니다. Consul 배포마다 최소 하나의 서버 에이전트가 필요하지만, 3~5개의 서버 에이전트를 권장합니다.

인프라 요구 사항 (Infrastructure requirements)

호스트, 포트, 메모리 및 기타 인프라 요구 사항에 대한 정보는 다음 섹션을 참조하세요:

데이터센터 배포 튜토리얼에는 프로덕션 환경을 위한 추가 정보(라이선싱 구성, 환경 변수 등)가 있습니다.

최대 지연 시간 네트워크 요구 사항 (Maximum latency network requirements)

Consul은 가십 프로토콜을 사용해 에이전트 간 정보를 공유합니다. 제대로 작동하려면 프로토콜의 최대 지연 시간 임계값 을 초과할 수 없습니다. 지연 시간 임계값은 모든 에이전트 간 통신의 총 왕복 시간(RTT)에 따라 계산됩니다. 가십 외의 다른 네트워크 사용(클라이언트-서버 RPC, HTTP API 요청, xDS 프록시 구성, DNS 요청)은 이러한 지연 시간 요구 사항에 묶이지 않습니다.

모든 Consul 에이전트 간에 전송되는 데이터에 대해 네트워크가 다음 지연 시간 요구 사항을 충족해야 합니다:

모든 트래픽의 평균 RTT는 50ms를 초과할 수 없습니다.
트래픽의 99%에 대한 RTT는 100ms를 초과할 수 없습니다.

Consul 에이전트 시작 (Start the Consul agent)

consul 명령과 agent 하위 명령으로 다음 문법을 사용해 Consul 에이전트를 시작합니다:

$ consul agent <options>

Consul이 실행에 필요한 최소 정보는 에이전트 상태 데이터를 저장할 디렉터리의 위치입니다. -data-dir 플래그로 위치를 지정하거나, 외부 파일에 위치를 정의하고 -config-file 플래그로 파일을 가리킬 수 있습니다.

-config-dir 플래그로 여러 구성 파일이 들어 있는 디렉터리를 가리킬 수도 있습니다. 구성 디렉터리를 사용하면 구성 설정을 논리적으로 별도의 파일로 그룹화할 수 있습니다.

다음 예제는 개발자 모드로 에이전트를 시작하고 tmp/consul 디렉터리에 에이전트 상태 데이터를 저장합니다:

$ consul agent -data-dir=tmp/consul -dev

참고

프로덕션 환경에서는 개발자 모드를 사용하지 마세요.

에이전트 시작 출력 (Agent startup output)

Consul은 시작 시 몇 가지 중요한 메시지를 출력합니다. 다음 예제는 consul agent 명령의 출력을 보여줍니다:

$ consul agent -data-dir=/tmp/consul
==> Starting Consul agent...
==> Consul agent running!
       Node name: 'Armons-MacBook-Air'
      Datacenter: 'dc1'
          Server: false (bootstrap: false)
     Client Addr: 127.0.0.1 (HTTP: 8500, DNS: 8600)
    Cluster Addr: 192.168.1.43 (LAN: 8301, WAN: 8302)

==> Log data will now stream in as it occurs:

    [INFO] serf: EventMemberJoin: Armons-MacBook-Air.local 192.168.1.43
...

에이전트 출력은 다음 정보를 포함합니다:

Node name: 에이전트의 고유한 이름입니다. 기본적으로 이 필드는 머신의 호스트 이름이지만 -node 플래그로 사용자 지정할 수 있습니다.
Datacenter: 에이전트가 실행되도록 구성된 데이터센터입니다. 단일 DC 구성에서 에이전트는 기본적으로 dc1로 설정되지만, -datacenter 플래그로 에이전트가 보고하는 데이터센터를 구성할 수 있습니다. Consul은 여러 데이터센터가 있는 네트워크를 지원하므로 각 노드가 자체 데이터센터를 보고하도록 구성하면 에이전트 효율이 향상됩니다.
Server: 에이전트가 서버 모드로 실행 중인지 클라이언트 모드로 실행 중인지 나타냅니다. 서버 모드에서 에이전트를 실행하려면 합의 쿼럼 참여, 클러스터 상태 저장, 쿼리 처리 때문에 추가 리소스 오버헤드가 필요합니다. 서버는 또한 서버가 스스로 Raft 리더로 선출되도록 하는 "bootstrap" 모드일 수 있습니다. 여러 서버가 bootstrap 모드에 있으면 클러스터가 불일치 상태가 되므로 안 됩니다.
Client address: 클라이언트가 에이전트와 인터페이스하는 데 사용하는 주소로, HTTP·DNS 인터페이스 포트를 포함합니다. 기본적으로 이 주소는 localhost에만 바인딩됩니다. 이 주소나 포트를 변경하면 에이전트에 도달하는 방법을 나타내기 위해 consul members 같은 명령을 실행할 때마다 -http-addr을 지정하세요. 다른 애플리케이션도 HTTP 주소와 포트를 사용해 HTTP API로 Consul을 제어할 수 있습니다.
Cluster address: 클러스터의 Consul 에이전트 간 통신에 사용되는 주소와 포트 집합입니다. 클러스터의 모든 Consul 에이전트가 같은 포트를 사용할 필요는 없지만, 이 주소는 다른 모든 노드가 도달할 수 있어야 합니다 (MUST).

Linux에서 systemd 아래 실행할 때 LAN 조인이 완료되면 Consul은 $NOTIFY_SOCKET에 READY=1을 보냅니다. 이 알림을 보내려면 join 또는 retry_join 옵션을 설정하고 서비스 정의 파일에 Type=notify를 설정해야 합니다.

Consul 에이전트 중지 (Stop a Consul agent)

에이전트를 정상적으로(gracefully) 또는 강제로(forcefully) 중지하는 두 가지 방법이 있습니다. 서버·클라이언트 에이전트는 수행되는 leave에 따라 다르게 동작합니다. 시스템 신호가 전송된 후 프로세스가 있을 수 있는 상태는 left 와 failed 두 가지입니다.

에이전트를 정상적으로 중지하려면 터미널에서 Ctrl-C 같은 인터럽트 신호 를 프로세스에 보내거나 kill -INT consul_pid를 실행합니다.

서버가 정상적으로 종료되면 합의 쿼럼에 대한 영향을 최소화하기 위해 서버가 failed 로 표시됩니다. 클러스터에서 서버를 제거하려면 force-leave 명령을 사용합니다. force-leave를 사용하면 서버 에이전트가 살아있지 않은 한 서버 인스턴스가 left 상태가 됩니다.

클라이언트가 정상적으로 종료되면 에이전트는 먼저 클러스터에 클러스터를 떠나려 한다고 알립니다. 이렇게 하면 다른 클러스터 멤버가 노드가 left 되었음을 클러스터에 알립니다.

또는 에이전트에 kill -KILL consul_pid 신호를 보내 강제로 중지할 수 있습니다. 이 명령은 에이전트를 즉시 중지합니다. 클러스터의 나머지는 보통 몇 초 안에 노드가 죽었음을 감지합니다. 그런 다음 서버는 카탈로그를 업데이트해 노드가 failed 되었음을 표시합니다.

Consul 에이전트 구성 (Configure Consul agents)

Consul CLI의 consul agent 명령으로 Consul 에이전트를 구성하거나 에이전트 구성 파일에 정의할 수 있습니다. 다음 예제는 현재 작업 디렉터리에 있는 server.hcl이라는 파일에서 구성 설정을 가져오는 Consul 에이전트를 시작합니다:

$ consul agent -config-file=server.hcl

구성 우선순위는 다음 순서로 평가됩니다:

Consul 에이전트는 파일과 디렉터리의 구성을 어휘 순서로 로드합니다. 예를 들어 구성 파일 basic_config.json은 extra_config.json보다 먼저 처리됩니다. 구성은 HCL 또는 JSON 형식으로 정의할 수 있습니다.

나중에 지정된 구성은 먼저 지정된 구성에 병합됩니다. 대부분의 경우 "merge"는 이후 버전이 이전 버전을 재정의한다는 의미입니다. 이벤트 핸들러 같은 일부 경우에는 병합이 기존 구성에 핸들러를 추가합니다. 정확한 병합 동작은 각 옵션에 대해 지정됩니다.

Consul 에이전트는 SIGHUP 신호를 받으면 구성 재로드를 지원합니다. 그러나 모든 변경이 반영되는 것은 아닙니다. consul reload 명령을 사용해 구성 재로드를 트리거할 수 있습니다.

일반적인 구성 설정 (Common configuration settings)

Consul 에이전트를 구성하는 데 에이전트 구성 파일에서 흔히 사용하는 설정은 다음과 같습니다:

`consul.d` 구성 디렉터리 (The `consul.d` configuration directory)

에이전트 구성이 단일 파일에 포함되면 유지 관리가 어려워질 수 있습니다. 에이전트 구성의 서로 다른 블록을 /etc/consul.d 디렉터리의 여러 파일로 분리하는 것을 권장합니다. 새 구성을 추가하거나 기존 구성을 업데이트하면 에이전트가 재부팅된 후 Consul이 자동으로 에이전트 구성을 추가합니다. 업데이트가 ACL 토큰 같은 지원되는 재로드 가능 구성이라면 Consul은 재시작 없이도 변경을 등록하고 클러스터의 나머지에 전파할 수 있습니다.

구성 디렉터리 사용을 시작하려면 /etc/consul.d 디렉터리에 consul.hcl이라는 빈 파일을 만드세요. datacenter와 data_dir처럼 모든 노드에 있을 구성(예: datacenter 및 data_dir)을 추가하거나, 파일을 비워 두고 선호하는 구성 구조를 따를 수 있습니다.

재로드 가능 구성 (Reloadable configurations)

일부 에이전트 구성 옵션은 런타임에 재로드할 수 있습니다.

consul reload 명령으로 구성 디렉터리의 구성 파일에서 지원되는 옵션을 수동으로 재로드할 수 있습니다. 디스크에서 업데이트된 구성 파일을 자동으로 재로드하도록 에이전트를 구성하려면 auto_reload_config 구성 옵션 매개변수를 true로 설정하세요.

다음 에이전트 구성 옵션은 런타임에 재로드할 수 있습니다:

ACL 토큰
부트스트랩된 구성 항목
헬스 체크 정의
체크 출력 폐기 (Discard Check Output)
HTTP 클라이언트 주소
로그 수준
메트릭 접두사 필터 (Metric Prefix Filter)
노드 메타데이터 (Node Metadata)
일부 Raft 옵션:
RPC 속도 제한
리포팅 (Reporting)
클라이언트당 HTTP 최대 연결 수
서비스 정의
TLS 구성. 현재 이는 이미 TLS가 활성화된 구성을 재로드하는 것으로 제한된다는 점에 유의하세요. 재로드만으로는 TLS를 활성화하거나 비활성화할 수 없습니다. 잠재적인 보안 문제를 피하기 위해 다음 TLS 구성 매개변수는 -auto-reload-config가 활성화되어 있어도 자동으로 재로드되지 않습니다:
라이선스 (License)

다음 단계 (Next steps)

다음으로 Consul 서비스의 기본 (fundamentals of services in Consul)에 대해 알아보세요.