외부 Iceberg 클라이언트의 네트워크 접근

외부 클라이언트는 Foundry Iceberg REST 카탈로그와 실제 저장소 버킷 양쪽에 도달할 수 있어야 합니다. 카탈로그 인증이 성공해도 저장소 연결이 차단되어 있으면 실제 파일을 읽거나 쓸 수 없습니다.

카탈로그 응답의 인라인 메타데이터는 버킷을 호출하지 않고 받을 수 있습니다. 인라인 JSON을 읽는 것과 저장소에 있는 메타데이터 파일을 가져오는 작업을 구분합니다.

카탈로그 인바운드

일반 Foundry API와 같은 애플리케이션 계층의 인바운드 규칙을 사용합니다. Control Panel에서 외부 클라이언트의 발신 네트워크가 Foundry 기본 도메인에 접근하도록 허용합니다. 인증은 API 토큰 또는 OAuth2로 별도 구성합니다.

저장소 위치 찾기

카탈로그의 테이블 메타데이터에서 location을 읽으면 기반 저장소를 확인할 수 있습니다. Dataset Preview의 Details > Metadata file에 표시되는 JSON에서도 같은 값을 찾을 수 있습니다.

이름 공간은 식별자에서 점으로 구분하지만 REST URL에서는 각 수준을 unit separator인 %1F로 구분합니다. 예를 들어 Namespace.Project.Folder는 URL에서 Namespace%1FProject%1FFolder가 됩니다. 개별 이름 자체에 점이 있으면 수준 목록을 별도로 전달하여 구분합니다.

다음은 Bash, cURL과 jq를 사용하는 조회입니다. 필요한 값은 다음과 같습니다.

인증 헤더 파일은 소유자만 읽을 수 있게 보호하고 코드 저장소에 넣지 않습니다.

set -euo pipefail
set +x
: "${FOUNDRY_URL:?Foundry HTTPS 기본 URL을 설정하세요}"
: "${AUTH_HEADER_FILE:?보호된 인증 헤더 파일을 설정하세요}"
: "${NAMESPACE_JSON:?이름 공간 수준의 JSON 배열을 설정하세요}"
: "${TABLE_NAME:?테이블 이름을 설정하세요}"

BASE_URL="${FOUNDRY_URL%/}"
NAMESPACE_PATH="$(printf '%s' "$NAMESPACE_JSON" | jq -er 'join("\u001f") | @uri')"
TABLE_PATH="$(printf '%s' "$TABLE_NAME" | jq -sRr @uri)"
TABLE_URL="$BASE_URL/iceberg/v1/namespaces/$NAMESPACE_PATH/tables/$TABLE_PATH"

curl --silent --show-error --fail-with-body \
  --header "@$AUTH_HEADER_FILE" "$TABLE_URL" |
  jq -er '.metadata.location'

S3 위치는 s3://버킷/경로 형태이며 ABFS 및 GCS도 해당 저장소 URI를 반환합니다. Azure에서는 컨테이너와 저장소 계정을 함께 식별합니다. 저장소가 여러 개이면 연결할 각 버킷의 테이블 하나씩 조회합니다.

버킷의 네트워크 허용

Foundry 관리 저장소라면 Palantir 지원에 외부 트래픽 허용을 요청합니다. 필요한 정보는 Foundry 호스트 이름, 확인한 저장소 버킷 이름, 외부 클라이언트의 발신 IPv4 주소 또는 VPC endpoint 식별자입니다.

BYOB라면 고객 클라우드 계정의 버킷 또는 저장소 계정 네트워크 정책에서 외부 클라이언트를 허용합니다. Source가 Foundry에서 버킷으로 연결할 수 있다는 사실만으로 외부 노트북이나 Snowflake에서도 연결할 수 있는 것은 아닙니다.

S3 파일 접근 확인

네트워크 구성이 끝난 뒤 카탈로그에서 새 인증 정보를 받아 실제 파일 하나를 가져옵니다. 다음 검사는 앞에서 정의한 TABLE_URL과 인증 헤더 파일, 실제 버킷 리전 S3_REGION을 사용합니다. Bash, jq, Python 3 표준 라이브러리와 AWS CLI가 필요합니다. /dev/null을 사용하는 Linux 또는 macOS 예제입니다.

현재 스냅샷이 있는 테이블을 선택합니다. 비어 있는 새 테이블에 manifest list가 없다는 사실은 네트워크 실패를 의미하지 않습니다.

: "${TABLE_URL:?앞 단계의 실제 테이블 URL을 설정하세요}"
: "${AUTH_HEADER_FILE:?인증 헤더 파일을 설정하세요}"
: "${S3_REGION:?실제 S3 버킷 리전을 설정하세요}"
(
  set -euo pipefail
  set +x
  RESPONSE="$(curl --silent --show-error --fail-with-body \
    --header "@$AUTH_HEADER_FILE" \
    --header 'X-Iceberg-Access-Delegation: vended-credentials' \
    "$TABLE_URL")"

  FILE_PATH="$(printf '%s' "$RESPONSE" | python3 -c '
import json
import sys
metadata = json.load(sys.stdin)["metadata"]
current_id = metadata.get("current-snapshot-id")
for snapshot in metadata.get("snapshots", []):
    if snapshot["snapshot-id"] == current_id:
        print(snapshot["manifest-list"])
        break
else:
    raise SystemExit("현재 스냅샷의 manifest list가 있는 테이블을 선택하세요")
')"
  AWS_ACCESS_KEY_ID="$(printf '%s' "$RESPONSE" | jq -er '.config["s3.access-key-id"]')"
  AWS_SECRET_ACCESS_KEY="$(printf '%s' "$RESPONSE" | jq -er '.config["s3.secret-access-key"]')"
  AWS_SESSION_TOKEN="$(printf '%s' "$RESPONSE" | jq -er '.config["s3.session-token"]')"
  export AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN

  aws s3 cp "$FILE_PATH" /dev/null --region "$S3_REGION" --only-show-errors
)

X-Iceberg-Access-Delegation: vended-credentials는 카탈로그에 임시 저장소 인증 정보를 요청합니다. 응답의 metadata는 인라인 테이블 정보이고 config에는 단기 인증 정보가 있습니다. 응답 전체를 출력하거나 지원 요청에 붙여 넣지 않습니다. 위 예제는 인증 정보를 자식 셸 환경에서만 사용하며 사용자 AWS 프로필 파일을 수정하지 않습니다.

Snapshot ID는 큰 정수일 수 있으므로 파일 선택에는 정수 정밀도를 보존하는 JSON 해석을 사용합니다. AWS 명령이 성공하면 선택한 manifest list 파일을 해당 임시 권한과 네트워크 경로로 읽은 것입니다. 모든 데이터 파일이나 쓰기 권한까지 검증한 결과로 확대하지 않습니다.

AccessDenied이면 발신 IP 및 VPC endpoint 허용 목록을 우선 확인하되, 임시 인증 정보의 만료와 실제 저장소 권한 및 정책도 구분하여 확인합니다. 오류 이름 하나만으로 네트워크 허용 목록이 유일한 원인이라고 단정하지 않습니다.

다른 저장소도 카탈로그와 버킷의 양쪽 접근이 필요합니다. 해당 클라이언트의 전체 읽기는 카탈로그 인증 확인이나 로컬 Jupyter 흐름으로 이어갈 수 있습니다. 네트워크 허용 목록은 인증을 대신하지 않으며, 카탈로그는 인증 정보 발급 전에 테이블 읽기 또는 쓰기 권한을 계속 검사합니다.