service-catalog/manifests/helm/airflow/1.16.0/CUSTOM-README.md

# Airflow 배포 

## 1. 배포 방법

### 1) 배포시 주의 사항

- 배포전 airflow dag를 저장할 git 리포지토리가 생성 필요
- 

### 2) 배포 방법 

``` sh
git clone https://github.com/paasup/dip-catalog.git
cd charts/flowise
helm upgrade airflow ./ -f custom-values.yaml  --install -n airflow --create-namespace
```

## 2.custom-values.yaml 설명

- custom-values.yaml에 정의된 값에 대한 설명이다.

### 1) Pod 설정


| Name                   | 설명                                                         | 기본값 |
| ---------------------- | ------------------------------------------------------------ | ------ |
| `defaultAirflowRepository` | 오프라인 설치 시에 설정. 내부 저장소 타겟으로 변경 | `"apache/airflow"`   |
| `defaultAirflowTag` | 이미지 태그 설정 | '0.5.4' |



### 2) Git Sync 설정

- Dag
  ``` yaml
  dags:
    gitSync:
      enabled: true
      # dag가 저장될 gitea의 repository url, k8s 서비스로 설정한다.
      repo: http://gitea-http.platform.svc.cluster.local:3000/dip/airflow-dags.git
      branch: master
      rev: HEAD
      depth: 1
      subPath: ""
      credentialsSecret: git-credentials
      env:
      - name: GIT_SSL_NO_VERIFY
        value: "true"
  # git 리포지토리의 clone 및 pull 실행 시 사용할 username, password 설정.
  # 실행하는 git 이미지의 버전은 v3, v4 2가지가 있고 사용하는 환경변수가 다름.
  # 2가지 설정을 하지 않을 시 동작 에러 발생.
  extraSecrets:
    git-credentials:
      data: |
        GIT_SYNC_USERNAME: c3Vkb3VzZXI=
        GITSYNC_USERNAME: c3Vkb3VzZXI=
        GIT_SYNC_PASSWORD: UGFhc2FkbTEyMzQh
        GITSYNC_PASSWORD: UGFhc2FkbTEyMzQh
  ```
   

### 3) Volume 설정

``` yaml
# Dag의 저장 공간 크기 설정
dags:
  persistence:
    enabled: true
    size: 5Gi

# airflow의 dag 동작시 생성되는 log의 저장 공간 크기 설정
logs:
  persistence:
    enabled: true
    size: 5Gi
```

### 3) Ingress 설정

#### 3.1) tls 시크릿 직접 생성

- flowise에서 ingress 사용을 위해서는 다음과 같이 설정할 수 있다.
  
  ``` yaml
  ingress:
    web:
      enabled: true
      hosts:
      - name: "airflow.example.org"
        tls:
          enabled: true
          secretName: "airflow-tls"
  ```
  
- ingress 사용을 위해서는 인증서를 secret으로 제공해야한다. 로컬 파일을 이용해 secret을 생성하는 방법은 다음과 같다.
  
  ``` sh
  kubectl create secret tls airflow-tls --cert=<path-to-cert-file> --key=<path-to-key-file> -n <namespace>
  ```

#### 3.2) cert-manager를 이용한 자동 생성

- cert manager를 통해 인증서 자동 생성 시 `custom-values.yaml` 수정한다.
- `ingress.web.annotations.cert-manager.io/cluster-issuer`에 미리 배포된 Cluster Issuer의 이름으로 변경한다. 그리고 
  ff
  ``` yaml
  ingress:
    web:
      enabled: true
      annotations:
        cert-manager.io/issuer: "root-ca-issuer"
        kubernetes.io/ingress.class: kong
        konghq.com/protocols: https
        konghq.com/https-redirect-status-code: "301"
      hosts:
      - name: "airflow.example.org"
        tls:
          enabled: true
          secretName: "airflow-tls"
  ```

#### 3.3) OIDC 인증 제외 경로 (`dip.unauthenticatedPaths`)

> **업스트림 차트에 없는 PaaSup 추가 템플릿이다.**
> `templates/webserver/webserver-ingress-static.yaml` — 차트 업그레이드 시 함께 이관한다.

APISIX `openid-connect` 플러그인(`oidc-keycloak-authz`)을 거는 배포에서만 필요하다.
`dip-values.yaml` 계열에 아래 키가 있으면 **애노테이션 없는 Ingress를 하나 더** 만들어
해당 경로를 인증 없이 통과시킨다.

``` yaml
dip:
  unauthenticatedPaths:
    - /static
```

**왜 필요한가** — 세션이 없는 상태로 접속하면 Airflow UI 한 페이지가 `/static` 자원을
수십 개 *동시에* 요청한다. 각 요청이 저마다 OIDC 로그인 플로우를 시작하면서 새 `state`를
발급해 세션에 덮어쓰는데, 세션은 `state`를 하나만 보관하므로 콜백이 동시에 돌아오면
마지막 하나를 뺀 전부가 state 검증에 실패해 **500**이 난다 (paasup/dip-catalog#24).

Airflow 웹서버는 Flask-AppBuilder 구조라 번들링 없이 CSS/JS를 개별로 받는다. 동시 요청
수가 커서 이 경합이 실제로 터지는 이유이고, 번들링하는 SPA 계열 서비스에서 같은 증상이
보고되지 않은 이유이기도 하다.

**주의**

- 이 Ingress는 애노테이션을 **하나도** 붙이지 않는다. `plugin-config-name`을 빼는 게 목적이고,
  `cert-manager.io/*`까지 빼는 이유는 웹 Ingress와 같은 TLS Secret을 두고 Certificate를
  중복 생성하지 않게 하기 위해서다. `tls` 블록도 두지 않는다 — 같은 호스트의 SNI 인증서는
  웹 Ingress가 이미 제공한다.
- 값을 `ingress.web` 아래에 두면 **배포가 실패한다.** `values.schema.json`의 `ingress.web`이
  `additionalProperties: false`라 새 키가 스키마 검증에서 거부된다. 그래서 카탈로그 공통
  `dip:` 네임스페이스(qdrant·litellm의 `dip.mainPath`와 같은 자리)에 둔다.
- 웹 Ingress는 `path: /.*` + `use-regex: "true"`이고 이 Ingress는 literal `/static` Prefix다.
  APISIX가 더 구체적인 쪽을 고르는 것에 의존한다. 수동 적용으로 실측 확인된 동작이지만
  (`/static/dist/d3.min.js` 200, `/home` 302), APISIX 업그레이드 후에는 재확인한다.
- 키를 비우거나 지우면 이 Ingress는 렌더되지 않는다. 향후 dip-console이 같은 리소스를
  차트 밖에서 생성하게 되면 여기를 비워 중복을 없앤다 (issue #24의 B안).

### 4) Postgresql 설정

- 내장 bitnami postgresql 서브차트 대신, `cnpg-cluster`(전용 인스턴스)를 외부 DB로 사용한다.
- **사전 조건**: `cloudnative-pg` operator(`manifests/helm/cloudnative-pg/0.29.0`)가 클러스터에
  먼저 설치되어 있어야 한다.
- **배포 순서**
  ``` sh
  # 1) airflow용 DB 계정 시크릿 생성 (아래 password는 metadataConnection.pass와 동일해야 한다)
  kubectl create secret generic airflow-db-app-secret \
    --from-literal=username=airflow --from-literal=password=airflow -n airflow

  # 2) 전용 cnpg-cluster 배포
  helm upgrade airflow-db manifests/helm/cnpg-cluster/1.0.0 \
    -f manifests/helm/cnpg-cluster/1.0.0/custom-values.yaml \
    -f manifests/applicationset/airflow/1.16.0/airflow-db-values.yaml \
    --install -n airflow

  # 3) airflow 배포 (기존 배포 방법과 동일)
  helm upgrade airflow ./ -f custom-values.yaml --install -n airflow --create-namespace
  ```
- ArgoCD로 배포한다면 `manifests/applicationset/airflow/1.16.0/`의 ApplicationSet을 쓴다 —
  `airflow-db`(syncWave 0) → `airflow`(syncWave 1) 순서로 자동 배포된다. 자세한 내용은
  해당 디렉토리의 `README.md` 참고.
- custom-values.yaml
  ``` yaml
  postgresql:
    enabled: false

  data:
    metadataConnection:
      user: airflow
      pass: airflow          # 위 시크릿 생성 시 사용한 password와 동일해야 한다
      protocol: postgresql
      host: airflow-db-rw    # cnpg-cluster 릴리스명이 airflow-db일 때의 rw 서비스명
      port: 5432
      db: airflow
      sslmode: disable
  ```
- 참고: `manifests/applicationset/airflow/1.16.0/airflow-db-values.yaml`

### 5) 반복 재배포 방지 설정

ArgoCD 배포에서 airflow가 반복 재배포되거나 Secret이 사라지는 것을 막기 위한 설정이다.
배경과 실측 근거는 paasup/dip-catalog#29 · #38 · #46 참고.

**두 비밀값 모두 값이 아니라 Secret 이름을 넘긴다.** 값을 넘기는 방식은 #29에서 시도했다가
재배포 경로에서 되살아났다(#46) — 콘솔의 재배포 분기가 placeholder가 남아 있는
`default_values_yaml`을 다시 parse해 매번 새 난수를 만든다.

| Name | 설명 | 기본값 |
| ---- | ---- | ------ |
| `webserverSecretKeySecretName` | 세션 서명 키 Secret 이름(키는 `webserver-secret-key`). 비우면 차트가 렌더할 때마다 난수를 만들어 webserver가 계속 롤링되고 웹 세션이 끊긴다 | `~` |
| `fernetKeySecretName` | fernet key Secret 이름(키는 `fernet-key`). 비우면 차트가 `pre-install` 훅으로 Secret을 만드는데, 변경이 없는 sync에서 삭제만 되고 재생성되지 않는다 | `~` |
| `migrateDatabaseJob.ttlSecondsAfterFinished` | `useHelmHooks: false`와 같이 두면 TTL 삭제 ↔ selfHeal 재생성 루프가 생긴다. `~`로 끈다 | `300` |

- dip-values.yaml
  ``` yaml
  webserverSecretKeySecretName: "$WEBSERVER_SECRET_KEY_SECRET"
  fernetKeySecretName: "$FERNET_KEY_SECRET"

  migrateDatabaseJob:
    useHelmHooks: false
    ttlSecondsAfterFinished: ~
  ```
- `$WEBSERVER_SECRET_KEY_SECRET`와 `$FERNET_KEY_SECRET`는 placeholder다. dip-console-api가
  배포 시점에 Secret을 보장하고 각각 그 이름으로 치환한다
  (`catalogs/catalogtype/catalog_airflow.go`의 `DeployPreInstall`). Secret이 이미 있으면
  값을 건드리지 않으므로, 재배포해도 같은 이름으로 치환되고 렌더가 안정적이다.
  **카탈로그와 dip-console-api를 함께 반영해야 한다** — 한쪽만 반영하면 placeholder 문자열이
  그대로 Secret 이름이 되거나 아무 일도 일어나지 않는다.
- **이름을 넘기는 것이 값을 고정하는 것보다 강하다.** `*SecretName`이 설정되면 차트의 Secret
  템플릿이 `{{- if not .Values.<key>SecretName }}` 가드로 비고, `checksum/` 애노테이션이
  해싱하는 대상이 상수가 된다 — Deployment spec이 애초에 키 값에 의존하지 않게 되므로
  앞으로 어떤 이유로 키가 바뀌어도 롤링이 발생하지 않는다.
- 같은 내용을 `manifests/applicationset/airflow/1.16.0/dip-values.yaml`(`---` 뒤 두 번째
  YAML 문서)에도 반영한다.
- 이미 배포된 테넌트는 **재배포해야 적용된다.** 두 Secret 모두 기존 것을 그대로 인수하므로
  fernet의 Connection·Variable과 webserver 세션이 유지된다.
- **마이그레이션 시 ArgoCD prune 주의** — 차트가 만들던 `<릴리스명>-webserver-secret-key`는
  `argocd.argoproj.io/tracking-id` 애노테이션이 붙은 추적 대상이다. 차트가 이 Secret을 더 이상
  렌더하지 않는 순간 ArgoCD는 "소스에서 사라졌다"고 보고 `prune: true`면 삭제한다. 콘솔이
  같은 이름으로 인수하되 `argocd.argoproj.io/tracking-id`와 `app.kubernetes.io/instance`를
  반드시 벗겨내야 한다.

- **helm으로 직접 배포할 때**는 dip-console-api를 거치지 않으므로 두 Secret을 직접 만든다.
  **키 이름이 정해져 있다** — 차트가 `secretKeyRef`로 하드코딩해 읽는다(`_helpers.yaml`).
  ``` sh
  gen() { python3 -c "import os,base64; print(base64.urlsafe_b64encode(os.urandom(32)).decode())"; }

  # fernet key (키 이름은 반드시 fernet-key)
  kubectl create secret generic airflow-fernet-key -n airflow \
    --from-literal=fernet-key="$(gen)"

  # webserver 세션 서명 키 (키 이름은 반드시 webserver-secret-key)
  kubectl create secret generic airflow-webserver-secret-key -n airflow \
    --from-literal=webserver-secret-key="$(gen)"
  ```
  ``` yaml
  webserverSecretKeySecretName: "airflow-webserver-secret-key"
  fernetKeySecretName: "airflow-fernet-key"
  ```
- 참고: `<릴리스명>-redis-password` · `<릴리스명>-broker-url`도 같은 `pre-install` 훅이라
  sync에서 사라진다. `executor: "KubernetesExecutor"`인 현재는 참조하는 워크로드가 없어
  무해하다(다음 배포 때 자동으로 다시 생긴다). CeleryExecutor로 바꾼다면 차트가 제공하는
  `redis.passwordSecretName` · `data.brokerUrlSecretName`으로 이 절과 같게 처리한다 —
  `broker-url`은 redis 비밀번호를 DSN에 포함하므로 두 Secret을 함께 생성해야 한다.