에이전트 권한, 인증서와 운영 설정

Data Connection에서 에이전트의 권한, 연결 설정, 상태와 업그레이드 시간을 관리합니다. 호스트의 설치 파일에도 별도 설정이 있으므로 Agent Manager, Bootstrapper와 실제 에이전트의 설정 위치를 구분해야 합니다. 호스트에서 Agent Manager는 bootvisor라는 이름으로 나타납니다.

생성과 관리 권한

에이전트를 생성하려면 다음 두 조건을 모두 충족해야 합니다.

• 조직의 Organization administrator, Data flows administrator 또는 Create agent 워크플로가 포함된 사용자 지정 역할
• 저장할 프로젝트의 Editor 또는 Owner

조직 역할은 Control Panel의 Organization permissions에서 관리합니다. 생성 후에는 프로젝트 기반 역할이 에이전트 조회, 수정, 삭제와 소스 배정을 통제하므로 저장 위치의 권한을 검토합니다. 생성 권한만 있다고 다운로드 링크 생성 등 모든 관리 작업을 수행할 수 있는 것은 아닙니다.

2023년 5월 27일 이전에 구축한 플랫폼 인스턴스는 권한 관리 방식이 다를 수 있습니다. 이 환경에서 역할 기반 생성 권한을 엄격하게 적용하려면 Organization administrator에게 Change agent creation authentication method 워크플로를 추가하여 전환해야 합니다. 그 이후 구축한 환경은 이 방식이 자동 적용됩니다. 이전 환경의 적용 조건은 Palantir 지원과 확인합니다.

인증서

에이전트의 인증서 설정은 두 연결 방향을 구분합니다.

UI에서 인증서 추가

에이전트 상세 화면의 Manage agent certificates를 선택합니다. 필요한 인증서와 선택적 alias를 지정하고 실제 PEM 내용을 입력합니다.

PEM의 -----BEGIN CERTIFICATE-----와 -----END CERTIFICATE-----를 포함하고 내부 줄바꿈은 유지하되 마지막 줄 뒤의 추가 줄바꿈은 넣지 않습니다. 체인 전체를 한 항목에 넣을 수 없으므로 인증서를 각각 등록합니다.

수정 후 에이전트를 다시 시작해야 적용됩니다. 최초 설치 전에 추가하면 새 다운로드 번들에 포함됩니다. 개인 키를 사용하는 클라이언트 인증은 에이전트 워커의 mTLS 설정을 따릅니다.

Foundry 연결에 필요한 인증서

명시적 또는 투명 프록시가 TLS를 중간 검사하면 프록시 CA가 필요할 수 있습니다. 이 인증서가 없으면 에이전트가 Foundry에서 설정을 받아 올 수 없으므로 초기 번들을 내려받기 전에 추가합니다.

설치 시작 시 인증서 오류로 Foundry에 연결하지 못하면 설치 루트의 var/service.log를 확인합니다. 추가 CA가 필요하다는 사실을 미리 알았다면 설치 마법사에서 다운로드를 진행하지 말고, 에이전트 관리 화면에 인증서를 추가한 뒤 새 번들을 받습니다. 명시적 프록시는 인증서 외에 아래 프록시 설정도 필요할 수 있습니다.

사용자가 관리하는 Foundry 또는 프록시 인증서는 만료나 교체 전에 갱신합니다. 이미 Agent Manager가 연결을 잃었다면 UI에서 인증서를 바꾸는 것만으로 복구되지 않습니다. 로컬 truststore 복구 또는 재설치를 사용합니다.

원천 시스템의 인증서

에이전트 워커가 새 원천의 TLS 연결을 사용할 때 필요한 인증서를 등록하고, 만료 또는 교체 시 갱신합니다. 누락되면 탐색이나 동기화 중 다음과 같은 오류가 발생할 수 있습니다.

javax.net.ssl.SSLHandshakeException
PKIX path building failed
unable to find valid certification path to requested target

TLS 검사 환경의 첫 연결

Agent Manager가 처음부터 TLS 검사 프록시를 통과해야 한다면 호스트의 truststore에도 조직의 실제 CA가 필요합니다.

1. 네트워크 관리자가 제공한 현재 루트 CA를 확보합니다. 호스트의 openssl s_client -showcerts -connect 호스트:포트는 체인을 살펴보는 데 사용할 수 있지만, 관찰한 인증서를 확인 없이 신뢰하지 않습니다.
2. Agent Manager를 실행하는 사용자가 읽을 수 있는 위치에 CA 파일을 둡니다. 설치 루트의 var/security를 사용할 수 있습니다.
3. 번들 JDK의 keytool로 Agent Manager의 var/security/truststore.jks에 가져옵니다. 기본 암호는 truststore입니다.

다음 변수에는 실제 번들 JDK, 설치 루트, 인증서 파일과 미사용 alias를 지정합니다.

: "${AGENT_JAVA_HOME:?번들 JDK 디렉터리를 설정하세요}"
: "${AGENT_MANAGER_DIR:?Agent Manager 설치 루트를 설정하세요}"
: "${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"

가져오기를 승인하기 전에 지문을 제공자의 값과 대조합니다. Agent Manager를 시작한 뒤 UI에 Connected to Agent Manager, but no connection from agent가 보이면 관리자 연결만 복구된 상태입니다. Manage agent certificates에도 같은 CA를 추가하여 에이전트 연결에 적용하고 다시 시작합니다.

프록시 설정

프록시 호스트 값에는 http:// 접두사를 넣지 않습니다. 다음 세 설정은 적용 대상이 다릅니다. 예시 도메인과 포트는 가상 값이며 실제 승인된 프록시로 바꿉니다.

Agent Manager에서 Foundry로 연결

호스트의 var/conf/runtime.yml에서 기존 service-discovery > services > magritte-coordinator 설정을 유지하고 proxy-configuration을 추가합니다.

service-discovery:
  services:
    magritte-coordinator:
      proxy-configuration:
        hostAndPort: proxy.example.com:3128

프록시 인증이 필요하면 proxy-configuration.credentials 아래 username과 password를 설정합니다. 이 프록시는 Agent Manager가 Foundry의 magritte-coordinator에 연결할 때 사용하며 원천 연결에 적용되지 않습니다.

Bootstrapper에서 Foundry로 연결

Data Connection의 Agent settings > Manage Configuration > Advanced > Bootstrapper에서 다음 블록을 구성합니다.

coordinator:
  proxyConfiguration:
    host: proxy.example.com
    port: 3128

인증이 필요하면 proxyConfiguration.credentials.username과 password를 추가합니다. 저장한 뒤 에이전트를 다시 시작합니다. 이 설정도 Bootstrapper와 Foundry 사이의 연결에 사용하며 원천 연결과는 별개입니다.

에이전트에서 원천으로 연결

Bootstrapper 설정의 agent.jvmArguments에 JVM 프록시 인수를 지정할 수 있습니다. 값 자체를 따옴표로 감싸지 않습니다.

agent:
  jvmArguments: >-
    -Dhttp.nonProxyHosts=host1.example.com|*.host2.example.com
    -Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8000
    -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8001

http.nonProxyHosts에는 프록시를 거치지 않을 호스트를 |로 구분합니다. 이 설정은 개별 소스 하나가 아니라 에이전트의 JVM 프록시 설정에 해당합니다. 커넥터가 소스별 프록시를 제공하면 그 설정을 우선 사용하는 것이 권장됩니다.

지표와 상태 모니터링

에이전트 페이지의 Metrics에서 지표를 봅니다. 카드에 마우스를 올리면 시각별 값을 확인할 수 있고 오른쪽 위에서 상세 화면을 펼칠 수 있습니다.

인증서 만료 지표

만료 지표는 저장소 안에서 가장 이른 만료를 표시합니다. 일주일 뒤와 한 달 뒤에 만료되는 인증서가 함께 있다면 1w를 표시합니다. 이미 만료되면 000ms, 인증서가 없으면 빈 그래프가 나타납니다.

저장소에는 사용자가 추가한 인증서와 Agent Manager가 관리하는 인증서가 함께 있을 수 있습니다. Agent Manager의 인증서는 자동 업그레이드 대상이며 사용자 인증서는 직접 만료와 교체를 관리합니다.

버전 stale time

최신 여부는 다른 플랫폼 인스턴스의 버전이 아니라 현재 환경에서 제공되는 버전과 비교합니다. 최신 상태일 때는 0이며, 새 버전이 나온 뒤 업데이트하기 전까지 값이 늘어날 수 있습니다. 단순히 새 버전의 공개 이후 경과일만 표시하는 지표로 해석하지 않습니다.

이 예에서 경보 조건이 > 2이면 3일째 경보가 발생하고 4일째 업데이트 후 해소됩니다. 새 버전의 제공 간격이 허용 일수보다 길면, 새 버전이 나오자마자 아직 유지보수 기회가 없었던 에이전트에도 경보가 생길 수 있습니다.

상태 경보

Data Health에서 Monitoring view를 만들고 관련 사용자 그룹이 구독할 규칙을 모읍니다. Monitoring views에서 뷰를 선택한 뒤 Manage monitors로 규칙을 추가합니다. 지표의 조건과 임계값에 따라 낮음, 보통 또는 높음 심각도의 경보를 설정할 수 있습니다.

모니터를 PagerDuty 같은 외부 시스템과 연결하는 구성도 사용할 수 있습니다.

자동 업그레이드 시간대

에이전트마다 Agent settings > Maintenance Window에서 주간 반복 시간대를 설정합니다. Coordinator는 새 버전이 있으면 해당 시간대에 자동 업그레이드합니다.

업그레이드는 에이전트를 다시 시작하므로 진행 중인 작업을 종료하고 새 작업 시작도 잠시 막습니다. 시간대 길이는 최소 60분이어야 합니다. 실제 업그레이드는 대체로 에이전트 재시작과 비슷한 정도의 시간이 걸립니다.

가능하면 소스에 에이전트를 두 개 이상 배정하고 업그레이드 시간을 나눕니다. 예를 들어 한 대는 일요일, 다른 한 대는 수요일로 정하면 중단된 작업을 다른 에이전트에서 재시도하고 새 작업을 계속 처리할 수 있습니다. 각 에이전트는 전체 배정 부하를 처리할 용량이 있어야 합니다.

시간대를 나눌 수 없다면 작업이 적거나 없는 시간에 업그레이드합니다. 동기화가 시간대 시작 전에 끝나도록 하거나, 시간대가 끝난 뒤 몇 분의 여유를 두고 시작합니다. 끝 무렵에도 재시작이 발생할 수 있기 때문입니다.

재설치

오랫동안 업데이트하지 못했거나 Unhealthy 상태가 지속되면 기존 에이전트의 Overview에서 Reinstall the agent를 사용할 수 있습니다. 실행 중단과 키 보존을 준비한 뒤 새 설치 안내를 따릅니다.

1. 선택한 설치의 Agent Manager를 중지하고 자동 재시작을 해제합니다.
2. 같은 디렉터리에 다시 설치하려면 기존 설치를 정확히 지정한 별도 백업 위치로 보존합니다. 여러 설치를 한꺼번에 선택하는 와일드카드는 사용하지 않습니다.
3. 새 패키지를 내려받아 설치합니다.
4. 기존 인증 정보를 유지하려면 백업의 var/data/source-encryption-key와 var/data/source-encryption-key.private를 새 설치의 같은 위치로 복사합니다.
5. 연결과 작업 동작을 확인한 다음 해당 백업만 삭제하여 공간을 회수합니다.

중지 명령의 설치 루트는 실제 값을 지정합니다.

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

키를 보존할 때는 백업과 새 설치 경로를 각각 확인합니다. 필요한 두 키를 잃었거나 덮어썼다면 인증 정보를 복원할 수 있다고 가정하지 말고 소스에서 다시 입력해야 합니다.

: "${BACKUP_BOOTVISOR_DIR:?기존 키가 보존된 백업 설치 루트를 설정하세요}"
: "${NEW_BOOTVISOR_DIR:?새 설치 루트를 설정하세요}"
mkdir -p -- "$NEW_BOOTVISOR_DIR/var/data"
cp -- "$BACKUP_BOOTVISOR_DIR/var/data/source-encryption-key" \
  "$BACKUP_BOOTVISOR_DIR/var/data/source-encryption-key.private" \
  "$NEW_BOOTVISOR_DIR/var/data/"

같은 호스트의 다른 디렉터리로 이동

1. Syncs에서 Running 작업을 확인합니다. 완료를 기다리거나 소유자에게 알린 뒤 해당 빌드를 취소합니다.
2. 이동할 에이전트의 Advanced 각 탭에서 이동으로 위치가 바뀌는 절대 경로를 수정합니다. Kerberos 설정은 절대 경로가 필요합니다.
3. Foundry의 Restart Agent 옆 메뉴에서 Stop (Unsafe)를 선택합니다. Unsafe는 실행 중 작업이 중단된다는 경고입니다.
4. 호스트에 SSH로 접속하여 에이전트를 관리하는 사용자로 전환하고 대상 설치의 service/bin/init.sh stop을 실행합니다.
5. Linux의 자동 재시작을 해제하거나 Windows에서 구성한 예약 작업을 제거합니다.
6. 몇 분 기다린 뒤 해당 설치의 Java 프로세스가 모두 종료되었는지 확인합니다. 다른 설치나 무관한 Java 프로세스와 구분합니다.
7. 전송량을 줄이려면 중지된 설치의 var/data/binaries, var/data/cache, var/data/processes 내용을 선택적으로 정리할 수 있습니다. 소스 암호화 키를 포함한 var/data 전체를 지우지 않습니다.
8. 설치 디렉터리를 정확한 새 위치로 옮깁니다.
9. 새 위치에서 service/bin/init.sh start로 시작합니다.
10. 이전에 사용한 자동 재시작을 다시 활성화합니다.
11. 약 5분 뒤 Foundry에서 연결과 동기화 상태를 확인합니다.

새 호스트로 이동

새 호스트는 요구사항을 충족하고 기존과 같은 운영체제 계열 및 아키텍처를 사용해야 합니다. Linux/x86-64에서 다른 Linux 배포판의 x86-64로 옮길 수 있지만, 폴더 복사만으로 Linux에서 Windows 또는 ARM으로 옮길 수는 없습니다. 그런 변경에는 UI에서 새 다운로드 링크를 받아 새 설치를 진행합니다.

새 호스트에도 필요한 방화벽과 네트워크 경로를 구성합니다. 기존과 같은 네트워크 설정을 옮겼더라도 실제 발신 IP가 바뀌면 Foundry의 인바운드 허용도 확인해야 합니다. Direct 업로드를 쓰는 기존 에이전트는 호스트 IP 변경 제한이 있으므로 업로드 전략을 함께 검토합니다.

1. 앞의 디렉터리 이동 절차에서 작업 중단, 자동 재시작 해제와 프로세스 종료를 완료합니다. 절대 경로 변경은 복사 후에 적용합니다.
2. rsync 같은 전송 도구로 선택한 설치 폴더를 새 호스트에 복사합니다.
3. 소스 암호화 키 두 파일과 에이전트가 참조하는 추가 파일을 보존합니다.
4. 모든 절대 경로 참조가 새 호스트의 실제 위치를 가리키도록 수정합니다.
5. 새 호스트에서 시작하고 자동 재시작을 활성화한 뒤 연결과 동작을 확인합니다.

새 링크로 설치하면 이전 인증 정보가 자동 복호화되지 않습니다. 원래 키를 보존하지 못했다면 각 소스의 인증 정보를 다시 입력해야 합니다.

Windows 호스트

Linux를 우선 사용합니다. Linux 호스트나 Linux VM을 사용할 수 없을 때 Windows 설치를 선택합니다. Windows 에이전트 워커에서는 테이블 내보내기가 지원되지 않습니다.

다운로드 단계에서 Windows를 선택하여 설치한 뒤 Task Scheduler에서 Agent Manager의 자동 재시작 작업을 구성합니다.

저장 후 해당 작업을 오른쪽 클릭하여 Run으로 시작합니다. Agent Manager가 실행되면 작업은 Running 상태를 계속 유지합니다. Foundry 화면에 반영되기까지 1~2분 걸릴 수 있습니다. 시작하지 않으면 Task Scheduler의 History를 확인하거나 실제 설치 위치에서 배치 파일을 실행하여 오류를 확인합니다.

Windows의 기본 Java heap 비율과 수동 메모리 설정은 에이전트 문제 해결에 설명되어 있습니다.

백업과 캐시

설치, 업그레이드, 다운그레이드와 실행 중 이전 버전 및 캐시 파일이 남을 수 있습니다. 업데이트 후 교체된 버전이 디스크에 남아 있다는 사실만으로 그 코드가 현재 실행된다는 뜻은 아닙니다. 최신 보안 및 안정성 수정은 현재 버전에 적용됩니다.

일반 백업과 캐시는 보통 30일 뒤 자동 정리됩니다. 수동 정리는 유지보수 시간대 밖에서 수행하고 사용 중인 프로세스 및 플러그인과 구분합니다. 아래 경로는 모두 에이전트 설치 루트 기준입니다.

프로세스 디렉터리마다 service/bin/init.sh status를 실행하여 현재 사용 중인 디렉터리를 식별합니다. 실행 중인 것을 제외한 비활성 디렉터리만 정리 대상으로 선택합니다.

Host override

에이전트에 호스트 이름과 IP의 대응을 등록하면 일반 DNS 조회보다 우선하여 해석합니다. Unix의 /etc/hosts와 비슷한 역할이며 해당 에이전트의 모든 연결에 적용됩니다.

1. Data Connection의 Agents에서 대상 에이전트를 선택합니다.
2. Agent settings에 원하는 호스트 이름과 IP 대응을 추가합니다.
3. 저장한 뒤 에이전트를 다시 시작합니다.

예를 들어 사설 IP 10.0.0.1로만 접근할 수 있는 원천을 my-private-internal-database.local에 대응시킬 수 있습니다. 소스와 외부 통신 정책에는 호스트 이름을 사용하고, 에이전트가 사설 네트워크 안에서 IP로 해석합니다.

Foundry 내부에서 사설 IP로 직접 연결을 시작하면 내부 인프라 주소와 충돌할 수 있으므로, 이름을 해석할 수 없는 사설 IP 원천에는 이 방식이 필요합니다. localhost 또는 로컬 서비스 시험에도 사용할 수 있습니다. Host override는 에이전트 9.2446.0 이상이 필요하며 버전은 Overview에서 확인합니다.