lakeFS Enterprise 설정 레퍼런스

원문 보기 위키 갱신 2026.10.11

lakeFS Enterprise 설정은 lakeFS 설정을 확장하며 같은 설정 파일을 사용해요. 이 페이지는 Enterprise 전용 설정 항목들을 다뤄요. 클라이언트 IP 해석, Redis 데이터베이스, SSO/SAML/OIDC/LDAP 인증, 멀티 스토리지 백엔드, 자격 증명 자동 발급(credential vending), 감사 로그 Iceberg 파이프라인 등을 확인할 수 있어요.

출처: 문서

본문

lakeFS Enterprise 설정은 lakeFS의 설정을 확장하고 같은 설정 파일을 사용해요.

lakeFS 설정

설정 옵션의 전체 목록은 lakeFS Server Configuration을 참고하세요. 아래 섹션들은 메인 설정 가이드를 보완하는 추가 설정 레퍼런스를 제공해요.

레퍼런스

이 레퍼런스는 값의 중첩을 .으로 표기해요.

클라이언트 IP 해석

lakeFS는 각 요청의 클라이언트 IP를 한 번 해석하고, 클라이언트 주소를 읽는 모든 기능이 그 결과를 사용해요. 클라이언트는 X-Forwarded-For 같은 포워딩 헤더에 어떤 값이든 넣을 수 있으므로, ip_strategy가 어떤 헤더를(있다면) 믿을지 결정해요.

Info

lakeFS Cloud에서는 서비스가 각 설치 앞의 로드밸런서와 그에 딸린 클라이언트 IP 설정을 함께 관리해요. 그래서 아래 키들은 셀프 관리형 lakeFS Enterprise에 적용돼요.

ip_strategy (one of ["direct", "proxy", "platform"] : "proxy") - 요청의 클라이언트 주소를 어디서 가져올지예요.

direct``proxy``platform

TCP 연결의 주소이며, 어떤 헤더도 참조하지 않아요. 클라이언트와 lakeFS 사이에 아무것도 없을 때와 로컬 개발에 사용하세요.

X-Forwarded-For, 이어서 X-Real-IP를, 연결이 trusted_proxies 안의 주소에서 온 경우에만 존중해요. 로드밸런서, 리버스 프록시, Kubernetes 인그레스 뒤에서 사용하고, trusted_proxies를 그 프록시가 실제로 쓰는 주소로 설정하세요. 빈 목록은 어떤 헤더도 존중하지 않아서, 해석 동작은 direct와 같아지고(포워딩 헤더를 실어 보낸 요청을 세는 것만 다름) 그 내용은 Monitoring client IP resolution에서 설명돼요.

trusted_platform_header가 지정한 헤더를, 어떤 연결에서든 읽고 proxy 전략보다 우선해요. proxy 전략은 이 헤더 없이 도착한 요청을 처리해요. 클라이언트 주소를 자체 헤더로 보고하는 CDN 뒤에서, 그리고 CDN을 우회해 lakeFS에 도달할 수 없는 곳에서만 사용하세요. 서버에 직접 도달한 클라이언트가 그 헤더를 직접 넣을 수 있으니까요.

trusted_proxies (list of strings : ["0.0.0.0/0", "::/0"]) - lakeFS 앞에 있는 프록시들의 CIDR 블록이나 단일 주소예요. proxy 전략이 읽어요.

Warning

기본값은 모든 네트워크를 신뢰하는데, 안전하지 않아요: lakeFS에 도달할 수 있는 어떤 클라이언트든 자기가 넣은 X-Forwarded-For 헤더로, 정책이 평가하고 감사 로그가 기록할 주소를 골라낼 수 있어요. trusted_proxies를 여러분의 프록시가 실제로 쓰는 주소로 설정하거나, 포워딩 헤더를 전부 무시하려면 빈 목록으로 두세요. 모든 네트워크를 신뢰하는 게 적절한 경우는, 자신이 관찰한 주소로 X-Forwarded-For를 교체하는 프록시가 lakeFS로의 유일한 경로일 때뿐이에요.

trusted_platform_header (string : "") - platform 전략이 읽는 프로바이더 헤더의 이름이에요. 흔히 CF-Connecting-IP, True-Client-IP, X-Cloudfront-Viewer-Address예요. platform 전략 아래에서 필수예요.
client_ip_debug_header (string : "") - lakeFS가 요청에 대해 해석한 주소를 담는 응답 헤더의 이름이에요. 예: X-Lakefs-Client-Ip. 인증된 요청에만 반환되므로, 익명 호출자는 이걸로 위조된 포워딩 헤더가 믿어졌는지 알아낼 수 없어요. 빈 값은 헤더를 추가하지 않아요.

각 키에는 대응하는 환경 변수가 있어요. 예컨대 ip_strategy는 LAKEFS_IP_STRATEGY로 설정할 수 있고, trusted_proxies는 LAKEFS_TRUSTED_PROXIES로 쉼표 구분 목록을 받아요:

ip_strategy: "proxy"
trusted_proxies:
  - "10.0.1.0/24"       # the ingress subnet
  - "192.168.1.50"      # a single reverse proxy

proxy 전략 아래에서 lakeFS는 X-Forwarded-For를 맨 오른쪽 항목(서버에 가장 가까운 프록시가 추가한 것)에서 왼쪽 방향으로 읽되, 신뢰된 프록시 주소는 건너뛰고, 신뢰된 프록시 주소가 아닌 첫 번째 주소를 사용해요. 클라이언트가 쓴 항목들은 더 왼쪽에 있어서 절대 닿지 않고, 모든 항목이 신뢰된 프록시라면 맨 왼쪽 항목이 사용돼요. 신뢰 범위 안의 모든 호스트가 클라이언트 주소를 주장할 수 있으니, 서브넷 전체가 아니라 여러분의 프록시가 실제로 쓰는 주소를 나열하세요. 그리고 pod와 인그레스가 같은 서브넷을 공유하는 경우가 많은 Kubernetes에서는 NetworkPolicy로 lakeFS 서비스 접근을 인그레스만 허용하도록 제한하세요.

클라이언트 IP 해석 모니터링

각 서버는 시작할 때 클라이언트 주소를 어디서 가져오는지, 즉 전략과 신뢰된 네트워크를 로그로 남겨요. 특정 호출자가 어떻게 해석되는지 보려면 client_ip_debug_header를 설정하고, 인증된 요청의 응답에서 주소를 읽어 보세요.

lakefs_client_ip_forwarding_anomalies_total 카운터는 reason으로 라벨링되어, X-Forwarded-For나 X-Real-IP가 설정대로 사용될 수 없었던 요청을 세어요. trusted_proxies에 구체적인 네트워크를 지정한 뒤에는, untrusted_peer가 잘못된 설정을 식별하는 이유예요: 목록 바깥의 연결 위에 포워딩 헤더를 실은 요청이 올 때 증가하고, 이는 거의 항상 lakeFS 앞의 프록시가 목록에 빠져 있다는 뜻이에요. 모든 네트워크를 신뢰하는 기본값에서는 어떤 연결도 untrusted가 아니므로 이 이유는 절대 발생하지 않아요.

reason	보고되는 시점	lakeFS가 사용하는 주소
untrusted_peer	요청이 X-Forwarded-For나 X-Real-IP를 실었지만, 연결이 trusted_proxies 주소에서 오지 않아 헤더가 무시됐어요.	TCP 연결의 주소예요.
invalid_entry	신뢰된 프록시에서 X-Forwarded-For를 읽는 중 IP 주소가 아닌 항목(난독화된 식별자, 호스트명 등)을 만났어요.	그 항목을 적힌 그대로, 45자로 줄여서 사용해요. 주소가 아니므로 클라이언트 주소에 대한 정책 조건은 매칭되지 않고, 그런 조건을 담은 정책을 지닌 사용자의 요청은 거부돼요.
entry_limit	신뢰된 프록시에서 온 X-Forwarded-For가 64개를 넘는 항목을 담았고 모두 신뢰된 프록시 주소라서 lakeFS가 읽기를 멈췄어요.	오른쪽에서 64번째 주소, 즉 도달한 가장 먼 신뢰된 프록시예요.

database

lakeFS Enterprise 데이터베이스 옵션의 설정 섹션이에요.

database.redis

database.redis.endpoint (string : "localhost:6379") - host:port 형식의 Redis 서버 엔드포인트예요
database.redis.enable_tls (bool : false) - Redis 연결에 TLS를 활성화해요 (AWS MemoryDB에 필수)
database.redis.cluster_mode (bool : false) - Redis Cluster 모드 지원을 활성화해요
database.redis.username (string : "") - Redis 인증용 사용자 이름이에요
database.redis.password (string : "") - Redis 인증용 비밀번호예요
database.redis.pool_size (int : 10) - Redis 연결의 연결 풀 크기예요
database.redis.min_idle_conns (int : 0) - 풀 안의 최소 유휴 연결 수예요
database.redis.dial_timeout (duration : 5s) - 새 연결 수립 타임아웃이에요
database.redis.read_timeout (duration : 3s) - 소켓 읽기 타임아웃이에요
database.redis.write_timeout (duration : 3s) - 소켓 쓰기 타임아웃이에요
database.redis.database (int : 0) - 선택할 데이터베이스 번호예요 (대부분의 Redis 구성에서 0-15)
database.redis.namespace (string : "") - 애플리케이션이 사용하는 모든 키의 접두사예요
database.redis.tls_skip_verify (bool : false) - 인증서 검증을 건너뛰어요 (개발 전용)
database.redis.batch_size (int : 1000) - Redis KV 작업의 기본 배치 크기예요

Note

Redis 또는 Amazon MemoryDB 같은 호환 서비스를 사용한다면 durable writes(영속 쓰기)를 활성화하세요. 노드 재시작이나 장애 시 데이터 유실을 막고 데이터가 확실히 저장되도록 해줘요.

auth

SAML이나 OIDC 같은 SSO 인증 서비스의 설정 섹션이에요.

auth.logout_redirect_url (string : "/auth/login") - SAML이나 OIDC 같은 SSO 인증 서비스를 사용할 때, 로그아웃 후 리다이렉트될 URL이에요.

설정은 인증 프로바이더에 따라 달라져요:

OIDC의 경우: OIDC 프로바이더의 로그아웃 URL (예: Auth0 로그아웃 엔드포인트).
SAML의 경우: 로그아웃 후 IdP가 리다이렉트해야 하는 lakeFS 내부의 URL (예: /auth/login).
auth.login_max_duration (time duration : "336h") - 외부 프린시펄 API를 통해 발급되는 로그인 토큰을 클라이언트가 요구할 수 있는 최대 기간이에요.
auth.allowed_authentication_methods (list of strings : []) - 클라이언트가 사용할 수 있는 인증 방식을 제한해요. 목록이 비어 있으면(기본값) 모든 방식이 허용돼요. 하나 이상의 방식을 지정하면 그것만 허용되고, 다른 방식을 사용하는 요청은 거부돼요.

지원되는 값:

"access_key" - 액세스 키 ID와 시크릿 액세스 키. S3 게이트웨이, API 기본 인증, 내장 사용자 이름/비밀번호 로그인을 커버해요.
"sso" - OIDC나 SAML을 통한 싱글 사인온.
"external_principal" - 외부 프린시펄 로그인 (예: AWS IAM).

예컨대 액세스 키를 끄고 SSO와 외부 프린시펄만 허용하려면:

auth:
  allowed_authentication_methods:
    - sso
    - external_principal

웹 UI도 이 제한에 맞춰 조정돼요: 자격 증명 기반 로그인이 성공할 수 없으면 로그인 폼이 숨겨지고 허용된 방식만 제공돼요. 별도로 설정된 LDAP나 원격 인증은 이 설정의 범위가 아니라서, 그 로그인 폼을 포함해 계속 동작해요.

Note

이 설정은 로컬 RBAC 인증 서비스(features.local_rbac, 셀프 관리형 설치의 기본값)와 함께만 지원돼요. 외부 인증 API 서비스나 basic auth를 사용할 때는 시작 시 거부돼요. 둘 다 이 제한을 존중하지 않으니까요.

auth.authentication_api

auth.authentication_api.endpoint (string : "") - authentication.yml에 설명된 외부 인증 서비스의 URL이에요.
auth.authentication_api.external_principals_enabled (bool : false) - true이면 외부 프린시펄 API(예: 인증 서비스와 로그인 API)가 활성화돼요.

auth.remote_authenticator

auth.remote_authenticator.enabled (bool : false) - 지정하면 이 Remote Authenticator 서버로도 사용자를 인증해요.
auth.remote_authenticator.endpoint (string : "" - required) - 원격 인증 서비스의 엔드포인트 URL이에요 (예: https://my-auth.example.com/auth).
auth.remote_authenticator.default_user_group (string : "Viewers") - 이 그룹에서 사용자를 생성해요 (예: Viewers, Developers 등).
auth.remote_authenticator.request_timeout (time duration : 10s) - 지정하면 원격 인증 요청의 타임아웃이 돼요.

auth.oidc

auth.oidc.default_initial_groups (string[] : []) - 기본적으로 OIDC 사용자가 이 그룹들에 배정돼요.
auth.oidc.initial_groups_claim_name (string : "") - ID 토큰에서 이 클레임을 사용해 새 사용자의 초기 그룹을 제공해요. auth.oidc.default_initial_groups도 설정돼 있으면 이쪽이 우선해요.
auth.oidc.friendly_name_claim_name (string : "") - 지정하면 이 이름의 클레임 값이 사용자 표시 이름으로 쓰여요.
auth.oidc.email_claim_name (string : "") - 지정하면 이 이름의 클레임 값이 사용자를 처음 만들 때 사용자 이메일로 쓰여요.
auth.oidc.persist_friendly_name (bool : false) - true로 설정하면 friendly name이 KV 스토어에 영속화되어 사용자 목록에 표시될 수 있어요. auth.oidc.friendly_name_claim_name과 함께 쓰려는 거예요.
auth.oidc.validate_id_token_claims (map[string]string : {}) - 사용자가 lakeFS에 접근하려 할 때, ID 토큰이 이 클레임들을 대응하는 값과 함께 담고 있는지 검증해요.

auth.cookie_auth_verification

auth.cookie_auth_verification.validate_id_token_claims (map[string]string : {}) - 사용자가 lakeFS에 접근하려 할 때, ID 토큰이 이 클레임들을 대응하는 값과 함께 담고 있는지 검증해요.
auth.cookie_auth_verification.default_initial_groups (string[] : []) - 기본적으로 사용자가 이 그룹들에 배정돼요.
auth.cookie_auth_verification.initial_groups_claim_name (string : "") - ID 토큰에서 이 클레임을 사용해 새 사용자의 초기 그룹을 제공해요. auth.cookie_auth_verification.default_initial_groups도 설정돼 있으면 이쪽이 우선해요.
auth.cookie_auth_verification.friendly_name_claim_name (string : "") - 지정하면 이 이름의 클레임 값이 사용자 표시 이름으로 쓰여요.
auth.cookie_auth_verification.email_claim_name (string : "") - 지정하면 이 이름의 클레임 값이 사용자를 처음 만들 때 사용자 이메일로 쓰여요.
auth.cookie_auth_verification.persist_friendly_name (bool : false) - true로 설정하면 friendly name이 KV 스토어에 영속화되어 사용자 목록에 표시될 수 있어요. auth.cookie_auth_verification.friendly_name_claim_name과 함께 쓰려는 거예요.
auth.cookie_auth_verification.external_user_id_claim_name - (string : "") - 지정하면 이 이름의 클레임 값이 사용자 id 이름으로 쓰여요.
auth.cookie_auth_verification.auth_source - (string : "") - 지정하면 사용자에게 이 인증 소스 라벨이 붙어요.

auth.ui_config

auth.ui_config.login_url (string : "") - 여러분 IdP의 로그인 페이지로의 절대 또는 상대 URL이에요. OIDC나 SAML로 SSO를 통해 lakeFS에 인증할 때 쓰여요.
auth.ui_config.logout_url (string : "") - 사용자가 lakeFS에서 로그아웃할 때 리다이렉트될 URL이에요 (지정하지 않으면 "/logout"이 기본값).
auth.ui_config.use_login_placeholders (bool: false) - true로 설정하면 로그인 페이지가 Access Key ID와 Secret Access Key 플레이스홀더(Username과 Password)를 보여줘요 (지정하지 않으면 "false"가 기본값).
auth.ui_config.login_url_method (string : "redirect") - auth.ui_config.login_url(OIDC나 SAML을 통한 SSO)이 설정되어 있을 때 lakeFS가 로그인을 다루는 방식을 제어해요. 이 파라미터는 auth.ui_config.login_url이 설정된 경우에만 의미가 있어요.

지원되는 값:

"redirect" - 로그인 시 사용자가 설정된 auth.ui_config.login_url로 리다이렉트돼요 (기본값).
"select" - 로그인 시 내장 lakeFS 로그인과 SSO 로그인 중 고르는 로그인 선택 페이지가 쓰여요.

auth.providers

LDAP, SAML, OIDC 같은 인증 서비스에 쓰이는 외부 아이덴티티 프로바이더의 설정 섹션이에요.

auth.providers.ldap

LDAP 설정 섹션이에요

auth.providers.ldap.server_endpoint (string : "" - required) - LDAP 서버 주소예요. 예: 'ldaps://ldap.company.com:636'.
auth.providers.ldap.bind_dn (string : "" - required) - bind 문자열이에요. 예: 'uid=<bind-user-name>,ou=Users,o=<org-id>,dc=<company>,dc=com'.
auth.providers.ldap.bind_password (string : "" - required) - bind할 사용자의 비밀번호예요.
auth.providers.ldap.username_attribute (string : "" - required) - 사용자 이름 속성이에요. 예: 'uid'.
auth.providers.ldap.user_base_dn (string : "" - required) - 검색 요청의 base dn이에요. 예: 'ou=Users,o=<org-id>,dc=<company>,dc=com'.
auth.providers.ldap.user_filter (string : "" - required) - 검색 요청의 사용자 필터예요. 예: '(objectClass=inetOrgPerson)'.
auth.providers.ldap.connection_timeout_seconds (int : 0 - required) - 단일 연결의 타임아웃이에요.
auth.providers.ldap.request_timeout_seconds (int : 0 - required) - 단일 요청의 타임아웃이에요.
auth.providers.ldap.default_user_group (string : "" - required) - 원격 서비스가 처음 인증한 사용자의 기본 그룹이에요.

auth.providers.saml

SAML 설정 섹션이에요

auth.providers.saml.sp_root_url (string : "") - lakeFS의 베이스 URL이에요. 예: 'https://<lakefs-url>'.
auth.providers.saml.sp_x509_key_path (string : "") - 개인 키의 경로예요. 예: '/etc/saml_certs/rsa_saml_private.cert'.
auth.providers.saml.sp_x509_cert_path (string : "") - 공개 키의 경로예요. '/etc/saml_certs/rsa_saml_public.pem'.
auth.providers.saml.sp_sign_request (bool : false) SLO 요청에 서명을 요구하는 IdP도 있어요.
auth.providers.saml.sp_signature_method (string : "") IdP 설정에 따른 선택적 유효 서명 값이에요. 예: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256'.
auth.providers.saml.idp_metadata_url (string : "") - 메타데이터 서버의 URL이에요. 예: 'https://<adfs-auth.company.com>/federationmetadata/2007-06/federationmetadata.xml'.
auth.providers.saml.idp_metadata_file_path (string : "") - Identity Provider(IdP) 메타데이터 XML 파일의 경로예요. 예: '/etc/saml/idp-metadata.xml'.
auth.providers.saml.idp_skip_verify_tls_cert (bool : false) - 프라이빗 CA로 서명된 경우처럼, IdP TLS 인증서 검증을 안전하지 않게 건너뛰어요.
auth.providers.saml.idp_authn_name_id_format (string : "") - 인증 요청의 NameIDPolicy에 쓰이는 형식이에요. (예: "urn:oasis:namesSAML:1.1:nameid-format:unspecified")
auth.providers.saml.idp_request_timeout (time duration : 10s) 원격 인증 요청의 타임아웃이에요.
auth.providers.saml.post_login_redirect_url (string : "") - SAML 인증이 성공한 후 사용자를 리다이렉트할 URL이에요. 예: 'http://localhost:8000/'.

auth.providers.oidc

OIDC 설정 섹션이에요

auth.providers.oidc.url (string : "") - OIDC 프로바이더 URL이에요. 예: 'https://oidc-provider-url.com/'
auth.providers.oidc.client_id (string : "") - 애플리케이션의 ID예요
auth.providers.oidc.client_secret (string : "") - 애플리케이션의 시크릿이에요
auth.providers.oidc.callback_base_url (string : "") - lakeFS 서버의 기본 콜백 주소예요
auth.providers.oidc.callback_base_urls (string[] : []) - callback_base_urls가 설정되어 있으면 현재 호스트가 화이트리스트에 있는지 확인하고, 아니면 callback_base_url('s' 없이)을 사용해요. 이 설정 키들은 상호 배타적이에요

Note

OIDC 프로바이더가 리다이렉트할 수 있는 URL 목록을 설정할 수 있어요. 연합 인증 능력을 유지하면서 lakeFS를 여러 호스트명으로 접근할 수 있게 해주죠. 프로바이더가 이 목록에 없는 URL로 리다이렉트하면 로그인이 실패해요. 이 속성과 callback_base_url은 상호 배타적이에요.

auth.providers.oidc.authorize_endpoint_query_parameters (map[string]string : {}) - 프로바이더의 authorization 엔드포인트에 전달되는 key/value 파라미터예요
auth.providers.oidc.logout_endpoint_query_parameters (string[] : []) - 로그아웃 후 사용자를 OIDC 프로바이더로 리다이렉트할 때 쓰이는 쿼리 파라미터예요. 예: ["returnTo", "https://<lakefs.ingress.domain>/oidc/login"]
auth.providers.oidc.logout_client_id_query_parameter (string : "") - OIDC 프로바이더에서 클라이언트 식별자를 나타내는 클레임 이름이에요
auth.providers.oidc.additional_scope_claims (string[] : []) - 사용 중인 openid와 profile 이외의 선택적 요청 권한을 지정해요
auth.providers.oidc.post_login_redirect_url (string : "") - OIDC 인증이 성공한 후 사용자를 리다이렉트할 URL이에요. 예: 'http://localhost:8000/'

auth.external_aws_auth

AWS presigned get-caller-identity 요청으로 lakeFS에 인증하는 설정 섹션이에요:

External Principals AWS Auth

auth.external_aws_auth.enabled (bool : false) - true이면 외부 프린시펄 API(예: 인증 서비스와 로그인 API)가 활성화돼요
auth.external_aws_auth.get_caller_identity_max_age (time duration : 24h) - 서버가 받아들이는 presigned GetCallerIdentity 요청의 최대 나이예요. lakeFS 클라이언트는 15분 후 만료되는 요청을 presign하므로, 기본값 대신 그에 가까운 값을 설정하면 유출된 presigned 요청이 쓸 수 있는 기간을 제한해요
auth.external_aws_auth.valid_sts_hosts (string[] : []) - 기본값은 유효한 모든 AWS STS 호스트예요 (sts.amazonaws.com, sts.us-east-2.amazonaws.com 등)
auth.external_aws_auth.required_headers (map[string]string : {}) - 로그인 요청 시 클라이언트가 반드시 포함해야 하는 헤더예요. 보안상 X-LakeFS-Server-ID: <lakefs.ingress.domain>을 설정하는 게 권장되고, lakeFS 클라이언트는 그것이 기본값이라고 가정해요
auth.external_aws_auth.optional_headers (map[string]string : {}) - 로그인 요청 시 클라이언트가 둘 수 있는 선택적 헤더예요
auth.external_aws_auth.http_client.timeout (time duration : 10s) - AWS STS와 통신하는 데 쓰이는 HTTP 클라이언트의 타임아웃이에요
auth.external_aws_auth.http_client.skip_verify (bool : false) - AWS STS와의 SSL 검증을 건너뛰어요

auth.prefetched_cache

사전 페치(prefetched) 캐시의 설정 섹션이에요. 사전 페치 캐시는 인증 KV 스토어의 항목을 메모리에 캐시해 KV 스토어 호출 수를 줄이는 데 쓰여요.

Note

사전 페치 캐시가 활성화되면, 인증 서비스의 응답을 캐시하던 auth 캐시는 비활성화돼요.

auth.prefetched_cache.enabled (bool : false) - 사전 페치 캐시를 활성화해요
auth.prefetched_cache.interval (duration : 30s) - 캐시를 새로 고치는 주기예요
auth.prefetched_cache.ttl (duration : 1m) - 각 캐시 항목의 생존 시간이에요
auth.prefetched_cache.size (int : 10000) - 캐시에 담을 수 있는 최대 항목 수예요
auth.prefetched_cache.eviction_jitter (duration : 3s) - thundering herd를 막으려고 축출 주기에 더할 최대 무작위 지터예요
auth.prefetched_cache.negative_cache_size (int : 40000) - 캐시가 기억할 수 있는 누락 항목의 최대 수예요

backpressure

백프레셔(backpressure) 설정의 섹션이에요. 활성화하면 백프레셔가 각 서버가 s3 게이트웨이를 통해 동시에 처리할 요청 수를 제한해요

backpressure.enabled (bool : false) - 백프레셔를 활성화해요
backpressure.upload_part_max_concurrent (int : 0) - 동시 upload part 요청의 최대 수예요. 0은 무제한을 뜻해요

blockstores

Info

blockstores 설정은 멀티 스토리지 백엔드 구성에 필요하고, 이전의 blockstore 설정을 대체해요.

blockstores.signing.secret_key (string : required) - get/link 물리 주소를 사용할 때 HMAC 서명에 쓰이는 무작위 생성 문자열이에요
blockstores.stores ([{id: string, type: string, ...}] : required) - 멀티 스토리지 백엔드 구성에서 쓰이는 여러 스토리지 백엔드를 정의해요. 각 스토리지 백엔드는 고유한 id와 유효한 설정을 지녀야 해요.

모든 스토어의 공통 필드

blockstores.stores[].id (string : required) - 스토리지 백엔드의 고유 식별자예요.
blockstores.stores[].backward_compatible (bool : false) - 선택 사항. 기본값은 false예요. 단일 스토리지 백엔드 구성에서 멀티 스토리지 백엔드 구성으로 마이그레이션할 때 쓰여요.
blockstores.stores[].description (string : ) - 스토리지 백엔드에 대한 사람이 읽을 수 있는 설명이에요.
blockstores.stores[].type (string : required) - (one of ["local", "s3", "gs", "azure", "mem"] : required). 사용할 블록 어댑터예요. 기반 데이터가 어디에 저장될지를 제어해요.

blockstores.stores.local``blockstores.stores.s3``blockstores.azure``blockstores.gs

blockstores.stores[].local.path (string: "~/lakefs/data") - 로컬 Block Adapter 사용 시 파일을 저장할 디렉터예요
blockstores.stores[].local.import_enabled (bool: false) - 로컬 Block Adapter에 임포트를 활성화해요. 공유 위치를 사용할 때만 관련 있어요
blockstores.stores[].local.import_hidden (bool: false) - 활성화하면 임포트가 점 문자로 시작하는 파일이나 폴더도 스캔하고 임포트해요.
blockstores.stores[].local.allowed_external_prefixes ([]string: []) - 외부 위치(예: /var/data/)에 대한 접근을 판정하는 데 쓰이는 절대 경로 접두사 목록이에요. 빈 목록은 외부 위치에 접근 불가를 뜻해요.
blockstores.stores[].s3.region (string : "us-east-1") - S3와 상호작용할 때 lakeFS가 사용하는 기본 리전이에요.
blockstores.stores[].s3.profile (string : ) - 지정하면 네임드 자격 증명 프로파일로 사용돼요
blockstores.stores[].credentials_file (string : ) - 지정하면 자격 증명 파일로 사용돼요
blockstores.stores[].credentials.access_key_id (string : ) - 지정하면 정적 자격 증명 세트로 사용돼요
blockstores.stores[].credentials.secret_access_key (string : ) - 지정하면 정적 자격 증명 세트로 사용돼요
blockstores.stores[].s3.credentials.session_token (string : ) - 지정하면 정적 세션 토큰으로 사용돼요
blockstores.stores[].s3.endpoint (string : ) - 지정하면 AWS S3 API의 커스텀 엔드포인트예요 (https://s3_compatible_service_endpoint:port)
blockstores.stores[].s3.force_path_style (bool : false) - true이면 path-style S3 URL을 사용해요 (https://bucket. 형식 대신 https://host/ 형식)
blockstores.stores[].s3.discover_bucket_region (bool : true) - (기반 S3 버킷이 GetBucketRegion API를 지원하지 않으면 끌 수 있어요).
blockstores.stores[].s3.skip_verify_certificate_test_only (bool : false) - 스토리지 엔드포인트에 연결할 때 인증서 검증을 건너뛰어요. 테스트에만 써야 해요.
blockstores.stores[].s3.server_side_encryption (string : ) - 사용되는 서버 측 암호화 형식이에요 (AWS에서 SSE-KMS를 쓰려면 "aws:kms"를 전달하는 예제 참고)
blockstores.stores[].s3.server_side_encryption_kms_key_id (string : ) - 서버 측 암호화 KMS 키 ID예요
blockstores.stores[].s3.pre_signed_expiry (time duration : "15m") - pre-signed URL의 만료 기간이에요.
blockstores.stores[].s3.pre_signed_endpoint (string : ) - pre-signed URL의 커스텀 엔드포인트예요.
blockstores.stores[].s3.disable_pre_signed (bool : false) - pre-signed URL 사용을 비활성화해요.
blockstores.stores[].s3.disable_pre_signed_ui (bool : true) - UI에서 pre-signed URL 사용을 비활성화해요.
blockstores.stores[].s3.disable_pre_signed_multipart (bool : ) - pre-signed multipart upload 사용을 비활성화해요. 실험적 기능이고, presign 지원이 있는 S3 블록 어댑터에서 활성화돼요.
blockstores.stores[].s3.client_log_request (bool : false) - 요청을 로그로 남기도록 SDK 로깅 비트를 설정해요
blockstores.stores[].s3.client_log_retries (bool : false) - 재시도를 로그로 남기도록 SDK 로깅 비트를 설정해요
blockstores.stores[].azure.storage_account (string : ) - 지정하면 Azure 스토리지 계정으로 사용돼요
blockstores.stores[].azure.storage_access_key (string : ) - 지정하면 Azure 스토리지 액세스 키로 사용돼요
blockstores.stores[].azure.managed_identity_client_id (string : ) - 이 스토어가 인증에 쓰는 사용자 지정 관리 ID의 클라이언트 ID예요. blockstores.stores[].azure.storage_access_key가 우선하고, 둘 다 비워 두면 기본 Azure 자격 증명 체인이 쓰여요. Selecting a user-assigned managed identity를 참고하세요.
blockstores.stores[].azure.pre_signed_expiry (time duration : "15m") - pre-signed URL의 만료 기간이에요.
blockstores.stores[].azure.disable_pre_signed (bool : false) - pre-signed URL 사용을 비활성화해요.
blockstores.stores[].azure.disable_pre_signed_ui (bool : true) - UI에서 pre-signed URL 사용을 비활성화해요.
blockstores.stores[].azure.domain (string : blob.core.windows.net) - 서로 다른 Azure 클라우드 도메인 지원을 활성화해요. 현재 지원되는 도메인(베타 단계): [blob.core.chinacloudapi.cn, blob.core.usgovcloudapi.net]
blockstores.stores[].gs.credentials_file (string : ) - 지정하면 Google 서비스 계정 키를 담은 JSON 파일의 경로로 사용돼요
blockstores.stores[].gs.credentials_json (string : ) - 지정하면 Google 서비스 계정 키를 담은 JSON 문자열로 사용돼요(credentials_file이 설정되지 않았을 때)
blockstores.stores[].gs.pre_signed_expiry (time duration : "15m") - pre-signed URL의 만료 기간이에요.
blockstores.stores[].gs.disable_pre_signed (bool : false) - pre-signed URL 사용을 비활성화해요.
blockstores.stores[].gs.disable_pre_signed_ui (bool : true) - UI에서 pre-signed URL 사용을 비활성화해요.
blockstores.stores[].gs.server_side_encryption_customer_supplied (string : ) - 16진수 AES 키를 쓰는 서버 측 암호화예요. 아래의 키 ID와 상호 배타적이에요
blockstores.stores[].gs.server_side_encryption_kms_key_id (string : ) - 서버 측 암호화 KMS 키 ID예요. 위와 상호 배타적이에요

blockstore.s3.credentials_vending

Iceberg REST Catalog 클라이언트에 짧은 수명의, 테이블 범위 S3 자격 증명을 발급(vending)하는 설정이에요. Iceberg credentials vending을 참고하세요. 멀티 스토리지 백엔드 구성에서는 대응하는 blockstores.stores[].s3.credentials_vending.* 필드를 사용하세요.

blockstore.s3.credentials_vending.role_arn (string : ) - 자격 증명을 발급할 때 lakeFS가(STS AssumeRole을 통해) 가정하는 IAM 역할의 ARN이에요. 빈 값이 아닌 값을 설정하면 credential vending이 활성화되고, 빈 값(기본값)은 비활성화돼요.
blockstore.s3.credentials_vending.session_duration (time duration : "1h") - 발급된 STS 세션의 수명이에요. 최소 15m이고, 더 짧은 값을 설정하면 lakeFS가 시작되지 않아요.
blockstore.s3.credentials_vending.external_id (string : ) - STS AssumeRole에 전달되는 External ID예요. 보통 역할의 신뢰 정책이 요구할 때 쓰여요.
blockstore.s3.credentials_vending.endpoint (string : ) - 발급된 설정에서 클라이언트에 반환되는 S3 엔드포인트를 재정의해요. lakeFS와 그 클라이언트가 서로 다른 (내부/외부) 주소로 S3에 접근할 때 유용해요.

features

features.local_rbac (bool: true) - 외부 RBAC 서비스(예: 레거시 fluffy)를 사용할 때의 하위 호환성이에요. false이면 lakeFS가 RBAC을 위해 auth.api와 fluffy 관련 설정 전체를 사용하려고 기대해요.

audit_log

Audit Log Iceberg System Table의 설정 섹션이에요.

audit_log.enabled (bool : false) - 감사 로그 Iceberg 파이프라인을 활성화해요. 활성화하면 lakeFS가 모든 감사 이벤트를 캡처해 Iceberg 테이블에 영속화해요.
audit_log.retention_days (int : 90) - 스냅샷 만료의 기본 보존 기간(일)이에요. 무한 보존은 0으로 설정하세요.
audit_log.storage_namespace (string : "") - lakefssystem 저장소의 스토리지 위치예요. 비워 두면 blockstore.default_namespace_prefix에 /lakefssystem을 붙여 파생돼요 (예: s3://my-bucket/lakefssystem).
audit_log.storage_id (string : "") - 멀티 스토리지 백엔드 구성의 스토리지 백엔드 ID예요. 위의 storage_namespace를 호스팅하는 백엔드와 반드시 대응되어야 해요.

audit_log.flush

audit_log.flush.interval (duration : 1m) - 버퍼에 쌓인 감사 이벤트를 내보내는(flush) 주기예요.
audit_log.flush.batch_size (int : 100000) - 이만큼의 이벤트가 쌓이면 flush해요. 주기와 배치 크기 임계값 중 먼저 도달하는 쪽에서 이벤트가 내보내져요.

audit_log.maintenance

감사 유지보수 설정이에요. 자세한 내용은 Maintenance를 참고하세요. 유지보수를 외부 잡으로 실행할 때는 내장 스케줄러를 끄려고 enabled를 false로 설정하세요.

audit_log.maintenance.enabled (bool : true) - audit_log.enabled 설정이 true일 때 유지보수를 프로세스 내에서 실행해요. 감사 로깅이 비활성화되어 있으면 이 설정은 효과가 없어요.
audit_log.maintenance.schedule (string : "0 * * * *") - 유지보수를 스케줄할 cron 표현식이에요. 기본값은 매시간이에요.
audit_log.maintenance.metrics_push_url (string : "") - 각 실행 후 유지보수 메트릭을 보낼 Prometheus Pushgateway URL이에요 (외부 잡 모드에서 사용). 비워 두면 메트릭이 전송되지 않아요.

iceberg_catalog

Iceberg REST Catalog의 설정 섹션이에요

iceberg_catalog.token_duration (duration : 1h) - 인증된 토큰의 지속 기간이에요

ui

커스텀 오브젝트 뷰어의 설정 섹션이에요. 오브젝트가 뷰어를 고르는 방식은 Matching rules에 설명되어 있어요.

ui.custom_viewers ([{name: string, url: string, ...}] : []) - 뷰어 항목들이에요. 각 뷰어에 콘텐츠 타입이나 확장자를 최소 하나 지정하세요. 뷰어 이름, 콘텐츠 타입, 확장자는 뷰어 항목 전반에서 고유해야 해요.
ui.custom_viewers[].name (string : required) - 뷰어를 식별하는 고유 이름이에요.
ui.custom_viewers[].url (string : required) - 뷰어 iframe에 로드될 URL이에요. Serve the page를 참고하세요.
ui.custom_viewers[].content_types (string[] : []) - 오브젝트의 전체 콘텐츠 타입과 매칭되는 정확한 값들이에요.
ui.custom_viewers[].extensions (string[] : []) - 선행 점 없는, 소문자의 파일 끝 접미사들이에요.
ui.custom_viewers[].allow_same_origin (bool : false) - 불투명(opaque) origin을 부여하는 대신 뷰어의 origin을 유지해요. Relaxing the sandbox with allow_same_origin을 참고하세요.

환경 변수 사용하기

모든 설정 변수는 환경 변수로 설정하거나 재정의할 수 있어요. 환경 변수를 설정하려면 이름 앞에 LAKEFS_를 붙이고, 대문자로 바꾸고, .을 _로 바꾸세요:

예컨대 auth.logout_redirect_url은 LAKEFS_AUTH_LOGOUT_REDIRECT_URL이 되고, auth.external.aws_auth.enabled는 LAKEFS_AUTH_EXTERNAL_AWS_AUTH_ENABLED가 되는 식이에요.

map[string]string 타입 필드에 값을 설정하려면 key1=value1,key2=value2,... 문법을 사용하세요.

더 알아보기 (Learn more)

공식 문서의 자세한 내용은 https://docs.lakefs.io/reference/enterprise-configuration/에서 확인하실 수 있어요.