From 7d501cebfe26ea5aad79ff883aaae78b01f410e6 Mon Sep 17 00:00:00 2001 From: kappa Date: Sun, 15 Mar 2026 09:38:19 +0900 Subject: [PATCH] =?UTF-8?q?APISIX=20=EC=9A=B4=EC=98=81=20=EB=A7=A4?= =?UTF-8?q?=EB=89=B4=EC=96=BC=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Admin API, SSL, 로깅, 플러그인 사용법 정리 Co-Authored-By: Claude Opus 4.6 (1M context) --- infra/apisix-manual.md | 194 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 194 insertions(+) create mode 100644 infra/apisix-manual.md diff --git a/infra/apisix-manual.md b/infra/apisix-manual.md new file mode 100644 index 0000000..3ef7c76 --- /dev/null +++ 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: ' +``` + +## 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]] — 인증서 자동 갱신