온프레미스 배포

원문 보기 위키 갱신 2026.10.11

Tip

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

보장된 SLA를 갖춘 호스티드 lakeFS 서비스가 필요하다면 lakeFS Cloud를 이용해 보세요.

출처: 문서

본문

⏰ 예상 배포 시간: 25분

사전 준비

lakeFS를 온프레미스로 사용하려면 로컬 블록스토어 어댑터를 쓰거나 MinIO 같은 S3 호환 객체 스토리지에 접근할 수 있어야 해요.

MinIO 설정 방법은 공식 배포 가이드를 참고하세요

데이터베이스 설정

lakeFS는 리포지토리에서의 액션 동기화를 위해 PostgreSQL 데이터베이스가 필요해요. 이 섹션은 접근 가능한 PostgreSQL >= 11.0 데이터베이스가 이미 있다고 가정해요.

lakeFS 서버 설정

LinuxDockerKubernetes

SSH로 호스트에 접속하세요:

VM에 다음 파라미터로 config.yaml을 만드세요:

---
database:
    type: "postgres"
    postgres:
    connection_string: "[DATABASE_CONNECTION_STRING]"

auth:
    encrypt:
    # replace this with a randomly-generated string. Make sure to keep it safe!
    secret_key: "[ENCRYPTION_SECRET_KEY]"

blockstore:
    type: s3
    s3:
        force_path_style: true
        endpoint: http://<minio_endpoint>
        discover_bucket_region: false
        credentials:
        access_key_id: <minio_access_key>
        secret_access_key: <minio_secret_key>

Info

lakeFS 블록스토어 타입이 s3로 설정된 점에 주목하세요 - 이 구성은 MinIO 같은 S3 호환 스토리지 엔진에서 동작해요.

서버로 바이너리를 다운로드하세요.
lakefs 바이너리를 실행하세요:

lakefs --config config.yaml run

Note

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

컨테이너 기반 환경을 지원하려면 환경 변수로 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="s3" \
    -e LAKEFS_BLOCKSTORE_S3_FORCE_PATH_STYLE="true" \
    -e LAKEFS_BLOCKSTORE_S3_ENDPOINT="http://<minio_endpoint>" \
    -e LAKEFS_BLOCKSTORE_S3_DISCOVER_BUCKET_REGION="false" \
    -e LAKEFS_BLOCKSTORE_S3_CREDENTIALS_ACCESS_KEY_ID="<minio_access_key>" \
    -e LAKEFS_BLOCKSTORE_S3_CREDENTIALS_SECRET_ACCESS_KEY="<minio_secret_key>" \
    treeverse/lakefs:latest run

Info

lakeFS 블록스토어 타입이 s3로 설정된 점에 주목하세요 - 이 구성은 MinIO 같은 S3 호환 스토리지 엔진에서 동작해요.

로컬 데이터베이스와 로컬 블록스토어

로컬 데이터베이스(LAKEFS_DATABASE_TYPE=local)와 로컬 블록스토어(LAKEFS_BLOCKSTORE_TYPE=local)를 사용하면 lakeFS가 모든 데이터와 메타데이터를 기본적으로 컨테이너 안 ${HOME}/lakefs에 저장해요 (설정 가능). Docker 볼륨으로 이 위치를 호스트에 마운트해 데이터와 메타데이터를 호스트 스토리지에 영속화할 수 있어요:

docker run \
    --name lakefs \
    -p 8000:8000 \
    -v /path/on/host:/home/lakefs/lakefs \
    -e LAKEFS_DATABASE_TYPE="local" \
    -e LAKEFS_BLOCKSTORE_TYPE="local" \
    -e LAKEFS_AUTH_ENCRYPT_SECRET_KEY="[ENCRYPTION_SECRET_KEY]" \
    treeverse/lakefs:latest run

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

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

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

S3 호환 스토리지(이 예시에서는 MinIO)에 맞는 Helm values 파일을 복사하세요:

secrets:
    # replace this with the connection string of the database you created in a previous step:
    databaseConnectionString: [DATABASE_CONNECTION_STRING]
    # replace this with a randomly-generated string
    authEncryptSecretKey: [ENCRYPTION_SECRET_KEY]
lakefsConfig: |
    blockstore:
        type: s3
        s3:
        force_path_style: true
        endpoint: http://<minio_endpoint>
        discover_bucket_region: false
        credentials:
            access_key_id: <minio_access_key>
            secret_access_key: <minio_secret_key>

Tip lakeFS 블록스토어 타입이 s3로 설정된 점에 주목하세요 - 이 구성은 MinIO 같은 S3 호환 스토리지 엔진에서 동작해요

빈 값을 채우고 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 엔드포인트를 노출해요.

Info

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

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

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

보안 연결

TLS/SSL 종단은 로드밸런서나 클러스터 매니저에서 처리하는 것이 권장돼요. 복호화 속도를 높이고 lakeFS의 처리 부담을 줄여 줘요.

예를 들어 개발 목적으로 lakeFS가 HTTPS로 리스닝·서빙해야 한다면 설정 yaml에 다음 섹션을 추가하세요:

tls:
  enabled: true
  cert_file: server.crt   # provide path to your certificate file
  key_file: server.key    # provide path to your server private key

로컬 블록스토어

모든 lakeFS 인스턴스가 공유하는 POSIX 호환 스토리지 위치에 블록 어댑터를 구성할 수 있어요. 공유 스토리지 위치를 사용하면 데이터와 메타데이터가 모두 그곳에 저장돼요.

로컬 블록스토어 임포트를 활성화하고 lakeFS가 특정 프리픽스에 접근하도록 허용하면, 공유 위치에서 파일을 임포트할 수 있어요. 임포트는 기본적으로 비활성화되어 있어요. 로컬 경로가 공유된다고 가정하지 않고, 블록스토어 설정에 지정된 경로 밖에 접근하는 데 보안 우려가 있기 때문이에요. 활성화는 설정 레퍼런스에 설명된 blockstore.local.import_enabled와 blockstore.local.allowed_external_prefixes로 수행해요.

로컬 블록스토어 사용 구성 예시

database:
  type: "postgres"
  postgres:
    connection_string: "[DATABASE_CONNECTION_STRING]"

auth:
  encrypt:
    # replace this with a randomly-generated string. Make sure to keep it safe!
    secret_key: "[ENCRYPTION_SECRET_KEY]"

blockstore:
  type: local
  local:
    path: /shared/location/lakefs_data    # location where data and metadata kept by lakeFS
    import_enabled: true                  # required to be true to enable import files
                                          # from `allowed_external_prefixes` locations
    allowed_external_prefixes:
      - /shared/location/files_to_import  # location with files we can import into lakeFS, require access from lakeFS

제한 사항

lakeFS는 공유 위치가 머신들 사이에서 어떻게 관리되는지 통제하지 않아요
lakectl이나 lakeFS UI를 사용할 때는 현재 디렉터리만 임포트할 수 있어요. 단일 파일을 임포트해야 한다면 요청 본문에 type=object, destination=<full-path-to-file>을 넣어 HTTP API나 API 클라이언트를 사용하세요.
가비지 컬렉터(커밋 및 비커밋)와 lakeFS Hadoop FileSystem은 현재 지원되지 않아요

관리자 사용자 만들기

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

브라우저에서 http://<lakefs-host>/를 여세요. 로드밸런서를 설정하지 않았다면 대개 http://<instance ip address>:8000/일 거예요
처음 사용 시 설정(setup) 페이지로 리디렉션돼요:
안내에 따라 초기 관리자 사용자를 만드세요. 받은 자격 증명은 안전한 곳에 보관하세요. 다시는 볼 수 없어요!
링크를 따라가 로그인 화면으로 이동하고, 이전 단계의 자격 증명으로 로그인하세요.

첫 리포지토리 만들기

이전 단계의 자격 증명으로 로그인하세요
Create Repository를 클릭하고 Blank Repository를 선택하세요.
Storage Namespace에 객체 스토리지에서 원하는 위치 경로를 입력하세요. 이 리포지토리에 쓰이는 데이터가 저장되는 곳이에요.
Create Repository를 클릭하세요
이제 설정이 완료된 리포지토리가 생겼어요. 바로 사용할 수 있어요!

축하합니다

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

더 알아보기 (Learn more)

공식 문서의 온프레미스 배포 페이지는 https://docs.lakefs.io/admin/install/onprem 에서 확인할 수 있어요.