에이전트 연결과 프로세스 문제 해결

Agent Manager는 호스트에서 bootvisor라는 이름으로 나타납니다. 호스트의 설치 루트에서 var/diagnostic/launch.yml을 먼저 확인합니다. Foundry에 연결하지 못한 경우 enhancedMessage에 안내가 있을 수 있습니다. 이후 Agent Manager, Bootstrapper와 agent의 상태를 나누어 조사합니다.

호스트 명령은 SSH로 접속한 실제 에이전트 호스트에서, 해당 설치를 관리할 권한으로 실행합니다. 아래 AGENT_MANAGER_DIR는 문제를 조사하는 설치의 정확한 루트입니다.

인증서 만료와 교체 후 복구

Foundry 연결 인증서나 TLS 검사 프록시의 인증서가 만료 또는 교체되면 Agent Manager가 연결을 잃을 수 있습니다. 연결이 끊긴 Agent Manager는 새 설정을 내려받을 수 없으므로 Manage agent certificates만 바꾸어서는 복구되지 않습니다.

호스트의 로그에서 SSLHandshakeException, PKIX path building failed, CertificateExpiredException을 확인합니다. Foundry의 현재 CA는 Palantir 지원에서, 프록시의 현재 CA는 네트워크 관리자에게서 확보합니다. 서버가 여전히 만료된 인증서를 제시한다면 서버 관리자가 먼저 갱신해야 합니다.

Data Connection의 대상 에이전트에 현재 CA들을 각각 등록한 뒤 다음 중 한 방법을 사용합니다. 영향을 받은 에이전트마다 적용해야 합니다.

기존 Linux 설치의 truststore 복구

호스트와 Agent Manager truststore에 접근할 수 있을 때 사용하는 방법입니다. 기존 설치와 소스 암호화 키를 유지합니다.

1. 에이전트를 실행하는 사용자로 접속합니다.
2. 자동 재시작을 사용했다면 해제하고 Agent Manager를 중지합니다.
3. var/security/truststore.jks를 별도 파일로 백업합니다. 기존 백업을 덮어쓰지 않도록 경로를 확인합니다.

: "${AGENT_MANAGER_DIR:?대상 설치 루트를 설정하세요}"
"$AGENT_MANAGER_DIR/service/bin/auto_restart.sh" clear
"$AGENT_MANAGER_DIR/service/bin/init.sh" stop

4. 현재 CA마다 별도 PEM 파일을 준비하고, 번들 JDK의 keytool로 truststore에 가져옵니다. AGENT_JAVA_HOME, CA_CERT_FILE, CERT_ALIAS는 실제 경로와 미사용 alias입니다.

: "${AGENT_JAVA_HOME:?번들 JDK 디렉터리를 설정하세요}"
: "${CA_CERT_FILE:?현재 CA 인증서 파일을 설정하세요}"
: "${CERT_ALIAS:?미사용 인증서 alias를 설정하세요}"
"$AGENT_JAVA_HOME/bin/keytool" -importcert \
  -alias "$CERT_ALIAS" -file "$CA_CERT_FILE" \
  -keystore "$AGENT_MANAGER_DIR/var/security/truststore.jks"

기본 truststore 암호는 truststore입니다. 가져오기를 승인하기 전에 제공자가 확인한 인증서 지문과 대조합니다. 변경된 암호를 확보할 수 없다면 아래 재설치 경로를 사용합니다.

5. Agent Manager를 시작합니다.

"$AGENT_MANAGER_DIR/service/bin/init.sh" start

6. Data Connection에서 Agent Manager가 다시 연결되는지 확인합니다. Restart Agent로 UI에 등록한 인증서를 적용한 뒤 관리자와 agent가 모두 연결되는지 확인합니다.
7. 이전에 자동 재시작을 사용했다면 다시 활성화합니다.

현재 인증서를 포함한 재설치

로컬 truststore를 수정할 수 없다면 기존 에이전트 리소스에서 재설치합니다.

1. Data Connection에 현재 인증서를 추가합니다.
2. 기존 에이전트 Overview의 Reinstall the agent에서 새 다운로드 URL을 받습니다. 이전 패키지에는 이전 인증서가 남아 있습니다.
3. 기존 설치를 중지하고 재설치 절차를 따릅니다.
4. 기존 var/data/source-encryption-key와 var/data/source-encryption-key.private를 보존하여 새 설치에 복사합니다.
5. Agent Manager와 agent가 모두 연결되는지 확인합니다.

UI는 Offline인데 호스트 프로세스는 Running일 때

호스트에서 Foundry 진단 엔드포인트의 HTTP 연결을 확인합니다. 실제 HTTPS 기본 URL을 지정합니다.

: "${FOUNDRY_URL:?Foundry HTTPS 기본 URL을 설정하세요}"
curl --fail --silent --show-error --output /dev/null \
  "${FOUNDRY_URL%/}/magritte-coordinator/api/ping"

연결이 되면 프록시가 필요한지, 필요한 설정이 적용되었는지 확인합니다. Unix의 http_proxy 환경 변수도 설정 단서가 되지만 그것만으로 Agent Manager, Bootstrapper 및 원천 프록시가 모두 구성되었다고 판단하지 않습니다. 프록시별 적용 범위를 확인합니다.

Could not resolve host 같은 오류라면 DNS, 방화벽 또는 프록시 경로를 조사합니다. 연결과 프록시 설정이 올바른데도 보고되지 않으면 로그와 상태를 Palantir 지원에 전달합니다.

Agent Manager가 Offline일 때

설치 루트의 var/log/startup.log를 확인합니다. java.net.BindException: Address already in use이면 시작하려는 포트를 다른 프로세스가 사용하고 있습니다.

Agent Manager 포트는 var/conf/install.yml의 port입니다. 지정하지 않았을 때 기본값은 7032입니다. 실제 포트를 확인한 뒤 리스닝 프로세스를 조회합니다.

: "${PORT:?조사할 실제 포트를 설정하세요}"
lsof -nP -iTCP:"$PORT" -sTCP:LISTEN

필요하면 확인한 PID의 명령과 소유자를 조사합니다.

: "${PID:?앞에서 식별한 실제 PID를 설정하세요}"
ps -p "$PID" -o pid,user,args

com.palantir.magritte.bootvisor.BootvisorApplication이면 다른 Agent Manager 또는 이전 설치의 잔여 프로세스일 수 있습니다. 사용할 설치와 중지할 잔여 설치를 구분합니다. 한 호스트에서 여러 Foundry 에이전트를 운영하는 구성은 지원하지 않으므로 단순한 포트 변경으로 그런 구성을 만드는 것은 아닙니다.

다른 정당한 포트 사용과 충돌하여 변경해야 한다면 사용하지 않는 1025~65535 범위의 포트를 선택하고 var/conf/install.yml의 port를 수정합니다. auto-start-agent 같은 기존 설정은 유지합니다. 선택한 설치의 Agent Manager를 중지 후 시작하여 적용합니다.

: "${AGENT_MANAGER_DIR:?대상 설치 루트를 설정하세요}"
"$AGENT_MANAGER_DIR/service/bin/init.sh" stop
"$AGENT_MANAGER_DIR/service/bin/init.sh" start

Bootstrapper가 Never reported일 때

설치 루트의 var/data/processes 아래 현재 또는 가장 최근 Bootstrapper 디렉터리에서 var/log/startup.log를 확인합니다.

BindException이 있다면 Data Connection의 Advanced > Bootstrapper에서 구성된 포트를 확인합니다. 기본값은 7002입니다. 앞의 lsof 및 PID 확인 절차로 사용 중인 프로세스를 찾습니다. com.palantir.magritte.bootstrapper.MagritteBootstrapperApplication이면 다른 Bootstrapper 또는 잔여 프로세스인지 확인합니다.

새 포트가 필요하면 기존 Bootstrapper 설정의 server.adminConnectors에서 해당 포트를 수정합니다. 다른 연결 및 보안 설정을 지우지 않고 포트 값만 바꾼 뒤 저장하고 에이전트를 다시 시작합니다.

Online이지만 재시작에 반응하지 않을 때

오래된 에이전트 프로세스가 계속 보고하는 이른바 ghost 인스턴스일 수 있습니다. 수동으로 호스트에서 에이전트를 시작하면 이러한 프로세스가 생길 수 있습니다.

1. 대상 설치의 Agent Manager를 중지합니다.
2. 그 설치의 var/data/processes/index.json을 정확히 식별하여 삭제합니다. processes 전체를 삭제하는 단계가 아닙니다.
3. 해당 설치에 속한 이전 프로세스들을 중지합니다.

다음 명령은 지정한 설치의 프로세스 디렉터리에 있는 실행 스크립트만 호출합니다.

: "${AGENT_MANAGER_DIR:?대상 설치 루트를 설정하세요}"
for process_dir in "$AGENT_MANAGER_DIR"/var/data/processes/*/; do
  if [ -x "$process_dir/service/bin/init.sh" ]; then
    "$process_dir/service/bin/init.sh" stop
  fi
done

4. Data Connection에서 더 이상 보고되지 않는지 확인합니다. 반영에는 2~3분 걸릴 수 있습니다.
5. 선택한 Agent Manager 하나를 다시 시작합니다.

중지와 삭제의 범위를 다른 설치나 무관한 Java 프로세스로 넓히지 않습니다.

Unhealthy와 메모리 부족

Unhealthy는 프로세스 충돌이나 운영체제 또는 보안 소프트웨어에 의한 종료 등으로 발생할 수 있습니다. 가장 흔한 원인 중 하나는 호스트 메모리 부족입니다.

프로세스 로그의 exited with return code 137은 SIGKILL 종료의 단서입니다. 이 값만으로 반드시 OOM이라고 단정하지 말고, 운영체제 로그의 Out of memory 및 Killed process와 함께 확인합니다. Linux에서 커널 로그를 볼 때는 권한과 로그 보존 범위도 확인합니다.

dmesg -T

종료 시각과 PID 및 실행 명령이 실제 에이전트 프로세스와 일치하는지 확인합니다. Java heap 내부의 OutOfMemory 오류와 호스트 전체가 부족하여 프로세스를 강제 종료한 경우는 조치 방향이 다를 수 있습니다.

가용 메모리 평가

heap을 바꾸기 전에 에이전트를 중지하고, 호스트가 평소 또는 높은 부하를 받는 상태에서 가용 메모리를 확인합니다.

free -h

available 열은 새 애플리케이션에 사용할 수 있는 메모리의 기준입니다. free 명령의 버전에 이 열이 없으면 같은 의미의 값을 확인합니다. 다른 프로세스의 변동과 Java off-heap 메모리를 위해 가능하면 2~4 GB 정도의 여유를 남깁니다. 기본 에이전트 프로세스에 사용할 가용 메모리도 최소 4 GB는 확보하는 것이 권장됩니다. 신규 호스트 자체의 권장 메모리는 16 GB입니다.

프로세스별 기본 heap

기본 heap 합계는 약 3 GB이며 프로세스의 전체 메모리는 이것만으로 정해지지 않습니다. 호스트가 메모리 부족으로 프로세스를 종료한다면 heap을 줄이거나 호스트 메모리를 늘리는 방안을 검토합니다. heap을 줄이면 OS 종료 위험은 낮아질 수 있지만 Java 내부 heap 부족 위험은 커집니다. 기본값보다 작게 줄이는 것은 권장하지 않습니다.

동시 동기화 수, 파일 업로드 병렬성, 데이터 종류와 부하에 맞춰 조정합니다. Advanced > Bootstrapper에서 예를 들어 다음과 같이 agent heap을 설정할 수 있습니다. 3g는 변경 예시이며 기본값이 아닙니다.

agent:
  jvmHeapSize: 3g

저장 후 에이전트를 다시 시작해야 적용됩니다. 적절한 크기를 판단하기 어렵다면 실제 지표와 구성을 Palantir 지원에 전달합니다.

Windows의 heap 설정

Windows 설치는 launcher-custom.yml을 사용하지 않습니다. 별도로 설정하지 않으면 Java가 Agent Manager와 Bootstrapper 각각에 시스템 메모리의 25%를 할당할 수 있습니다.

1. 해당 설치의 Agent Manager, Bootstrapper, agent 및 Explorer를 모두 중지합니다.
2. 관리자 권한의 명령 프롬프트에서 AGENT_JAVA_HOME을 실제 번들 JDK 위치로 설정합니다.
3. 다음 시스템 환경 변수를 설정합니다.

setx -m JAVA_HOME "%AGENT_JAVA_HOME%"
setx -m MAGRITTE_BOOTVISOR_WIN_OPTS "-Xmx512M -Xms512M"
setx -m MAGRITTE_BOOTSTRAPPER_OPTS "-Xmx512M -Xms512M"

4. 명령 프롬프트를 닫고 새로 엽니다. 변경한 환경 변수는 기존 창에 자동 반영되지 않습니다.
5. 설치 루트에서 service\bin\magritte-bootvisor-win을 실행하여 Agent Manager를 시작합니다.

패키지를 내려받지 못할 때

Foundry에 접근할 수 있는데 잘못된 tar.gz 파일이나 다운로드 오류를 받으면 URL 만료 및 무효화를 확인합니다.

• 다운로드 링크는 10분 뒤 만료됩니다.
• 링크는 일회용 다운로드 비밀 정보로 보호됩니다. Microsoft Teams 같은 도구에 붙여 넣으면 링크 미리보기 검사가 먼저 접근하여 사용할 수 없게 만들 수 있습니다.
• 무효화되었다면 UI에서 새 링크를 만들고, 전체 링크를 다시 복사하는 대신 안내된 두 비밀 단어를 직접 입력하는 방식을 사용합니다.

다운로드가 disconnected unexpectedly로 끊기면 생성된 다운로드 cURL 명령에 --http1.0을 추가하여 프로토콜 협상 문제를 피할 수 있는지 확인합니다. 새 링크의 실제 다운로드 명령을 사용하고 오래된 토큰이나 주소를 재사용하지 않습니다.

생성은 했지만 관리할 수 없을 때

프로젝트 Editor는 그 프로젝트에 에이전트를 만들 수 있지만 관리에는 Owner 권한이 필요합니다. 따라서 생성한 뒤 다운로드 링크를 만들거나 관리 작업을 수행하지 못할 수 있습니다. 프로젝트 및 에이전트 역할을 확인합니다.

PERMISSION_DENIED로 생성이 막히면 조직 수준의 Create agent 권한과 프로젝트 Editor 또는 Owner를 모두 확인합니다. 다른 프로젝트로 바꾸는 것만으로 누락된 조직 권한이 생기지는 않습니다. 새 프로젝트가 속한 조직과 프로젝트 양쪽에서 필요한 권한이 있는 경우에만 해당 위치를 사용할 수 있습니다.

TLS 1.0과 TLS 1.1 원천

TLS 1.0과 TLS 1.1은 오래되고 안전하지 않아 Palantir가 지원하지 않는 프로토콜입니다. 에이전트의 Amazon Corretto OpenJDK는 java.security의 jdk.tls.disabledAlgorithms로 이 프로토콜을 기본적으로 비활성화합니다. 원천이 이전 TLS만 지원하면 The server selected protocol version TLS10 is not accepted by client preferences 같은 오류가 날 수 있습니다.

원천을 현대적인 TLS로 전환하는 것을 우선합니다. 조직이 위험을 승인한 긴급한 일시 호환이 필요할 때에는 Agent settings > Manage Configuration > Advanced > Bootstrapper에서 기존 agent 및 explorer 블록에 허용 프로토콜을 추가할 수 있습니다. 기존 TLS 1.2 연결을 끊지 않도록 그 값도 유지합니다.

agent:
  tlsProtocols:
    - TLSv1
    - TLSv1.1
    - TLSv1.2
explorer:
  tlsProtocols:
    - TLSv1
    - TLSv1.1
    - TLSv1.2

저장 후 Restart agent를 선택합니다. 이 구성은 업그레이드와 재시작 뒤에도 유지되므로 원천이 새 TLS로 전환되면 변경을 되돌립니다. 이전 프로토콜을 사용하는 보안 위험에 대해 Palantir가 책임을 지는 것은 아닙니다.

로그 설정과 중단 시각

Data Connection의 Agents에서 대상을 열고 Configuration의 Advanced에서 Logging 블록을 수정합니다. 로그를 언제 버릴지, 아카이브할지와 보관 수준은 호스트 자원 및 필요한 로그 상세 수준에 맞춥니다. 저장 후 Restart Agent로 적용합니다.

언제부터 사용할 수 없었는지는 Metrics의 uptime 및 availability 지표와 Overview의 상태 및 마지막 보고 시각을 함께 확인합니다. 재시작 중인지 호스트 자체가 중단되었는지도 구분합니다.

호스트가 중단된 뒤 캐시 파일

호스트가 중단되면 캐시 파일은 디스크에 남아 있다가 Bootvisor 정리 대상이 됩니다. 기본 정리 기준에는 30일 보존과 이전 프로세스 폴더 수가 있으며, 상세 경로와 최근 10개 비활성 폴더 유지 조건은 백업과 캐시에 있습니다.

이 임시 파일들은 암호화되어 있고 복호화 키는 종료된 프로세스의 메모리에만 있었으므로, 파일이 남아 있어도 그 메모리 키는 사라집니다. 재설치 및 이동에서 보존해야 하는 소스 인증 정보용 source-encryption-key 파일과 임시 데이터 캐시의 메모리 키는 구분해야 합니다.