NGINX web server κ³ κ°€μš©μ„±

Live Activity λͺ¨λ‹ˆν„°λ§

NGINX Plus 의 λ‚΄μž₯된 Live Activity λͺ¨λ‹ˆν„°λ§ λŒ€μ‹œλ³΄λ“œμ—μ„œ λ˜λŠ” λ‹€λ₯Έ λ„κ΅¬λ‘œ JSON을 μ „μ†‘ν•˜μ—¬ NGINX Plus 및 μ• ν”Œλ¦¬μΌ€μ΄μ…˜μ˜ μ„±λŠ₯을 μ‹€μ‹œκ°„μœΌλ‘œ 좔적할 수 μžˆμŠ΅λ‹ˆλ‹€.

이 λ¬Έμ„œμ—μ„œλŠ” λŒ€ν™”ν˜• λŒ€μ‹œλ³΄λ“œμ™€ NGINX Plus REST API인 NGINX Plusμ—μ„œ λŸ°νƒ€μž„ λͺ¨λ‹ˆν„°λ§ μ„œλΉ„μŠ€λ₯Ό κ΅¬μ„±ν•˜κ³  μ‚¬μš©ν•˜λŠ” 방법에 λŒ€ν•΄ μ„€λͺ…ν•©λ‹ˆλ‹€.

λͺ©μ°¨

1. Live Activity λͺ¨λ‹ˆν„°λ§ 정보
2. μ „μ œ 쑰건
3. 톡계에 ν‘œμ‹œν•  데이터 μˆ˜μ§‘
4. API ꡬ성
5. λŒ€μ‹œλ³΄λ“œ μ‚¬μš©
5-1. λŒ€μ‹œλ³΄λ“œμ— μ•‘μ„ΈμŠ€
5-2. νƒ­ κ°œμš”
5-3. λŒ€μ‹œλ³΄λ“œμ—μ„œ Upstream μ„œλ²„ κ΄€λ¦¬ν•˜κΈ°
5-4. λŒ€μ‹œλ³΄λ“œ μ˜΅μ…˜ ꡬ성
6. REST API μ‚¬μš©
6-1. API둜 톡계 κ°€μ Έμ˜€κΈ°
6-2. 톡계 μž¬μ„€μ •ν•˜κΈ°
6-3. API둜 Upstream μ„œλ²„ κ΄€λ¦¬ν•˜κΈ°
7. OpenAPI 사양
7-1. Swagger UI ν™œμ„±ν™”ν•˜κΈ°
7-2. Swagger UI λΉ„ν™œμ„±ν™”
7-3. Swagger UI μ‚¬μš©
7-4. API 및 Swagger UI 라이브 예제

1. Live Activity λͺ¨λ‹ˆν„°λ§ 정보

NGINX PlusλŠ” μ„œλ²„ 인프라λ₯Ό μœ„ν•œ λ‹€μ–‘ν•œ λͺ¨λ‹ˆν„°λ§ 도ꡬλ₯Ό μ œκ³΅ν•©λ‹ˆλ‹€.

μ„œλ²„ μΈν”„λΌμ˜ μ£Όμš” λΆ€ν•˜ 및 μ„±λŠ₯ μ§€ν‘œλ₯Ό λ³΄μ—¬μ£ΌλŠ” Live Activity λͺ¨λ‹ˆν„°λ§ μΈν„°νŽ˜μ΄μŠ€μΈ λŒ€ν™”ν˜• λŒ€μ‹œλ³΄λ“œ νŽ˜μ΄μ§€λŠ” NGINX Plus 릴리슀 9λΆ€ν„° μ‚¬μš©ν•  수 μžˆμŠ΅λ‹ˆλ‹€.

ν™•μž₯된 μƒνƒœ 정보λ₯Ό μ–»κ³ , 톡계λ₯Ό μž¬μ„€μ •ν•˜κ³ , Upstream μ„œλ²„λ₯Ό μ¦‰μ„μ—μ„œ κ΄€λ¦¬ν•˜κ³ , Key-Value Storeλ₯Ό 관리할 수 μžˆλŠ” μΈν„°νŽ˜μ΄μŠ€λ‘œ NGINX Plus 릴리슀 14λΆ€ν„° μ‚¬μš©ν•  수 μžˆλŠ” NGINX REST API. 이 APIλ₯Ό μ‚¬μš©ν•˜λ©΄ NewRelic λ˜λŠ” 자체 λŒ€μ‹œλ³΄λ“œμ™€ 같이 JSON μΈν„°νŽ˜μ΄μŠ€λ₯Ό μ§€μ›ν•˜λŠ” 타사 도ꡬ에 NGINX Plus μƒνƒœ 정보λ₯Ό μ—°κ²°ν•  수 μžˆμŠ΅λ‹ˆλ‹€.

Note: NGINX Plus R14 μ΄μ „μ—λŠ” λŒ€μ‹œλ³΄λ“œμ—μ„œ Upstream μ„œλ²„μ˜ 톡계 μˆ˜μ§‘ 및 관리가 status 및 upstream_conf λͺ¨λ“ˆμ„ μ‚¬μš©ν•˜μ—¬ μˆ˜ν–‰λ˜μ—ˆμŠ΅λ‹ˆλ‹€. 이제 ν™•μž₯된 status 및 upstream_conf λͺ¨λ“ˆμ€ api λͺ¨λ“ˆλ‘œ λŒ€μ²΄λ©λ‹ˆλ‹€. R16λΆ€ν„°λŠ” status 및 upstream_conf λͺ¨λ“ˆμ΄ 제거되고 api λͺ¨λ“ˆλ‘œ μ™„μ „νžˆ λŒ€μ²΄λ©λ‹ˆλ‹€.

live activity monitoring

2. μ „μ œ 쑰건

NGINX Plus REST API 및 λŒ€μ‹œλ³΄λ“œμš© NGINX Plus R14 이상 버전

ν†΅κ³„μš© 데이터(톡계에 ν‘œμ‹œν•  데이터 μˆ˜μ§‘ μ°Έμ‘°)

3. 톡계에 ν‘œμ‹œν•  데이터 μˆ˜μ§‘

가상 μ„œλ²„, Upstream μ„œλ²„ κ·Έλ£Ή λ˜λŠ” μΊμ‹œ Zoneμ—μ„œ 데이터λ₯Ό μˆ˜μ§‘ν•˜λ €λ©΄ 데이터λ₯Ό μˆ˜μ§‘ν•˜λ €λŠ” 객체에 λŒ€ν•΄ 곡유 λ©”λͺ¨λ¦¬ Zone을 μ‚¬μš©ν•˜λ„λ‘ μ„€μ •ν•΄μ•Ό ν•©λ‹ˆλ‹€. 곡유 λ©”λͺ¨λ¦¬ Zone은 NGINX Worker Processμ—μ„œ μ°Έμ‘°ν•˜λŠ” ꡬ성 및 λŸ°νƒ€μž„ μƒνƒœ 정보λ₯Ό μ €μž₯ν•©λ‹ˆλ‹€.

  • HTTP 및 TCP μ„œλ²„λ₯Ό 톡계에 ν‘œμ‹œν•˜λ €λ©΄ status_zone μ§€μ‹œλ¬Έμ„ μ§€μ •ν•©λ‹ˆλ‹€. μ—¬λŸ¬ server 블둝에 λ™μΌν•œ Zone 이름을 두 번 이상 지정할 수 μžˆμŠ΅λ‹ˆλ‹€. R19λΆ€ν„°λŠ” location 블둝에도 status_zone μ§€μ‹œλ¬Έμ„we 지정할 수 있으며, 이 경우 ν†΅κ³„λŠ” λŒ€μ‹œλ³΄λ“œμ—μ„œ μ„œλ²„μ™€ μœ„μΉ˜μ— λŒ€ν•΄ λ³„λ„λ‘œ μ§‘κ³„λ©λ‹ˆλ‹€.
server {
    # ...
    status_zone status_page;
    location / {
        proxy_pass http://backend;
        status_zone location_zone;
    }
}
  • Upstream μ„œλ²„ 그룹이 톡계에 ν‘œμ‹œλ˜λ„λ‘ ν•˜λ €λ©΄ 각 upstream 블둝 λ³„λ‘œ zone μ§€μ‹œλ¬Έμ„ μ§€μ •ν•©λ‹ˆλ‹€.
upstream backend {
    zone   backend 64k;
    server backend1.example.com;
    server backend2.example.com;
}
  • μΊμ‹œλ₯Ό 톡계에 ν‘œμ‹œν•˜λ €λ©΄ μ„€μ •μ—μ„œ 캐싱이 ν™œμ„±ν™”λ˜μ–΄ μžˆλŠ”μ§€ ν™•μΈν•˜μ„Έμš”. 캐싱을 μœ„ν•œ 곡유 λ©”λͺ¨λ¦¬ Zone은 keys_zone λ§€κ°œλ³€μˆ˜μ˜ proxy_cache_path, fastcgi_cache_path, scgi_cache_path λ˜λŠ” uwsgi_cache_path μ§€μ‹œλ¬Έμ— 지정할 수 μžˆμŠ΅λ‹ˆλ‹€.
http {
    # ...
    proxy_cache_path /data/nginx/cache keys_zone=one:10m;
}
  • Health Check을 톡계에 ν‘œμ‹œν•˜λ €λ©΄ health_check μ§€μ‹œλ¬ΈμœΌλ‘œ Health Check을 μ‚¬μš©ν•˜λ„λ‘ μ„€μ •ν•˜κ³  μ„œλ²„ 그룹이 곡유 λ©”λͺ¨λ¦¬μ— μžˆλŠ”μ§€ ν™•μΈν•©λ‹ˆλ‹€.
server {
    # ...
    status_zone status_page;
    location / {
        proxy_pass http://backend;
        health_check;
    }
}
  • ν΄λŸ¬μŠ€ν„° 정보가 λŒ€μ‹œλ³΄λ“œμ— ν‘œμ‹œλ˜λ„λ‘ ν•˜λ €λ©΄ ν΄λŸ¬μŠ€ν„°μ— NGINX Plus μΈμŠ€ν„΄μŠ€κ°€ κ΅¬μ„±λ˜μ–΄ 있고 각 μΈμŠ€ν„΄μŠ€μ—μ„œ Zone 동기화가 μ‚¬μš© μ„€μ •λ˜μ–΄ μžˆλŠ”μ§€ ν™•μΈν•˜μ„Έμš”.
  • λŒ€μ‹œλ³΄λ“œμ— Resolver 톡계λ₯Ό ν‘œμ‹œν•˜λ €λ©΄ resolver μ§€μ‹œλ¬Έμ˜ status_zone λ§€κ°œλ³€μˆ˜λ₯Ό μ§€μ •ν•©λ‹ˆλ‹€.
resolver 192.168.33.70 status_zone=resolver-zone1;

server {
    # ...
    }
  • μ™„λ£Œλ˜λ©΄ ꡬ성 νŒŒμΌμ„ μ €μž₯ν•˜κ³  μ’…λ£Œν•©λ‹ˆλ‹€.
  • ꡬ성을 ν…ŒμŠ€νŠΈν•˜κ³  NGINX Plusλ₯Ό Reloadν•©λ‹ˆλ‹€.
sudo nginx -t && sudo nginx -s reloadp

4. API ꡬ성

APIλ₯Ό ν™œμ„±ν™”ν•˜λ €λ©΄ λ‹€μŒκ³Ό 같이 ν•˜μ„Έμš”.

  • http μ»¨ν…μŠ€νŠΈμ—μ„œ APIλ₯Ό λ‹΄λ‹Ήν•  server 블둝을 μ§€μ •ν•©λ‹ˆλ‹€.
http {
    server {
        # your api configuration will be here
    }
}
  • API μš”μ²­μ„ μœ„ν•œ locationλ₯Ό μƒμ„±ν•˜κ³  이 μœ„μΉ˜μ— api μ§€μ‹œλ¬Έμ„ μ§€μ •ν•©λ‹ˆλ‹€.
http {
    # ...
    server {
        listen 192.168.1.23;
        # ...
        location /api {
            api;
            # ...
        }
    }
}
http {
    # ...
    server {
        listen 192.168.1.23;
        # ...
        location /api {
            api write=on;
            # ...
        }
    }
}
  • 예λ₯Ό λ“€μ–΄ allow 및 deny μ§€μ‹œλ¬Έμ„ μ‚¬μš©ν•˜μ—¬ 둜컬 λ„€νŠΈμ›Œν¬μ—μ„œλ§Œ μ•‘μ„ΈμŠ€λ₯Ό ν—ˆμš©ν•˜λŠ” λ“± API μœ„μΉ˜μ— λŒ€ν•œ μ•‘μ„ΈμŠ€λ₯Ό μ œν•œν•˜λŠ” 것이 μ’‹μŠ΅λ‹ˆλ‹€.
http {
    # ...
    server {
        listen 192.168.1.23;
        # ...
        location /api {
            api write=on;
            allow 192.168.1.0/24;
            deny  all;
        }
    }
}
  • λ˜ν•œ νŠΉμ • μ‚¬μš©μžμ—κ²Œλ§Œ PATCH, POST 및 DELETE λ©”μ„œλ“œμ— λŒ€ν•œ μ•‘μ„ΈμŠ€λ₯Ό μ œν•œν•˜λŠ” 것이 μ’‹μŠ΅λ‹ˆλ‹€. μ΄λŠ” HTTP κΈ°λ³Έ 인증을 κ΅¬ν˜„ν•˜μ—¬ μˆ˜ν–‰ν•  수 μžˆμŠ΅λ‹ˆλ‹€.
http {
    # ...
    server {
        listen 192.168.1.23;
        # ...
        location /api {
            limit_except GET {
                auth_basic "NGINX Plus API";
                auth_basic_user_file /path/to/passwd/file;
            }
            api   write=on;
            allow 192.168.1.0/24;
            deny  all;
        }
    }
}

/dashboard.html μœ„μΉ˜λ₯Ό μ§€μ •ν•˜μ—¬ λŒ€μ‹œλ³΄λ“œλ₯Ό ν™œμ„±ν™”ν•©λ‹ˆλ‹€. 기본적으둜 λŒ€μ‹œλ³΄λ“œλŠ” root μ§€μ‹œλ¬ΈμœΌλ‘œ μ§€μ •ν•œ root 디렉터리(예: /usr/share/nginx/html)에 μžˆμŠ΅λ‹ˆλ‹€.

http {
    # ...
    server {
        listen 192.168.1.23;
        # ...
        location /api {
            limit_except GET {
                auth_basic "NGINX Plus API";
                auth_basic_user_file /path/to/passwd/file;
            }
            api   write=on;
            allow 192.168.1.0/24;
            deny  all;
        }
        location = /dashboard.html {
            root   /usr/share/nginx/html;
        }
    }
}

μ˜΅μ…˜μœΌλ‘œ OpenAPI YAML νŒŒμΌμ— 제곡되고 NGINX Plus와 ν•¨κ»˜ μ‚¬μš©λ˜λŠ” API 사양에 λŒ€ν•œ λŒ€ν™”ν˜• λ¬Έμ„œν™” 도ꡬ인 Swagger UIλ₯Ό μ‚¬μš©ν•΄ λ³Ό 수 μžˆμŠ΅λ‹ˆλ‹€. Swagger UI와 OpenAPI YAML 사양을 λ‹€μš΄λ‘œλ“œν•˜κ³ , ν•΄λ‹Ή 파일의 location(예: /swagger-ui)λ₯Ό μ§€μ •ν•˜κ³ , root μ§€μ‹œλ¬Έμ„ μ‚¬μš©ν•˜μ—¬ ν•΄λ‹Ή 파일의 경둜(예: /usr/share/nginx/html)λ₯Ό μ§€μ •ν•œ λ‹€μŒ, allow 및 deny μ§€μ‹œλ¬Έμ„ μ‚¬μš©ν•˜μ—¬ 둜컬 λ„€νŠΈμ›Œν¬μ— λŒ€ν•œ μ•‘μ„ΈμŠ€λ₯Ό μ œν•œν•˜μ„Έμš”.

http {
    # ...

    server {
        listen 192.168.1.23;
        # ...

        location /api {
            limit_except GET {
                auth_basic "NGINX Plus API";
                auth_basic_user_file /path/to/passwd/file;
            }

            api   write=on;
            allow 192.168.1.0/24;
            deny  all;
        }

        location = /dashboard.html {
            root   /usr/share/nginx/html;
        }

        location /swagger-ui {
            add_header Content-Security-Policy "default-src 'self'";
            root       /usr/share/nginx/html;
            allow      192.168.1.0/24;
            deny       all;
        }
    }
}

5. λŒ€μ‹œλ³΄λ“œ μ‚¬μš©

NGINX Plus λŒ€μ‹œλ³΄λ“œλŠ” μ„œλ²„ μΈν”„λΌμ˜ μ£Όμš” λΆ€ν•˜ 및 μ„±λŠ₯ μ§€ν‘œλ₯Ό λ³΄μ—¬μ£ΌλŠ” μ‹€μ‹œκ°„ Live Activity λͺ¨λ‹ˆν„°λ§ μΈν„°νŽ˜μ΄μŠ€λ₯Ό μ œκ³΅ν•©λ‹ˆλ‹€.

5-1. λŒ€μ‹œλ³΄λ“œμ— μ•‘μ„ΈμŠ€

λΈŒλΌμš°μ €μ˜ μ£Όμ†Œ ν‘œμ‹œμ€„μ— λŒ€μ‹œλ³΄λ“œ νŽ˜μ΄μ§€μ— ν•΄λ‹Ήν•˜λŠ” μ£Όμ†Œλ₯Ό μž…λ ₯ν•©λ‹ˆλ‹€(예: http://192.168.1.23/dashboard.html). 그러면 root μ§€μ‹œλ¬Έμ— μ§€μ •λœ λŒ€λ‘œ /usr/share/nginx/html에 μžˆλŠ” λŒ€μ‹œλ³΄λ“œ νŽ˜μ΄μ§€κ°€ ν‘œμ‹œλ©λ‹ˆλ‹€.

λ‹€μŒ λ§ν¬μ—μ„œ NGINX의 라이브 데λͺ¨ νŽ˜μ΄μ§€λ„ 확인할 수 μžˆμŠ΅λ‹ˆλ‹€.

demo.nginx.com/dashboard.html

live activity monitor

5-2. νƒ­ κ°œμš”

NGINX Plus λŒ€μ‹œλ³΄λ“œμ˜ λͺ¨λ“  μ •λ³΄λŠ” νƒ­μœΌλ‘œ ν‘œμ‹œλ©λ‹ˆλ‹€.

The row of tabs at the top of the window on the NGINXΒ Plus dashboard make it easy to drill down to more detailed information about server zones, upstream groups, or the cache

HTTP Zones 탭은 Frontend μ„±λŠ₯에 λŒ€ν•œ μžμ„Έν•œ 톡계λ₯Ό μ œκ³΅ν•©λ‹ˆλ‹€. ν†΅κ³„λŠ” http μ»¨ν…μŠ€νŠΈμ—μ„œ 각 server, location 및 limit_req μ˜μ—­λ³„λ‘œ ν‘œμ‹œλ©λ‹ˆλ‹€. NGINX Plusκ°€ 각 μ„œλ²„μ— λŒ€ν•œ 정보λ₯Ό μˆ˜μ§‘ν•˜λ €λ©΄ 각 server λ˜λŠ” location 블둝에 status_zone μ§€μ‹œλ¬Έμ„ 포함해야 ν•©λ‹ˆλ‹€. limit_req μ œν•œμ— λŒ€ν•œ 차트λ₯Ό ν¬ν•¨ν•˜λ €λ©΄ limit_req_zone μ§€μ‹œλ¬Έμ„ ꡬ성해야 ν•©λ‹ˆλ‹€.

The β€˜HTTP zones’ tab in the NGINXΒ Plus live activity monitoring dashboard displays information about NGINXΒ Plus' interaction with clients

μ—°κ²° μ œν•œ(limit_conn)에 λŒ€ν•œ μ°¨νŠΈκ°€ μžˆλŠ” TCP 및 UDP μƒνƒœ Zone이 TCP/UDP Zones 탭에 ν‘œμ‹œλ©λ‹ˆλ‹€.

The β€˜TCP/UDP zones’ tab in the NGINXΒ Plus live activity monitoring dashboard

HTTP Upstreams 탭은 HTTP 및 HTTPS νŠΈλž˜ν”½μ— λŒ€ν•œ 각 Upstream 그룹에 λŒ€ν•œ 정보λ₯Ό μ œκ³΅ν•©λ‹ˆλ‹€. TCP 및 UDP Upstreams 그룹은 TCP/UDP Upstreams 탭에 ν‘œμ‹œλ©λ‹ˆλ‹€. NGINX Plusκ°€ Upstream 그룹에 λŒ€ν•œ 정보λ₯Ό μˆ˜μ§‘ν•˜λ €λ©΄ upstream ꡬ성 블둝에 zone μ§€μ‹œλ¬Έμ„ μΆ”κ°€ν•΄μ•Ό ν•©λ‹ˆλ‹€.

The β€˜Upstreams’ tab on the NGINXΒ Plus live activity monitoring dashboard provides information about the servers in each upstream group for HTTP/HTTPS traffic

Caches 탭은 NGINX Plus에 κ΅¬μ„±λœ μΊμ‹œμ— λŒ€ν•œ 톡계λ₯Ό μ œκ³΅ν•©λ‹ˆλ‹€. NGINX Plusκ°€ Upstream 그룹에 λŒ€ν•œ 정보λ₯Ό μˆ˜μ§‘ν•˜λ €λ©΄ μΊμ‹œλ₯Ό ꡬ성해야 ν•©λ‹ˆλ‹€.

The β€˜Caches’ tab in the NGINXΒ Plus live activity monitoring dashboard provides information about cache readiness, fullness, and hit ratio

Shared Zones νƒ­μ—λŠ” cache zone, SSL session cache, upstream zone, keyval zone, session log, sticky session, limit_conn 및 limit_req zone을 ν¬ν•¨ν•œ 각 곡유 λ©”λͺ¨λ¦¬ Zoneμ—μ„œ μ‚¬μš©ν•˜λŠ” λ©”λͺ¨λ¦¬μ˜ μ‚¬μš©λŸ‰μ΄ ν‘œμ‹œλ©λ‹ˆλ‹€.

The β€˜Shared Zones’ tab in the NGINXΒ Plus live activity monitoring dashboard provides information about memory usage across all shared memory zones

Cluster 탭은 λͺ¨λ“  NGINX ν΄λŸ¬μŠ€ν„° λ…Έλ“œμ—μ„œ 곡유 λ©”λͺ¨λ¦¬ Zone의 동기화 μƒνƒœλ₯Ό μ œκ³΅ν•©λ‹ˆλ‹€.

The β€˜Cluster’ tab in the NGINXΒ Plus live activity monitoring dashboard provides synchronization information of shared memory zones of NGINX cluster nodes

Resolvers 탭은 각 DNS μƒνƒœ Zone 별 μš”μ²­ 및 응닡에 λŒ€ν•œ DNS μ„œλ²„ 톡계λ₯Ό μ œκ³΅ν•©λ‹ˆλ‹€. NGINX Plusμ—μ„œ DNS μ„œλ²„μ— λŒ€ν•œ 정보λ₯Ό μˆ˜μ§‘ν•˜λ €λ©΄ resolver μ§€μ‹œλ¬Έμ— status_zone λ§€κ°œλ³€μˆ˜λ₯Ό ν¬ν•¨ν•˜μ„Έμš”.

The β€˜Resolvers’ tab in the NGINXΒ Plus live activity monitoring dashboard provides information about cache readiness, fullness, and hit ratio

Workers 탭은 Worker Process에 λŒ€ν•œ 정보λ₯Ό μ œκ³΅ν•˜κ³  Worker별 μ—°κ²° 톡계λ₯Ό λ³΄μ—¬μ€λ‹ˆλ‹€.

5-3. λŒ€μ‹œλ³΄λ“œμ—μ„œ Upstream μ„œλ²„ κ΄€λ¦¬ν•˜κΈ°

λŒ€μ‹œλ³΄λ“œ μΈν„°νŽ˜μ΄μŠ€μ—μ„œ 직접 μƒˆ μ„œλ²„λ₯Ό μΆ”κ°€ν•˜κ±°λ‚˜ Upstream μ„œλ²„λ₯Ό μˆ˜μ • 및 μ œκ±°ν•  수 μžˆμŠ΅λ‹ˆλ‹€. 이전에 μ“°κΈ° λͺ¨λ“œμ—μ„œ apiλ₯Ό ν™œμ„±ν™”ν•΄μ•Ό ν•œλ‹€λŠ” 점에 μœ μ˜ν•˜μ„Έμš”.

Upstreams λ˜λŠ” TCP/UDP Upstreams νƒ­μ—μ„œ μ„œλ²„ 이름 μ˜†μ˜ μ—°ν•„ μ•„μ΄μ½˜μ„ ν΄λ¦­ν•˜κ³  Edit selected 및 Add server λ²„νŠΌ μ€‘μ—μ„œ μ„ νƒν•©λ‹ˆλ‹€.

Upstream μ„œλ²„λ₯Ό μΆ”κ°€ν•˜λ €λ©΄ Add serverλ₯Ό ν΄λ¦­ν•©λ‹ˆλ‹€.

The β€˜Add server’ interface for adding servers to an upstream group in the NGINXΒ Plus live activity monitoring dashboard

Upstream μ„œλ²„λ₯Ό μ œκ±°ν•˜κ±°λ‚˜ μˆ˜μ •ν•˜λ €λ©΄ 각 μ„œλ²„ 이름 μ™Όμͺ½μ— μžˆλŠ” μƒμžλ₯Ό ν΄λ¦­ν•œ λ‹€μŒ Edit selected을 ν΄λ¦­ν•©λ‹ˆλ‹€.

The β€˜Edit selected’ interface for modifying or removing servers in an upstream group in the NGINXΒ Plus live activity monitoring dashboard

μ™„λ£Œλ˜λ©΄ Save λ²„νŠΌμ„ ν΄λ¦­ν•˜μ—¬ λ³€κ²½ 사항을 μ €μž₯ν•©λ‹ˆλ‹€.

5-4. λŒ€μ‹œλ³΄λ“œ μ˜΅μ…˜ ꡬ성

νƒ­ λ©”λ‰΄μ—μ„œ ν†±λ‹ˆλ°”ν€΄ λ²„νŠΌμ„ ν΄λ¦­ν•˜μ—¬ λŒ€μ‹œλ³΄λ“œ κ²½κ³  및 μ•Œλ¦Όμ˜ μž„κ³„κ°’μ„ ꡬ성할 수 μžˆμŠ΅λ‹ˆλ‹€.

The β€˜Dashboard configuration’ interface for modifying Dashboard settings

Update every N sec – μ§€μ •λœ μ‹œκ°„(초) 후에 λŒ€μ‹œλ³΄λ“œ 데이터λ₯Ό μ—…λ°μ΄νŠΈν•˜λ©° 기본값은 1μ΄ˆμž…λ‹ˆλ‹€.

4xx warnings threshold – λŠ” HTTP Upstreamsκ³Ό HTTP Zones의 Total μš”μ²­ μˆ˜μ™€ 4xx 였λ₯˜ 수 μ‚¬μ΄μ˜ λΉ„μœ¨μ„ λ‚˜νƒ€λƒ…λ‹ˆλ‹€. 기본값은 30%μž…λ‹ˆλ‹€.

Calculate hit ratio for the past N sec – λŠ” μΊμ‹œμ— λŒ€ν•΄ μ§€μ •λœ μ‹œκ°„(초) λ‚΄μ˜ λͺ¨λ“  μΊμ‹œ hitλ₯Ό λ‚˜νƒ€λƒ…λ‹ˆλ‹€. 기본값은 300μ΄ˆμž…λ‹ˆλ‹€.

Not synced data threshold – ν΄λŸ¬μŠ€ν„°μ— λŒ€ν•œ Pending 쀑인 λ ˆμ½”λ“œμ™€ Total λ ˆμ½”λ“œ κ°„μ˜ λΉ„μœ¨μ„ λ‚˜νƒ€λƒ…λ‹ˆλ‹€. 기본값은 70%μž…λ‹ˆλ‹€.

Resolver errors threshold – Resolver에 λŒ€ν•΄ Nμ΄ˆλ§ˆλ‹€ μ—…λ°μ΄νŠΈμ— μ§€μ •λœ μ‹œκ°„ ν”„λ ˆμž„ λ‚΄ Request와 Resolver 였λ₯˜ κ°„μ˜ λΉ„μœ¨μ„ λ‚˜νƒ€λƒ…λ‹ˆλ‹€. 기본값은 3%μž…λ‹ˆλ‹€.

6. REST API μ‚¬μš©

NGINX Plusλ₯Ό μ‚¬μš©ν•˜λ©΄ REST API μΈν„°νŽ˜μ΄μŠ€λ₯Ό 톡해 μ„œλ²„ μΈν”„λΌμ˜ 톡계λ₯Ό 관리할 수 μžˆμŠ΅λ‹ˆλ‹€. APIλŠ” ν‘œμ€€ HTTP μš”μ²­μ„ 기반으둜 ν•˜λ©°, GET μš”μ²­μœΌλ‘œ 톡계λ₯Ό κ°€μ Έμ˜€κ³  DELETE μš”μ²­μœΌλ‘œ μž¬μ„€μ •ν•  수 μžˆμŠ΅λ‹ˆλ‹€. Upstream μ„œλ²„λŠ” POST μš”μ²­μ„ 톡해 μΆ”κ°€ν•  수 있고 PATCH μš”μ²­μ„ 톡해 μˆ˜μ •ν•  수 μžˆμŠ΅λ‹ˆλ‹€. μžμ„Έν•œ λ‚΄μš©μ€ API둜 Upstream μ„œλ²„ κ΄€λ¦¬ν•˜κΈ°λ₯Ό μ°Έμ‘°ν•˜μ„Έμš”.

μš”μ²­μ€ JSON ν˜•μ‹μœΌλ‘œ μ „μ†‘λ˜λ©°, 이λ₯Ό 톡해 톡계λ₯Ό JSON을 μ§€μ›ν•˜λŠ” λͺ¨λ‹ˆν„°λ§ λ„κ΅¬λ‚˜ λŒ€μ‹œλ³΄λ“œμ— μ—°κ²°ν•  수 μžˆμŠ΅λ‹ˆλ‹€.

6-1. API둜 톡계 κ°€μ Έμ˜€κΈ°

μŠ¬λž˜μ‹œλ‘œ κ΅¬λΆ„λœ URL을 μ‚¬μš©ν•˜μ—¬ λͺ¨λ“  μš”μ†Œμ˜ μƒνƒœ 정보에 μ•‘μ„ΈμŠ€ν•  수 μžˆμŠ΅λ‹ˆλ‹€. URL은 λ‹€μŒκ³Ό κ°™μŠ΅λ‹ˆλ‹€.

https://demo.nginx.com/api/8/http/caches/http_cache?fields=expi

  • /apiλŠ” API에 λŒ€ν•œ NGINX ꡬ성 νŒŒμΌμ—μ„œ κ΅¬μ„±ν•œ μœ„μΉ˜μž…λ‹ˆλ‹€.
  • /8은 API 버전이며, ν˜„μž¬ API 버전은 8μž…λ‹ˆλ‹€.
  • /http/caches/http_cacheλŠ” λ¦¬μ†ŒμŠ€ κ²½λ‘œμž…λ‹ˆλ‹€.
  • ?.fields=expired,bypassλŠ” μš”μ²­λœ 객체의 μ–΄λ–€ ν•„λ“œλ₯Ό 좜λ ₯할지 μ§€μ •ν•˜λŠ” 선택적 μΈμˆ˜μž…λ‹ˆλ‹€.

μš”μ²­λœ μ •λ³΄λŠ” JSON 데이터 ν˜•μ‹μœΌλ‘œ λ°˜ν™˜λ©λ‹ˆλ‹€.

μ‚¬μš© κ°€λŠ₯ν•œ λͺ¨λ“  rootpoint λͺ©λ‘μ„ κ°€μ Έμ˜€λ €λ©΄ ν„°λ―Έλ„μ—μ„œ ‘curl’ λͺ…λ ΉμœΌλ‘œ GET μš”μ²­μ„ λ³΄λ‚΄μ„Έμš”(μ˜ˆμ œμ—μ„œλŠ” JSON pretty print extension “json_pp”κ°€ μ‚¬μš©λ¨).

curl -s 'https://demo.nginx.com/api/8/' | json_pp

λ°˜ν™˜λœ JSON λ°μ΄ν„°μž…λ‹ˆλ‹€.

[
   "nginx",
   "processes",
   "connections",
   "slabs",
   "http",
   "stream",
   "resolvers",
   "ssl"
]

예λ₯Ό λ“€μ–΄ νŠΉμ • Endpoint에 λŒ€ν•œ 톡계λ₯Ό μ–»μœΌλ €λ©΄, 즉 NGINX에 λŒ€ν•œ 일반 정보λ₯Ό μ–»μœΌλ €λ©΄ λ‹€μŒ GET μš”μ²­μ„ λ³΄λ‚΄μ„Έμš”.

curl -s 'https://demo.nginx.com/api/8/nginx' | json_pp

λ°˜ν™˜λœ JSON λ°μ΄ν„°μž…λ‹ˆλ‹€.

{
   "generation" : 14,
   "timestamp" : "2021-06-28T14:04:51.515Z",
   "pid" : 2201,
   "address" : "206.251.255.64",
   "build" : "nginx-plus-r28",
   "version" : "1.23.2",
   "load_timestamp" : "2022-11-29T10:00:00.114Z",
   "ppid" : 92033
}

μš”μ²­ 쀄에 선택적 ν•„λ“œ 인수λ₯Ό μ‚¬μš©ν•˜μ—¬ μš”μ²­λœ 객체의 μ–΄λ–€ ν•„λ“œλ₯Ό 좜λ ₯할지 지정할 수 μžˆμŠ΅λ‹ˆλ‹€. 예λ₯Ό λ“€μ–΄, NGINX Plus 버전과 λΉŒλ“œλ§Œ ν‘œμ‹œν•˜λ €λ©΄ λ‹€μŒκ³Ό 같이 λͺ…λ Ήμ–΄λ₯Ό μ§€μ •ν•©λ‹ˆλ‹€.

curl -s 'https://demo.nginx.com/api/8/nginx?fields=version,build' | json_pp

λ°˜ν™˜λœ JSON λ°μ΄ν„°μž…λ‹ˆλ‹€.

{
   "version" : "1.23.2",
   "build" : "nginx-plus-r28"
}

μ‚¬μš© κ°€λŠ₯ν•œ Endpoint 및 μ§€μ›λ˜λŠ” λ°©λ²•μ˜ 전체 λͺ©λ‘μ€ μ°Έμ‘° λ¬Έμ„œλ₯Ό μ°Έμ‘°ν•˜μ„Έμš”.

6-2. 톡계 μž¬μ„€μ •ν•˜κΈ°

톡계 μž¬μ„€μ •μ€ DELETE λ©”μ„œλ“œκ°€ ν¬ν•¨λœ API λͺ…령을 λŒ€μƒ Endpoint에 μ „μ†‘ν•˜μ—¬ μˆ˜ν–‰ν•©λ‹ˆλ‹€. APIκ°€ Read-Write λͺ¨λ“œλ‘œ κ΅¬μ„±λ˜μ–΄ μžˆλŠ”μ§€ ν™•μΈν•˜μ„Έμš”.

λ‹€μŒκ³Ό 같은 μœ ν˜•μ˜ 톡계λ₯Ό μž¬μ„€μ •ν•  수 μžˆμŠ΅λ‹ˆλ‹€.

  • λΉ„μ •μƒμ μœΌλ‘œ μ’…λ£Œλ˜μ—ˆλ‹€κ°€ λ‹€μ‹œ μ‹œμž‘λœ μžμ‹ ν”„λ‘œμ„ΈμŠ€
  • ν—ˆμš© 및 μ‚­μ œλœ ν΄λΌμ΄μ–ΈνŠΈ μ—°κ²°
  • SSL Handshake 및 μ„Έμ…˜ μž¬μ‚¬μš©
  • 각 λ©”λͺ¨λ¦¬ μŠ¬λ‘―μ— λŒ€ν•œ μš”κ΅¬ 사항 및 μ‹€νŒ¨ μ§€ν‘œ
  • 총 ν΄λΌμ΄μ–ΈνŠΈ HTTP μš”μ²­
  • νŠΉμ • HTTP μ„œλ²„ μ˜μ—­μ—μ„œ 수락 및 폐기된 μš”μ²­, 응닡, μˆ˜μ‹  및 μ „μ†‘λœ Byte
  • νŠΉμ • μΊμ‹œ Zoneμ—μ„œ μΊμ‹œ 적쀑 및 μΊμ‹œ 미슀
  • Upstream μ„œλ²„ 그룹의 νŠΉμ • HTTP λ˜λŠ” Stream Upstream μ„œλ²„μ— λŒ€ν•œ 톡계

예λ₯Ό λ“€μ–΄ λΉ„μ •μƒμ μœΌλ‘œ μ’…λ£Œλ˜μ—ˆλ‹€κ°€ λ‹€μ‹œ μ‹œμž‘λœ μžμ‹ ν”„λ‘œμ„ΈμŠ€λ₯Ό μž¬μ„€μ •ν•˜λ €λ©΄ ν„°λ―Έλ„μ—μ„œ curl을 톡해 λ‹€μŒ λͺ…령을 μ‹€ν–‰ν•˜λ©΄ λ©λ‹ˆλ‹€.

curl -X DELETE -i 'http://192.168.1.23/api/8/processes'

ν—ˆμš© 및 μ‚­μ œλœ ν΄λΌμ΄μ–ΈνŠΈ 연결을 μž¬μ„€μ •ν•˜λ €λ©΄ λ‹€μŒ λͺ…령을 μˆ˜ν–‰ν•©λ‹ˆλ‹€.

curl -X DELETE  -i 'http://192.168.1.23/api/8/connections'

6-3. API둜 Upstream μ„œλ²„ κ΄€λ¦¬ν•˜κΈ°

NGINX Plus REST APIλŠ” Upstream 그룹에 μ„œλ²„λ₯Ό λ™μ μœΌλ‘œ μΆ”κ°€ν•˜κ±°λ‚˜ μ„œλ²„ λ§€κ°œλ³€μˆ˜λ₯Ό μˆ˜μ •ν•˜κΈ° μœ„ν•œ POST 및 PATCH HTTP λ©”μ„œλ“œλ₯Ό μ§€μ›ν•©λ‹ˆλ‹€.

Upstream 그룹의 ꡬ성을 λ™μ μœΌλ‘œ λ³€κ²½ν•˜λ €λ©΄ μ μ ˆν•œ API λ©”μ„œλ“œλ₯Ό μ‚¬μš©ν•˜μ—¬ HTTP μš”μ²­μ„ λ³΄λ‚΄μ„Έμš”. λ‹€μŒ μ˜ˆμ œμ—μ„œλŠ” curl λͺ…령을 μ‚¬μš©ν•˜μ§€λ§Œ, HTTP μš”μ²­μ„ μœ„ν•œ λͺ¨λ“  λ©”μ»€λ‹ˆμ¦˜μ΄ μ§€μ›λ©λ‹ˆλ‹€. λͺ¨λ“  μš”μ²­ λ³Έλ¬Έκ³Ό 응닡은 JSON ν˜•μ‹μž…λ‹ˆλ‹€.

URIλŠ” λ‹€μŒ 정보λ₯Ό μˆœμ„œλŒ€λ‘œ μ§€μ •ν•©λ‹ˆλ‹€.

  • μš”μ²­μ„ μ²˜λ¦¬ν•˜λŠ” λ…Έλ“œμ˜ 호슀트 λͺ… λ˜λŠ” IP μ£Όμ†Œ(λ‹€μŒ μ˜ˆμ‹œμ—μ„œλŠ” 192.168.1.23)
  • API μ§€μ‹œλ¬Έμ΄ ν‘œμ‹œλ˜λŠ” μœ„μΉ˜(api)
  • API 버전 (8)
  • Upstream 그룹의 이름, μŠ¬λž˜μ‹œλ‘œ κ΅¬λΆ„λœ 경둜(http/upstreams/appservers)둜 ν‘œμ‹œλ˜λŠ” NGINX Plus ꡬ성 계측 κ΅¬μ‘°μ—μ„œ ν•΄λ‹Ή μœ„μΉ˜λ₯Ό μ™„μ„±ν•©λ‹ˆλ‹€.

예λ₯Ό λ“€μ–΄, appservers Upstream 그룹에 μƒˆ μ„œλ²„λ₯Ό μΆ”κ°€ν•˜λ €λ©΄ λ‹€μŒ curl λͺ…령을 μ „μ†‘ν•©λ‹ˆλ‹€.

curl -X POST -d '{ \
   "server": "10.0.0.1:8089", \
   "weight": 4, \
   "max_conns": 0, \
   "max_fails": 0, \
   "fail_timeout": "10s", \
   "slow_start": "10s", \
   "backup": true, \
   "down": true \
 }' -s 'http://192.168.1.23/api/8/http/upstreams/appservers/servers'

Upstream κ·Έλ£Ήμ—μ„œ μ„œλ²„λ₯Ό μ œκ±°ν•˜λ €λ©΄ λ‹€μŒκ³Ό 같이 ν•˜μ„Έμš”.

curl -X DELETE -s 'http://192.168.1.23/api/8/http/upstreams/appservers/servers/0'

그룹의 첫 번째 μ„œλ²„(ID 0)에 λŒ€ν•œ down λ§€κ°œλ³€μˆ˜λ₯Ό μ„€μ •ν•˜λ €λ©΄ λ‹€μŒκ³Ό 같이 ν•˜μ„Έμš”.

curl -X PATCH -d '{ "down": true }' -s 'http://192.168.1.23/api/8/http/upstreams/appservers/servers/0'

7. OpenAPI 사양

NGINX Plusλ₯Ό μ‚¬μš©ν•˜λ©΄ κ·Έλž˜ν”½ μ‚¬μš©μž μΈν„°νŽ˜μ΄μŠ€λ₯Ό 톡해 REST API μ„€λͺ…μ„œλ₯Ό νƒμƒ‰ν•˜κ³  API λͺ…령을 보낼 수 μžˆμŠ΅λ‹ˆλ‹€. 이 μž‘μ—…μ€ YAML ν˜•μ‹μ˜ NGINX Plus OpenAPI 사양과 Swagger UIλ₯Ό μ‚¬μš©ν•˜μ—¬ μˆ˜ν–‰ν•  수 μžˆμŠ΅λ‹ˆλ‹€.

Swagger UI와 YAML OpenAPI μ‚¬μ–‘μ˜ μ£Όμš” λͺ©μ μ€ NGINX API λͺ…령을 λ¬Έμ„œν™”ν•˜κ³  μ‹œκ°ν™”ν•˜λŠ” κ²ƒμž…λ‹ˆλ‹€. λ³΄μ•ˆμƒμ˜ 이유둜 Production ν™˜κ²½μ—μ„œλŠ” μ‚¬μš©ν•˜μ§€ μ•ŠλŠ” 것이 μ’‹μŠ΅λ‹ˆλ‹€.

NGINX Plus 릴리슀 25 μ΄μ „μ—λŠ” Swagger UIκ°€ NGINX Plus νŒ¨ν‚€μ§€μ™€ ν•¨κ»˜ μ œκ³΅λ˜μ—ˆμŠ΅λ‹ˆλ‹€. NGINX Plus 릴리슀 26λΆ€ν„° OpenAPI YAML 사양과 Swagger UIλŠ” μ•„λž˜μ—μ„œ λ³„λ„λ‘œ κ²Œμ‹œλ©λ‹ˆλ‹€.

λ˜λŠ” μ μ ˆν•œ YAML νŒŒμΌμ— λŒ€ν•œ 링크λ₯Ό λ³΅μ‚¬ν•˜μ—¬ μ„ ν˜Έν•˜λŠ” OpenAPI v2 도ꡬλ₯Ό κ°€μ Έμ˜¬ μˆ˜λ„ μžˆμŠ΅λ‹ˆλ‹€.

7-1. Swagger UI ν™œμ„±ν™”ν•˜κΈ°

Swagger UIλ₯Ό ν™œμ„±ν™”ν•©λ‹ˆλ‹€:

1. Swagger UIλ₯Ό μ„€μΉ˜ν•˜κ³  κ΅¬μ„±ν•©λ‹ˆλ‹€. μ„€μΉ˜ νŒ¨ν‚€μ§€ 및 지침은 Swagger UI νŽ˜μ΄μ§€μ—μ„œ 확인할 수 μžˆμŠ΅λ‹ˆλ‹€.

2. μ‚¬μš© 쀑인 NGINX Plus 버전과 μΌμΉ˜ν•˜λŠ” OpenAPI YAML 파일 버전을 μ„ νƒν•˜κ³  νŒŒμΌμ„ λ‹€μš΄λ‘œλ“œν•œ ν›„ Swagger UI 파일이 λ“€μ–΄ μžˆλŠ” 폴더에 λ„£μŠ΅λ‹ˆλ‹€.

OpenAPI YAML File/API VersionNGINX Plus Versionλ³€κ²½ 사항
OpenAPI v2 for API version 8NGINX Plus Releases 27, 28각 HTTP Upstream 및 Stream Upstream에 λŒ€ν•œ SSL 톡계, 각 HTTP μ„œλ²„ Zone 및 Stream μ„œλ²„ Zone에 λŒ€ν•œ SSL 톡계, SSL Endpoint에 λŒ€ν•œ ν™•μž₯ 톡계
OpenAPI v2 for API version 7NGINX Plus Releases 25, 26각 HTTP Upstream, Server Zone 및 location Zone에 λŒ€ν•œ responses의 codes 데이터가 μΆ”κ°€λ˜μ—ˆμŠ΅λ‹ˆλ‹€.
OpenAPI v2 for API version 6NGINX Plus Releases 20, 21, 22, 23, 24/stream/limit_conns/, /http/limit_conns/ 및 /http/limit_reqs/ 데이터가 μΆ”κ°€λ˜μ—ˆμŠ΅λ‹ˆλ‹€.
OpenAPI v2 for API version 5NGINX Plus Release 19Key-Value 쌍의 expire λ§€κ°œλ³€μˆ˜λ₯Ό μ„€μ •ν•˜κ±°λ‚˜ λ³€κ²½ν•  수 있으며, /resolvers/ 및 /http/location_zones/ 데이터가 μΆ”κ°€λ˜μ—ˆμŠ΅λ‹ˆλ‹€.
OpenAPI v2 for API version 4NGINX Plus Release 18nginx error 객체의 path 및 method ν•„λ“œκ°€ μ œκ±°λ˜μ—ˆμŠ΅λ‹ˆλ‹€. μ΄λŸ¬ν•œ ν•„λ“œλŠ” 이전 API 버전에 계속 μ‘΄μž¬ν•˜μ§€λ§Œ 빈 값을 ν‘œμ‹œν•©λ‹ˆλ‹€.
OpenAPI v2 for API version 3NGINX Plus Releases 15, 16, 17/stream/zone_sync/ 데이터가 μΆ”κ°€λ˜μ—ˆμŠ΅λ‹ˆλ‹€.
OpenAPI v2 for API version 2NGINX Plus Release 14drain λ§€κ°œλ³€μˆ˜κ°€ μΆ”κ°€λ˜μ—ˆμŠ΅λ‹ˆλ‹€.
OpenAPI v2 for API version 1NGINX Plus Release 13/stream/keyvals/ 데이터가 μΆ”κ°€λ˜μ—ˆμŠ΅λ‹ˆλ‹€.

3. Swagger UI와 ν•¨κ»˜ μž‘λ™ν•˜λ„λ‘ NGINX Plusλ₯Ό κ΅¬μ„±ν•©λ‹ˆλ‹€. 예λ₯Ό λ“€μ–΄ /swagger-ui locationλ₯Ό μƒμ„±ν•©λ‹ˆλ‹€.

location /swagger-ui {
    # ...
}

4. Swagger UI 파일 κ²½λ‘œμ™€ root μ§€μ‹œλ¬Έμ„ μ‚¬μš©ν•˜μ—¬ YAML 사양을 μ§€μ •ν•©λ‹ˆλ‹€(예: usr/share/nginx/html).

location /swagger-ui {
    root   /usr/share/nginx/html;
    # ...
}

NGINX Plus 릴리슀 25 이전 λ²„μ „μ˜ 경우 Swagger UIλŠ” root μ§€μ‹œλ¬ΈμœΌλ‘œ μ§€μ •λœ root 디렉터리(예: /usr/share/nginx/html)에 μžˆμŠ΅λ‹ˆλ‹€.

5. allow 및 deny μ§€μ‹œλ¬Έμ„ μ‚¬μš©ν•˜μ—¬ 둜컬 λ„€νŠΈμ›Œν¬μ—μ„œλ§Œ 이 μœ„μΉ˜μ— λŒ€ν•œ μ•‘μ„ΈμŠ€λ₯Ό μ œν•œν•©λ‹ˆλ‹€.

location /swagger-ui {
    root   /usr/share/nginx/html;
    allow  192.168.1.0/24;
    deny   all;
}

6. λ˜ν•œ add_header μ§€μ‹œλ¬Έμ„ μ‚¬μš©ν•˜μ—¬ λͺ¨λ“  λ¦¬μ†ŒμŠ€κ°€ Swagger UI와 λ™μΌν•œ Originμ—μ„œ λ‘œλ“œλ˜λ„λ‘ μ •μ˜ν•˜λŠ” μ½˜ν…μΈ  λ³΄μ•ˆ μ •μ±… 헀더λ₯Ό ν™œμ„±ν™”ν•˜λŠ” 것이 μ’‹μŠ΅λ‹ˆλ‹€:

location /swagger-ui {
    add_header Content-Security-Policy "default-src 'self'";
    root       /usr/share/nginx/html;
    allow      192.168.1.0/24;
    deny       all;
}

7-2. Swagger UI λΉ„ν™œμ„±ν™”

NGINX Plus 릴리슀 25 μ΄ν•˜μ—μ„œ Swagger UIλŠ” NGINX Plus νŒ¨ν‚€μ§€μ˜ 일뢀이며 기본적으둜 μ„€μΉ˜λ©λ‹ˆλ‹€. λ³΄μ•ˆμƒμ˜ 이유둜 Swagger UI에 λŒ€ν•œ μ•‘μ„ΈμŠ€λ₯Ό 차단할 수 μžˆμŠ΅λ‹ˆλ‹€. 이λ₯Ό μœ„ν•œ 방법 쀑 ν•˜λ‚˜λŠ” /swagger-ui μœ„μΉ˜μ™€ μΌμΉ˜ν•˜λŠ” URL에 λŒ€ν•œ μ‘λ‹΅μœΌλ‘œ 404 μƒνƒœ μ½”λ“œλ₯Ό λ°˜ν™˜ν•˜λŠ” κ²ƒμž…λ‹ˆλ‹€.

location /swagger-ui {
    return 404;
}

7-3. Swagger UI μ‚¬μš©

Swagger UI νŽ˜μ΄μ§€μ— μ•‘μ„ΈμŠ€ν•˜λ €λ©΄ λ‹€μŒκ³Ό 같이 ν•˜μ„Έμš”.

  • λΈŒλΌμš°μ €μ˜ μ£Όμ†Œ ν‘œμ‹œμ€„μ— Swagger UI의 μ£Όμ†Œλ₯Ό μž…λ ₯ν•©λ‹ˆλ‹€(이 예의 μ£Όμ†ŒλŠ” http://192.168.1.23/swagger-ui/).
Swagger UI
  • Swagger UI νŽ˜μ΄μ§€μ— HTTPS ν”„λ‘œν† μ½œμ„ κ΅¬μ„±ν•œ 경우 ‘Schemes’ λ©”λ‰΄μ—μ„œ ‘HTTPS’ κ΅¬μ„±ν‘œλ₯Ό 선택해야 ν•©λ‹ˆλ‹€.
  • μˆ˜ν–‰ν•˜κ³ μž ν•˜λŠ” μž‘μ—…μ„ ν΄λ¦­ν•©λ‹ˆλ‹€.
  • Try it out을 ν΄λ¦­ν•©λ‹ˆλ‹€.
  • ν•„μš”ν•œ 경우 ν•„μˆ˜ μž…λ ₯λž€μ„ μ±„μ›λ‹ˆλ‹€. 일반적으둜 ν•„μˆ˜ μž…λ ₯λž€μ€ 곡유 λ©”λͺ¨λ¦¬ Zone의 μ΄λ¦„μž…λ‹ˆλ‹€.
  • μ˜΅μ…˜μœΌλ‘œ νŠΉμ • ν•„λ“œλ§Œ ν‘œμ‹œν•  수 μžˆμŠ΅λ‹ˆλ‹€. “Fields” 쀄에 ν‘œμ‹œν•  ν•„λ“œλ₯Ό μ‰Όν‘œλ‘œ κ΅¬λΆ„ν•˜μ—¬ μ§€μ •ν•©λ‹ˆλ‹€. ν•„λ“œλ₯Ό μ§€μ •ν•˜μ§€ μ•ŠμœΌλ©΄ λͺ¨λ“  ν•„λ“œκ°€ ν‘œμ‹œλ©λ‹ˆλ‹€.
  • Executeλ₯Ό ν΄λ¦­ν•©λ‹ˆλ‹€. 결과와 ν•΄λ‹Ή HTTP 였λ₯˜ μ½”λ“œκ°€ Execute λͺ…λ Ή μ•„λž˜μ— ν‘œμ‹œλ©λ‹ˆλ‹€.

7-4. API 및 Swagger UI 라이브 예제

NGINXλŠ” 데λͺ¨ μ›Ήμ‚¬μ΄νŠΈμ—μ„œ JSON 데이터와 Swagger UI의 라이브 예제λ₯Ό μ œκ³΅ν•©λ‹ˆλ‹€.

JSON λ°μ΄ν„°μ˜ 라이브 μ˜ˆμ œλŠ” λ‹€μŒ λ§ν¬μ—μ„œ 확인할 수 μžˆμŠ΅λ‹ˆλ‹€. https://demo.nginx.com/api/8/

curl λ˜λŠ” λΈŒλΌμš°μ €λ₯Ό μ‚¬μš©ν•˜μ—¬ API λͺ…령을 보낼 수 μžˆμŠ΅λ‹ˆλ‹€.

curl -s 'https://demo.nginx.com/api/8/'
curl -s 'https://demo.nginx.com/api/8/nginx?fields=version,build'
curl -s 'https://demo.nginx.com/api/8/http/caches/http_cache'
curl -s 'https://demo.nginx.com/api/8/http/upstreams/'
curl -s 'https://demo.nginx.com/api/8/http/upstreams/demo-backend'
curl -s 'https://demo.nginx.com/api/8/http/upstreams/demo-backend/servers/0'

Swagger UI 데λͺ¨ νŽ˜μ΄μ§€λŠ” https://demo.nginx.com/swagger-ui/ μ—μ„œ 확인할 수 μžˆμŠ΅λ‹ˆλ‹€.

Swagger UI

Live μ˜ˆμ œλŠ” 읽기 μ „μš© λͺ¨λ“œλ‘œ μž‘λ™ν•˜λ©°, DELETE λ©”μ„œλ“œλ₯Ό ν†΅ν•œ 톡계 μž¬μ„€μ • 및 POST/PATCH λ©”μ„œλ“œλ₯Ό ν†΅ν•œ Upstream μ„œλ²„ 생성/μˆ˜μ • κΈ°λŠ₯은 μ‚¬μš©ν•  수 μ—†μŠ΅λ‹ˆλ‹€. λ˜ν•œ 데λͺ¨ APIλŠ” HTTP ν”„λ‘œν† μ½œμ„ 톡해 μ œκ³΅λ˜λ―€λ‘œ Swagger UI 데λͺ¨ νŽ˜μ΄μ§€μ˜ “Schemes” λ©”λ‰΄μ—μ„œ “HTTP” μŠ€ν‚€λ§ˆλ₯Ό 선택해야 ν•©λ‹ˆλ‹€.