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. etcd StorageClass 확인

etcd:
  persistence:
    storageClass: longhorn   # 클러스터에 설치된 StorageClass로 변경

클러스터에 longhorn이 없으면 PVC가 Pending 상태로 남아 배포가 중단된다. 사용 가능한 StorageClass는 kubectl get storageclass로 확인한다.

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          # 내장 etcd 사용 (개발/테스트용)
  replicaCount: 3        # 운영 환경 HA: 3개 권장
  persistence:
    enabled: true
    size: 8Gi

운영 환경 주의: 내장 etcd는 테스트 전용이다. 운영에서는 etcd.enabled: false로 설정하고 외부 etcd를 externalEtcd로 연결한다.

externalEtcd (외부 etcd 연동)

etcd:
  enabled: false
externalEtcd:
  host:
    - http://etcd-cluster.platform.svc.cluster.local:2379
  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 데이터 마이그레이션

• 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
• APISIX 공식 문서
• APISIX Admin API