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

Airflow 배포

1. 배포 방법

1) 배포시 주의 사항

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

2) 배포 방법

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

  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 설정

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

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

3) Ingress 설정

3.1) tls 시크릿 직접 생성

• flowise에서 ingress 사용을 위해서는 다음과 같이 설정할 수 있다.

  ingress:
    web:
      enabled: true
      hosts:
      - name: "airflow.example.org"
        tls:
          enabled: true
          secretName: "airflow-tls"
  

• ingress 사용을 위해서는 인증서를 secret으로 제공해야한다. 로컬 파일을 이용해 secret을 생성하는 방법은 다음과 같다.

  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

  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를 하나 더 만들어 해당 경로를 인증 없이 통과시킨다.

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)가 클러스터에 먼저 설치되어 있어야 한다.
• 배포 순서

  # 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

  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) 반복 재배포 방지 설정

dip-values.yaml에 있는 두 항목은 airflow가 반복 재배포되는 것을 막기 위한 것이다. 원인이 서로 다르므로 따로 설명한다 (issue #29).

5.1) webserverSecretKey — 렌더 결정성

webserverSecretKey: "$WEBSERVER_SECRET_KEY"

• 이 값을 주지 않으면 차트가 템플릿 안에서 직접 난수를 만든다 (templates/secrets/webserver-secret-key-secret.yaml의 randAlphaNum 32).
• 그 Secret은 webserver·worker Deployment의 checksum/webserver-secret-key 애노테이션에 물려 있어서, 매니페스트를 다시 렌더할 때마다 Deployment spec이 바뀌고 롤링이 걸린다. 실측에서 webserver가 반복 재배포되고 그때마다 웹 세션이 끊겼다. 캐시된 매니페스트를 그대로 쓰는 reconcile로는 일어나지 않지만, 일반 refresh만으로도 일어난다.
• 차트 안에서는 못 고친다. lookup으로 기존 Secret을 재사용하는 방법은 ArgoCD repo-server가 클러스터 접근 없이 클라이언트 렌더를 하므로 항상 빈 값이 된다(클러스터에 Secret이 실제로 있는데도 빈 값인 것을 실측 확인). 릴리스명·네임스페이스 기반 결정적 파생은 렌더가 안정되는 대신 파생 입력이 전부 공개 정보라 세션 서명 키를 예측할 수 있어 부적합하다. 값이 차트 바깥에서 와야 한다.
• 그래서 $WEBSERVER_SECRET_KEY는 placeholder다. 배포 시점에 dip-console-api가 난수로 치환한다 — catalogs/catalogtype/catalog_airflow.go의 DeployPreInstall (crypto/rand 32바이트, URL-safe base64). 치환된 values가 tenant 레포에 저장되므로 이후 렌더는 그 고정값을 쓴다.
• dip-console-api와 짝이다. 한쪽만 반영되면 placeholder 문자열이 그대로 키가 되거나 (카탈로그만) 아무 일도 일어나지 않는다(console만).
• helm으로 직접 배포할 때는 dip-console-api를 거치지 않으므로 치환이 일어나지 않는다. custom-values.yaml에 실제 값을 직접 넣는다.

  # 값 생성
  python3 -c "import os,base64; print(base64.urlsafe_b64encode(os.urandom(32)).decode())"
  

• 재배포하면 새 키가 생성되어 기존 웹 세션은 무효화된다 — 사용자는 다시 로그인해야 한다.

5.2) migrateDatabaseJob.ttlSecondsAfterFinished — TTL ↔ selfHeal 루프

migrateDatabaseJob:
  useHelmHooks: false
  ttlSecondsAfterFinished: ~

• useHelmHooks: false로 두면 migrations Job이 helm hook이 아니라 ArgoCD가 추적하는 일반 리소스가 된다. ArgoCD 환경에서 hook을 끄라는 것은 업스트림 권고다 (values.yaml 주석: Disable this if you are using ArgoCD for example).
• 그런데 차트 기본값 ttlSecondsAfterFinished: 300이 그대로 남아 있으면, 완료 300초 뒤 TTL 컨트롤러가 Job을 지우고 ArgoCD는 그것을 OutOfSync로 보고 selfHeal로 다시 만든다. migrations job이 5분 주기로 재실행되는 루프가 된다.
• 둘의 조합이 문제다. 하나만 있으면 발생하지 않는다.
• 리소스 수명은 ArgoCD가 관리하므로 TTL을 끈다. ~(null)이면 템플릿의 kindIs "invalid" 가드에 걸려 ttlSecondsAfterFinished 필드 자체가 렌더되지 않는다 (templates/jobs/migrate-database-job.yaml). 대신 완료된 Job 객체가 네임스페이스에 남는다.
• createUserJob도 ttlSecondsAfterFinished: 300 + useHelmHooks: true로 구조가 같지만, hook이 살아 있어 ArgoCD 추적 대상이 아니므로 지금은 문제가 없다. useHelmHooks를 끄게 되면 TTL도 같이 꺼야 한다.

5.3) 반영 위치가 2곳이다

같은 내용을 아래 두 파일에 모두 반영해야 한다. 한쪽만 고치면 배포 경로에 따라 증상이 남는다.

• manifests/helm/airflow/1.16.0/dip-values.yaml
• manifests/applicationset/airflow/1.16.0/dip-values.yaml (--- 뒤 두 번째 YAML 문서)

5.4) 이미 배포된 테넌트

tenant 레포에 저장된 values에는 이 설정이 없으므로, 재배포해야 적용된다. 그전까지 기존 테넌트의 롤링·job 재실행 루프는 계속된다.