Google Cloud Storage 파일과 가상 테이블
Google Cloud Storage(GCS) 커넥터는 저장소 버킷과 Foundry 데이터셋 사이에서 파일을 전달합니다. 파일 형식을 그대로 보존하며 전송 과정이나 전송 직후에 스키마를 자동 적용하지 않습니다. 출력 데이터셋에 스키마를 적용하거나 하위 변환에서 파일을 해석합니다.
원천 탐색, 대량 가져오기, 증분 수집, 가상 테이블, 파일 내보내기, Lakehouse Iceberg REST 카탈로그와 Iceberg 자체 버킷 저장(BYOB)을 일반 제공(GA)합니다. 이전 Export tasks 방식은 Sunset 단계이며 아래에 해당 구성과 제약을 설명합니다.
전송 규모와 실행 시간
전송할 수 있는 파일 크기 자체에 제한은 없습니다. 다만 대규모 전송은 네트워크 문제로 실패할 수 있으며, 직접 클라우드 동기화가 이틀 넘게 실행되면 중단됩니다. 파일 크기를 줄이고 한 번에 수집하는 파일 수를 제한한 뒤 스케줄을 더 자주 실행하는 구성을 검토합니다.
소스 생성과 권한
Data Connection의 +New Source에서 Google Cloud Storage 소스를 선택합니다. Google Cloud IAM 서비스 계정이 필요하며 대상 버킷에 다음 권한을 부여합니다.
| 역할 | 필요한 작업 |
|---|---|
Storage Object Viewer | 데이터 읽기 |
Storage Object Creator | GCS에 데이터 내보내기 |
Storage Object Admin | Foundry로 가져온 뒤 원천 파일 삭제. UPDATE 트랜잭션을 사용하는 증분 데이터셋을 내보내면서 기존 파일을 덮어쓰는 작업에도 필요합니다. |
인증 방식
| 방식 | 조건 |
|---|---|
| GCP instance | 적절하게 구성된 GCP 인스턴스에서 실행하는 에이전트를 경유하는 커넥터에서만 동작합니다. |
| JSON credentials | 다운로드한 서비스 계정 JSON 키 파일을 사용합니다. |
| PKCS8 auth | 서비스 계정 JSON 키 파일의 개별 인증 정보 값을 입력합니다. |
| Workload Identity Federation(OIDC) | 소스 화면에 표시되는 원천 설정 절차에 따라 워크로드 신원 연합을 구성합니다. |
가상 테이블과 BYOB는 아래의 별도 인증 제한을 따릅니다. 목록의 모든 인증 방식이 모든 기능에 적용되는 것은 아닙니다.
외부 통신
다음 호스트의 443 포트에 접근할 수 있어야 합니다.
| 호스트 | 필요 조건 |
|---|---|
storage.googleapis.com | 항상 필요합니다. |
biglake.googleapis.com | Lakehouse Iceberg REST 카탈로그를 사용할 때 필요합니다. |
www.googleapis.com | Lakehouse Iceberg REST 카탈로그를 사용할 때 필요합니다. |
oauth2.googleapis.com | JSON credentials 또는 PKCS8 auth를 사용할 때 필요합니다. |
sts.googleapis.com | Workload Identity Federation을 사용할 때 필요합니다. |
iamcredentials.googleapis.com | Workload Identity Federation을 사용할 때 필요합니다. |
소스 구성 속성
| 항목 | 필수 여부 | 의미 |
|---|---|---|
Project Id | 필수 | GCS 버킷이 속한 Google Cloud 프로젝트 ID입니다. |
Bucket name | 필수 | 읽거나 쓸 버킷 이름입니다. |
Credentials settings | 필수 | 위의 인증 방식 중 기능에 맞는 것을 설정합니다. |
Catalog | 선택 | 이 버킷에 저장한 Iceberg 테이블의 카탈로그를 구성합니다. |
Proxy settings | 선택 | GCS 연결에 프록시를 사용하도록 설정합니다. |
파일을 Foundry 데이터셋으로 수집할 때에는 파일 기반 동기화를 구성합니다.
가상 테이블 지원 범위
가상 테이블은 외부 데이터를 Foundry 테이블 입력이나 출력으로 사용하는 리소스입니다. 일반 파일 수집과 구분합니다.
| 기능 | 지원 범위 |
|---|---|
| 대량 등록 | 지원하지 않습니다. |
| 자동 등록 | 카탈로그를 구성한 Iceberg 테이블에만 일반 제공합니다. |
| 테이블 입력 | Code Repositories와 Pipeline Builder에서 Avro, Delta, Iceberg, Parquet을 일반 제공합니다. |
| 테이블 출력 | Code Repositories와 Pipeline Builder에서 Avro, Delta, Iceberg, Parquet을 일반 제공합니다. |
| 증분 파이프라인 | Delta와 Iceberg의 APPEND만 일반 제공합니다. Parquet은 지원하지 않습니다. |
| 원천 시스템으로 연산 위임 | 지원하지 않습니다. |
가상 테이블에는 Foundry 워커 소스가 필요하며 에이전트 워커는 지원하지 않습니다. 필요한 양방향 연결과 허용 목록을 구성하고 Code Repositories에서 사용할 경우 코드에 소스를 가져오는 등 가상 테이블의 추가 설정도 수행합니다.
가상 테이블 인증은 JSON credentials, PKCS8 auth, Workload Identity Federation(OIDC) 중 하나여야 합니다. GCP instance 방식은 지원하지 않습니다.
Delta
Delta 가상 테이블의 증분 지원에는 원천 Delta 테이블의 Change Data Feed가 활성화되어 있어야 합니다. Python Transforms에서 current와 added 읽기 모드를 지원하며 _change_type, _commit_version, _commit_timestamp 열을 제공합니다. 증분 파이프라인 지원 범위는 APPEND입니다.
Iceberg
Iceberg 가상 테이블을 읽으려면 Iceberg 카탈로그가 필요합니다. 같은 소스에서 등록한 모든 Iceberg 테이블은 동일한 카탈로그를 사용해야 합니다.
Object Storage 카탈로그에서는 테이블 등록 시 GCS의 Iceberg 메타데이터 파일을 가리키는 warehousePath를 지정합니다.
Iceberg 증분 읽기는 추가 전용이며 Python Transforms의 current, added 모드를 지원합니다.
Parquet
Parquet 가상 테이블은 스키마를 추론합니다. 스키마 판별에는 최대 100개 파일을 사용합니다.
Lakehouse 카탈로그 구성
Lakehouse는 테이블을 찾는 카탈로그이고 Iceberg는 테이블 형식입니다. GCS 소스의 버킷 이름이 Lakehouse 카탈로그 ID가 됩니다. 개별 가상 테이블을 등록할 때 이 ID를 바꿀 수 없습니다.
소스의 Google Cloud 인증 정보는 Lakehouse 카탈로그뿐 아니라 Iceberg 데이터와 메타데이터를 저장하는 기반 GCS 버킷에도 접근할 수 있어야 합니다.
- Data Connection에서 GCS 소스의 구성을 엽니다.
- Additional settings에서 Catalog를 추가합니다.
- 카탈로그 유형으로 Lakehouse Catalog를 선택합니다.
- 소스를 저장합니다.
같은 소스를 Lakehouse 카탈로그와 BYOB Iceberg 저장소에 동시에 사용할 수 없습니다. Lakehouse 소스에는 Catalog를 설정하고 BYOB 소스는 Catalog 없이 별도로 만듭니다.
Lakehouse 테이블 등록
- 구성한 소스의 Virtual tables 탭에서 Create virtual table을 선택합니다.
- Configuration의 Format을 Iceberg로 설정합니다.
- Table name에는
namespace.table_id형식의 카탈로그 테이블 식별자를 입력합니다.analytics.orders는 예시입니다. - 읽기 전용인 Catalog ID (bucket)이 소스의 GCS 버킷과 일치하는지 확인합니다.
- Confirm location of virtual table에서 Foundry 리소스 이름을 정합니다.
- 출력 폴더 또는 소스의 기본 출력 위치를 선택하고 마법사를 완료합니다.
Foundry 가상 테이블 이름을 바꾸어도 Lakehouse의 실제 테이블 이름은 바뀌지 않습니다.
BYOB Iceberg 저장소
GCS 버킷을 Foundry Iceberg 테이블의 자체 저장소로 사용할 수 있습니다. 이 구성은 JSON credentials 또는 PKCS8 auth만 지원합니다. Lakehouse 카탈로그 소스와 별도로 만들며 Catalog 설정을 추가하지 않습니다.
기존 Export task 구성
Export tasks는 Sunset 단계의 내보내기 방식입니다. 기존 워크플로에서는 Foundry 데이터셋의 파일을 GCS 버킷의 지정 위치로 복사하는 데 사용합니다. 파일 내보내기 기능 자체는 일반 제공됩니다.
GCS 소스가 있는 프로젝트에서 소스를 오른쪽 클릭하고 Create Data Connection Task를 선택합니다. 왼쪽 패널에서 Source가 대상 커넥터인지 확인하고, inputDataset이라는 Input과 outputDataset이라는 Output을 추가합니다. 입력은 내보낼 Foundry 데이터셋이고 출력은 작업의 실행, 스케줄과 모니터링에 사용합니다. 패널의 표시 이름은 YAML에 정의한 이름을 대신하지 않습니다.
| YAML 속성 | 필수 여부 | 의미 |
|---|---|---|
directoryPath | 필수 | GCS에 파일을 쓸 디렉터리입니다. |
excludePaths | 선택 | 파일 이름이 일치하면 내보내지 않을 정규식 목록입니다. |
uploadConfirmation | 선택 | exportedFiles이면 출력 데이터셋에 내보낸 파일 목록을 기록합니다. |
retriesPerFile | 선택 | 파일 업로드 재시도 횟수입니다. 네트워크 실패가 반복되면 전체 작업이 실패하기 전에 허용할 횟수를 조정합니다. |
createTransactionFolders | 선택 | 내보낸 트랜잭션마다 커밋 시각을 기반으로 고유한 하위 폴더를 만듭니다. |
threads | 선택 | 병렬 업로드 스레드 수입니다. 늘리면 자원을 더 사용하며 에이전트 실행에서는 호스트 자원이 충분해야 합니다. |
incrementalType | 선택 | incremental이면 이전 내보내기 이후의 트랜잭션만 처리합니다. |
다음은 경로와 값을 예시로 지정한 작업 구성입니다.
type: export-google-cloud-storage
directoryPath: directory/to/export/to
excludePaths:
- ^_.*
- ^spark/_.*
uploadConfirmation: exportedFiles
incrementalType: incremental
retriesPerFile: 0
createTransactionFolders: true
threads: 0
구성을 입력한 뒤 오른쪽 위 Save를 선택합니다. 증분 데이터셋의 UPDATE로 기존 파일을 덮어쓰려면 Storage Object Admin 권한이 필요합니다.