dipup 사용 차트를 카탈로그에 동기화 (7개 갱신 + 5개 신규)

dipup 이 go:embed 로 직접 보관·관리하던 Helm 차트를 카탈로그로 옮기는 첫 단계다. 두 저장소가 각자 CVE/SBOM 파이프라인을 운영하는 이중화를 해소하려면, 먼저 카탈로그가 dipup 과 같은 차트·같은 이미지를 보게 만들어야 한다. 배경: CVE 파이프라인 구성 이전에 두 곳에서 같은 차트를 유지하기 어려워 dipup 이 별도로 차트를 관리해 왔고, 그 결과 버전이 갈라졌다. 겹치는 10개 중 버전까지 일치하는 것은 postgresql-ha·dnsup 2개뿐이었다. ## 버전 갱신 (7개) — 신규 버전 디렉토리 추가, 구버전은 보존 | 차트 | 기존 | 신규 | appVersion | |---|---|---|---| | apisix | 2.14.0 | 2.16.0 | 3.16.0 → 3.17.0 | | argo-cd | 7.7.0 | 7.8.11 | v2.13.0 → v2.14.5 | | cert-manager | v1.16.1 | v1.21.0 | 동일 | | gitea | 12.4.0 | 12.6.0 | 1.24.6 → 1.26.1 | | harbor | 1.16.2 | 1.19.1 | 2.12.2 → 2.15.1 | | kyverno | 3.4.1 | 3.8.2 | v1.14.1 → v1.18.2 | | rancher | 2.10.1 | 2.14.3 | v2.10.1 → v2.14.3 | 차트 본문은 dipup 이 임베딩한 .tgz 를 그대로 전개했다(네트워크 pull 이 아니라 dipup 이 실제 배포하는 바이트와 동일함을 보장하기 위함). BUILD-README/CUSTOM-README/custom-values 3개 파일은 구버전에서 승계했다. ## 신규 추가 (5개) infisical-standalone 1.9.0, longhorn 109.3.1+up1.11.2, longhorn-crd 109.3.1+up1.11.2, metallb 0.16.1, secrets-operator v0.10.33. longhorn/longhorn-crd 는 업스트림이 아니라 Rancher 패키징 차트(109.x 라인, Rancher 2.14 계열과 짝)다. BUILD-README 의 `helm repo add` 라인은 chart_version_detector 가 파싱하는 계약이라 실제 업스트림 repo 를 검증해 기재했고, 감지기로 현재/최신 버전이 정상 조회되는 것을 확인했다. ## custom-values — 버전과 결합된 이미지 핀 정리 카탈로그 스캐너가 dipup 의 effective image 를 보게 하려면 이미지 핀이 맞아야 한다. - **kyverno: 승계본이 3.8.2 에서 깨져 재작성.** 3.4.1 은 정리 훅이 `registry: ~ / repository: bitnami/kubectl` 이라 bitnamilegacy 오버라이드가 맞았지만, 3.8.2 는 `registry: ghcr.io / repository: kyverno/readiness-checker` 로 바뀌었다. 그대로 옮기면 ghcr.io/bitnamilegacy/kubectl 이라는 없는 좌표가 된다. 해당 오버라이드를 제거하고, 3.8.2 에서 삭제된 policyReportsCleanup 키도 함께 뺐다. 남는 조치는 tag 고정뿐 (기본 tag 가 비어 latest 로 떨어짐 → v1.18.2 로 고정). - apisix: 3.16.0-keycloak-authz → 3.17.0-keycloak-authz (차트 appVersion 과 함께 이동) - gitea: image.tag 1.26.4 핀 추가 — 차트 기본 1.26.1 대비 CRITICAL 2→0, HIGH 44→12 - infisical: image.tag v0.162.7 핀 — 기본 v0.158.x 는 stale Debian base 로 OS 기인 CVE 다수(fixable CRITICAL 53→5, HIGH 491→55). redis/postgresql 은 bitnamilegacy 좌표로. - longhorn: 실측 기반 리소스 튜닝(manager request, guaranteedInstanceManagerCPU, systemManagedCSIComponentsResourceLimits). replica 수처럼 노드 수에 의존하는 값은 넣지 않았다 — 소비 측에서 주입한다. ## 검증 12개 차트 전부 `helm template --kube-version 1.34.1` 렌더 성공. 렌더 결과 이미지가 dipup 배포 이미지와 일치함을 확인(paasup/apisix:3.17.0-keycloak-authz, gitea:1.26.4-rootless, readiness-checker:v1.18.2, infisical:v0.162.7). ## 범위에서 뺀 것 - **keycloak**: 카탈로그는 codecentric(app 17.0.1-legacy), dipup 은 bitnami(app 26.2.4)로 계보가 다르다. 이슈 #1(bitnami 대체 방안 검토)의 결론이 나온 뒤 처리한다. - **rancher-monitoring(-crd)**: 14c05f1 에서 불필요 판단으로 제거된 차트이고 victoria-metrics 스택으로 대체 예정이라 추가하지 않는다. - **dip-api/dip-console**: 자체 개발 차트로 각 앱 저장소가 출처다. 대조 결과 앱 저장소와 dipup 사본이 일치해 카탈로그가 개입할 이유가 없다. - **postgresql-ha/dnsup**: 이미 버전이 일치해 작업 대상이 아니었다. ## 후속 과제 dnsup 은 카탈로그·dipup 사본(1.0.1)이 원본(dip-console-api helm/dnsup 1.0.0)보다 앞서 있다. 1.0.1 에만 있는 service.LoadBalancerIP·service.annotations 지원을 원본으로 백포트한 뒤, 카탈로그에서 dnsup 을 제거하는 것이 자체 개발 차트 출처 원칙에 맞다.
2026-08-06 09:42:24 +09:00
parent 9d5a10b09c
commit 16321b52c7
1262 changed files with 314285 additions and 0 deletions
@@ -0,0 +1,214 @@
+# Apache APISIX 2.14.0 (appVersion 3.16.0) — PaaSup 커스텀 가이드
+
+## 개요
+
+Apache APISIX는 고성능 클라우드 네이티브 API Gateway이다.
+이 차트는 APISIX 게이트웨이와 선택적으로 내장 etcd, Ingress Controller를 함께 배포한다.
+
+## 배포 전 필수 변경사항
+
+> 아래 항목을 변경하지 않으면 **보안 취약점 또는 배포 오류**가 발생한다.
+
+### 1. 어드민 키 교체 (보안)
+
+`custom-values.yaml`에 어드민 키가 두 곳에 있으며, **반드시 동일한 값**으로 교체해야 한다.
+
+```bash
+# 키 생성
+openssl rand -hex 16
+```
+
+```yaml
+# 변경 위치 1
+apisix:
+  admin:
+    credentials:
+      admin: "<생성된 키>"
+
+# 변경 위치 2
+ingress-controller:
+  gatewayProxy:
+    provider:
+      controlPlane:
+        auth:
+          adminKey:
+            value: "<동일한 키>"
+```
+
+두 값이 불일치하면 ingress-controller가 Admin API 인증에 실패해 라우트 등록이 되지 않는다.
+
+### 2. etcd StorageClass 확인
+
+```yaml
+etcd:
+  persistence:
+    storageClass: longhorn   # 클러스터에 설치된 StorageClass로 변경
+```
+
+클러스터에 `longhorn`이 없으면 PVC가 Pending 상태로 남아 배포가 중단된다.
+사용 가능한 StorageClass는 `kubectl get storageclass`로 확인한다.
+
+### 3. ingress-controller 엔드포인트 및 publishService 확인
+
+릴리스 이름이나 네임스페이스가 다를 경우 아래 두 값을 수정한다.
+
+```yaml
+ingress-controller:
+  gatewayProxy:
+    publishService: <namespace>/<release-name>-gateway   # 기본: apisix/apisix-gateway
+    provider:
+      controlPlane:
+        endpoints:
+          - http://<release-name>-admin.<namespace>.svc.cluster.local:9180
+          # 기본: http://apisix-admin.apisix.svc.cluster.local:9180
+```
+
+---
+
+## custom-values.yaml 필드 설명
+
+### image
+
+```yaml
+image:
+  repository: apache/apisix
+  tag: 3.16.0-ubuntu
+  pullPolicy: IfNotPresent
+```
+
+- `tag`: `-ubuntu` 접미사 이미지 사용 권장 (distroless 대비 디버깅 편의)
+- 내부 레지스트리 사용 시 `repository`를 `<registry>/apache/apisix`로 변경한다
+
+### replicaCount
+
+- 기본값 `2` (HA 구성)
+- 단일 노드 테스트 환경에서는 `1`로 줄여도 무방하다
+
+### resources
+
+```yaml
+resources:
+  limits:
+    cpu: "1000m"
+    memory: "1Gi"
+  requests:
+    cpu: "250m"
+    memory: "512Mi"
+```
+
+- 트래픽 규모에 따라 조정한다 (`doc/define-chart-resources.md` 참고)
+
+### service
+
+```yaml
+service:
+  type: LoadBalancer   # 또는 NodePort / ClusterIP
+  http:
+    enabled: true
+    servicePort: 80
+  tls:
+    enabled: false
+    servicePort: 443
+```
+
+- 클러스터 내부 전용이면 `type: ClusterIP`로 변경한다
+- TLS 종료를 APISIX에서 처리하려면 `tls.enabled: true`로 설정한다
+
+### ingress
+
+```yaml
+ingress:
+  enabled: false
+  annotations:
+    kubernetes.io/ingress.class: kong
+  hosts:
+    - host: apisix.example.com
+      paths:
+        - path: /
+          pathType: Prefix
+```
+
+- APISIX Admin API를 외부에 노출할 경우에만 활성화한다
+- `host`를 실제 도메인으로 변경한다
+
+### etcd (내장 etcd)
+
+```yaml
+etcd:
+  enabled: true          # 내장 etcd 사용 (개발/테스트용)
+  replicaCount: 3        # 운영 환경 HA: 3개 권장
+  persistence:
+    enabled: true
+    size: 8Gi
+```
+
+> **운영 환경 주의**: 내장 etcd는 테스트 전용이다.
+> 운영에서는 `etcd.enabled: false`로 설정하고 외부 etcd를 `externalEtcd`로 연결한다.
+
+### externalEtcd (외부 etcd 연동)
+
+```yaml
+etcd:
+  enabled: false
+externalEtcd:
+  host:
+    - http://etcd-cluster.platform.svc.cluster.local:2379
+  user: ""
+  password: ""
+```
+
+### ingress-controller
+
+```yaml
+ingress-controller:
+  enabled: false   # Kubernetes Ingress Controller 역할이 필요할 때만 true
+```
+
+## 배포 명령어
+
+```bash
+# 네임스페이스 생성
+kubectl create namespace apisix
+
+# 설치
+helm install apisix apisix/apisix \
+  --namespace apisix \
+  --version 2.14.0 \
+  -f custom-values.yaml
+
+# 업그레이드
+helm upgrade apisix apisix/apisix \
+  --namespace apisix \
+  --version 2.14.0 \
+  -f custom-values.yaml
+
+# 템플릿 렌더링 확인 (dry-run)
+helm template apisix apisix/apisix \
+  --version 2.14.0 \
+  -f custom-values.yaml
+```
+
+## 업그레이드 주의사항
+
+### etcd 데이터 마이그레이션
+
+- etcd 내장 차트를 사용 중이라면 버전 업그레이드 전 etcd 스냅샷을 반드시 백업한다
+- `etcd.image.tag`가 `latest`로 고정되어 있으므로 버전 고정이 필요하면 `externalEtcd`로 전환한다
+
+### Breaking Change 체크 키
+
+`custom-values.yaml`에서 관리하는 핵심 키 목록 (Breaking Change 판단 기준):
+
+- `image.repository` / `image.tag`
+- `replicaCount`
+- `resources`
+- `service.type` / `service.http.servicePort`
+- `etcd.enabled` / `etcd.replicaCount` / `etcd.persistence.size`
+- `externalEtcd.host`
+- `ingress-controller.enabled`
+
+## 참고 링크
+
+- [Apache APISIX Helm Chart GitHub](https://github.com/apache/apisix-helm-chart)
+- [APISIX 공식 문서](https://apisix.apache.org/docs/)
+- [APISIX Admin API](https://apisix.apache.org/docs/apisix/admin-api/)