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

# Upgrade History

## 2.16.0 → 2.17.0
### 변경 요약
- from_version: 2.16.0
- to_version: 2.17.0
- Chart `apisix` 2.16.0 → 2.17.0 업데이트
- Values: +0 / -0 / ~1 / type~0
- Templates: +0 / -0
- Dependencies: +0 / -0 / ~1

### custom-values.yaml 수정 필요 항목
없음

### 참고
- severity: warning
- breaking: false

### ⚠️ ingress-controller 서브차트 — 신규 CRD 수동 적용 필요

`ingress-controller.enabled: true`(이 카탈로그의 기본 설정)로 켜서 쓰는
`apisix-ingress-controller` 서브차트가 1.2.0 → 1.3.0으로 함께 올라간다. 이 diff는
자동 파이프라인(`helm_diff`)이 못 잡는다 — `ingress-controller`가 차트 기본값으로는
꺼져 있어(`enabled: false`) 커스텀 오버라이드 없이 렌더링하면 이 서브차트 자체가
스캔 대상에서 빠지기 때문이다(수동 확인, `catalog-update-pipeline` SKILL.md
"helm_diff 사각지대" 참고).

**새 CRD `l4routepolicies.apisix.apache.org`가 추가됐다.** ClusterRole도 그에 맞춰
`configmaps`·`l4routepolicies`·`l4routepolicies/status` 권한이 확장됐다(전부 추가,
제거 없음 — 하위 호환 깨지지 않음).

**Helm은 `helm upgrade`에서 기존 설치의 CRD를 자동 갱신하지 않는다.** 업그레이드 전에
새 CRD를 직접 적용해야 한다:

```bash
kubectl apply -f https://raw.githubusercontent.com/apache/apisix-helm-chart/apisix-ingress-controller-1.3.0/charts/apisix-ingress-controller/crds/apisixic-crds.yaml
```

적용하지 않아도 기존 리소스(`ApisixRoute` 등)는 그대로 동작한다 — `L4RoutePolicy`
리소스를 새로 쓰려는 경우에만 필요하다.

# 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. 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`) 차트를 가리킨다.

```yaml
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 확인

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

```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          # 켜면 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 차트 연동)

```yaml
etcd:
  enabled: false
externalEtcd:
  host:
    - http://etcd.etcd-system.svc.cluster.local:2379   # manifests/helm/etcd/1.1.12 기본 배포 기준
  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 데이터 마이그레이션

- 기본값은 `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](https://github.com/apache/apisix-helm-chart)
- [APISIX 공식 문서](https://apisix.apache.org/docs/)
- [APISIX Admin API](https://apisix.apache.org/docs/apisix/admin-api/)