Azure에 lakeFS 배포

원문 보기 위키 갱신 2026.10.11

Tip

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

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

출처: 문서

본문

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

이 가이드는 사용 가능한 옵션과 설정 방법을 안내하고, lakeFS 자체를 구성·실행해 첫 리포지토리를 만드는 것으로 마무리해요.

⏰ 예상 배포 시간: 25분

객체 스토리지

lakeFS는 다음 Azure Storage 유형을 지원해요:

Data Lake Storage Gen1은 지원되지 않아요.

인증 방식

lakeFS는 Azure와 인증하는 두 가지 방식을 지원해요.

Identity Based Authentication (권장)Storage Account Credentials

lakeFS는 인증에 사용할 자격 증명을 환경 변수로 결정해요. 다음 인증 방법들을 지원해요:

Managed Service Identity (MSI)
Service Principal RBAC
Azure CLI

Managed Identity 사용하기

Virtual Machine, Virtual Machine Scale Set, Azure Kubernetes Service 파드처럼 Azure 내부에서 실행되는 배포에서는 관리 ID(managed identity)가 권장되는 인증 방식이에요. lakeFS가 Azure SDK 자격 증명 체인을 통해 ID를 해석하므로 lakeFS 설정에 시크릿을 저장할 필요가 없거든요. 어떤 경우든 해당 ID에는 lakeFS가 사용하는 스토리지 계정(또는 그것을 포함하는 리소스 그룹)에 대한 "Storage Blob Data Contributor" 역할이 부여되어야 해요.

시스템 할당 관리 ID는 자동으로 인식되며 추가 설정이 필요 없어요. 대신 사용자 할당 관리 ID를 쓰려면 AZURE_CLIENT_ID 환경 변수를 그 ID의 클라이언트 ID로 설정하세요. lakeFS가 그 ID로 인증할 거예요:

AZURE_CLIENT_ID = <user-assigned managed identity client ID>

사용자 할당 관리 ID 선택하기

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

AZURE_CLIENT_ID는 lakeFS 프로세스 전체에 적용되므로 설치 단위로 하나의 ID를 선택해요. 개별 Azure 블록스토어에 대해 사용자 할당 관리 ID를 선택하려면 managed_identity_client_id를 그 ID의 클라이언트 ID로 설정하세요:

blockstore:
  type: azure
  azure:
    storage_account: mystorageaccount
    managed_identity_client_id: 00000000-0000-0000-0000-000000000000

LAKEFS_BLOCKSTORE_AZURE_MANAGED_IDENTITY_CLIENT_ID를 설정할 수도 있고, 멀티 스토리지 백엔드 구성에서는 스토어별로 blockstores.stores[].azure.managed_identity_client_id를 설정할 수도 있어요.

storage_access_key도 함께 설정되어 있다면 lakeFS는 스토리지 액세스 키를 사용하고 managed_identity_client_id를 무시했다는 경고를 기록해요. 어느 쪽도 설정되어 있지 않으면 lakeFS는 기본 Azure 자격 증명 체인을 사용해요.

리소스 그룹용 서비스 프린시펄 만들기

lakeFS가 접근해야 할 모든 리소스로 이루어진 리소스 그룹을 만드는 것이 좋아요.

리소스 그룹을 사용하면 그룹에서 서비스를 동적으로 추가/제거할 수 있어서, lakeFS 설정을 바꾸거나 lakeFS에 추가 자격 증명을 제공하지 않고도 이 리소스들에 대한 접근을 효과적으로 허용·차단할 수 있어요.

서비스 프린시펄에 필요한 최소 역할은 "Storage Blob Data Contributor"예요

다음 Azure CLI 명령은 "lakeFS"라는 리소스 그룹에 대해 리소스 그룹 내 Blob Storage 리소스에 접근(읽기/쓰기/삭제) 권한을 가지고 5년 후 만료되는 서비스 프린시펄을 생성해요

az ad sp create-for-rbac \
--role "Storage Blob Data Contributor" \
--scopes /subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/resourceGroups/lakeFS --years 5

Creating 'Storage Blob Data Contributor' role assignment under scope '/subscriptions/947382ea-681a-4541-99ab-b718960c6289/resourceGroups/lakeFS'
The output includes credentials that you must protect. Be sure that you do not include these credentials in your code or check the credentials into your source control. For more information, see https://aka.ms/azadsp-cli
{
"appId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"displayName": "azure-cli-2023-01-30-06-18-30",
"password": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"tenant": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
}

명령 출력으로 다음 환경 변수를 채우세요:

AZURE_CLIENT_ID      =  $appId
AZURE_TENANT_ID      =  $tenant
AZURE_CLIENT_SECRET  =  $password

Danger

서비스 프린시펄 자격 증명에는 만료일이 있고, 자격 증명을 제때 갱신하지 않으면 lakeFS가 리소스에 접근하지 못하게 돼요.

Info

Azure 생태계 내부의 배포에서는 관리 ID 사용을 권장해요.

계정 기반 자격 증명과 환경 변수를 모두 lakeFS에 제공할 수도 있어요. 그 경우 lakeFS는 해당 계정 내 데이터 접근에는 계정 자격 증명을, 계정 밖 데이터 접근에는 ID 자격 증명을 사용하려고 시도해요.

인증 방법과 환경 변수에 대한 자세한 내용은 여기에서 확인하세요.

스토리지 계정 자격 증명은 다음 파라미터로 lakeFS 설정에 직접 지정할 수 있어요:

blockstore.azure.storage_account
blockstore.azure.storage_access_key

제한 사항

이 인증 방식을 사용하면 lakeFS가 주어진 스토리지 계정 범위로 한정된다는 점을 유의하세요.

구체적으로 다음 연산은 동작하지 않아요:

다른 스토리지 계정에서의 데이터 임포트
다른 스토리지 계정에서 임포트된 데이터의 복사/읽기/쓰기
다른 스토리지 계정에서 임포트된 데이터의 pre-signed URL 생성

K/V 스토어

lakeFS는 버저닝 엔진을 위해 메타데이터를 데이터베이스에 저장해요. 이는 어떤 DB 엔진으로도 구현할 수 있는 Key-Value 인터페이스를 통해 이루어지며, lakeFS에는 여러 내장 드라이버 구현이 포함되어 있어요 (자세한 내용은 여기에서 읽을 수 있어요).

사용하는 데이터베이스가 꼭 전용 K/V 데이터베이스일 필요는 없어요.

CosmosDBPostgreSQL

CosmosDB는 Azure가 제공하는 관리형 데이터베이스 서비스예요.

lakeFS는 CosmosDB For NoSQL을 데이터베이스 백엔드로 지원해요.

NoSQL용 CosmosDB 계정 생성 방법은 공식 Azure 문서를 따르세요.
CosmosDB 계정이 준비되면 lakeFS용 데이터베이스를 만들 수 있어요. lakeFS의 ACID 보장을 위해 단일 리전 배포에서는 Bounded staleness 일관성을 선택하세요.
데이터베이스 안에 새 컨테이너를 만들고 파티션 키로 partitionKey 유형을 선택하세요 (대소문자 구분).
설정 가이드에 설명된 대로 엔드포인트, 데이터베이스 이름, 컨테이너 이름을 lakeFS에 전달하세요. CosmosDB 계정의 읽기-쓰기 키를 lakeFS에 전달하거나, 앞서 설명한 대로 관리 ID로 CosmosDB에 인증할 수도 있어요.

아래에서는 Azure Database에 데이터베이스를 만드는 방법을 보여주지만, lakeFS 설치에서 접근 가능한 모든 PostgreSQL 데이터베이스를 사용할 수 있어요.

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

PostgreSQL 인스턴스 생성 및 연결 방법은 공식 Azure 문서를 따르세요. PostgreSQL 버전 >= 11을 사용 중인지 확인하세요.
Azure Database for PostgreSQL 서버가 준비되고 Available 상태가 되면 엔드포인트와 사용자명을 기록해 두세요.
액세스 제어 역할이 데이터베이스 인스턴스 연결을 허용하는지 확인하세요.

4. lakeFS 서버 실행

이제 객체 스토리지, K/V 스토어, 인증을 모두 선택하고 구성했으니 lakeFS를 구성하고 실행할 준비가 되었어요. lakeFS를 실행하는 방법은 세 가지가 있어요:

Azure VMDockerAzure Kubernetes Service (AKS)

SSH로 VM 인스턴스에 접속하세요:

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: azure
    azure:

VM에서 실행할 바이너리를 다운로드하세요.
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="azure" \
    -e LAKEFS_BLOCKSTORE_AZURE_STORAGE_ACCOUNT="[YOUR_STORAGE_ACCOUNT]" \
    -e LAKEFS_BLOCKSTORE_AZURE_STORAGE_ACCESS_KEY="[YOUR_ACCESS_KEY]" \
    treeverse/lakefs:latest run

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

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

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

Azure Blob에 맞는 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: azure
        azure:
    #  If you chose to authenticate via access key, unmark the following rows and insert the values from the previous step
    #  storage_account: [your storage account]
    #  storage_access_key: [your access key]

빈 값을 채우고 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 구성 예시를 확인하세요.

관리자 사용자 만들기

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

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

첫 리포지토리 만들기

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

축하합니다

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

더 알아보기 (Learn more)

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