From 29d02dc6d3589b78b194a9f5174e2d837947f04d Mon Sep 17 00:00:00 2001 From: wbsong111 Date: Wed, 26 Nov 2025 15:11:54 +0900 Subject: [PATCH] Add custom-values.yaml, READMD.md document --- charts/lakekeeper/BUILD-README.md | 98 +++++++++++ charts/lakekeeper/CUSTOM-README.md | 246 +++++++++++++++++++++++++++ charts/lakekeeper/custom-values.yaml | 70 ++++++++ 3 files changed, 414 insertions(+) create mode 100644 charts/lakekeeper/BUILD-README.md create mode 100644 charts/lakekeeper/CUSTOM-README.md create mode 100644 charts/lakekeeper/custom-values.yaml diff --git a/charts/lakekeeper/BUILD-README.md b/charts/lakekeeper/BUILD-README.md new file mode 100644 index 0000000..0c8b407 --- /dev/null +++ b/charts/lakekeeper/BUILD-README.md @@ -0,0 +1,98 @@ +# Lakekeeper 버전 갱신 가이드 + +## 1. git 작업 환경 구성 + +- DIP 카탈로그 git 다운로드 +``` +$ git clone https://github.com/paasup/dip-catalog.git +``` + +- 작업 브랜치로 체크아웃 +``` +$ git checkout -b update-lakekeeper/0.8.1 +``` + +## 2. helm chart 업데이트 + +### 1) 차트 버전 변경 + +- BUILD-README.md, CUSTOM-README.md, custom-values.yaml을 제외한 파일 삭제 + ``` sh + # chart 디렉토리로 이동 + cd ~/dip-catalog/charts/lakekeeper + + # 파일 삭제 전 삭제할 파일 목록 확인 + find . -mindepth 1 \( -name "CUSTOM-README.md" -o -name "BUILD-README.md" -o -name "custom-values.yaml" \) -prune -o -print + + # 파일 삭제 + find . -mindepth 1 \( -name "CUSTOM-README.md" -o -name "BUILD-README.md" -o -name "custom-values.yaml" \) -prune -o -exec rm -rf {} + + ``` + +- lakekeeper 차트 다운로드 + ``` sh + # charts 디렉토리로 이동 + cd ~/dip-catalog/charts + + # helm repo 추가 + helm repo add lakekeeper https://lakekeeper.github.io/lakekeeper-charts/ + helm repo update + + # helm 차트 다운로드 + helm pull lakekeeper/lakekeeper --version="0.8.1" + + # 차트 변경 + tar xzvf lakekeeper-*.tgz + + # 필요 없는 파일 삭제 + rm lakekeeper-*.tgz + ``` + +### 2) 차트 수정 사항 반영 + +- Lakekeeper 차트는 기본적으로 별도의 수정 사항 없이 사용 가능합니다. + +## 3. git push 및 tag 추가 + +- 갱신작업 진행후 commit +``` +$ git add . +$ git commit -m "update lakekeeper/0.8.1" +``` + +- main 브랜치에 체크아웃 후 merge +``` +$ git checkout main +$ git merge update-lakekeeper/0.8.1 +``` + +- git에 push 후 작업 브랜치 삭제 +``` +$ git push -u origin main +$ git branch -d update-lakekeeper/0.8.1 +``` + +- git tag 추가 후 push +``` +$ git tag lakekeeper/0.8.1 +$ git push origin lakekeeper/0.8.1 +``` + +## 4. 차트 버전 정보 + +- lakekeeper/0.8.1 + - Lakekeeper v0.10.4 기반 + - Rust 네이티브 Apache Iceberg REST Catalog + - OpenFGA 기반 세밀한 권한 제어 지원 + - OIDC 인증 지원 (Keycloak 등) + - Kubernetes 서비스 계정 인증 지원 + - 다중 데이터베이스 백엔드 지원 (PostgreSQL) + - 내장 PostgreSQL 및 OpenFGA 서브차트 포함 + - Prometheus 메트릭 지원 + - 고가용성 및 수평 확장 지원 + - 서비스 배포를 위하여 custom-values.yaml에 정의 + - 차트의 빌드 방법과 배포 방법을 BUILD-README.md, CUSTOM-README.md 문서에 작성 + + +### 의존성 +- PostgreSQL (groundhog2k/postgres v1.5.8) +- OpenFGA (openfga/openfga v0.2.44) \ No newline at end of file diff --git a/charts/lakekeeper/CUSTOM-README.md b/charts/lakekeeper/CUSTOM-README.md new file mode 100644 index 0000000..1123db6 --- /dev/null +++ b/charts/lakekeeper/CUSTOM-README.md @@ -0,0 +1,246 @@ +# Lakekeeper 배포 + +## 1. 배포 방법 + +### 1) 배포시 주의 사항 +- Lakekeeper는 Rust 기반의 Apache Iceberg REST Catalog 서비스입니다. +- 기본적으로 PostgreSQL 데이터베이스가 필요하며, 내장된 PostgreSQL은 프로덕션 환경에 적합하지 않습니다. +- 프로덕션 환경에서는 외부 데이터베이스 사용을 권장합니다. +- OpenFGA를 사용한 인증/권한 관리가 가능하며, 내장 OpenFGA 또는 외부 OpenFGA를 사용할 수 있습니다. +- OIDC 인증을 사용하는 경우 올바른 Provider URI와 클라이언트 설정이 필요합니다. + +### 2) 배포 방법 +```sh +git clone https://github.com/paasup/dip-catalog.git +cd charts/lakekeeper +helm upgrade lakekeeper ./ -f custom-values.yaml --install -n lakekeeper --create-namespace +``` + +## 2. custom-values.yaml 예시 + +다음은 배포 시 사용할 수 있는 custom-values.yaml 파일의 예시입니다: + +```yaml +catalog: + resources: {} + ingress: + enabled: true + annotations: + cert-manager.io/issuer: root-ca-issuer + cert-manager.io/duration: 8760h + cert-manager.io/renew-before: 720h + konghq.com/https-redirect-status-code: '301' + konghq.com/protocols: https + + host: "lakekeeper.example.org" + ingressClassName: "kong" + tls: + enabled: true + secretName: "lakekeeper-tls" + + # keycloak 사설 인증서 사용 시 설정 + extraEnv: + - name: SSL_CERT_FILE + value: "/tmp/ca.crt" + extraVolumeMounts: + - name: keycloak-tls + mountPath: "/tmp/ca.crt" + subPath: ca.crt + readOnly: true + extraVolumes: + - name: keycloak-tls + secret: + secretName: root-ca-secret + +# lakekeeper DB +postgresql: + storage: + className: + requestedSize: 5Gi + resources: {} + +# OIDC 인증 +auth: + oauth2: + providerUri: "https://keycloak.example.org/realms/paasup" + audience: "lakekeeper" + ui: + clientID: "lakekeeper" + scopes: "lakekeeper" + +# 권한 관리 +authz: + backend: "openfga" + openfga: + apiKey: "your-api-key" # openfga.authn.preshared.key에 정의된 값가 동일하게 설정. + +internalOpenFGA: true +openfga: + # 테스트 환경 비활성화, authn을 oidc 타입으로 실행하기 위해서는 playground에서는 불가. + playground: + enabled: true + authn: + method: "preshared" + preshared: + # openssl rand -base64 32 + keys: ["your-api-key"] + postgresql: + primary: + resources: {} + persistence: + storageClass: "" + size: 8Gi +``` + +## 3. custom-values.yaml 설정 설명 + +### 1) 카탈로그 설정 + +| Name | 설명 | 기본값 | +| ------------------------- | ------------------------------------------------------------ | ------------------------- | +| `catalog.resources` | CPU/메모리 리소스 설정 | `{}` | + +### 2) Ingress 설정 + +| Name | 설명 | 기본값 | +| ------------------------- | ------------------------------------------------------------ | ----------- | +| `catalog.ingress.enabled` | Ingress 활성화 여부 | `true` | +| `catalog.ingress.annotations` | Ingress 어노테이션 | 참고 예시 | +| `catalog.ingress.host` | Ingress 호스트명 | `lakekeeper.example.org` | +| `catalog.ingress.ingressClassName` | Ingress 클래스 | `kong` | +| `catalog.ingress.tls.enabled` | TLS 활성화 여부 | `true` | +| `catalog.ingress.tls.secretName` | TLS 시크릿 이름 | `lakekeeper-tls` | + +#### Ingress 어노테이션 설명 +```yaml +annotations: + cert-manager.io/issuer: root-ca-issuer # cert-manager 발급자 + cert-manager.io/duration: 8760h # 인증서 유효기간 (1년) + cert-manager.io/renew-before: 720h # 갱신 시점 (30일 전) + konghq.com/https-redirect-status-code: '301' # HTTPS 리다이렉트 상태 코드 + konghq.com/protocols: https # Kong 프로토콜 설정 +``` + +### 3) 사설 인증서 설정 (Keycloak 연동 시) + +| Name | 설명 | 기본값 | +| ------------------------- | ------------------------------------------------------------ | ----------- | +| `catalog.extraEnv` | 추가 환경 변수 (SSL 인증서 경로 설정) | 참고 예시 | +| `catalog.extraVolumeMounts` | 추가 볼륨 마운트 (인증서 파일 마운트) | 참고 예시 | +| `catalog.extraVolumes` | 추가 볼륨 (인증서 시크릿) | 참고 예시 | + +```yaml +extraEnv: +- name: SSL_CERT_FILE + value: "/tmp/ca.crt" +extraVolumeMounts: +- name: keycloak-tls + mountPath: "/tmp/ca.crt" + subPath: ca.crt + readOnly: true +extraVolumes: +- name: keycloak-tls + secret: + secretName: root-ca-secret +``` + +### 4) PostgreSQL 데이터베이스 설정 + +| Name | 설명 | 기본값 | +| ------------------------- | ------------------------------------------------------------ | ----------- | +| `postgresql.storage.className` | 스토리지 클래스 | `""` | +| `postgresql.storage.requestedSize` | PostgreSQL 스토리지 크기 | `5Gi` | +| `postgresql.resources` | PostgreSQL 리소스 설정 | `{}` | + +### 5) OIDC 인증 설정 + +| Name | 설명 | 기본값 | +| ------------------------- | ------------------------------------------------------------ | ----------- | +| `auth.oauth2.providerUri` | OIDC Provider URI (Keycloak Realm) | `https://keycloak.example.org/realms/paasup` | +| `auth.oauth2.audience` | 예상되는 Audience (일반적으로 Client ID) | `lakekeeper` | +| `auth.oauth2.ui.clientID` | UI용 클라이언트 ID | `lakekeeper` | +| `auth.oauth2.ui.scopes` | 요청할 스코프 | `lakekeeper` | + +### 6) 권한 관리 설정 (OpenFGA) + +| Name | 설명 | 기본값 | +| ------------------------- | ------------------------------------------------------------ | ----------- | +| `authz.backend` | 권한 관리 백엔드 ("openfga") | `openfga` | +| `authz.openfga.apiKey` | OpenFGA API 키 (사전 공유 키 인증) | 예시 키 | + +### 7) 내장 OpenFGA 설정 + +| Name | 설명 | 기본값 | +| ------------------------- | ------------------------------------------------------------ | ----------- | +| `internalOpenFGA` | 내장 OpenFGA 배포 여부 | `true` | +| `openfga.playground.enabled` | OpenFGA Playground 활성화 | `true` | +| `openfga.authn.method` | 인증 방법 | `preshared` | +| `openfga.authn.preshared.keys` | 사전 공유 키 목록 | 예시 키 | + +### 8) OpenFGA PostgreSQL 설정 + +| Name | 설명 | 기본값 | +| ------------------------- | ------------------------------------------------------------ | ----------- | +| `openfga.postgresql.primary.resources` | OpenFGA PostgreSQL 리소스 설정 | `{}` | +| `openfga.postgresql.primary.persistence.storageClass` | 스토리지 클래스 | `""` | +| `openfga.postgresql.primary.persistence.size` | 스토리지 크기 | `8Gi` | + +## 4. 인증 설정 상세 + +### 1) Keycloak OIDC 인증 설정 +```yaml +auth: + oauth2: + providerUri: "https://keycloak.example.org/realms/paasup" + audience: "lakekeeper" + ui: + clientID: "lakekeeper" + scopes: "lakekeeper" +``` + +- `providerUri`: Keycloak의 Realm URL +- `audience`: Lakekeeper 클라이언트 ID +- `ui.clientID`: UI에서 사용할 클라이언트 ID +- `ui.scopes`: 요청할 OAuth 스코프 + +### 2) 사설 인증서 처리 +Keycloak이 사설 인증서를 사용하는 경우 다음 설정이 필요합니다: + +```yaml +catalog: + extraEnv: + - name: SSL_CERT_FILE + value: "/tmp/ca.crt" + extraVolumeMounts: + - name: keycloak-tls + mountPath: "/tmp/ca.crt" + subPath: ca.crt + readOnly: true + extraVolumes: + - name: keycloak-tls + secret: + secretName: root-ca-secret +``` + +## 5. OpenFGA 권한 관리 + +### 1) 내장 OpenFGA 사용 +```yaml +authz: + backend: "openfga" + openfga: + apiKey: "uNGpW1LOA48HLVh9OVLTAprgQAPAu5hyxyBZvW55M0U=" + +internalOpenFGA: true +openfga: + authn: + method: "preshared" + preshared: + keys: ["uNGpW1LOA48HLVh9OVLTAprgQAPAu5hyxyBZvW55M0U="] +``` + +### 2) API 키 생성 +OpenFGA API 키는 다음 명령으로 생성할 수 있습니다: +```sh +openssl rand -base64 32 +``` \ No newline at end of file diff --git a/charts/lakekeeper/custom-values.yaml b/charts/lakekeeper/custom-values.yaml new file mode 100644 index 0000000..5ae1927 --- /dev/null +++ b/charts/lakekeeper/custom-values.yaml @@ -0,0 +1,70 @@ +catalog: + resources: {} + ingress: + enabled: true + annotations: + cert-manager.io/issuer: root-ca-issuer + cert-manager.io/duration: 8760h + cert-manager.io/renew-before: 720h + konghq.com/https-redirect-status-code: '301' + konghq.com/protocols: https + + host: "lakekeeper.example.org" + ingressClassName: "kong" + tls: + enabled: true + secretName: "lakekeeper-tls" + + # keycloak 사설 인증서 사용 시 설정 + extraEnv: + - name: SSL_CERT_FILE + value: "/tmp/ca.crt" + extraVolumeMounts: + - name: keycloak-tls + mountPath: "/tmp/ca.crt" + subPath: ca.crt + readOnly: true + extraVolumes: + - name: keycloak-tls + secret: + secretName: root-ca-secret + +# lakekeeper DB +postgresql: + storage: + className: + requestedSize: 5Gi + resources: {} + + +# OIDC 인증 +auth: + oauth2: + providerUri: "https://keycloak.example.org/realms/paasup" + audience: "lakekeeper" + ui: + clientID: "lakekeeper" + scopes: "lakekeeper" +authz: + backend: "openfga" + openfga: + apiKey: "your-api-key" # openfga.authn.preshared.key에 정의된 값가 동일하게 설정. + +internalOpenFGA: true +openfga: + resources: {} + # 테스트 환경 비활성화, authn을 oidc 타입으로 실행하기 위해서는 playground에서는 불가. + playground: + enabled: true + authn: + method: "preshared" + preshared: + # openssl rand -base64 32 + keys: ["your-api-key"] + postgresql: + primary: + resources: {} + persistence: + storageClass: "" + size: 8Gi +