에이전트 하네스 연결 오류—서버 설정부터 해결까지 정리

새로 구축한 클라우드 서버에 에이전트 하네스를 설치했는데 연결이 끊겨 로그 수집이 멈춰 서비스 모니터링이 불가능한 상황이라면, 매우 당황스러우실 겁니다. 이러한 연결 두절은 대부분 서버 보안 그룹의 방화벽 규칙이나 DNS 설정 누락, 혹은 버전 호환성 문제 때문에 발생합니다. 특히 한국 기업 환경에서는 보안 정책이 엄격한 내부망이나 특정 클라우드 제공업체(CSP)의 네트워크 정책과 충돌하여 발생하는 cases가 많습니다. 이 글에서는 에이전트 하네스의 정확한 정의와 한국인 적용 가이드라인을 제시하며, 서버의 방화벽 포트부터 네트워크 설정, 그리고 버전 호환성까지 연결 오류를 해결하는 3가지 구체적 방법을 상세히 정리합니다. 단순한 오류 해결을 넘어, 안정적인 모니터링 환경을 구축하는 데 필요한 모든 과정을 다룹니다.

함께 보면 좋은 글: AI 프로젝트 지원 신청, 마감 2일 전이라면 체크리스

연결 끊김 증상과 원인 진단

새로운 서버 인스턴스에 에이전트를 배포한 직후, 대시보드에는 "연결 끊김" 상태가 지속되면서 실시간 메트릭 수집이 이루어지지 않는 것이 가장 전형적인 증상입니다. 이 경우 에이전트 프로세스는 서버 내에서 실행 중인 것처럼 보이지만, 실제로는 관리 서버로 향하는 송신 트래픽이 막혀 있어 "Handshake failed" 또는 "Connection timeout" 로그가 반복적으로 기록됩니다. 특히 한국 데이터 센터(AWS Seoul Region, NCP, NHN Cloud 등)를 사용할 경우, 해외에 비해 네트워크 경로상의 방화벽이 더 엄격하게 설정되어 있거나 보안 장비가 중간에 패킷을 깎아버리는 경우가 있어 초기 설정 단계에서 이 문제가 빈번하게 발생합니다.

원인을 정확히 파악하려면 에이전트가 실행 중인 서버의 로그 파일을 직접 확인해야 합니다. 리눅스 환경에서 주로 사용하는 systemd 기반의 에이전트는 journalctl -u harness-agent -f 명령어를 통해 실시간 로그를 모니터링할 수 있습니다. 로그 마지막 부분에 "Unable to resolve host" 메시지가 보인다면 DNS 문제일 가능성이 높고, "Connection refused"가 보인다면 방화벽에 의해 포트가 차단된 문제일 확률이 높습니다. 반면, 인증서 관련 에러가 발생한다면 시스템 시간 동기화 문제나 MTLS(Mutual TLS) 설정 오류를 의심해 볼 수 있습니다.

서드파티 모니터링 도구를 함께 사용 중이라면 네트워크 대기 시간(Latency)이 급격히 증가했거나 송신 패킷만 나가고 수신 패킷이 들어오지 않는 비대칭 트래픽 현상을 확인할 수 있습니다. 이는 에이전트가 하트비트(Heartbeat) 신호를 보내려 하지만 서버의 응답을 받지 못하고 있음을 의미합니다. 진단의 첫 단계는 에이전트가 설치된 서버에서 관리 서버로의 네트워크 연결이 물리적으로, 그리고 논리적으로 가능한지 확인하는 것입니다. 이를 위해 다음과 같은 단계별 진단 명령어를 사용하여 문제의 범위를 좁혀야 합니다.

# 1. 기본 연결 테스트 (HTTPS)
curl -v https://app.harness.io/grpc

# 2. 포트 개방 여부 테스트 (Telnet 활용)
telnet app.harness.io 443

# 3. Netcat을 이용한 빠른 포트 스캔
nc -zv app.harness.io 443

# 4. DNS 정상 해제 확인
dig app.harness.io

위 명령어 중 curl 명령어가 SSL handshake error를 반환한다면, 네트워크 경로 상의 방화벽이 SSL 트래픽을 제대로 통과시키지 못하거나 Deep Packet Inspection(DPI) 기능에 의해 트래픽이 변경되고 있을 수 있습니다. 이는 금융권이나 대기업 보안망에서 종종 발생하는 현상입니다. 만약 명령어 실행 결과 "Timeout"이 발생한다면 아예 경로가 막혀 있는 것이므로 보안 그룹 설정을 의심해야 하고, "Name or service not known"이 뜬다면 DNS 설정을 재점검해야 합니다.

Photo by panumas nikhomkhai on Pexels

해결책 1. 보안 그룹 및 방화벽 포트 설정

가장 흔한 원인은 클라우드 서버의 보안 그룹(Security Group)이나 온프레미스 방화벽에서 에이전트가 사용하는 포트를 차단하고 있기 때문입니다. 에이전트 하네스는 기본적으로 아웃바운드 트래픽을 위해 443번(HTTPS) 포트를 사용하지만, 특정 상황에서는 8080번이나 기타 커스텀 포트가 필요할 수 있습니다. AWS 서비스 콘솔의 "네트워크 및 보안" > "보안 그룹" 메뉴로 이동하여 해당 인스턴스에 할당된 보안 그룹의 아웃바운드 규칙을 확인해야 합니다.

아래 표는 일반적인 에이전트 연결에 필요한 포트 설정을 비교한 것입니다. 현재 설정이 "모든 트래픽 차단"으로 되어 있거나 특정 포트만 허용되어 있다면, 대상 IP(0.0.0.0/0)에 대해 443번 포트를 열어주는 작업이 필수적입니다. 특히 국내 클라우드 환경(NHN Cloud, KT Cloud 등)에서는 인바운드는 막아도 되지만, 아웃바운드는 제한적으로 열어두는 정책을 사용하므로 아웃바운드 규칙을 더 꼼꼼히 확인해야 합니다.

방화벽 설정을 변경할 때는 '최소 권한의 원칙(Principle of Least Privilege)'을 따르는 것이 좋습니다. 모든 아웃바운드(0.0.0.0/0)를 열어버리는 것은 보안상 위험할 수 있으므로, 가능하다면 Harness 서비스의 IP 대역만을 허용하는 방식을 권장합니다. 하지만 Harness는 클라우드 네이티브 특성상 IP가 동적으로 변경될 수 있으므로, 도메인 이름(app.harness.io 등)에 대한 접근만 허용하는 UTM(Unified Threat Management)이나 프록시 서버 설정이 대안이 될 수 있습니다.

만약 온프레미스 서버를 사용 중이라면 리눅스 내부 방화벽인 firewalld나 iptables 규칙도 확인해야 합니다. sudo iptables -L -v -n 명령어를 입력하여 OUTPUT 체인에 443번 포트에 대한 DROP 규칙이 없는지 확인하세요. 경우에 따라서는 보안 관리자의 승인 없이 방화벽을 열 수 없으므로, 에이전트 하네스의 통신이 보안 정책에 위배되지 않음을 증명하는 문서를 미리 준비하는 것이 좋습니다.

해결책 2. DNS 및 프록시 환경 변수 점검

보안 그룹 설정이 정상적임에도 불구하고 연결이 실패한다면, DNS 설정이나 프록시(Proxy) 환경이 원인일 수 있습니다. 특히 한국의 많은 기업들은 보안과 트래픽 효율을 위해 내부 프록시 서버를 경유하여 인터넷에 접속하도록 강제하는 경우가 많습니다. 이때 에이전트 하네스는 프록시 설정을 인식하지 못해 직접 외부로 연결을 시도하다가 실패하게 됩니다.

먼저 DNS 문제인지 확인하기 위해 ping app.harness.io 명령어를 실행해 봅니다. 만약 IP 주소가 반환되지 않는다면 /etc/resolv.conf 파일을 열어 네임서버 설정이 올바른지 확인해야 합니다. 클라우드 서버의 기본 DNS(예: AWS의 169.254.169.253 resolver)를 사용하는 것이 가장 안정적이지만, 사내 정책상 사설 DNS를 사용해야 한다면 해당 DNS 서버가 외부 도메인을 정상적으로 리졸브할 수 있는지 확인해야 합니다.

프록시 환경은 에이전트 실행 시 시스템 환경 변수 또는 에이전트 설정 파일에 주입해야 합니다. 리눅스 systemd 서비스를 통해 에이전트를 실행하는 경우, 서비스 파일(/etc/systemd/system/harness-agent.service) 내에 Environment 옵션을 추가하여 프록시 주소를 명시해야 합니다. 아래는 프록시 설정 예시입니다.

자주 묻는 질문

 에이전트 하네스 연결 오류 체크리스트


      ︎

      설정 파일 경로 확인 – /etc/agent_harness/agent_harness.conf 존재 여부 확인
    

      ︎

      서버 주소 및 포트 – server.host=127.0.0.1, server.port=5672 정확히 입력
    

      ︎

      방화벽 규칙 – iptables -L | grep 5672 로 포트 개방 확인
    

      ︎

      서비스 재시작 – systemctl restart agent_harness 실행 후 상태 확인 (systemctl status agent_harness)
    

      ︎

      로그 검증 – journalctl -u agent_harness -f 에서 “Connection established” 메시지 확인
    



Q. 에이전트 하네스란 정확히 무엇인가요?
A. 에이전트 하네스는 클라이언트와 서버 간 통신을 중계하고 관리하는 미들웨어로, 데이터 암호화·압축·로드밸런싱을 제공해 성능과 보안을 향상시킵니다.


Q. 연결 오류가 발생했을 때 가장 먼저 확인해야 할 설정은 무엇인가요?
A. 먼저 서버 IP와 포트가 올바른지, 방화벽 또는 보안 그룹이 해당 포트를 차단하고 있지 않은지 확인하고, 에이전트 하네스의 인증서와 키 파일이 일치하는지 검증합니다.


Q. 서버 방화벽에서 에이전트 하네스 포트를 허용하려면 어떻게 해야 하나요?
A. Linux에서는 `ufw allow <포트>/tcp` 혹은 `iptables -A INPUT -p tcp --dport <포트> -j ACCEPT` 명령을 사용하고, Windows 방화벽에서는 인바운드 규칙에 해당 포트를 추가하면 됩니다.


Q. 한국어 환경에서 에이전트 하네스를 사용할 때 주의할 점은 무엇인가요?
A. 한국어 로그와 메시지는 UTF-8 인코딩을 적용하고, 로케일 설정(`LANG=ko_KR.UTF-8`)을 지정해 문자 깨짐을 방지합니다. 또한, 한글 파일 경로가 포함된 설정 파일은 절대 경로로 명시하는 것이 안전합니다.