# 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/)