GCP에 lakeFS 배포

Tip

여기 안내는 GCP에서 lakeFS를 셀프 매니지드로 배포하는 내용이에요.

보장된 SLA를 갖춘 호스티드 lakeFS 서비스가 필요하다면 lakeFS Cloud on GCP의 세부 사항을 위해 문의해 주세요.

출처: 문서

본문

GCP에 lakeFS를 배포할 때 사용할 수 있는 옵션은 아래와 같아요:

⏰ 예상 배포 시간: 25분

데이터베이스 만들기

lakeFS는 리포지토리에서의 액션 동기화를 위해 PostgreSQL 데이터베이스가 필요해요. 여기서는 Google Cloud SQL에 데이터베이스를 만드는 방법을 보여주지만, lakeFS 설치에서 접근 가능한 모든 PostgreSQL 데이터베이스를 사용할 수 있어요.

이미 데이터베이스가 있다면 연결 문자열을 기록해 두고 다음 단계로 건너뛰세요

• PostgreSQL 인스턴스 생성 방법은 공식 Google 문서를 따르세요. PostgreSQL 버전 >= 11을 사용 중인지 확인하세요.

• 콘솔의 Users 탭에서 사용자를 만드세요. lakeFS 설치가 이 사용자로 데이터베이스에 연결해요.

• lakeFS가 데이터베이스에 연결할 방식을 선택하세요. Google은 SQL Auth Proxy 사용을 권장해요.

lakeFS 서버 실행

GCE InstanceDockerGKE

다음 설정 파일을 config.yaml로 저장하세요:

---
database:
    type: "postgres"
    postgres:
    connection_string: "[DATABASE_CONNECTION_STRING]"
auth:
    encrypt:
    # replace this with a randomly-generated string:
    secret_key: "[ENCRYPTION_SECRET_KEY]"
blockstore:
    type: gs
    # Uncomment the following lines to give lakeFS access to your buckets using a service account:
    # gs:
    #   credentials_json: [YOUR SERVICE ACCOUNT JSON STRING]

• GCE 인스턴스에서 실행할 바이너리를 다운로드하세요.

• GCE 머신에서 lakefs 바이너리를 실행하세요:

lakefs --config config.yaml run

참고: systemd 등 운영체제 기능으로 서비스 형태로 실행하는 편이 좋아요.

Google Cloud Run 같은 컨테이너 기반 환경을 지원하려면 lakeFS를 환경 변수로 구성할 수 있어요. Docker로 lakeFS를 시작하는 docker run 명령 예시예요:

docker run \
    --name lakefs \
    -p 8000:8000 \
    -e LAKEFS_DATABASE_TYPE="postgres" \
    -e LAKEFS_DATABASE_POSTGRES_CONNECTION_STRING="[DATABASE_CONNECTION_STRING]" \
    -e LAKEFS_AUTH_ENCRYPT_SECRET_KEY="[ENCRYPTION_SECRET_KEY]" \
    -e LAKEFS_BLOCKSTORE_TYPE="gs" \
    treeverse/lakefs:latest run

전체 환경 변수 목록은 레퍼런스를 참고하세요.

Kubernetes에는 Helm 차트로 lakeFS를 설치할 수 있어요.

Helm으로 lakeFS를 설치하는 방법:

• Google Storage에 맞는 Helm values 파일을 복사하세요:

secrets:
    # replace DATABASE_CONNECTION_STRING with the connection string of the database you created in a previous step.
    # e.g.: postgres://postgres:***@localhost/postgres:5432
    databaseConnectionString: [DATABASE_CONNECTION_STRING]
    # replace this with a randomly-generated string
    authEncryptSecretKey: [ENCRYPTION_SECRET_KEY]
lakefsConfig: |
    blockstore:
        type: gs
        # Uncomment the following lines to give lakeFS access to your buckets using a service account:
        # gs:
        #   credentials_json: [YOUR SERVICE ACCOUNT JSON STRING]

1. 빈 값을 채우고 conf-values.yaml로 저장하세요. 더 많은 설정 옵션은 Helm 차트 README를 참고하세요.

Note

lakefsConfig 파라미터는 여기에 문서화된 lakeFS 설정에서 민감 정보를 뺀 것이에요. databaseConnectionString 같은 민감 정보는 별도 파라미터로 제공되며 차트가 Kubernetes 시크릿에 주입해요.

• conf-values.yaml을 만든 디렉터리에서 다음 명령을 실행하세요:

# Add the lakeFS repository
helm repo add lakefs https://charts.lakefs.io
# Deploy lakeFS
helm install my-lakefs lakefs/lakefs -f conf-values.yaml

my-lakefs는 Helm Release 이름이에요.

로드밸런싱

lakeFS 서버로 요청을 분기하는 로드밸런서는 LoadBalancer 서비스 타입이나 Kubernetes Ingress로 구성할 수 있어요. 기본적으로 lakeFS는 포트 8000에서 동작하며 헬스 체크에 사용할 수 있는 /_health 엔드포인트를 노출해요.

Tip

NGINX Ingress Controller는 기본적으로 클라이언트 바디 크기를 1 MiB로 제한해요.

일부 클라이언트는 더 큰 청크로 객체를 업로드해요 - 예를 들어 S3 호환 Gateway를 통한 lakeFS 멀티파트 업로드나 OpenAPI Server를 통한 단순 PUT 요청이 그렇죠.

한도를 늘리려면 Nginx 문서를 참고하거나 MinIO를 사용한 Nginx 구성 예시를 확인하세요.

관리자 사용자 만들기

lakeFS UI를 처음 열면 초기 관리자 사용자 생성을 요청받아요.

• 브라우저에서 http://<lakefs-host>/를 여세요. 로드밸런서를 설정하지 않았다면 대개 http://<instance ip address>:8000/일 거예요

• 처음 사용 시 설정(setup) 페이지로 리디렉션돼요:

• 안내에 따라 초기 관리자 사용자를 만드세요. 받은 자격 증명은 안전한 곳에 보관하세요. 다시는 볼 수 없어요!

• 링크를 따라가 로그인 화면으로 이동하고, 이전 단계의 자격 증명으로 로그인하세요.

GCS 버킷의 최소 권한 구성

필요하다면 lakeFS는 데이터 자체에 접근하지 않고 동작할 수 있어요. 이 권한 모델은 제로 트러스트 아키텍처를 운영하거나 presigned URL 모드, lakeFS Hadoop FileSystem Spark 통합을 사용할 때 유용해요.

전용 GCP 프로젝트 권장

VPC Service Controls는 GCS 서비스 전체에 경계를 두는 특성이 있으므로, lakeFS 버킷에는 전용 GCP 프로젝트를 사용하는 것이 강력히 권장돼요. 권한과 접근 관리가 크게 단순해져요.

아키텍처 개요

이 구성은 두 개의 서비스 계정을 사용해요:

• 메타데이터 서비스 계정 (SA_OPEN): gs://<bucket-name>/<prefix>/_lakefs/ 형태의 버킷 프리픽스에 어디서든 접근해요.

• 데이터 서비스 계정 (SA_RESTRICTED): gs://<bucket-name>/<prefix>/_lakefs/ 형태의 버킷 프리픽스를 제외한 모든 데이터에 접근하며, VPC Service Controls로 네트워크가 제한돼요.

lakeFS는 스토리지 네임스페이스 아래 _lakefs 프리픽스에 접근할 권한을 항상 요구해요. 메타데이터가 저장되는 곳이에요.

제한 사항

이 구성은 presign 모드만 지원해요. 즉 다음은 불가능해요:

• lakeFS 웹 UI로 객체 업로드 (presign 모드는 설정 가능)

• lakeFS S3 Gateway를 통한 객체 업로드

• lakectl fs 명령 실행

설정 단계

1. 서비스 계정 생성

환경 변수를 설정하세요:

export PROJECT_ID="[YOUR_PROJECT_ID]"
export SA_OPEN_ID="lakefs-metadata"
export SA_RESTRICTED_ID="lakefs-data"
export BUCKET="[YOUR_BUCKET_NAME]"

서비스 계정을 생성하세요:

# Metadata service account (accesses _lakefs/** from anywhere)
gcloud iam service-accounts create "${SA_OPEN_ID}" \
  --project="${PROJECT_ID}" \
  --description="lakeFS metadata - RW only under /_lakefs/** (from anywhere)" \
  --display-name="lakeFS Metadata Service Account"

# Data service account (accesses everything except _lakefs/**, network-restricted)
gcloud iam service-accounts create "${SA_RESTRICTED_ID}" \
  --project="${PROJECT_ID}" \
  --description="lakeFS data - RW everywhere except /_lakefs/** (network-restricted)" \
  --display-name="lakeFS Data Service Account"

전체 서비스 계정 이메일을 가져오세요:

export SA_OPEN="${SA_OPEN_ID}@${PROJECT_ID}.iam.gserviceaccount.com"
export SA_RESTRICTED="${SA_RESTRICTED_ID}@${PROJECT_ID}.iam.gserviceaccount.com"

2. 버킷 IAM 정책 구성

이 단계에서는 버킷 수준에서 IAM 정책을 구성해 서비스 계정에 필요한 권한을 부여해요.

메타데이터 서비스 계정에 gs://<bucket-name>/<prefix>/_lakefs/ 프리픽스만 접근을 부여하세요:

gcloud storage buckets add-iam-policy-binding "gs://${BUCKET}" \
  --member="serviceAccount:${SA_OPEN}" \
  --role="roles/storage.objectAdmin" \
  --condition='title=lakefs-metadata-only,description=Access_only_to_lakefs_prefix,expression=resource.type == "storage.googleapis.com/Object" && resource.name.extract("/objects/{prefix}/_lakefs/") != ""'

데이터 서비스 계정에 gs://<bucket-name>/<prefix>/_lakefs/ 프리픽스를 제외한 모든 접근을 부여하세요:

# Object access (read/write) for non-_lakefs paths
gcloud storage buckets add-iam-policy-binding "gs://${BUCKET}" \
  --member="serviceAccount:${SA_RESTRICTED}" \
  --role="roles/storage.objectAdmin" \
  --condition='title=lakefs-data-only,description=Access_except_lakefs_prefix,expression=resource.type == "storage.googleapis.com/Object" && resource.name.extract("/objects/{prefix}/_lakefs/") == ""'

객체 나열용 커스텀 IAM 역할을 만들어 데이터 서비스 계정에 부여하세요:

# Create custom role for listing objects only
gcloud iam roles create lakefsDataListOnly \
  --project="${PROJECT_ID}" \
  --title="lakeFS Data List Only" \
  --description="Custom role for lakeFS data service account to list objects" \
  --permissions="storage.objects.list"

# Grant the custom role to the data service account
gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
  --member="serviceAccount:${SA_RESTRICTED}" \
  --role="projects/${PROJECT_ID}/roles/lakefsDataListOnly"

3. VPC Service Controls 설정

허용 네트워크를 정의하는 액세스 레벨을 만드세요 (IP 대역과 VPC는 필요에 맞게 조정):

# Get your organization's access policy ID
export ORG_ID="[YOUR_ORG_ID]"
export POLICY_ID=$(gcloud access-context-manager policies list \
  --organization="${ORG_ID}" \
  --format="value(name)")

# Create an access level for your allowed networks
cat > access-level.yaml <<EOF
- ipSubnetworks:
  - "[YOUR_ALLOWED_IP_CIDR]"
  vpcNetworkSources:
  - vpcSubnetwork:
      network: "projects/[YOUR_VPC_PROJECT]/global/networks/[YOUR_VPC_NAME]"
EOF

gcloud access-context-manager levels create Restrict_Network_Access \
  --policy="${POLICY_ID}" \
  --title="Restrict Network Access to Approved IPs and VPCs" \
  --combine-function=OR \
  --basic-level-spec=access-level.yaml

4. 인그레스 정책 생성

제한된 서비스 계정용 인그레스 정책을 정의하세요:

export ACCESS_LEVEL="accessPolicies/${POLICY_ID}/accessLevels/Restrict_Network_Access"

cat > ingress-policy.yaml <<EOF
- ingressFrom:
    identities:
    - serviceAccount:${SA_RESTRICTED}
    sources:
    - accessLevel: ${ACCESS_LEVEL}
  ingressTo:
    operations:
    - serviceName: storage.googleapis.com
    resources:
    - '*'
  title: lakeFS Data Service Account Ingress
EOF

5. VPC Service Controls 경계 생성

gcloud access-context-manager perimeters create lakefs_perimeter \
  --policy="${POLICY_ID}" \
  --title="lakeFS Security Perimeter" \
  --resources="projects/${PROJECT_ID}" \
  --restricted-services="storage.googleapis.com" \
  --ingress-policies=ingress-policy.yaml

6. lakeFS 구성 업데이트

lakeFS 구성에서 블록스토어 자격 증명을 메타데이터·데이터 서비스 계정으로 업데이트하세요:

blockstore:
  type: gs
  gs:
    credentials_json: [SA_OPEN_SERVICE_ACCOUNT_JSON]
    # Alternatively, you can use a file path:
    # data_credentials_file: /path/to/sa_restricted_service_account.json

데이터 연산에는 클라이언트가 데이터 서비스 계정(SA_RESTRICTED) 자격 증명을 사용해야 하고, VPC Service Controls에 정의된 허용 네트워크와 VPC 내부에서만 접근해야 해요.

네트워크 접근 제어

이 구성에서는:

• lakeFS 서버가 SA_OPEN으로 어느 네트워크에서든 메타데이터(_lakefs/)에 접근해요

• SA_RESTRICTED를 통한 데이터 접근은 VPC Service Controls 액세스 레벨에 정의된 승인된 IP 주소와 VPC에서만 허용돼요

• 데이터에 접근하는 클라이언트는 허용된 네트워크 경계 안에 있어야 해요

이는 aws:SourceVpc, aws:SourceIp 같은 AWS의 조건 키와 비슷한 보안을 GCP의 VPC Service Controls로 제공하는 방식이에요.

첫 리포지토리 만들기

• 이전 단계의 자격 증명으로 로그인하세요

• Create Repository를 클릭하고 Blank Repository를 선택하세요.

• Storage Namespace에 객체 스토리지에서 원하는 위치 경로를 입력하세요. 이 리포지토리에 쓰이는 데이터가 저장되는 곳이에요.

• Create Repository를 클릭하세요

• 이제 설정이 완료된 리포지토리가 생겼어요. 바로 사용할 수 있어요!

축하합니다

여러분의 환경이 준비되었어요 🤩

더 알아보기 (Learn more)

공식 문서의 GCP 배포 페이지는 https://docs.lakefs.io/admin/install/gcp 에서 확인할 수 있어요.