wbsong111
6290322f1b
- VM stack 10 charts: victoria-metrics-cluster/auth, victoria-logs-cluster, victoria-metrics-agent/alert, opentelemetry-collector, kube-state-metrics, prometheus-node-exporter, alertmanager, perses (JWT/OIDC, Infisical-ready) - ArgoCD ApplicationSet (syncWave) + per-chart dip-values overlays - doc/victoria-metrics-architecture.md, define-chart-resources updates - includes pending working-tree changes (mlflow, kubeflow, apisix, CLAUDE.md) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
215 lines
5.1 KiB
Markdown
215 lines
5.1 KiB
Markdown
# 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/)
|