obsidian/infra/apisix-manual.md

---
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]] — 인증서 자동 갱신