ConfigMap 리소스
ConfigMap 리소스 를 사용하면 NGINX 동작을 사용자 정의하거나 미세 조정할 수 있습니다. 예를 들어 Worker Processes 수를 설정하거나 액세스 로그 형식을 사용자 지정합니다.
목차
1. ConfigMap 사용
2. ConfigMap 및 Ingress Annotation
3. ConfigMap 및 VirtualServer/VirtualServerRoute 리소스
4. ConfigMap Key 요약
4-1. Ingress Controller(NGINX 구성과 관련 없음)
4-2. 일반 사용자 정의
4-3. 로깅
4-4. 요청 URI/Header 조작
4-5. 인증 및 SSL/TLS
4-6. Listeners
4-7. Backend 서비스 (Upstreams)
4-8. Snippets 및 Custom Templates
4-9. Modules
1. ConfigMap 사용
1. Manifests를 사용한 설치가 Ingress Controller의 Command-Line에 지정하는 동안 빈 ConfigMap을 배포합니다. 그러나 Manifests를 사용자 정의한 경우 ConfigMap을 사용하려면 Ingress Controller의 Command-Line를 통해 사용할 ConfigMap 리소스 를 지정해야 합니다.
2. 이름이 nginx-config.yaml인 ConfigMap 파일을 만들고 설정에 적합한 값을 설정합니다.
kind: ConfigMap
apiVersion: v1
metadata:
name: nginx-config
namespace: nginx-ingress
data:
proxy-connect-timeout: "10s"
proxy-read-timeout: "10s"
client-max-body-size: "2m"사용 가능한 ConfigMap Key(이 예의 proxy-connect-timeout)에 대한 설명은 ConfigMap Key 요약 섹션을 참조하세요.
3. 새 ConfigMap 리소스를 생성하거나 기존 ConfigMap 리소스 를 업데이트합니다.
$ kubectl apply -f nginx-config.yamlNGINX 구성이 업데이트됩니다.
2. ConfigMap 및 Ingress Annotation
Annotation을 사용하면 고급 NGINX 기능을 구성하고 NGINX 동작을 사용자 정의하거나 미세 조정할 수 있습니다.
ConfigMap은 전역적으로 적용됩니다. 즉, 모든 Ingress 리소스에 영향을 미칩니다. 반대로 Annotation은 항상 Ingress 리소스에 적용됩니다. Annotation을 사용하면 일부 ConfigMap Key를 Overriding할 수 있습니다. 예를 들어 nginx.org/proxy-connect-timeout Annotation은 proxy-connect-timeout ConfigMap Key를 Override합니다.
Annotation에 대한 자세한 내용은 설명서를 참조하십시오.
3. ConfigMap 및 VirtualServer/VirtualServerRoute 리소스
ConfigMap은 모든 VirtualServer 및 VirtualServerRoute 리소스에 영향을 미칩니다. 그러나 해당 리소스의 필드에서는 일부 ConfigMap Key를 Overriding할 수 있습니다. 예를 들어 Upstream의 connect-timeout 필드는 proxy-connect-timeout ConfigMap Key를 Override합니다.
VirtualServer 및 VirtualServerRoute 리소스에 대한 자세한 내용은 설명서를 참조하십시오.
4. ConfigMap Key 요약
4-1. Ingress Controller(NGINX 구성과 관련 없음)
| ConfigMap Key | 설명 | Default | Example |
|---|---|---|---|
external-status-address | Ingress 리소스 상태에서 보고할 주소를 설정합니다. -report-status Command-Line Argument가 필요합니다. -external-service Argument를 Override 합니다. | N/A | Ingress 상태 보고 |
4-2. 일반 사용자 정의
| ConfigMap Key | 설명 | Default | Example |
| proxy-connect-timeout | proxy_connect_timeout 및 grpc_connect_timeout 지시문의 값을 설정합니다. | 60s | |
| proxy-read-timeout | proxy_read_timeout 및 grpc_read_timeout 지시문의 값을 설정합니다. | 60s | |
| proxy-send-timeout | proxy_send_timeout 및 grpc_send_timeout 지시문의 값을 설정합니다. | 60s | |
| client-max-body-size | client_max_body_size 지시문의 값을 설정합니다. | 1m | |
| proxy-buffering | Proxy 서버의 buffering of responses을 사용 가능 또는 사용 불가능으로 설정합니다. | True | |
| proxy-buffers | proxy_buffers 지시문의 값을 설정합니다. | Depends on the platform. | |
| proxy-buffer-size | proxy_buffer_size 및 grpc_buffer_size 지시문의 값을 설정합니다. | Depends on the platform. | |
| proxy-max-temp-file-size | proxy_max_temp_file_size 지시문의 값을 설정합니다. | 1024m | |
| set-real-ip-from | set_real_ip_from 지시문의 값을 설정합니다. | N/A | |
| real-ip-header | real_ip_header 지시문의 값을 설정합니다. | X-Real-IP | |
| real-ip-recursive | real_ip_recursive 지시문을 사용하거나 사용하지 않도록 설정합니다. | False | |
| default-server-return | Ingress 또는 VirtualServer 리소스의 호스트가 일치하지 않는 경우 클라이언트 요청을 처리하는 return 지시문을 기본 서버에서 구성합니다. 기본값은 404 error 페이지를 return하도록 NGINX를 구성합니다. 고정 응답 또는 리다이렉션을 구성할 수 있습니다. 예를 들어 default-server-return: 302 https://nginx.org는 클라이언트를 https://nginx.org로 리다이렉션합니다. | 404 | |
| server-tokens | server_tokens 지시문을 활성화하거나 비활성화합니다. 또한 NGINX Plus를 사용하여 빈 문자열 값을 포함한 사용자 지정 문자열 값을 지정할 수 있으며, 이로 인해 “Server” 필드가 실행 중지됩니다. | True | |
| worker-processes | worker_processes 지시문의 값을 설정합니다. | auto | |
| worker-rlimit-nofile | worker_rlimit_nofile 지시문의 값을 설정합니다. | N/A | |
| worker-connections | worker_connections 지시문의 값을 설정합니다. | 1024 | |
| worker-cpu-affinity | worker_cpu_affinity 지시문의 값을 설정합니다. | N/A | |
| worker-shutdown-timeout | worker_shutdown_timeout 지시문의 값을 설정합니다. | N/A | |
| server-names-hash-bucket-size | server_names_hash_bucket_size 지시문의 값을 설정합니다. | 256 | |
| server-names-hash-max-size | server_names_hash_max_size 지시문의 값을 설정합니다. | 1024 | |
map-hash-bucket-size | map_hash_bucket_size 지시문의 값을 설정합니다. | 256 | |
map-hash-max-size | map_hash_max_size 지시문의 값을 설정합니다. | 2048 | |
| resolver-addresses | resolver 주소 값을 설정합니다. 참고: DNS 이름(예: kube-dns.kube-system.svc.cluster.local)을 resolver 주소로 사용하는 경우 NGINX Plus는 시작하는 동안과 구성을 Reload할 때마다 시스템 resolver를 사용하여 이를 확인합니다. 이름을 확인할 수 없거나 DNS 서버가 응답하지 않으면 NGINX Plus가 시작되거나 Reload되지 않습니다. 이를 방지하려면 DNS 이름 대신 IP 주소를 resolver 주소로 사용하는 것이 좋습니다. NGINX Plus에서만 지원됩니다. | N/A | ExternalName Services Type 지원 |
| resolver-ipv6 | resolver에서 IPv6를 사용하도록 활성화합니다. NGINX Plus에서만 지원됩니다. | True | ExternalName Services Type w;dmks |
| resolver-valid | NGINX가 확인된 DNS 레코드를 캐시하는 시간을 설정합니다. NGINX Plus에서만 지원됩니다. | TTL value of a DNS record | ExternalName Services Type w;dmks |
| resolver-timeout | 이름 확인에 대한 resolver_timeout을 설정합니다. NGINX Plus에서만 지원됩니다. | 30s | ExternalName Services Type w;dmks |
| keepalive-timeout | keepalive_timeout 지시문의 값을 설정합니다. | 65s | |
| keepalive-requests | keepalive_requests 지시문의 값을 설정합니다. | 100 | |
| variables-hash-bucket-size | variables_hash_bucket_size 지시문의 값을 설정합니다. | 256 | |
| variables-hash-max-size | variables-hash-max-size 지시문의 값을 설정합니다. | 1024 |
4-3. 로깅
| ConfigMap Key | 설명 | Default | Example |
| error-log-level | NGINX의 global error log level을 설정합니다. | notice | |
| access-log-off | access log를 비활성화 합니다. | False | |
| default-server-access-log-off | 기본 서버에 대한 access log를 비활성화로 설정합니다. access log가 전체적으로 비활성화된 경우(access-log-off: "True"), 기본 서버 access log는 항상 비활성화됩니다. | False | |
| log-format | HTTP 및 HTTPS 트래픽에 대한 사용자 정의 log format을 설정합니다. 편의를 위해 여러 줄에 걸쳐 log format을 정의할 수 있습니다(각 줄은 \n으로 구분됨). 이 경우 Ingress Controller는 모든 \n 문자를 공백 문자로 바꿉니다. 모든 ' 문자는 이스케이프(Escape)해야 합니다. | See the template file for the access log. | Custom Log Format. |
| log-format-escaping | log format의 변수에 대한 이스케이프 문자를 설정합니다. 지원되는 값: json (JSON 이스케이프 처리), default (기본 이스케이프 처리) none (이스케이프 비활성화). | default | |
| stream-log-format | TCP, UDP 및 TLS 통과 트래픽에 대한 사용자 정의 log format을 설정합니다. 편의를 위해 여러 줄에 걸쳐 log format을 정의할 수 있습니다(각 줄은 \n으로 구분됨). 이 경우 Ingress Controller는 모든 \n 문자를 공백 문자로 바꿉니다. 모든 ' 문자는 이스케이프해야 합니다. | See the template file. | |
| stream-log-format-escaping | stream log format의 변수에 대한 이스케이프 문자를 설정합니다. 지원되는 값: json(JSON 이스케이프), default(기본 이스케이프) none(이스케이프 비활성화). | default |
4-4. 요청 URI/Header 조작
| ConfigMap Key | 설명 | Default | Example |
| proxy-hide-headers | 하나 이상의 proxy_hide_header 지시문 값을 설정합니다. 예: "nginx.org/proxy-hide-headers": "https-a,https-b" | N/A | |
| proxy-pass-headers | 하나 이상의 proxy_pass_header 지시문 값을 설정합니다. 예: "nginx.org/proxy-pass-headers": "https-a,https-b" | N/A |
4-5. 인증 및 SSL/TLS
| ConfigMap Key | 설명 | Default | Example |
redirect-to-https | 서버 블록의 http_x_forwarded_proto 헤더 값을 기반으로 301 리다이렉션 규칙을 설정하여 들어오는 트래픽이 HTTPS를 통과하도록 합니다. Ingress Controller 앞에 있는 Load Balancer에서 SSL을 종료할 때 유용합니다(115 참조). | False | |
ssl-redirect | 수신 트래픽이 HTTPS를 통해 강제로 수신되도록 모든 수신 HTTP 트래픽에 대해 무조건 301 리다이렉션 규칙을 설정합니다. | True | |
hsts | HSTS(HTTP Strict Transport Security) 활성화: HSTS 헤더가 Backend의 응답에 추가됩니다. preload 지시문은 헤더에 포함되어 있습니다. | False | |
hsts-max-age | HSTS 헤더의 max-age 지시문 값을 설정합니다. | 2592000 (1 month) | |
hsts-include-subdomains | HSTS 헤더에 includeSubDomains 지시문을 추가합니다. | False | |
hsts-behind-proxy | http_x_forwarded_proto 요청 헤더 값을 기반으로 HSTS를 활성화합니다. Ingress Controller 앞의 Load Balancer(Proxy)에서 TLS 종료가 구성된 경우에만 사용해야 합니다. 참고: HTTP에서 HTTPS로의 리다이렉션을 제어하려면 nginx.org/redirect-to-https Annotation을 구성하십시오. | False | |
ssl-protocols | ssl_protocols 지시문의 값을 설정합니다. | TLSv1 TLSv1.1 TLSv1.2 | |
ssl-prefer-server-ciphers | ssl_prefer_server_ciphers 지시문을 사용하거나 사용하지 않도록 설정합니다. | False | |
ssl-ciphers | ssl_ciphers 지시문의 값을 설정합니다. | HIGH:!aNULL:!MD5 | |
ssl-dhparam-file | dhparam 파일의 내용을 설정합니다. Controller는 파일을 생성하고 파일 경로로 ssl_dhparam 지시문의 값을 설정합니다. | N/A |
4-6. Listeners
| ConfigMap Key | 설명 | Default | Example |
http2 | SSL이 활성화된 서버에서 HTTP/2를 활성화합니다. | False | |
proxy-protocol | 들어오는 연결에 대해 PROXY 프로토콜을 활성화합니다. | False | Proxy Protocol. |
4-7. Backend 서비스 (Upstreams)
| ConfigMap Key | 설명 | Default | Example |
lb-method | load balancing method을 설정합니다. 라운드 로빈 방법을 사용하려면 "round_robin"을 지정합니다. | "random two least_conn" | |
max-fails | server 지시문의 max_fails 매개 변수 값을 설정합니다. | 1 | |
upstream-zone-size | Upstream의 공유 메모리 zone를 설정합니다. NGINX의 경우 특수 값 0은 공유 메모리 영역을 비활성화합니다. NGINX Plus의 경우 공유 메모리 영역이 필요하며 비활성화할 수 없습니다. 특수 값 0은 무시됩니다. | 256k for NGINX, 512k for NGINX Plus | |
fail-timeout | server 지시문의 fail_timeout 매개 변수 값을 설정합니다. | 10s | |
keepalive | keepalive 지시문의 값을 설정합니다. 값이 0보다 클 때 생성된 구성에 proxy_set_header Connection "";이 추가됩니다.. | 0 |
4-8. Snippets 및 Custom Templates
| ConfigMap Key | 설명 | Default | Example |
main-snippets | main context에 사용자 정의 snippet을 설정합니다. | N/A | |
http-snippets | http context에 사용자 정의 snippet을 설정합니다. | N/A | |
location-snippets | location context에 사용자 정의 snippet을 설정합니다. | N/A | |
server-snippets | server context에 사용자 정의 snippet을 설정합니다. | N/A | |
stream-snippets | Stream Context에 사용자 정의 Snippet을 설정합니다. | N/A | TCP/UDP Load Balancing지원. |
main-template | Main NGINX 구성 템플릿을 설정합니다. | 기본적으로 템플릿은 컨테이너의 파일에서 읽습니다. | Custom Templates. |
ingress-template | Ingress 리소스에 대한 NGINX 구성 템플릿을 설정합니다. | 기본적으로 템플릿은 컨테이너의 파일에서 읽습니다. | Custom Templates. |
virtualserver-template | VirtualServer 리소스에 대한 NGINX 구성 템플릿을 설정합니다. | 기본적으로 템플릿은 컨테이너의 파일에서 읽습니다.. | Custom Templates. |
4-9. Modules
| ConfigMap Key | 설명 | Default | Example |
opentracing | OpenTracing을 전역적으로 활성화합니다(모든 Ingress, VirtualServer 및 VirtualServerRoute 리소스에 대해). 참고: OpenTracing 모듈 및 Tracer이 포함된 수신 컨트롤러 이미지가 필요합니다. 자세한 내용은 문서를 참조하세요. | False | |
opentracing-tracer | Vendor Tracer Binary 플러그인의 경로를 설정합니다. | N/A | |
opentracing-tracer-config | Tracer 구성을 JSON Format으로 설정합니다. | N/A | |
app-protect-compressed-requests-action | app_protect_compressed_requests_action 전역 지시문을 설정합니다. | drop | |
app-protect-cookie-seed | app_protect_cookie_seed 전역 지시문을 설정합니다. | Random automatically generated string | |
app-protect-failure-mode-action | app_protect_cookie_seed 전역 지시문을 설정합니다. | pass | |
app-protect-cpu-thresholds | app_protect_cpu_thresholds 전역 지시문을 설정합니다. | high=100 low=100 | |
app-protect-physical-memory-util-thresholds | app_protect_physical_memory_util_thresholds 전역 지시문을 설정합니다. | high=100 low=100 | |
app-protect-reconnect-period-seconds | app_protect_reconnect_period_seconds 전역 지시문을 설정합니다. | 5 | |
app-protect-dos-log-format | Dos Access로그 트래픽에 대한 사용자 정의 Log Format을 설정합니다. 편의를 위해 여러 줄에 걸쳐 Log Format을 정의할 수 있습니다(각 줄은 \n으로 구분됨). 이 경우 Ingress Controller는 모든 \n 문자를 공백 문자로 대체합니다. 모든 ' 문자는 이스케이프해야 합니다. | , vs_name_al=$app_protect_dos_vs_name, ip=$remote_addr, tls_fp=$app_protect_dos_tls_fp, outcome=$app_protect_dos_outcome, reason=$app_protect_dos_outcome_reason, policy_name=$app_protect_dos_policy_name, dos_version=$app_protect_dos_version, ip_tls=$remote_addr:$app_protect_dos_tls_fp, | |
app-protect-dos-log-format-escaping | 스트림 로그 형식의 변수에 대한 이스케이프 문자를 설정합니다. 지원되는 값: json (JSON 이스케이프 처리), default (기본 이스케이프 처리) none (이스케이프 비활성화). | default | |
app-protect-dos-arb-fqdn | app-protect-dos-arb-fqdn 지시문을 설정합니다. | svc-appprotect-dos-arb |