본문 바로가기
WIKI 기술 지식 베이스

lakeFS Enterprise 설치

원문 보기 위키 갱신

lakeFS Enterprise 설치 (셀프 매니지드)

이 가이드는 셀프 매니지드 lakeFS Enterprise를 다뤄요. 직접 운영하고 싶지 않다면 호스티드 배포를 고려해 보세요. 에디션 간 위치를 이해하려면 lakeFS editions 문서를 참고하세요.

출처: 문서

본문

로컬에서 체험하기

프로덕션 배포 전에 lakeFS Enterprise를 가장 빨리 체험하는 방법은 로컬에서 실행하는 것이에요. 이 구성은 평가용이며 프로덕션에 적합하지 않으므로, 준비가 되면 이 페이지 아래쪽의 프로덕션 배포 단계로 넘어가세요.

사전 준비

lakeFS Enterprise를 사용하려면 서버 실행에 라이선스가 필요해요. 라이선스는 문의하기로 받으세요.

lakeFS Enterprise Sample이 가장 빠른 시작점이에요. lakeFS Enterprise, KV 스토어로서의 Postgres, 스토리지용 MinIO 컨테이너, Apache Spark, 데모가 미리 채워진 Jupyter 노트북으로 구성된 바로 쓸 수 있는 환경을 띄워 줘요. 여기에는 접근 제어가 실제로 동작하는 모습을 보여주는 RBAC 데모도 포함되어 있어요.

Docker Compose로 직접 최소 구성을 실행하려면 로컬 블록스토어에 연결되는 docker-compose.yaml을 만들고 docker compose up을 실행한 뒤 http://localhost:8080을 여세요:

version: "3"
services:
  lakefs:
    image: "treeverse/lakefs-enterprise:latest"
    command: "RUN"
    ports:
      - "8000:8000"
    depends_on:
      - "postgres"
    environment:
      - LAKEFS_LISTEN_ADDRESS=0.0.0.0:8000
      - LAKEFS_LOGGING_LEVEL=DEBUG
      - LAKEFS_AUTH_ENCRYPT_SECRET_KEY=random_secret
      - LAKEFS_AUTH_UI_CONFIG_RBAC=internal
      - LAKEFS_DATABASE_TYPE=postgres
      - LAKEFS_DATABASE_POSTGRES_CONNECTION_STRING=postgres://lakefs:***@postgres:5432/postgres?sslmode=disable
      - LAKEFS_BLOCKSTORE_TYPE=local
      - LAKEFS_BLOCKSTORE_LOCAL_PATH=/home/lakefs
      - LAKEFS_BLOCKSTORE_LOCAL_IMPORT_ENABLED=true
      - LAKEFS_AUTH_POST_LOGIN_REDIRECT_URL=http://localhost:8000/
      - LAKEFS_FEATURES_LOCAL_RBAC=true
      - LAKEFS_LICENSE_CONTENTS=<license token> # for production use, we recommend using LAKEFS_LICENSE_PATH instead
    configs:
      - source: lakefs.yaml
        target: /etc/lakefs/config.yaml
  postgres:
    image: "postgres:11"
    ports:
      - "5433:5432"
    environment:
      POSTGRES_USER: lakefs
      POSTGRES_PASSWORD: lakefs

configs:
  lakefs.yaml:
    content: |
      auth:
        ui_config:
          login_cookie_names:
            - internal_auth_session

샘플 리포지토리에는 OIDC가 구성된 SSO 활성화 Docker Compose 변형도 포함되어 있어요. 싱글 사인온 평가를 시작할 준비가 되었을 때 유용해요.

대신 Kubernetes에서 체험하려면 helm repo add lakefs https://charts.lakefs.io로 Helm 리포지토리를 추가하고, values.yaml을 만들어 helm install lakefs lakefs/lakefs -f values.yaml을 실행하세요. 아래 values는 SSO 없이 로컬 블록스토어와 개발용 Postgres에 연결된, 동작 가능한 Enterprise 구성을 띄워 줘요:

enterprise:
  enabled: true

lakefsConfig: |
  logging:
    level: "DEBUG"
  blockstore:
    type: local
  auth:
    ui_config:
      rbac: internal

ingress:
  enabled: true
  ingressClassName: <ingress-class-name>
  annotations: {}
  hosts:
    - host: <lakefs.acme.com>
      paths:
       - /

# useDevPostgres is false by default and will override any other db configuration,
# set false or remove for configuring your own db
useDevPostgres: true

프로덕션 배포

lakeFS Enterprise의 프로덕션 배포는 이 가이드의 나머지 부분을 따르세요.

lakeFS Enterprise 아키텍처

배포할 컴포넌트를 이해하려면 lakeFS Enterprise 아키텍처를 먼저 검토하는 것을 권장해요.

Note

Fluffy 서비스는 차트 버전 1.5.0 이상에서 지원 중단(deprecated)되었어요. 자세한 내용은 Upgrade Guide를 참고하세요.

Kubernetes에 lakeFS Enterprise 배포하기

이 가이드는 lakeFS Helm Chart를 사용해 완전히 동작하는 lakeFS Enterprise를 배포해요.

가이드에는 예제 구성이 포함되어 있으니 아래 단계를 따르고 예제 구성을 다음에 맞게 조정하세요:

  • 실행 플랫폼: lakeFS가 지원하는 플랫폼 중에서

  • 사용하는 KV 스토어 유형

  • 여러분의 SSO IdP와 프로토콜

사전 준비

  • lakeFS가 지원하는 플랫폼 중 하나에서 실행 중인 Kubernetes 클러스터가 있어요.

  • Helm이 설치되어 있어요

  • lakeFS Enterprise 기능 접근을 위해 문의하기를 진행했어요.

  • KV 데이터베이스. 사용 가능한 옵션은 배포 플랫폼에 따라 달라요.

  • 클러스터 밖에서 lakeFS로 트래픽을 라우팅하는 방법(Ingress 또는 Service).

선택 사항

lakeFS Enterprise가 지원하는 SSO IdP 구성 접근 권한.

Info

SSO를 구성하지 않고 lakeFS Enterprise를 설치해도 다른 모든 lakeFS Enterprise 기능은 그대로 활용할 수 있어요.

lakeFS Enterprise 라이선스

lakeFS Enterprise를 사용하려면 유효한 라이선스가 필요해요. 이 라이선스는 lakeFS Enterprise 서버와 유료 기능에 대한 접근을 제공하는 JSON Web Token(JWT)이에요. 라이선스는 설치 ID로 특정 설치에, 조직 ID로 특정 조직에 묶여 있어요.

라이선스가 필요한 기능

다음 lakeFS Enterprise 기능들은 사용 가능하려면 lakeFS Enterprise 라이선스에 포함되어 있어야 해요:

인증 및 권한 부여

  • SSO (Single Sign-On)

  • RBAC (Role-Based Access Control)

  • SCIM (System for Cross-domain Identity Management)

  • IAM (Identity and Access Management) Role Authentication

고급 기능

  • Mount

  • Iceberg Catalog

  • Metadata Search

  • MSB (Multiple Storage Backends)

  • Transactional Mirroring

  • Sparkless GC (Garbage Collection)

Warning

이 기능들에 대한 라이선스가 없으면 비활성화되고, 접근을 시도하면 'feature not licensed' 오류가 발생해요.

lakeFS Enterprise 라이선스 구성

  • 라이선스를 받으려면 지원팀에 문의

📧 이메일: [email protected]

  • 라이선스 토큰 받기

받게 될 라이선스 토큰에는 다음이 포함되어 있어요:

  • Organization ID

  • Installation ID

  • 발급일

  • 만료일

  • 활성화된 기능

  • 기능 제한 사항

  • lakeFS Enterprise 서버 구성

  • 라이선스 토큰을 파일로 저장하세요.

  • lakeFS Enterprise 설정 파일에 파일 경로를 지정하세요:

license:
  path: "/path/to/your/license.txt"

Tip

lakeFS Enterprise 설정 파일 대신 환경 변수 LAKEFS_LICENSE_PATH로 라이선스 토큰 경로를 설정할 수도 있어요.

액티베이션 키 (lakeFS Team)

lakeFS Team 구독은 라이선스 토큰 대신 액티베이션 키를 제공해요. lakeFS가 키를 라이선스로 교환하고 구독이 활성 상태인 동안 갱신을 유지해요:

license:
  activation_key: "<your activation key>"

키는 환경 변수 LAKEFS_LICENSE_ACTIVATION_KEY로도 설정할 수 있어요. 이것과 함께 license.path나 license.contents는 설정하지 마세요.

  • lakefs run은 처음 시작할 때 라이선스를 가져오고 매일 갱신해요. 라이선스는 KV 스토어에 보관되므로 모든 레플리카와 다른 모든 lakeFS 프로세스(예: 메타데이터 검색 서비스)가 동일한 것을 읽고 1분 이내에 갱신을 반영해요.

API로 현재 설치된 라이선스 토큰 읽기

요청:

GET https://your-lakefs-server/api/v1/license

응답:

{
  "token": "eyJhbG...NiIs..."
}

반환된 토큰은 아무 JWT 디코딩 도구로 디코딩해 라이선스 정보를 볼 수 있어요.

라이선스 모니터링 및 업데이트

라이선스 갱신

  • 라이선스 파일 내용을 새 라이선스 토큰으로 교체하세요.

  • lakeFS Enterprise가 1분 이내에 새 라이선스를 자동 감지하고 다시 로드해요.

Warning

서버가 실행 중일 때 파일 경로 자체를 새 파일로 바꿀 수는 없어요.

자동 모니터링

  • 검증 및 만료 확인: 라이선스 유효성과 만료를 주기적으로 확인해요.

  • 파일 모니터링: 서버가 주기적으로 확인해 라이선스 파일 변경을 감지해요. 라이선스 토큰이 파일에서 갱신되면 서버를 재시작할 필요 없이 라이선스가 자동으로 업데이트돼요.

트러블슈팅

서버가 시작되지 않아요

Error: lakeFS Enterprise requires a valid license.

Set 'license.path', 'license.contents' or 'license.activation_key' in your
configuration file, or set LAKEFS_LICENSE_PATH, LAKEFS_LICENSE_CONTENTS or
LAKEFS_LICENSE_ACTIVATION_KEY in the environment.

해결: lakeFS Enterprise 설정 파일이나 환경 변수에 license.path를 설정했는지, lakeFS Team이라면 license.activation_key를 설정했는지 확인하세요.

라이선스 서명 검증 실패

Error: token signature did not match any known public key: token signature is invalid: crypto/rsa

해결 방법:

1. 라이선스 토큰을 원본 소스에서 다시 다운로드하세요.

2. 라이선스 파일에 라이선스 토큰만 있고 여분의 문자나 줄바꿈이 없는지 확인하세요.

3. 유효한 라이선스 토큰을 받으려면 [email protected] 로 연락하세요.

라이선스 만료

Error: license has expired. Please contact support immediately: invalid license found
Error: license expired: invalid expiry date

해결 방법:

1. 최근에 갱신했다면 라이선스 파일에 새 토큰으로 업데이트했는지 확인하세요.

2. 라이선스 갱신을 위해 즉시 [email protected] 로 연락하세요.

라이선스 파일을 찾을 수 없어요

Error: open /path/to/license/file/you/provided: no such file or directory

해결 방법:

1. `license.path` 설정의 정확한 경로와 파일명을 확인하세요.

2. 파일명의 오탈자를 확인하세요.

3. 설정 후 라이선스 파일이 이동되거나 삭제되지 않았는지 확인하세요.

4. 지정한 위치에 라이선스 파일이 존재하는지 확인하세요.

5. 파일 확장자가 포함되어 있는지 확인하세요.

6. 상대 경로 대신 절대 경로를 사용하세요.

라이선스 파일 권한 거부됨

Error: open /path/to/license/file/you/provided: permission denied

해결 방법:

1. 파일 권한을 확인하고 적절히 설정하세요.

2. lakeFS Enterprise 프로세스가 파일과 상위 디렉터리를 읽고 접근할 권한이 있는지 확인하세요.

설치 ID 불일치

Error: license belongs to installation ID X (current installation ID: Y)

해결 방법:

1. 이 특정 설치에 맞는 올바른 라이선스 파일인지 확인하세요.

2. 설치 ID가 변경되지 않았는지 확인하세요.

3. 올바른 새 라이선스를 받으려면 [email protected] 로 연락하세요.

형식이 잘못되었거나 비어 있는 라이선스 토큰

Error: parsing token: token is malformed: token contains an invalid number of segments
Error: license has invalid expiry (no license?): invalid license found

해결 방법:

1. 라이선스 파일에 완전한 라이선스 토큰이 들어 있는지 확인하세요.

2. 라이선스 파일에서 여분의 공백, 줄바꿈, 문자를 제거하세요.

3. 라이선스 토큰을 원본 소스에서 다시 복사하세요.

4. 파일에 라이선스 토큰만 있고 다른 것은 없는지 확인하세요.

기능을 사용할 수 없어요

Error: feature not licensed - to enable, contact [email protected]

해결: 현재 라이선스에 이 기능이 포함되어 있지 않아요. 라이선스 업그레이드를 위해 [email protected] 로 연락하세요.

도움이 필요하신가요?

여기서 다루지 않는 문제를 만나면 [email protected] 로 지원팀에 연락하세요.

lakeFS Helm 차트 추가

  • helm repo add lakefs https://charts.lakefs.io로 lakeFS Helm 리포지토리를 추가하세요

  • 차트에는 이 가이드를 따라가며 필요에 맞게 커스터마이즈할 수 있는 values.yaml이 포함되어 있어요. helm show values lakefs/lakefs로 기본 값을 볼 수 있어요.

라이선스 구성

Note

당장은 이 단계 없이 진행할 수 있어요. 하지만 라이선스 강제 적용이 곧 도입될 예정이에요. 설치 라이선스를 받으려면 지원팀에 연락하세요.

lakeFS Enterprise는 동작하려면 유효한 라이선스가 필요해요. Helm 차트에서 라이선스는 기존 시크릿이나 명시적으로 JWT 토큰 형태로 제공돼요. values 파일에서 라이선스를 구성하는 방법은 다음과 같아요:

시크릿에 토큰을 담아 제공하는 라이선스License with token provided from existing secret

enterprise:
  enabled: true

secrets:
    licenseContents: <Your licese JWT token>
enterprise:
  enabled: true

# Name of existing secret to use
existingSecret: <Name of existing secret>

secretKeys:
  # Use to fetch license token from an existing secret:
   licenseContentsKey: <Name of license contents key from existing secret>

인증 구성

lakeFS Enterprise의 인증은 lakeFS Enterprise 서비스가 직접 처리해요. 이 섹션은 SSO 설정에 필요한 구성을 설명해요.

지원되는 IdP와 프로토콜은 SSO for lakeFS Enterprise 문서를 참고하세요.

아래 예시에는 지원되는 각 SSO 프로토콜의 예제 구성이 포함되어 있어요. IdP별 세부 사항은 여러분의 IdP 정보로 교체해야 한다는 점을 유의하세요.

OpenID ConnectSAML (With Azure AD)LDAP

다음 values 파일은 OIDC 통합으로 lakeFS Enterprise를 실행해요.

Tip

여기서 설명하는 전체 OIDC 구성은 문서에서 확인하세요.

enterprise:
  enabled: true
  auth:
    oidc:
      enabled: true
      # secret given by the OIDC provider (e.g auth0, Okta, etc)
      client_secret: <oidc-client-secret>

lakefsConfig: |
  logging:
    level: "INFO"
  blockstore:
    type: s3
  auth:
    logout_redirect_url: https://oidc-provider-url.com/logout/example
    oidc:
      # the claim that's provided by the OIDC provider (e.g Okta) that will be used as the username according to OIDC provider claims provided after successful authentication
      friendly_name_claim_name: "<some-oidc-provider-claim-name>"
      default_initial_groups: ["Developers", "Admins"]
      # if true then the value of friendly_name_claim_name will be refreshed during each login to maintain the latest value
      # and the the claim value (i.e user name) will be stored in the lakeFS database
      persist_friendly_name: true
    providers:
      oidc:
        post_login_redirect_url: /
        url: https://oidc-provider-url.com/
        client_id: <oidc-client-id>
        callback_base_url: https://<lakefs.acme.com>
        # the claim name that represents the client identifier in the OIDC provider (e.g Okta)
        logout_client_id_query_parameter: client_id
        # the query parameters that will be used to redirect the user to the OIDC provider after logout
        logout_endpoint_query_parameters:
          - returnTo
          - https://<lakefs.acme.com>/oidc/login

ingress:
  enabled: true
  ingressClassName: <class-name>
  hosts:
    - host: <lakefs.acme.com>
      paths:
        - /

다음 values 파일은 Azure AD를 IdP로 사용해 SAML로 lakeFS Enterprise를 실행해요.

이 예제 구성으로 Active Directory Federation Services(AD FS)를 SAML로 구성할 수도 있어요.

Tip

여기서 설명하는 전체 SAML 구성은 문서에서 확인하세요.

Azure 앱 구성

SAML 구성

  • IdP(예: Azure AD)에서 SAML 애플리케이션을 구성하고 필요한 파라미터를 아래 values.yaml에 넣으세요.

  • 인증서 키페어 생성: openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=lakefs.acme.com"

enterprise:
  enabled: true
  auth:
    saml:
      enabled: true
      createCertificateSecret: true  # NEW: Auto-creates secret
      certificate:
        # certificate and private key for the SAML service provider to sign outgoing SAML requests
        samlRsaPublicCert: |          # RENAMED: from saml_rsa_public_cert
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----
        samlRsaPrivateKey: |          # RENAMED: from saml_rsa_private_key
          [REDACTED PRIVATE KEY]

secrets:
  authEncryptSecretKey: "some random secret string"

lakefsConfig: |
  logging:
    level: "DEBUG"
  blockstore:
    type: local
  auth:
    logout_redirect_url: https://<lakefs.acme.com>
    cookie_auth_verification:
      auth_source: saml
      # claim name to use for friendly name in lakeFS UI
      friendly_name_claim_name: displayName
      external_user_id_claim_name: samName
      default_initial_groups:
        - "Developers"
    providers:
      saml:
        post_login_redirect_url: https://<lakefs.acme.com>
        sp_root_url: https://<lakefs.acme.com>
        sp_sign_request: false
        sp_signature_method: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
        idp_metadata_url: "https://<adfs-auth.company.com>/federationmetadata/2007-06/federationmetadata.xml"
        # the default id format urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
        # idp_authn_name_id_format: "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
        idp_skip_verify_tls_cert: true

ingress:
  enabled: true
  ingressClassName: <class-name>
  annotations: {}
  hosts:
    - host: <lakefs.acme.com>
      paths:
        - /

다음 values 파일은 LDAP로 lakeFS Enterprise를 실행해요.

Tip

여기서 설명하는 전체 LDAP 구성은 문서에서 확인하세요.

enterprise:
  enabled: true
  auth:
    ldap:
      enabled: true
      bindPassword: <ldap bind password>

lakefsConfig: |
  logging:
    level: "INFO"
  blockstore:
    type: local
  auth:
    ui_config:
      login_url: /auth/login
      logout_url: /logout
      login_cookie_names:
        - internal_auth_session
    providers:
      ldap:
        server_endpoint: 'ldaps://ldap.company.com:636'
        bind_dn: uid=<bind-user-name>,ou=Users,o=<org-id>,dc=<company>,dc=com
        username_attribute: uid
        user_base_dn: ou=Users,o=<org-id>,dc=<company>,dc=com
        user_filter: (objectClass=inetOrgPerson)
        connection_timeout_seconds: 15
        request_timeout_seconds: 17
        # RBAC group for first time users
        default_user_group: "Developers"

ingress:
  enabled: true
  ingressClassName: <class-name>
  hosts:
    - host: <lakefs.acme.com>
      paths:
        - /

각 인증 방식(oidc, saml, ldap, rbac, external AWS IAM)에 대해 우리가 제공하는 GitHub의 추가 예시를 참고하세요.

데이터베이스 구성

이 섹션에서는 lakeFS Enterprise가 만들어 둔 KV 데이터베이스(사전 준비 참고)와 함께 동작하도록 구성하는 방법을 배워요.

참고 사항:

  • 기본적으로 lakeFS Helm 차트는 useDevPostgres: false로 제공되며, 개발 용도라면 useDevPostgres: true로 바꿀 수 있어요. 이 구성은 멀티 레플리카 구성을 실행하거나 컨테이너 재시작 사이의 데이터 손실을 막고 싶을 때 유용해요.

  • lakeFS 데이터베이스 구성 문서를 참고하세요.

데이터베이스 구성은 lakefsConfig로 직접 설정하거나, K8S Secret Kind로, 또는 환경 변수로 지정할 수 있어요.

환경 변수로 PostgresPostgres via lakefsConfig공유 Secret Kind로 Postgres

이 예시는 환경 변수로 구성된 KV 데이터베이스로서의 Postgres를 사용해요.

extraEnvVars:
  - name: LAKEFS_DATABASE_TYPE
    value: postgres
  - name: LAKEFS_DATABASE_POSTGRES_CONNECTION_STRING
    value: '<postgres connection string>'

이 예시는 KV 데이터베이스로 DynamoDB를 사용해요.

lakefsConfig: |
  database:
    type: dynamodb
    dynamodb:
      table_name: <table>
      aws_profile: <profile>
      aws_region: <region>

이 예시는 KV 데이터베이스로 Postgres를 사용해요. 차트가 데이터베이스 연결 문자열을 담은 kind: Secret을 생성해요.

secrets:
  authEncryptSecretKey: shared-key-hello
  databaseConnectionString: <postgres connection string>

lakefsConfig: |
  database:
    type: postgres

lakeFS Helm 차트 설치

values.yaml 파일에 필요한 구성을 채운 뒤, 원하는 K8S 네임스페이스에서 helm install lakefs lakefs/lakefs -f values.yaml을 실행하세요.

lakeFS UI 접근

브라우저에서 Ingress 호스트로 이동해 lakeFS UI에 접근하세요.

로그 수집

권장되는 로그 수집 방식은 컨테이너 표준 출력(기본 구성)으로 로그를 보내고 외부 서비스가 그것을 싱크로 수집하게 하는 것이에요. 로그 컬렉터의 예로는 fluentbit이 있어요. 컨테이너 로그를 수집하고, 형식을 정하고, S3 같은 대상으로 전송할 수 있어요.

로그에는 두 종류가 있어요:

  • 디버깅에 쓰이는 API 오류나 이벤트 설명 같은 일반 로그
  • 사용자 액션(예: create branch)을 설명하는 감사 로그

일반 로그와 audit_logs의 구분은 boolean 필드 log_audit로 이루어지며, 자세한 내용은 감사 레퍼런스에서 확인할 수 있어요.

고급 배포 구성

다음 예시는 lakeFS용 HTTP 프록시 구성, Ingress용 TLS 인증서, Helm 차트를 포크하지 않고 K8S 매니페스트를 확장하는 시나리오를 보여줘요.

ingress:
  enabled: true
  ingressClassName: <class-name>
  # configure TLS certificate for the Ingress
  tls:
    - hosts:
      - lakefs.acme.com
      secretName: somesecret
  hosts:
    - host: lakefs.acme.com
      paths:
       - /

# configure proxy for lakeFS
extraEnvVars:
  - name: HTTP_PROXY
    value: 'http://my.company.proxy:8081'
  - name: HTTPS_PROXY
    value: 'http://my.company.proxy:8081'

# advanced: extra manifests to extend the K8S resources
extraManifests:
  - apiVersion: v1
    kind: ConfigMap
    metadata:
      name: '{% raw %}{{ .Values.lakefs.name }}{% endraw %}-extra-config'
    data:
      config.yaml: my-data

더 알아보기 (Learn more)

공식 문서의 lakeFS Enterprise 설치 페이지는 https://docs.lakefs.io/admin/install/enterprise 에서 확인할 수 있어요.