AWS에 lakeFS 배포

원문 보기 위키 갱신 2026.10.11

Tip

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

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

출처: 문서

본문

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

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

⏰ 예상 배포 시간: 25분

필요한 기술 지식과 접근 권한

AWS에서 lakeFS를 성공적으로 배포·운영하려면 다음 주제에 익숙하고 해당 수준의 접근 권한을 갖추고 있어야 해요.

AWS 계정 관리

IAM 역할과 정책을 생성·수정할 수 있는 능력
S3 버킷과 프리픽스를 생성·구성할 수 있는 능력
AWS 계정에 네트워킹과 컴퓨트 리소스를 프로비저닝할 권한 (예: VPC, 서브넷, 보안 그룹, 로드밸런서, EC2, ECS, EKS)

lakeFS가 사용하는 핵심 AWS 서비스

Amazon S3 – 버킷 레이아웃, 프리픽스, 암호화 옵션, 라이프사이클 규칙.
메타데이터 백엔드, 둘 중 하나:
Amazon DynamoDB
PostgreSQL / Amazon RDS for PostgreSQL
Amazon MemoryDB

어떤 메타데이터 백엔드를 선택하든 설정, 연결성, 스토리지·영속성 구성, 백업, 모니터링을 수행할 수 있어야 해요.

선택 사항: 컨테이너와 오케스트레이션 지식

선택한 배포 모델에 따라:

Kubernetes / Amazon EKS – Deployment, Service, Ingress, kubectl에 대한 이해, 그리고 선택적으로 Helm.
Amazon ECS 또는 컨테이너를 쓰는 EC2 – 태스크 정의, 서비스, 컨테이너 로그, 태스크용 IAM 역할에 대한 이해.

lakeFS에 DynamoDB 권한 부여하기

기본적으로 lakeFS는 필요한 DynamoDB 테이블이 아직 없다면 직접 생성해요. lakeFS가 사용하는 IAM 역할에 다음 권한을 부여해야 해요:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "ListAndDescribe",
            "Effect": "Allow",
            "Action": [
                "dynamodb:List*",
                "dynamodb:DescribeReservedCapacity*",
                "dynamodb:DescribeLimits",
                "dynamodb:DescribeTimeToLive"
            ],
            "Resource": "*"
        },
        {
            "Sid": "kvstore",
            "Effect": "Allow",
            "Action": [
                "dynamodb:BatchGet*",
                "dynamodb:DescribeTable",
                "dynamodb:Get*",
                "dynamodb:Query",
                "dynamodb:Scan",
                "dynamodb:BatchWrite*",
                "dynamodb:CreateTable",
                "dynamodb:Delete*",
                "dynamodb:Update*",
                "dynamodb:PutItem"
            ],
            "Resource": "arn:aws:dynamodb:*:*:table/kvstore"
        }
    ]
}

Tip

DynamoDB 대신 PostgreSQL을 사용할 수도 있어요!

자세한 내용은 설정 레퍼런스를 참고하세요.

lakeFS 서버 실행하기

EC2EKS

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

EC2 인스턴스에 다음 파라미터로 config.yaml을 만드세요:

---
database:
    type: "dynamodb"

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

blockstore:
    type: s3

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

lakefs --config config.yaml run

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

Advanced: lakeFS를 AWS Application Load Balancer 뒤에 배포하기

보안 그룹이 로드밸런서가 lakeFS 서버에 접근할 수 있게 해야 해요.
포트 8000용 리스너를 가진 타겟 그룹을 만드세요.
사용할 도메인 이름으로 TLS 종단(termination)을 구성하세요 (예: lakefs.example.com, 그리고 virtual-host addressing을 쓴다면 s3.lakefs.example.com, *.s3.lakefs.example.com).
헬스 체크가 노출된 /_health URL을 사용하도록 구성하세요

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

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

S3에 맞는 Helm values 파일을 복사하세요:

secrets:
    # replace this with a randomly-generated string
    authEncryptSecretKey: [ENCRYPTION_SECRET_KEY]
lakefsConfig: |
    database:
        type: dynamodb
    blockstore:
        type: 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 이름이에요.

Warning Kubernetes 노드가 lakeFS와 함께 사용하려는 모든 버킷/컨테이너에 접근할 수 있는지 확인하세요. 그렇게 할 수 없다면 lakeFS를 AWS 키페어로 구성해야 해요.

로드밸런싱

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

Tip

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

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

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

S3 버킷 준비

lakeFS와 함께 사용할 버킷 이름을 기록해 두세요
다음을 버킷 정책으로 사용하되 플레이스홀더를 채우세요:

Standard PermissionsStandard Permissions (with s3express)Minimal Permissions (Advanced)

{
    "Id": "lakeFSPolicy",
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "lakeFSObjects",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:AbortMultipartUpload",
                "s3:ListMultipartUploadParts"
            ],
            "Effect": "Allow",
            "Resource": ["arn:aws:s3:::[BUCKET_NAME_AND_PREFIX]/*"],
            "Principal": {
                "AWS": ["arn:aws:iam::[ACCOUNT_ID]:role/[IAM_ROLE]"]
            }
        },
        {
            "Sid": "lakeFSBucket",
            "Action": [
                "s3:ListBucket",
                "s3:GetBucketLocation",
                "s3:ListBucketMultipartUploads"
            ],
            "Effect": "Allow",
            "Resource": ["arn:aws:s3:::[BUCKET]"],
            "Principal": {
                "AWS": ["arn:aws:iam::[ACCOUNT_ID]:role/[IAM_ROLE]"]
            }
        }
    ]
}

[BUCKET_NAME], [ACCOUNT_ID], [IAM_ROLE]을 여러분 환경에 맞는 값으로 교체하세요.
[BUCKET_NAME_AND_PREFIX]는 버킷 이름이어도 돼요. 버킷 정책 권한을 최소화하고 싶다면 버킷 이름에 프리픽스를 함께 쓰세요 (예: example-bucket/a/b/c). 이렇게 하면 lakeFS가 이 특정 경로 아래에서만 리포지토리를 만들 수 있어요 (참고: Storage Namespace).
lakeFS는 [IAM_ROLE] 역할을 수임하려고 시도해요.

S3 Express One Zone 디렉터리 버킷을 사용하려면 다음 정책을 쓰세요. 디렉터리 버킷 사용에 특별히 필요한 lakeFSDirectoryBucket 문을 주목하세요.

{
    "Id": "lakeFSPolicy",
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "lakeFSObjects",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:AbortMultipartUpload",
                "s3:ListMultipartUploadParts"
            ],
            "Effect": "Allow",
            "Resource": ["arn:aws:s3:::[BUCKET_NAME_AND_PREFIX]/*"],
            "Principal": {
                "AWS": ["arn:aws:iam::[ACCOUNT_ID]:role/[IAM_ROLE]"]
            }
        },
        {
            "Sid": "lakeFSBucket",
            "Action": [
                "s3:ListBucket",
                "s3:GetBucketLocation",
                "s3:ListBucketMultipartUploads"
            ],
            "Effect": "Allow",
            "Resource": ["arn:aws:s3:::[BUCKET]"],
            "Principal": {
                "AWS": ["arn:aws:iam::[ACCOUNT_ID]:role/[IAM_ROLE]"]
            }
        },
        {
            "Sid": "lakeFSDirectoryBucket",
            "Action": [
                "s3express:CreateSession"
            ],
            "Effect": "Allow",
            "Resource": "arn:aws:s3express:[REGION]:[ACCOUNT_ID]:bucket/[BUCKET_NAME]"
        }
    ]
}

[BUCKET_NAME], [ACCOUNT_ID], [IAM_ROLE]을 여러분 환경에 맞는 값으로 교체하세요.
[BUCKET_NAME_AND_PREFIX]는 버킷 이름이어도 돼요. 버킷 정책 권한을 최소화하고 싶다면 버킷 이름에 프리픽스를 함께 쓰세요 (예: example-bucket/a/b/c). 이렇게 하면 lakeFS가 이 특정 경로 아래에서만 리포지토리를 만들 수 있어요 (참고: Storage Namespace).
lakeFS는 [IAM_ROLE] 역할을 수임하려고 시도해요.

필요하다면 lakeFS는 데이터 자체에 접근하지 않고 동작할 수 있어요. 이 권한 구성은 presigned URL 모드를 쓰거나 lakeFS Hadoop FileSystem Spark 통합을 사용할 때 유용해요. 이 FileSystem은 스토리지에서 많은 연산을 직접 수행하므로 lakeFS에 덜 관대한 권한만 요구되고, 그만큼 보안이 강화돼요.

lakeFS는 여러분의 스토리지 네임스페이스 아래 _lakefs 프리픽스에 접근할 권한을 항상 요구해요. 이곳에 메타데이터가 저장돼요 (더 알아보기).

이 정책을 presign 모드 없이 설정하면 lakeFS를 통해서는 메타데이터 연산만 수행할 수 있어요. 즉 lakeFS로 객체를 업로드하거나 다운로드할 수 없어요. 구체적으로 다음이 불가능해요:

lakeFS GUI로 객체 업로드 (presign 모드에서 동작)
S3 게이트웨이를 통한 Spark 객체 업로드
lakectl fs 명령 실행 (--pre-sign 플래그로 presign 모드를 쓰는 경우 제외)
Actions와 Hooks 사용

{
    "Id": "[POLICY_ID]",
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "lakeFSObjects",
            "Action": [
                "s3:GetObject",
                "s3:PutObject"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:s3:::[STORAGE_NAMESPACE]/_lakefs/*"
            ],
            "Principal": {
                "AWS": ["arn:aws:iam::[ACCOUNT_ID]:role/[IAM_ROLE]"]
            }
        },
        {
            "Sid": "lakeFSBucket",
            "Action": [
                "s3:ListBucket",
                "s3:GetBucketLocation"
            ],
            "Effect": "Allow",
            "Resource": ["arn:aws:s3:::[BUCKET]"],
            "Principal": {
                "AWS": ["arn:aws:iam::[ACCOUNT_ID]:role/[IAM_ROLE]"]
            }
        }
    ]
}

presigned URL 모드를 사용하면 lakeFS 서버가 데이터에 직접 접근할 수 없어도 돼요. 조건 키인 aws:referer, aws:SourceVpc, aws:SourceVpcArn, aws:SourceIp를 사용해 이를 달성할 수 있어요.

예를 들어 다음 시나리오를 가정해 볼게요

lakeFS가 회사 밖에 배포되어 있음 (즉 lakeFS cloud 또는 vpc-123이 아닌 다른 VPC)
lakeFS가 데이터에 접근하지 못하게 하고 싶어서 presign URL을 사용하지만, lakeFS 역할이 URL에 서명할 수는 있어야 해요.
회사 내부 VPC vpc-123에서의 접근은 허용하고 싶어요.
lakeFS와 회사 버킷이 같은 리전에 배포되어 있고, 그 경우가 us-east-1이에요.

{
    "Sid": "allowLakeFSRoleFromCompanyOnly",
    "Effect": "Allow",
    "Principal": {
        "AWS": "arn:aws:iam::[ACCOUNT_ID]:role/[IAM_ROLE]"
    },
    "Action": [
        "s3:GetObject",
        "s3:PutObject",
    ],
    "Resource": [
        "arn:aws:s3:::[BUCKET]/*",
    ],
    "Condition": {
        "StringEquals": {
            "aws:SourceVpcArn": "arn:aws:ec2:us-east-1:*:vpc/vpc-123"
        }
    }
}

S3 스토리지 티어 클래스

lakeFS는 현재 다음 S3 스토리지 클래스를 지원해요:

S3 Standard - AWS S3 기본 스토리지 티어. 완전 지원.
S3 Express One-Zone - 완전 지원.
S3 Glacier Instant Retrival - 제한적으로 지원: 현재 Instant Retrival 사용 시 pre-signed URL은 지원되지 않아요. 진행 중인 기능 요청은 여기서 추적할 수 있어요.

다른 스토리지 클래스는 현재 지원되지 않아요 - lakeFS와 테스트되지 않았거나 지원 자체가 불가능하기 때문이에요.

지원 목록에 없는 스토리지 티어가 필요하다면 GitHub에 이슈를 열어 주세요.

대안: AWS 사용자 사용하기

lakeFS는 액세스 키와 시크릿으로 AWS 사용자를 통해 여러분의 AWS 계정과 인증할 수 있어요. 이를 위해 정책의 Principal을 다음처럼 변경하세요:

 "Principal": {
   "AWS": ["arn:aws:iam::<ACCOUNT_ID>:user/<IAM_USER>"]
 }

관리자 사용자 만들기

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

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

첫 리포지토리 만들기

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

축하합니다

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

더 알아보기 (Learn more)

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