스탠드얼론 가비지 컬렉션(Standalone Garbage Collection)

lakeFS Enterprise에서 제공되는 기능이에요. 무료 체험을 시작해 보세요.

출처: 문서

본문

스탠드얼론 GC란?

스탠드얼론 GC는 외부 의존성 없이 실행되는 Spark 기반 GC의 간소화 버전이에요. 독립 실행형 docker 이미지로 제공돼요. S3와 MinIO 같은 셀프 매니지드 S3 호환 스토리지를 지원해요.

제한 사항

• 수평 확장 불가: 주어진 리포지토리에서 lakefs-sgc는 한 번에 단일 인스턴스만 실행할 수 있어요.

• Mark 단계 전용: 스탠드얼론 GC는 mark 단계만 지원해요. 삭제 대상 객체를 식별하지만 실제 삭제를 수행하는 sweep 단계는 실행하지 않아요. GC의 mark-only 모드와 비슷하게 동작해요.

• AWS S3와 S3 호환 객체 스토리지만 지원해요. 다만 Azure blob과 GCS 지원이 로드맵에 있어요.

설치

1단계: 라이선스 받기

lakeFS Enterprise 고객

계정 관리자에게 연락해 라이선스에 스탠드얼론 GC가 포함되어 있는지 확인하세요.

lakeFS Enterprise가 처음인 경우

문의하기를 통해 스탠드얼론 GC 체험 접근을 요청하세요.

2단계: docker 이미지 다운로드

Docker Hub에서 treeverse/lakefs-sgc 이미지를 다운로드하세요:

docker pull treeverse/lakefs-sgc:<tag>

설정

권한

lakefs-sgc를 실행하려면 아래에 설명된 대로 AWS(또는 S3 호환) 스토리지 권한과 lakeFS 사용자 권한이 모두 필요해요.

스토리지 권한

AWS 또는 S3 호환 스토리지에 필요한 최소 권한은 다음과 같아요:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject"
      ],
      "Resource": [
        "arn:aws:s3:::some-bucket/some/prefix/*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::some-bucket"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:ListAllMyBuckets"
      ],
      "Resource": [
        "arn:aws:s3:::*"
      ]
    }
  ]
}

이 예시에서 리포지토리 스토리지 네임스페이스는 s3://some-bucket/some/prefix 이에요.

lakeFS 권한

lakeFS에 필요한 최소 권한은 다음과 같아요:

{
  "statement": [
    {
      "action": [
        "retention:PrepareGarbageCollectionCommits",
        "retention:PrepareGarbageCollectionUncommitted",
        "fs:ReadConfig",
        "fs:ReadRepository",
        "fs:ListObjects",
        "fs:ReadConfig"
      ],
      "effect": "allow",
      "resource": "arn:lakefs:fs:::repository/<repository>"
    }
  ]
}

자격 증명

스탠드얼론 GC는 S3와 S3 호환 스토리지 백엔드를 지원하고 인증에 AWS 자격 증명을 사용해요. 자격 증명을 제공하는 방법은 여러 가지가 있어요:

• AWS 자격 증명 파일: 이 가이드에 나온 AWS 가이드라인을 따르세요.

• AWS 프로파일: aws.profile 설정 옵션으로 AWS 프로파일을 지정할 수 있어요.

• 정적 자격 증명: aws.s3.credentials.access_key_id, aws.s3.credentials.secret_access_key, 선택적으로 aws.s3.credentials.session_token으로 설정 파일을 통해 직접 자격 증명을 제공할 수 있어요.

lakefs-sgc에 자격 증명을 전달하는 방법의 자세한 내용은 How to Run Standalone GC 섹션의 안내를 참고하세요.

S3 호환 클라이언트 사용하기

lakefs-sgc는 AWS 자격 증명을 활용해 MinIO 같은 S3 호환 스토리지 솔루션과 매끄럽게 동작해요. S3 호환 엔드포인트를 구성하는 방법은 두 가지예요:

옵션 1: 자격 증명 파일과 함께 AWS 프로파일 사용

• ~/.aws/config 파일에 프로파일을 추가하세요:

[profile minio]
region = us-east-1
endpoint_url = <MinIO URL>
s3 =
    signature_version = s3v4

• ~/.aws/credentials 파일에 액세스 키와 시크릿 키를 추가하세요:

[minio]
aws_access_key_id     = <MinIO access key>
aws_secret_access_key = <MinIO secret key>

• lakefs-sgc docker 이미지를 실행하며 minio 프로파일을 전달하세요 - 아래 예시를 참고하세요.

옵션 2: 커스텀 엔드포인트가 포함된 설정 파일 사용

대신 설정 파일에 S3 호환 엔드포인트를 직접 구성할 수도 있어요:

• S3 호환 엔드포인트 정보를 담은 설정 파일을 만드세요:

aws:
  region: us-east-1
  s3:
    endpoint: https://your-minio-endpoint.example.com
    addressing_path_style: true
    credentials:
      access_key_id: <access key>
      secret_access_key: <secret key>

• docker 이미지를 실행하며 --config 플래그로 설정 파일을 전달하세요.

구성

다음 설정 키를 사용할 수 있어요:

Key	Description	Default value	Possible values
logging.format	로그 출력 형식	"text"	"text","json"
logging.level	로그 레벨	"info"	"error","warn",info","debug","trace"
logging.output	로그 출력 위치	"-"	"-" (stdout), "=" (stderr), 또는 파일 경로 문자열
cache_dir	실행 중 데이터 캐싱에 사용할 디렉터리	~/.lakefs-sgc/data	string
aws.region	S3 연산에 사용할 AWS 리전	NOT SET	string (예: "us-east-1")
aws.profile	사용할 AWS 자격 증명 프로파일	NOT SET	string
aws.max_page_size	AWS에서 객체를 나열할 때 페이지당 최대 항목 수	1000	number
aws.s3.endpoint	커스텀 S3 호환 엔드포인트 URL (예: MinIO용)	NOT SET	URL
aws.s3.addressing_path_style	AWS에서 객체를 읽을 때 path-style 사용 여부	true	boolean
aws.s3.credentials.access_key_id	S3용 정적 AWS 액세스 키 ID	NOT SET	string
aws.s3.credentials.secret_access_key	S3용 정적 AWS 시크릿 액세스 키	NOT SET	string
aws.s3.credentials.session_token	임시 자격 증명용 AWS 세션 토큰	NOT SET	string
lakefs.endpoint_url	lakeFS 설치의 URL - /api/v1로 끝나야 해요	NOT SET	URL
lakefs.access_key_id	lakeFS 설치의 액세스 키	NOT SET	string
lakefs.secret_access_key	lakeFS 설치의 시크릿 액세스 키	NOT SET	string

이 키들은 다음 방법으로 제공할 수 있어요:

1. 설정 파일: 키들을 담은 YAML 파일을 만들되, 각 .은 새 중첩 레벨이 돼요.
   예를 들어 logging.level은 다음과 같아요:

logging:
  level: <value> # info,debug...

그다음 --config path/to/config.yaml 인자로 프로그램에 전달하세요. 2. 환경 변수: LAKEFS_SGC_<KEY> 형식으로, 대문자로 바꾸고 .을 _로 변환해서 설정해요.
예를 들어 logging.level은 다음과 같아요:

export LAKEFS_SGC_LOGGING_LEVEL=info

최소 구성 예시 설정 파일:

logging:
  level: debug

커스텀 S3 엔드포인트와 정적 자격 증명이 포함된 설정 파일 예시:

logging:
  level: debug
aws:
  region: us-east-1
  s3:
    endpoint: https://my-s3-endpoint.example.com
    addressing_path_style: true
    credentials:
      access_key_id: <AWS access key>
      secret_access_key: <AWS secret key>
      session_token: <optional AWS session token>
lakefs:
  endpoint_url: https://your.url/api/v1
  access_key_id: <lakeFS access key>
  secret_access_key: <lakeFS secret key>

스탠드얼론 GC 실행 방법

명령줄 레퍼런스

플래그

• -c, --config: 사용할 설정 파일 (기본값은 $HOME/.lakefs-sgc.yaml)

명령

run

사용법:

lakefs-sgc run <repository>

플래그:

• --cache-dir: 읽은 파일을 캐시할 디렉터리 (기본값은 $HOME/.lakefs-sgc/data/)

• --parallelism: 메타데이터 파일의 병렬 다운로드 수 (기본값 10)

• --presign: 데이터 다운로드/업로드 시 pre-signed URL 사용 (권장) (기본값 true)

스탠드얼론 GC를 실행하려면 AWS 자격 증명을 전달하는 방법을 선택하고 아래 명령을 실행하세요.

~/.aws/credentials에서 파싱한 자격 증명을 직접 전달

docker run \
    -e AWS_REGION=<region> \
    -e AWS_SESSION_TOKEN="$(grep 'aws_session_token' ~/.aws/credentials | awk -F' = ' '{print $2}')" \
    -e AWS_ACCESS_KEY_ID="$(grep 'aws_access_key_id' ~/.aws/credentials | awk -F' = ' '{print $2}')" \
    -e AWS_SECRET_ACCESS_KEY="$(grep 'aws_secret_access_key' ~/.aws/credentials | awk -F' = ' '{print $2}')" \
    -e LAKEFS_SGC_LAKEFS_ENDPOINT_URL=<lakefs endpoint URL> \
    -e LAKEFS_SGC_LAKEFS_ACCESS_KEY_ID=<lakefs accesss key> \
    -e LAKEFS_SGC_LAKEFS_SECRET_ACCESS_KEY=<lakefs secret key> \
    -e LAKEFS_SGC_LOGGING_LEVEL=debug \
    treeverse/lakefs-sgc:<tag> run <repository>

~/.aws 디렉터리 마운트

S3 호환 클라이언트를 사용할 때는 ~/.aws 디렉터리를 마운트하고 원하는 프로파일을 전달하는 편이 더 편리한 경우가 많아요.

먼저 docker 컨테이너가 이 디렉터리를 읽을 수 있도록 ~/.aws/*의 권한을 변경하세요:

chmod 644 ~/.aws/*

그다음 docker 이미지를 실행하며 ~/.aws를 컨테이너의 lakefs-sgc 홈 디렉터리로 마운트하세요:

docker run \
--network=host \
-v ~/.aws:/home/lakefs-sgc/.aws \
-e AWS_REGION=us-east-1 \
-e AWS_PROFILE=<profile> \
-e LAKEFS_SGC_LAKEFS_ENDPOINT_URL=<lakefs endpoint URL> \
-e LAKEFS_SGC_LAKEFS_ACCESS_KEY_ID=<lakefs accesss key> \
-e LAKEFS_SGC_LAKEFS_SECRET_ACCESS_KEY=<lakefs secret key> \
-e LAKEFS_SGC_LOGGING_LEVEL=debug \
treeverse/lakefs-sgc:<tag> run <repository>

삭제 표시된 객체 목록 확인

lakefs-sgc는 리포트를 <REPOSITORY_STORAGE_NAMESPACE>/_lakefs/retention/gc/reports/<RUN_ID>/에 기록해요.
RUN_ID는 스탠드얼론 GC가 런타임에 생성하며 로그에서 확인할 수 있어요:

"Marking objects for deletion" ... run_id=gcoca17haabs73f2gtq0

이 프리픽스 아래에는 2개의 객체가 있어요:

• deleted.csv - address 컬럼 하나를 가진 CSV로, 표시된 모든 객체를 담고 있어요.

예시

address
"data/gcnobu7n2efc74lfa5ug/csfnri7n2efc74lfa69g,_e7P9j-1ahTXtofw7tWwJUIhTfL0rEs_dvBrClzc_QE"
"data/gcnobu7n2efc74lfa5ug/csfnri7n2efc74lfa78g,mKZnS-5YbLzmK0pKsGGimdxxBlt8QZzCyw1QeQrFvFE"
...

• summary.json - GC 실행을 요약한 작은 json이에요.

예시

{
    "run_id": "gcoca17haabs73f2gtq0",
    "success": true,
    "first_slice": "gcss5tpsrurs73cqi6e0",
    "start_time": "2024-10-27T13:19:26.890099059Z",
    "cutoff_time": "2024-10-27T07:19:26.890099059Z",
    "num_deleted_objects": 33000
}

표시된 객체 삭제

삭제하기 전에 표시된 객체를 다른 버킷에 백업하는 것부터 시작하는 것을 권장해요. 백업이 완료되었는지 확인한 뒤 백업 위치에서 직접 객체를 삭제하면 돼요.

표시된 객체를 다른 버킷에 백업하는 스크립트:

# Update these variables with your actual values
storage_ns=<storage namespace (s3://...)>
output_bucket=<output bucket (s3://...)>
run_id=<GC run id>

# Download the CSV file
aws s3 cp "$storage_ns/_lakefs/retention/gc/reports/$run_id/deleted.csv" "./run_id-$run_id.csv"

# Move all addresses to the output bucket under the "run_id=$run_id" prefix
cat run_id-$run_id.csv | tail -n +2 | xargs -I {} aws s3 mv "$storage_ns/{}" "$output_bucket/run_id=$run_id/"

표시된 객체를 삭제하는 스크립트:

# Update these variables with your actual values
output_bucket=<output bucket (s3://...)>
run_id=<GC run id>

aws s3 rm $output_bucket/run_id=$run_id --recursive

Tip

실제로 스토리지 비용을 줄이려면 백업도 주기적으로 삭제하는 것을 잊지 마세요.

실험실 테스트 결과

스탠드얼론 GC는 아래의 lakeFS 환경에서 테스트되었어요.

리포지토리 사양

• 100k 객체

• 250 커밋

• 100 브랜치

머신 사양

• 4GiB RAM

• 8 CPU

테스트 결과

• 소요 시간: < 5분

• 디스크 공간: 123MB

더 알아보기 (Learn more)

공식 문서의 스탠드얼론 GC 페이지는 https://docs.lakefs.io/admin/garbage-collection/standalone-gc 에서 확인할 수 있어요.