service-catalog/manifests/helm/lakekeeper/0.11.0/CUSTOM-README.md

# Upgrade History

## 0.8.1 → 0.11.0
### 변경 요약
- from_version: 0.8.1
- to_version: 0.11.0
- Chart `lakekeeper` 0.8.1 → 0.11.0 업데이트
- Values: +31 / -0 / ~0 / type~0
- Templates: +0 / -0
- Dependencies: +0 / -0 / ~2

### custom-values.yaml 수정 필요 항목
없음

### 참고
- severity: warning
- breaking: false

# Lakekeeper 배포

## 1. 배포 방법

### 1) 배포시 주의 사항
- Lakekeeper는 Rust 기반의 Apache Iceberg REST Catalog 서비스입니다.
- OpenFGA를 사용한 인증/권한 관리가 가능하며, 내장 OpenFGA를 사용할 수 있습니다.
- OIDC 인증을 사용하는 경우 배포전 keycloak 설정을 선행해야 합니다.

### 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 — 내장 postgres 서브차트 대신 cnpg-cluster(전용 인스턴스)를 외부 DB로 사용한다.
postgresql:
  enabled: false

externalDatabase:
  type: postgres
  # -ro는 replica 전용이라 instances:1(권장 기준, small 티어)에서는 엔드포인트가 없다 —
  # -r(전체 인스턴스 라운드로빈, primary 포함)을 대신 쓴다. 배포 테스트로 실측된 문제다.
  host_read: "lakekeeper-db-r"
  host_write: "lakekeeper-db-rw"
  port: 5432
  database: lakekeeper
  user: lakekeeper
  password: lakekeeper

# 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 데이터베이스 설정

- 내장 postgres 서브차트(`groundhog2k/postgres`) 대신 `cnpg-cluster`(전용 인스턴스)를 외부 DB로
  사용한다. **사전 조건**: `cloudnative-pg` operator가 클러스터에 먼저 설치되어 있어야 한다.
- **배포 순서**
  ``` sh
  kubectl create secret generic lakekeeper-db-app-secret \
    --from-literal=username=lakekeeper --from-literal=password=lakekeeper -n lakekeeper

  helm upgrade lakekeeper-db manifests/helm/cnpg-cluster/1.0.0 \
    -f manifests/helm/cnpg-cluster/1.0.0/custom-values.yaml \
    -f manifests/applicationset/lakekeeper/0.11.0/lakekeeper-db-values.yaml \
    --install -n lakekeeper

  helm upgrade lakekeeper ./ -f custom-values.yaml --install -n lakekeeper --create-namespace
  ```
- ArgoCD로 배포한다면 `manifests/applicationset/lakekeeper/0.11.0/`의 ApplicationSet을 쓴다 —
  `lakekeeper-db`(syncWave 0) → `lakekeeper`(syncWave 1) 순서로 자동 배포된다. 자세한 내용은
  해당 디렉토리의 `README.md` 참고.

| Name                      | 설명                                                         | 기본값      |
| ------------------------- | ------------------------------------------------------------ | ----------- |
| `postgresql.enabled`      | 내장 postgres 서브차트 사용 여부. cnpg-cluster 사용 시 `false` | `false`     |
| `externalDatabase.host_write` | cnpg-cluster의 rw 서비스명(`<release>-rw`)                | `lakekeeper-db-rw` |
| `externalDatabase.host_read`  | cnpg-cluster의 ro 서비스명(`<release>-ro`)                | `lakekeeper-db-ro` |
| `externalDatabase.database`, `.user`, `.password` | DB 계정 정보. cnpg-cluster 부트스트랩 시크릿과 동일해야 한다 | 참고 예시 |

> 참고: `manifests/applicationset/lakekeeper/0.11.0/lakekeeper-db-values.yaml`
>
> OpenFGA 인증/권한 스토어(`internalOpenFGA: true`)는 여전히 자체 bitnami postgresql
> 서브차트(`openfga.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
```