service-catalog/manifests/helm/apisix/2.16.0/CUSTOM-README.md

Apache APISIX 2.14.0 (appVersion 3.16.0) — PaaSup 커스텀 가이드

개요

Apache APISIX는 고성능 클라우드 네이티브 API Gateway이다. 이 차트는 APISIX 게이트웨이와 선택적으로 내장 etcd, Ingress Controller를 함께 배포한다.

배포 전 필수 변경사항

아래 항목을 변경하지 않으면 보안 취약점 또는 배포 오류가 발생한다.

1. 어드민 키 교체 (보안)

custom-values.yaml에 어드민 키가 두 곳에 있으며, 반드시 동일한 값으로 교체해야 한다.

# 키 생성
openssl rand -hex 16

# 변경 위치 1
apisix:
  admin:
    credentials:
      admin: "<생성된 키>"

# 변경 위치 2
ingress-controller:
  gatewayProxy:
    provider:
      controlPlane:
        auth:
          adminKey:
            value: "<동일한 키>"

두 값이 불일치하면 ingress-controller가 Admin API 인증에 실패해 라우트 등록이 되지 않는다.

2. externalEtcd 접속 정보 확인 (CVE 대응으로 기본값 변경됨)

etcd.enabled는 **기본 false**다. 내장 etcd(bitnami 서브차트)가 쓰던 bitnamilegacy/etcd:latest가 CVE 게이트 차단 65건(2026-08-11 실측)이었고, 업스트림이 latest 태그만 제공해 태그 교체로 해소되지 않는 알려진 이슈다 (bitnami/containers#83267). 기본값은 카탈로그의 하드닝된 별도 etcd(manifests/helm/etcd/1.1.12) 차트를 가리킨다.

externalEtcd:
  host:
    - http://etcd.etcd-system.svc.cluster.local:2379   # 릴리스명 etcd, 네임스페이스 etcd-system 기준

manifests/helm/etcd/1.1.12를 다른 릴리스명/네임스페이스로 배포했거나 TLS(autoTls)를 켰다면 host/TLS 설정을 그에 맞게 바꾼다. 그 차트가 아직 없다면 먼저 배포한다 (manifests/helm/etcd/1.1.12/CUSTOM-README.md).

개발/테스트에서 내장 etcd가 필요하면 etcd.enabled: true로 되돌릴 수 있지만, 그러면 bitnamilegacy/etcd:latest의 CVE 노출이 그대로 돌아온다는 점을 감수해야 한다.

3. ingress-controller 엔드포인트 및 publishService 확인

릴리스 이름이나 네임스페이스가 다를 경우 아래 두 값을 수정한다.

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

image:
  repository: apache/apisix
  tag: 3.16.0-ubuntu
  pullPolicy: IfNotPresent

• tag: -ubuntu 접미사 이미지 사용 권장 (distroless 대비 디버깅 편의)
• 내부 레지스트리 사용 시 repository를 <registry>/apache/apisix로 변경한다

replicaCount

• 기본값 2 (HA 구성)
• 단일 노드 테스트 환경에서는 1로 줄여도 무방하다

resources

resources:
  limits:
    cpu: "1000m"
    memory: "1Gi"
  requests:
    cpu: "250m"
    memory: "512Mi"

• 트래픽 규모에 따라 조정한다 (doc/define-chart-resources.md 참고)

service

service:
  type: LoadBalancer   # 또는 NodePort / ClusterIP
  http:
    enabled: true
    servicePort: 80
  tls:
    enabled: false
    servicePort: 443

• 클러스터 내부 전용이면 type: ClusterIP로 변경한다
• TLS 종료를 APISIX에서 처리하려면 tls.enabled: true로 설정한다

ingress

ingress:
  enabled: false
  annotations:
    kubernetes.io/ingress.class: kong
  hosts:
    - host: apisix.example.com
      paths:
        - path: /
          pathType: Prefix

• APISIX Admin API를 외부에 노출할 경우에만 활성화한다
• host를 실제 도메인으로 변경한다

etcd (내장 etcd, 기본 비활성)

etcd:
  enabled: true          # 켜면 bitnamilegacy/etcd:latest 의 CVE 노출이 돌아온다
  replicaCount: 3        # 운영 환경 HA: 3개 권장
  persistence:
    enabled: true
    size: 8Gi

기본값이 externalEtcd로 바뀌었다(CVE 대응). 내장 etcd는 개발/테스트에서 etcd.enabled: true로 켤 수 있지만, bitnamilegacy/etcd:latest는 상위 태그가 없어 CVE 게이트가 계속 차단한다.

externalEtcd (기본값 — 카탈로그의 하드닝된 etcd 차트 연동)

etcd:
  enabled: false
externalEtcd:
  host:
    - http://etcd.etcd-system.svc.cluster.local:2379   # manifests/helm/etcd/1.1.12 기본 배포 기준
  user: ""
  password: ""

ingress-controller

ingress-controller:
  enabled: false   # Kubernetes Ingress Controller 역할이 필요할 때만 true

배포 명령어

# 네임스페이스 생성
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 데이터 마이그레이션

• 기본값은 externalEtcd(카탈로그 etcd 차트)라 이 차트 자체의 업그레이드는 etcd 데이터에 영향을 주지 않는다
• etcd.enabled: true로 내장 etcd를 쓰는 중이라면 버전 업그레이드 전 스냅샷을 반드시 백업한다 — etcd.image.tag가 latest 고정이라(bitnami/containers#83267) 버전 고정이 필요하면 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
• APISIX 공식 문서
• APISIX Admin API