APISIX 운영 매뉴얼 추가

Admin API, SSL, 로깅, 플러그인 사용법 정리 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-15 09:38:19 +09:00
parent e914b7c564
commit 7d501cebfe
1 changed files with 194 additions and 0 deletions
--- a/infra/apisix-manual.md
+++ b/infra/apisix-manual.md
@@ -0,0 +1,194 @@
+---
+title: APISIX 운영 매뉴얼
+updated: 2026-03-15
+tags: [infra, apisix, manual]
+---
+
+## 접속
+
+### 서울 (incus-hp2)
+```bash
+sudo incus exec apisix -- sh
+# Admin API
+sudo incus exec apisix -- curl -s http://127.0.0.1:9180/apisix/admin/routes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
+```
+
+### 오사카 (apisix-osaka)
+```bash
+ssh apisix-osaka
+curl -s http://127.0.0.1:9180/apisix/admin/routes -H 'X-API-KEY: <key>'
+```
+
+## Admin API
+
+### 라우트 조회/생성/삭제
+```bash
+KEY="X-API-KEY: edd1c9f034335f136f87ad84b625c8f1"
+
+# 전체 조회
+curl -s http://127.0.0.1:9180/apisix/admin/routes -H "$KEY"
+
+# 특정 라우트 조회
+curl -s http://127.0.0.1:9180/apisix/admin/routes/{id} -H "$KEY"
+
+# 라우트 생성/수정
+curl -X PUT http://127.0.0.1:9180/apisix/admin/routes/{id} -H "$KEY" \
+  -H 'Content-Type: application/json' -d '{
+    "uri": "/*",
+    "hosts": ["example.com"],
+    "upstream_id": "my-upstream"
+}'
+
+# 라우트 삭제
+curl -X DELETE http://127.0.0.1:9180/apisix/admin/routes/{id} -H "$KEY"
+```
+
+### Upstream 관리
+```bash
+# 전체 조회
+curl -s http://127.0.0.1:9180/apisix/admin/upstreams -H "$KEY"
+
+# 생성/수정
+curl -X PUT http://127.0.0.1:9180/apisix/admin/upstreams/{id} -H "$KEY" \
+  -H 'Content-Type: application/json' -d '{
+    "name": "my-upstream",
+    "type": "roundrobin",
+    "scheme": "https",
+    "pass_host": "pass",
+    "nodes": [
+        {"host": "192.168.9.134", "port": 443, "weight": 1},
+        {"host": "192.168.9.214", "port": 443, "weight": 1}
+    ]
+}'
+
+# 삭제
+curl -X DELETE http://127.0.0.1:9180/apisix/admin/upstreams/{id} -H "$KEY"
+```
+
+### SSL 인증서 관리
+```bash
+# 전체 조회
+curl -s http://127.0.0.1:9180/apisix/admin/ssls -H "$KEY"
+
+# 등록 (cert-manager에서 가져올 때)
+CERT=$(sudo k3s kubectl get secret wildcard-inouter-com-tls -n tools -o jsonpath='{.data.tls\.crt}' | base64 -d)
+SKEY=$(sudo k3s kubectl get secret wildcard-inouter-com-tls -n tools -o jsonpath='{.data.tls\.key}' | base64 -d)
+
+curl -X PUT http://127.0.0.1:9180/apisix/admin/ssls/{id} -H "$KEY" \
+  -H 'Content-Type: application/json' -d '{
+    "snis": ["*.inouter.com", "inouter.com"],
+    "cert": "'"$CERT"'",
+    "key": "'"$SKEY"'"
+}'
+
+# 삭제
+curl -X DELETE http://127.0.0.1:9180/apisix/admin/ssls/{id} -H "$KEY"
+```
+
+## 로깅
+
+### 현재 상태
+access.log/error.log가 `/dev/stdout`, `/dev/stderr`로 심링크 → 파일로 안 남음.
+
+### file-logger 플러그인 (라우트별 파일 로깅)
+```bash
+# 특정 라우트에 file-logger 추가
+curl -X PATCH http://127.0.0.1:9180/apisix/admin/routes/{id} -H "$KEY" \
+  -H 'Content-Type: application/json' -d '{
+    "plugins": {
+        "file-logger": {
+            "path": "/tmp/apisix/logs/access.log"
+        }
+    }
+}'
+```
+
+### 커스텀 로그 포맷 (글로벌)
+```bash
+curl -X PUT http://127.0.0.1:9180/apisix/admin/plugin_metadata/file-logger -H "$KEY" -d '{
+    "log_format": {
+        "host": "$host",
+        "@timestamp": "$time_iso8601",
+        "client_ip": "$remote_addr",
+        "method": "$request_method",
+        "uri": "$request_uri",
+        "status": "$status",
+        "upstream_addr": "$upstream_addr"
+    }
+}'
+```
+
+### log-rotate 설정 (config.yaml)
+```yaml
+plugin_attr:
+    log-rotate:
+        interval: 3600
+        max_kept: 168
+        enable_compression: false
+```
+
+### nginx access log 포맷 (config.yaml)
+현재 설정:
+```yaml
+nginx_config:
+  http:
+    access_log_format: >
+      $remote_addr - $remote_user [$time_local] $http_host "$request"
+      $status $body_bytes_sent $request_time "$http_referer"
+      "$http_user_agent" $upstream_addr $upstream_status
+      $upstream_response_time "$upstream_scheme://$upstream_host$upstream_uri"
+    access_log_format_escape: default
+```
+
+## 주요 플러그인
+
+| 플러그인 | 용도 |
+|---------|------|
+| chaitin-waf | SafeLine WAF 연동 |
+| ip-restriction | IP 차단/허용 |
+| cors | CORS 설정 |
+| real-ip | 실제 클라이언트 IP 추출 |
+| redirect | HTTP→HTTPS 리다이렉트 |
+| proxy-rewrite | URI/헤더 변환 |
+| file-logger | 파일 로깅 |
+| http-logger | HTTP 엔드포인트로 로그 전송 |
+| log-rotate | 로그 로테이션 |
+| jwt-auth | JWT 인증 |
+| basic-auth | Basic 인증 |
+| limit-req | 요청 제한 |
+| limit-count | 요청 횟수 제한 |
+
+### 플러그인 활성화/비활성화
+```bash
+# 라우트에 플러그인 추가 (PATCH로 기존 설정 유지)
+curl -X PATCH http://127.0.0.1:9180/apisix/admin/routes/{id} -H "$KEY" \
+  -H 'Content-Type: application/json' -d '{
+    "plugins": {
+        "ip-restriction": {
+            "whitelist": ["192.168.9.0/24"]
+        }
+    }
+}'
+
+# 플러그인 제거
+curl -X PATCH http://127.0.0.1:9180/apisix/admin/routes/{id} -H "$KEY" \
+  -H 'Content-Type: application/json' -d '{
+    "plugins": {
+        "ip-restriction": null
+    }
+}'
+```
+
+## 설정 파일
+
+- config.yaml: `/usr/local/apisix/conf/config.yaml`
+- 설정 변경 후: `apisix reload` (컨테이너 내부)
+
+## SSL ID 규칙
+
+도메인 MD5 해시 앞 16자리 사용.
+
+## 참고
+
+- [[apisix]] — 아키텍처 및 라우트 현황
+- [[cert-manager]] — 인증서 자동 갱신