Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

에이전트 워커의 실행과 인증 정보

Agent worker는 소스의 연결 기능을 에이전트 호스트에서 Java 작업으로 실행하는 방식입니다. Legacy 단계이며 추가 개발은 예정되어 있지 않지만 전체 지원은 유지됩니다. 새 소스와 기존 워크플로 개선에는 Foundry 워커를 권장합니다. 전환 절차와 운영 차이는 Foundry 워커와 에이전트 워커 비교에 있습니다.

소스 배정과 네트워크

에이전트를 설치한 뒤 소스의 워커 선택에서 Agent worker를 고르고 사용 가능한 에이전트를 하나 이상 배정합니다. 배치 동기화는 원천에서 데이터를 읽어 Foundry로 보내고, 내보내기는 Foundry에서 데이터를 읽어 외부로 보낼 수 있습니다.

네트워크는 에이전트 호스트에서 구성합니다. Foundry 쪽 외부 통신 정책을 추가하는 것만으로 에이전트 워커의 연결이 허용되는 것은 아닙니다. 호스트의 방화벽, DNS 및 프록시가 대상 시스템에 직접 연결할 수 있어야 합니다.

메모리와 동시 실행

에이전트의 JVM heap 기본값은 1 GB이며 시작 시 할당할 메모리를 에이전트 설정에서 지정합니다. 호스트의 가용 메모리를 초과해서는 안 되며 호스트 메모리는 최소 16 GB를 권장합니다.

OS physical memory 지표는 에이전트뿐 아니라 다른 프로세스와 네이티브 메모리까지 포함한 호스트 사용량입니다. Agent heap 지표는 설정한 JVM heap 범위 안의 사용량입니다. 에이전트 프로세스 전체의 물리 메모리가 항상 heap 크기 이하인 것은 아닙니다.

Maximum concurrent syncs의 기본값은 16입니다. 이름과 달리 모든 배정 소스의 모든 연결 기능에 공통으로 적용됩니다. 배치 및 스트리밍 동기화, CDC, 내보내기, 웹훅과 기존 Task의 실행 하나가 각각 동시 실행 슬롯 하나를 사용합니다. 한도에 도달하면 새 작업은 앞선 작업이 끝날 때까지 대기합니다.

여러 에이전트 배정

작업은 시작할 때 사용 가능한 배정 에이전트 중 하나에 무작위로 할당됩니다. 여러 에이전트를 배정하는 주된 목적은 유지보수 동안 다른 에이전트로 작업을 이어가는 것입니다.

한 대로 처리할 수 없는 큰 부하를 단순히 여러 대에 나누는 부하 분산 용도로 사용하는 것은 권장하지 않습니다. 각 에이전트가 배정된 소스의 전체 작업을 처리할 수 있도록 용량을 준비하는 것이 권장됩니다. 업그레이드 시간대도 서로 다르게 설정합니다.

배치 업로드 전략

Data proxy

현재 새 에이전트의 기본값이자 지원되는 업로드 전략입니다. 데이터셋 읽기 및 쓰기 API와 같은 게이트웨이의 data proxy 서비스를 사용합니다.

destinations:
  foundry:
    uploadStrategy:
      type: data-proxy

Direct 모드

Direct 업로드는 Sunset 단계입니다. 새 에이전트와 2024년 6월 이후 구축된 플랫폼 인스턴스에는 제공되지 않습니다. 이미 Direct를 사용하는 에이전트는 설치 호스트의 IP 주소가 바뀌지 않는 동안 계속 동작할 수 있습니다.

이 모드는 Foundry 데이터 카탈로그의 기반 저장소 버킷에 직접 업로드하며 Palantir 지원의 별도 네트워크 구성이 필요합니다. 최신 클라우드 인프라에서는 사용할 수 없습니다.

destinations:
  foundry:
    uploadStrategy:
      type: direct

호스트 이전이나 IP 변경을 계획할 때는 현재 업로드 전략도 확인합니다.

사용자 지정 JDBC 드라이버

에이전트 워커에서 쓸 사용자 지정 JDBC JAR은 Palantir 지원의 서명을 받고 에이전트에 직접 추가해야 합니다. 사용자 지정 JDBC 소스의 에이전트 워커 절차를 적용합니다. JAR의 의존성이 에이전트에 포함된 라이브러리와 충돌할 수 있습니다.

인증 정보의 암호화와 이동

Data Connection에서 입력한 인증 정보는 브라우저에서 배정된 각 에이전트의 공개 키로 암호화된 뒤 Foundry로 전송됩니다. Foundry에는 암호문이 저장되며 해당 에이전트가 자신의 개인 키로 필요한 시점에 메모리에서 복호화합니다. 저장 및 전송 중 암호화와 별개로, 복호화가 Foundry 밖의 에이전트 호스트에서 일어난다는 점이 이 방식의 특징입니다.

다음 변경에는 인증 정보 처리가 필요합니다.

  • 소스에 배정된 에이전트 집합을 바꾸면 인증 정보를 다시 입력합니다.
  • 새 다운로드 링크로 재설치한 에이전트에는 이전 암호화 키가 자동 이전되지 않습니다. 기존 키를 보존하여 복원하거나 모든 소스 인증 정보를 다시 입력해야 합니다.

디렉터리 및 호스트 이동에서 보존할 source-encryption-key와 source-encryption-key.private 파일은 공통 운영 설정에 설명되어 있습니다.

인증서와 mTLS 개인 키

에이전트는 Foundry와 원천 시스템의 인증서를 신뢰할 수 있어야 합니다. 서버 CA는 인증서 설정을 사용합니다. 원천이 상호 TLS(mTLS)를 요구하면 에이전트에 개인 키가 포함된 별도 keystore를 구성합니다.

기본 Bootstrapper keystore와 truststore는 재시작 때 다시 생성됩니다. 기본 파일을 직접 수정하면 변경이 사라지므로, 별도 위치에 복사한 사용자 지정 keystore를 가리키도록 설정합니다.

keystore 복사와 키 가져오기

에이전트를 실행하는 동일한 호스트 사용자로 작업합니다. 다음 변수에는 실제 경로를 지정합니다.

변수값
DEFAULT_KEYSTORE현재 Bootstrapper 작업 디렉터리의 var/conf/keyStore.jks
CUSTOM_KEYSTORE_DIR사용자 지정 keystore를 보관할 별도 디렉터리
CUSTOMER_KEYSTORE원천 연결에 사용할 개인 키가 들어 있는 고객 keystore
AGENT_JAVA_HOME에이전트에 포함된 실제 JDK 디렉터리
KEY_ALIAS가져온 개인 키의 실제 alias

기존 사용자 지정 keystore가 있다면 복사로 덮어쓰지 않도록 먼저 보존합니다.

: "${DEFAULT_KEYSTORE:?현재 Bootstrapper keystore 경로를 설정하세요}"
: "${CUSTOM_KEYSTORE_DIR:?사용자 지정 keystore 디렉터리를 설정하세요}"
mkdir -p -- "$CUSTOM_KEYSTORE_DIR"
cp -- "$DEFAULT_KEYSTORE" "$CUSTOM_KEYSTORE_DIR/keyStore.jks"

다음 명령은 목적지와 원본 keystore 암호를 대화형으로 묻습니다. 복사한 기본 목적지 keystore의 기본 암호는 keystore입니다.

: "${AGENT_JAVA_HOME:?번들 JDK 디렉터리를 설정하세요}"
: "${CUSTOMER_KEYSTORE:?원본 개인 키 keystore 경로를 설정하세요}"
"$AGENT_JAVA_HOME/bin/keytool" -importkeystore \
  -srckeystore "$CUSTOMER_KEYSTORE" \
  -destkeystore "$CUSTOM_KEYSTORE_DIR/keyStore.jks"

keytool -list로 실제 alias와 PrivateKeyEntry를 확인하고, 인증서 지문을 신뢰할 수 있는 값과 대조합니다.

"$AGENT_JAVA_HOME/bin/keytool" -list \
  -keystore "$CUSTOM_KEYSTORE_DIR/keyStore.jks"

가져온 개인 키의 암호는 keystore 암호와 같아야 합니다. 다음 명령의 대화형 입력에서 같은 값으로 설정합니다.

: "${KEY_ALIAS:?가져온 개인 키 alias를 설정하세요}"
"$AGENT_JAVA_HOME/bin/keytool" -keypasswd -alias "$KEY_ALIAS" \
  -keystore "$CUSTOM_KEYSTORE_DIR/keyStore.jks"

Agent와 Explorer에 경로 지정

Data Connection의 Agent settings > Manage Configuration > Advanced에서 Agent 탭을 엽니다. 기존 설정을 유지하면서 security.keyStore와 keyStorePassword를 사용자 지정 값으로 바꿉니다. 다음 경로는 가상 예시입니다.

security:
  keyStore: /home/agent/security/keyStore.jks
  keyStorePassword: keystore
  trustStore: var/conf/trustStore.jks

Explorer 탭에서는 경로 필드 이름이 keyStorePath입니다. keyStorePassword도 같은 값으로 설정합니다.

security:
  keyStorePath: /home/agent/security/keyStore.jks
  keyStorePassword: keystore
  trustStorePath: var/conf/trustStore.jks

Bootstrapper 설정은 변경하지 않습니다. 저장한 뒤 에이전트를 다시 시작해야 적용됩니다.

실행 방식의 제한

에이전트의 작업들은 메모리와 디스크를 공유합니다. 한 작업이 자원을 많이 사용하면 다른 작업이 시작하지 못하거나 실패할 수 있습니다. 긴 동기화가 짧은 웹훅을 막지 않도록 에이전트 워커 웹훅에는 전용 에이전트를 두는 것이 강하게 권장됩니다.

코드에서 소스 사용, 가상 테이블과 가상 미디어는 에이전트 워커와 호환되지 않습니다. 이러한 기능은 Foundry에서 동기적으로 연결하는 경로가 필요하며 에이전트의 작업으로 실행할 수 없습니다.