Apache APISIX는 강력하고 유연한 API 게이트웨이지만, 운영 안정성을 위해서는 장애나 시스템 이전 상황에 대비한 체계적인 백업 및 복원 전략이 필수적입니다. APISIX의 설정은 정적 파일과 동적 데이터 저장소(etcd)에 나뉘어 저장되므로, 이 두 가지를 모두 고려해야 완벽한 백업이 가능합니다.
이 가이드에서는 APISIX의 모든 설정 요소를 안정적으로 백업하고, 필요시 복원하는 방법을 단계별로 상세히 설명합니다.
1. APISIX 설정의 두 가지 축: 정적 파일과 동적 데이터
APISIX 설정을 이해하는 핵심은 두 가지 저장소의 역할을 구분하는 것입니다.
- 정적 설정 파일: APISIX 서비스 자체의 동작 방식을 정의합니다. 주로 시스템 부팅 시 한 번 읽히며, 변경 시 서비스 재시작이 필요합니다.
- 동적 설정 데이터 (etcd): 라우팅 규칙, 서비스, 업스트림 등 실시간으로 변경되는 운영 데이터를 저장합니다. APISIX는 etcd의 변경 사항을 실시간으로 감지하여 서비스 재시작 없이 적용합니다.
따라서 성공적인 백업은 이 두 가지를 모두 포함해야 합니다.
2. 주요 정적 설정 파일 백업
APISIX의 핵심 동작을 정의하는 파일들은 주로 설치 경로의 conf 디렉토리에 위치합니다.
| 경로 | 설명 | 백업 중요도 |
|---|---|---|
/usr/local/apisix/conf/config.yaml | APISIX 핵심 설정 파일: etcd 연결 정보, 플러그인 목록, 로그 레벨 등 가장 중요한 설정을 포함합니다. | 필수 |
/usr/local/apisix/conf/apisix.yaml | 정적 Route/Upstream 정의 파일: YAML 파일로 라우팅 규칙을 관리할 때 사용됩니다. (선택적 사용) | 선택 |
/usr/local/apisix/conf/certs/ | SSL 인증서 저장 디렉토리: HTTPS 통신을 위한 모든 인증서(.crt)와 개인 키(.key) 파일이 저장됩니다. | 필수 (HTTPS 사용 시) |
/usr/local/apisix/plugins/ | 커스텀 플러그인 디렉토리: Lua로 직접 개발한 커스텀 플러그인 파일(*.lua)이 위치합니다. | 필수 (커스텀 플러그인 사용 시) |
/usr/local/apisix/conf/config-default.yaml | 기본값 설정 파일. (사용자 설정이 아니므로 백업 대상은 아니지만, 설정 비교 시 참고용으로 유용합니다.) | 참고용 |
💡 Tip: 기본 설치 경로는
/usr/local/apisix/입니다. Docker, Kubernetes(Helm) 등 컨테이너 환경에서는 볼륨 마운트 경로가 다를 수 있으니, 실제 환경에 맞게 경로를 확인해야 합니다.
3. etcd에 저장된 동적 설정 백업
APISIX 운영의 핵심인 Routes, Services, Upstreams, Consumers, SSL 인증서 정보 등은 모두 etcd에 저장됩니다. etcd 데이터를 백업하는 방법은 크게 두 가지입니다.
방법 1: etcd 스냅샷 (가장 권장되는 공식적인 방법)
etcd 클러스터 전체를 특정 시점의 바이너리 파일로 백업합니다. 가장 안정적이고 일관된 복원을 보장합니다.
# etcdctl v3 API 사용, 인증서 경로 등은 실제 환경에 맞게 수정
ETCDCTL_API=3 etcdctl \
--endpoints=https://127.0.0.1:2379 \
--cacert=/etc/etcd/ssl/ca.pem \
--cert=/etc/etcd/ssl/etcd.pem \
--key=/etc/etcd/ssl/etcd-key.pem \
snapshot save /backup/etcd_snapshot_$(date +%Y%m%d).db방법 2: Key-Value 데이터를 JSON으로 백업
etcd에 저장된 모든 Key-Value 쌍을 사람이 읽을 수 있는 JSON 형식으로 추출합니다. 데이터 확인 및 부분 복원에 유용하지만, 대규모 데이터 복원 시에는 스냅샷 방식이 더 효율적입니다.
# APISIX가 사용하는 모든 데이터를 JSON 형식으로 백업
ETCDCTL_API=3 etcdctl get "" --prefix -w=json > /backup/etcd-backup_$(date +%Y%m%d).json4. 환경별 추가 백업 항목
Helm 기반 설치 환경
Kubernetes에서 Helm으로 APISIX를 배포한 경우, 배포 시 사용된 values.yaml 파일이 인프라 설정의 원본 소스가 됩니다. 이 파일을 반드시 백업해야 합니다.
# 현재 배포된 APISIX의 values 설정을 파일로 저장
helm get values apisix -n apisix > apisix-values-backup.yaml모니터링 및 대시보드 환경
APISIX와 연동된 Prometheus, Grafana, APISIX Dashboard를 사용한다면, 해당 컴포넌트의 설정도 백업 대상에 포함해야 합니다.
- Grafana: 대시보드 JSON 파일
- Prometheus:
prometheus.yml설정 파일 - APISIX Dashboard:
/usr/local/apisix-dashboard/conf/conf.yaml
5. 통합 백업 스크립트 예시 (로컬 설치 기준)
아래 스크립트는 위에서 설명한 주요 항목들을 한 번에 백업하는 예시입니다. 실제 운영 환경에서는 이 스크립트를 정기적으로 실행하도록 자동화하는 것이 좋습니다.
#!/bin/bash
# 백업 디렉토리 생성 (날짜 포함)
BACKUP_DIR=~/apisix-backup-$(date +%Y%m%d_%H%M%S)
mkdir -p $BACKUP_DIR
echo "1. 정적 설정 파일 백업 시작..."
cp /usr/local/apisix/conf/config.yaml $BACKUP_DIR/
[ -f /usr/local/apisix/conf/apisix.yaml ] && cp /usr/local/apisix/conf/apisix.yaml $BACKUP_DIR/
echo "2. SSL 인증서 디렉토리 백업..."
[ -d /usr/local/apisix/conf/certs ] && cp -r /usr/local/apisix/conf/certs $BACKUP_DIR/
echo "3. 커스텀 플러그인 디렉토리 백업..."
[ -d /usr/local/apisix/plugins ] && cp -r /usr/local/apisix/plugins $BACKUP_DIR/
echo "4. etcd 동적 데이터 백업 (JSON)..."
ETCDCTL_API=3 etcdctl get "" --prefix -w=json > $BACKUP_DIR/etcd-backup.json
# 또는 스냅샷 방식 사용
# ETCDCTL_API=3 etcdctl snapshot save $BACKUP_DIR/etcd_snapshot.db
echo "✅ APISIX 설정 백업 완료: $BACKUP_DIR"6. 복원 시 핵심 주의사항
- 정적 파일 복원: 백업된
config.yaml,certs/,plugins/등을 원본 위치에 복사한 후에는 반드시 APISIX 서비스를 재시작해야 변경 사항이 적용됩니다. (apisix restart) - etcd 데이터 복원:
- 스냅샷 복원:
etcdctl snapshot restore명령을 사용합니다. 이 작업은 기존 etcd 데이터 디렉토리를 덮어쓰므로, etcd 서비스를 중지한 상태에서 진행해야 합니다. 데이터 손실 위험이 있으므로 매우 신중하게 접근해야 합니다. - JSON 복원:
jq와 같은 도구를 사용하여 필요한 데이터를 추출하고, APISIX Admin API를 통해 부분적으로 복원하는 것이 더 안전할 수 있습니다.
- 스냅샷 복원:
- 순서: 일반적으로
1) etcd 데이터 복원→2) 정적 파일 복원→3) APISIX 서비스 시작/재시작순서로 진행하는 것이 논리적으로 안전합니다.
체계적인 백업은 안정적인 시스템 운영의 초석입니다. 이 가이드를 바탕으로 자신의 환경에 맞는 백업/복원 정책을 수립하고 자동화하여, 예기치 않은 상황에도 신속하게 대응할 수 있기를 바랍니다.
