obsidian/infra/apisix-manual.md

title, updated, tags

title	updated	tags
APISIX 운영 매뉴얼	2026-03-15	infra apisix manual

접속

서울 (incus-hp2)

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)

ssh apisix-osaka
curl -s http://127.0.0.1:9180/apisix/admin/routes -H 'X-API-KEY: <key>'

Admin API

라우트 조회/생성/삭제

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 관리

# 전체 조회
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 인증서 관리

# 전체 조회
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 플러그인 (라우트별 파일 로깅)

# 특정 라우트에 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"
        }
    }
}'

커스텀 로그 포맷 (글로벌)

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)

plugin_attr:
    log-rotate:
        interval: 3600
        max_kept: 168
        enable_compression: false

nginx access log 포맷 (config.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	요청 횟수 제한

플러그인 활성화/비활성화

# 라우트에 플러그인 추가 (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 — 인증서 자동 갱신