Community Ingress Controller에서 NGINX Ingress Controller로 마이그레이션하는 두 가지 방법
Kubernetes를 처음 설정하는 많은 기업은 Kubernetes 커뮤니티(kubernetes/ingress-nginx)에서 개발하고 유지 관리하는 NGINX Ingress Controller 로 시작합니다. 그러나 Kubernetes 배포가 성숙해짐에 따라 일부 기업에서는 NGINX를 Data Plane으로 유지하면서 고급 기능이 필요하거나 상업적 지원을 원합니다.
한 가지 옵션은 NGINX(nginxinc/kubernetes-ingress)에서 개발하고 유지 관리하는 NGINX Ingress Controller로 마이그레이션하는 것입니다. 여기서는 두 프로젝트 간의 차이로 인해 발생하는 몇 가지 복잡성을 피할 수 있도록 완전한 지침을 제공합니다.
이 포스트의 나머지 두 프로젝트를 구별하기 위해, 우리는 Kubernetes 커뮤니티(kubernetes/inginx)가 유지하는 NGINX Ingress Controller를 “Community Ingress Controller”로, NGINX(nginxinc/kubernetes-ress)가 유지하는 것을 “NGINX Ingress Controller”로 지칭합니다.
Community Ingress Controller에서 NGINX Ingress Controller로 마이그레이션하는 방법에는 두 가지가 있습니다.
옵션 1: NGINX Ingress Controller를 사용하여 마이그레이션
NGINX Ingress 리소스 Production등급 Kubernetes 환경에 필요한 광범위한 Ingress 네트워킹 기능을 지원하기 때문에 이 솔루션이 최적입니다.
옵션 2: Kubernetes Ingress 리소스를 사용하여 마이그레이션
이 옵션은 표준 Kubernetes Ingress 리소스를 사용하여 Ingress Load Balancing 규칙을 정의하는 경우에 권장합니다.
목차
1. NGINX Ingress Controller를 사용하여 마이그레이션
1-1. SSL Termination 및 HTTP 경로 기반 라우팅 구성
1-2. TCP/UDP 로드 밸런싱 및 TLS 패스스루 구성
1-3. Community Ingress Controller 주석을 NGINX Ingress 리소스로 변환
1-3-1. Canary 배포
1-3-2. 트래픽 제어
1-3-3. Header Manipulation
1-3-4. Proxying 및 Load Balancing
1-3-5. mTLS 인증
1-3-6. 세션 지속성(NGINX Plus 전용)
2. Kubernetes Ingress 리소스를 사용하여 마이그레이션
2-1. 고급 구성의 주석
2-2. ConfigMap을 사용한 글로벌 구성
3. 요약
1. NGINX Ingress Controller를 사용하여 마이그레이션
이 마이그레이션 옵션을 사용하면 표준 Kubernetes Ingress 리소스를 사용하여 Root 기능을 설정하고 NGINX Ingress 리소스를 사용하여 향상된 기능과 사용 편의성으로 구성을 향상시킬 수 있습니다.
NGINX Ingress 리소스(VirtualServer, VirtualServerRoute, TransportServer, GlobalConfiguration, Policy)에 대한 사용자 지정 리소스 정의(CRD)를 사용하면 구성의 다양한 부분에 대한 제어 권한을 다른 팀(예: AppDev 및 보안 팀)에 쉽게 위임할 수 있을 뿐만 아니라 구성 안전성과 검증 기능을 향상시킬 수 있습니다.
1-1. SSL Termination 및 HTTP 경로 기반 라우팅 구성
다음 표는 표준 Kubernetes Ingress 리소스의 사양 필드에 있는 SSL Termination 및 Layer 7 경로 기반 라우팅의 구성을 NGINX VirtualServer 리소스의 사양 필드에 매핑합니다. 구문과 들여쓰기는 두 리소스에서 약간 다르지만 동일한 기본적인 Ingress 기능은 동일합니다.
| Kubernetes Ingress Resource | NGINX VirtualServer Resource |
| apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: nginx-test spec: tls: – hosts: – foo.bar.com secretName: tls-secret rules: – host: foo.bar.com http: paths: – path: /login backend: serviceName: login-svc servicePort: 80 – path: /billing serviceName: billing-svc servicePort: 80 | apiVersion: networking.k8s.io/v1 kind: VirtualServer metadata: name: nginx-test spec: host: foo.bar.com tls: secret: tls-secret upstreams: – name: login service: login-svc port: 80 – name: billing service: billing-svc port: 80 routes: – path: /login action: pass: login – path: /billing action: pass: billing |
1-2. TCP/UDP Load Balancing 및 TLS Passthrough 구성
Community Ingress Controller를 사용하면 Kubernetes ConfigMap API 객체가 TCP 및 UDP 서비스를 Expose하는 유일한 방법입니다.
NGINX Ingress Controller를 사용하 TransportServer 리소스는 TCP/UDP 및 TLS Passthrough Load Balancing을 위한 광범위한 옵션을 정의합니다. TransportServer 리소스는 GlobalConfiguration 리소스와 함께 인바운드(Inbound) 및 아웃바운드(Outbound) 연결을 제어하는 데 사용됩니다.
1-3. Community Ingress Controller 주석을 NGINX Ingress 리소스로 변환
Production 등급 Kubernetes 배포는 Canary 및 Blue-Green 배포, Traffic Throttling, Ingress‑Egress Traffic Manipulation 등 고급 사용 사례를 구현하기 위해 기본 Ingress 규칙을 확장해야 하는 경우가 많습니다.
Community Ingress Controller는 Kubernetes 주석을 사용하여 이러한 많은 사용 사례를 구현합니다. 그러나 이러한 주석의 대부분은 매우 구체적인 NGINX Ingress 리소스 정의와 관련된 사용자 지정 Lua 확장으로 구축되므로 안정적이고 지원되는 Production 환경에서 고급 기능을 구현하는 데 적합하지 않습니다.
다음 섹션에서는 Community Ingress Controller 주석을 NGINX Ingress Controller 리소스로 변환하는 방법을 보여줍니다.
1-3-1. Canary 배포
Production 컨테이너 Workload에 코드를 자주 변경하더라도 기존 사용자에게 서비스를 계속 제공해야 합니다. Canary 및 Blue-Green 배포를 통해 이 작업을 수행할 수 있으며, NGINX Ingress Controller Data Plane에서 이 작업을 수행하여 Production 급 Kubernetes 환경에서 안정적이고 예측 가능한 업데이트를 수행할 수 있습니다.
다음 표에서는 Canary 배포에 대한 Community Ingress Controller 주석에 해당하는 NGINX VirtualServer 및 VirtualServerRoute 리소스의 필드를 보여 줍니다.
Community Ingress Controller는 다음 우선 순위에 따라 Canary 주석을 평가합니다.
nginx.ingress.kubernetes.io/canary-by-headernginx.ingress.kubernetes.io/canary-by-cookienginx.ingress.kubernetes.io/canary-by-weight
NGINX Ingress Controller가 동일한 방식으로 평가하려면 NGINX VirtualServer 또는 VirtualServerRoute Manifest에 순서대로 나타나야 합니다.
| Community Ingress Controller | NGINX Ingress Controller |
| nginx.ingress.kubernetes.io/canary: “true” nginx.ingress.kubernetes.io/canary-by-header: “httpHeader” | matches: – conditions: – header: httpHeader value: never action: pass: echo – header: httpHeader value: always action: pass: echo-canary action: pass: echo |
| nginx.ingress.kubernetes.io/canary: “true” nginx.ingress.kubernetes.io/canary-by-header: “httpHeader” nginx.ingress.kubernetes.io/canary-by-header-value: “my-value“ | matches: – conditions: – header: httpHeader value: my-value action: pass: echo-canary action: pass: echo |
| nginx.ingress.kubernetes.io/canary: “true” nginx.ingress.kubernetes.io/canary-by-cookie: “cookieName” | matches: – conditions: – cookie: cookieName value: never action: pass: echo – cookie: cookieName value: always action: pass: echo-canary action: pass: echo |
| nginx.ingress.kubernetes.io/canary: “true” nginx.ingress.kubernetes.io/canary-weight: “10” | splits: – weight: 90 action: pass: echo weight: 10 action: pass: echo-canary |
1-3-2. 트래픽 제어
애플리케이션이 본질적으로 일시적이어서 오류 응답을 반환할 가능성이 더 높은 Microservices 환경에서 DevOps팀은 회로 차단, 속도 및 연결 제한과 같은 트래픽 제어 정책을 광범위하게 사용하여 애플리케이션이 정상적으로 작동하지 않는 오류를 방지합니다.
다음 표에서는 속도 제한, 사용자 정의 HTTP 오류, 사용자 정의 기본 Backend 및 URI 재작성에 대한 Community Ingress Controller 주석에 해당하는 NGINX VirtualServer 및 VirtualServerRoute 리소스의 필드를 보여줍니다.
| Community Ingress Controller | NGINX Ingress Controller |
| nginx.ingress.kubernetes.io/custom-http-errors: “code“ nginx.ingress.kubernetes.io/default-backend: “default-svc” | errorPages: – codes: [code] redirect: code: 301 url: default-svc |
| nginx.ingress.kubernetes.io/limit-connections: “number“ | http-snippets: | limit_conn_zone $binary_remote_addr zone=zone_name:size; routes: – path: /path location-snippets: | limit_conn zone_name number; |
| nginx.ingress.kubernetes.io/limit-rate: “number” nginx.ingress.kubernetes.io/limit-rate-after: “number“ | location-snippets: | limit_rate number; limit_rate_after number; |
| nginx.ingress.kubernetes.io/limit-rpm: “number” nginx.ingress.kubernetes.io/limit-burst-multiplier: “multiplier“ | rateLimit: rate: numberr/s burst: number * multiplier key: ${binary_remote_addr} zoneSize: size |
| nginx.ingress.kubernetes.io/limit-rps: “number” nginx.ingress.kubernetes.io/limit-burst-multiplier: “multiplier“ | rateLimit: rate: numberr/s burst: number * multiplier key: ${binary_remote_addr} zoneSize: size |
| nginx.ingress.kubernetes.io/limit-whitelist: “CIDR“ | http-snippets: | server-snippets: | |
| nginx.ingress.kubernetes.io/rewrite-target: “URI“ | rewritePath: “URI“ |
표에 나와 있는 것처럼, 이 문서에서 NGINX Ingress 리소스에는 다음 네 가지 Community Ingress Controller 주석을 직접 변환하는 필드가 포함되어 있지 않으며 스니펫(Snippet)을 사용해야 합니다. 정책 리소스를 사용하는 네 가지 주석에 대한 직접 지원은 NGINX Ingress Controller의 향후 릴리스에서 지원할 계획입니다.
nginx.ingress.kubernetes.io/limit-connectionsnginx.ingress.kubernetes.io/limit-ratenginx.ingress.kubernetes.io/limit-rate-afternginx.ingress.kubernetes.io/limit-whitelist
1-3-3. Header Manipulation
HTTP Header Manipulation은 HTTP 트랜잭션과 관련된 시스템에 중요하고 관련된 추가 정보를 포함하므로 많은 사용 사례에서 유용합니다. 예를 들어 Community Ingress Controller는 브라우저의 FrontEnd JavaScript 코드가 BackEnd 애플리케이션 또는 웹 서버에 연결되는 AJAX 애플리케이션과 함께 사용되는 CORS(Cross-Origin Resource Sharing) 헤더를 활성화 및 설정할 수 있도록 지원합니다.
다음 표에서는 Header Manipulation을 위한 Community Ingress Controller 주석에 해당하는 NGINX VirtualServer 및 VirtualServerRoute 리소스의 필드를 보여줍니다.
| Community Ingress Controller | NGINX Ingress Controller |
| nginx.ingress.kubernetes.io/enable-cors: “true” nginx.ingress.kubernetes.io/cors-allow-credentials: “true” nginx.ingress.kubernetes.io/cors-allow-headers: “X-Forwarded-For” nginx.ingress.kubernetes.io/cors-allow-methods: “PUT, GET, POST, OPTIONS” nginx.ingress.kubernetes.io/cors-allow-origin: “*” nginx.ingress.kubernetes.io/cors-max-age: “seconds” | responseHeaders: add: – name: Access-Control-Allow-Credentials value: “true” – name: Access-Control-Allow-Headers value: “X-Forwarded-For” – name: Access-Control-Allow-Methods value: “PUT, GET, POST, OPTIONS” – name: Access-Control-Allow-Origin value: “*” – name: Access-Control-Max-Age value: “seconds” |
1-3-4. Proxying 및 Load Balancing
특정 사용 사례에 따라 NGINX Ingress Controller에서 구성할 수 있는 다른 Proxy 및 Load Balancing 기능이 있습니다. 이러한 기능에는 Load Balancing 알고리즘 설정과 Proxy 연결에 대한 제한 시간 및 버퍼링 설정이 포함됩니다.
다음 표는 사용자 지정 NGINX Load Balancing, Proxy 시간 초과, Proxy 버퍼링 및 서비스의 클러스터 IP 주소 및 포트에 대한 라우팅 연결에 대한 Community Ingress Controller 주석에 해당하는 NGINX VirtualServer 및 VirtualServerRoute 리소스의 Upstream 필드에 있는 명령문을 보여줍니다.
| Community Ingress Controller | NGINX Ingress Controller |
| nginx.ingress.kubernetes.io/load-balance | lb-method |
| nginx.ingress.kubernetes.io/proxy-buffering | buffering |
| nginx.ingress.kubernetes.io/proxy-buffers-number nginx.ingress.kubernetes.io/proxy-buffer-size | buffers |
| nginx.ingress.kubernetes.io/proxy-connect-timeout | connect-timeout |
| nginx.ingress.kubernetes.io/proxy-next-upstream | next-upstream |
| nginx.ingress.kubernetes.io/proxy-next-upstream-timeout | next-upstream-timeout |
| nginx.ingress.kubernetes.io/proxy-read-timeout | read-timeout |
| nginx.ingress.kubernetes.io/proxy-send-timeout | send-timeout |
| nginx.ingress.kubernetes.io/service-upstream | use-cluster-ip |
1-3-5. mTLS 인증
Service Mesh는 클러스터 내부의 분산 애플리케이션이 상호 인증을 통해 안전하게 통신하는 엄격한 Zero Trust 환경에서 특히 유용합니다. 클러스터에 들어오고 나가는 트래픽(North‑South 트래픽)에 동일한 수준의 보안을 적용해야 하는 경우에는 어떻게 해야 합니까?
Ingress Controller Layer에서 mTLS 인증을 구성하여 유효한 인증서를 제시하여 외부 연결의 End 시스템이 서로 인증하도록 할 수 있습니다.
다음 표에서는 클라이언트 인증서 인증 및 BackEnd 인증서 인증을 위한 Community Ingress Controller 주석에 해당하는 NGINX 정책 리소스의 필드를 보여줍니다.
| Community Ingress Controller | NGINX Ingress Controller |
| nginx.ingress.kubernetes.io/auth-tls-secret: secretName nginx.ingress.kubernetes.io/auth-tls-verify-client: “on” nginx.ingress.kubernetes.io/auth-tls-verify-depth: “1” | ingressMTLS: clientCertSecret: secretName verifyClient: “on” verifyDepth: 1 |
| nginx.ingress.kubernetes.io/proxy-ssl-secret: “secretName” nginx.ingress.kubernetes.io/proxy-ssl-verify: “on|off” nginx.ingress.kubernetes.io/proxy-ssl-verify-depth: “1” nginx.ingress.kubernetes.io/proxy-ssl-protocols: “TLSv1.2” nginx.ingress.kubernetes.io/proxy-ssl-ciphers: “DEFAULT” nginx.ingress.kubernetes.io/proxy-ssl-name: “server-name” nginx.ingress.kubernetes.io/proxy-ssl-server-name: “on|off” | egressMTLS: tlsSecret: secretName verifyServer: true|false verifyDepth: 1 protocols: TLSv1.2 ciphers: DEFAULT sslName: server-name serverName: true|false |
1-3-6. 세션 지속성(NGINX Plus 전용)
다음 표에서는 NGINX Plus를 기반으로 하는 NGINX Ingress Controller전용이며 세션 지속성에 대한 Community Ingress Controller 주석에 해당하는 NGINX Policy 리소스의 필드를 보여 줍니다.
| Community Ingress Controller | NGINX Ingress Controller |
| nginx.ingress.kubernetes.io/affinity: “cookie” nginx.ingress.kubernetes.io/session-cookie-name: “cookieName” nginx.ingress.kubernetes.io/session-cookie-expires: “x” nginx.ingress.kubernetes.io/session-cookie-path: “/route” nginx.ingress.kubernetes.io/session-cookie-secure: “true” | sessionCookie: enable: true name: cookieName expires: xh path: /route secure: true |
2. Kubernetes Ingress 리소스를 사용하여 마이그레이션
Community Ingress Controller에서 NGINX Ingress Controller로 마이그레이션하는 두 번째 옵션은 표준 Kubernetes Ingress 리소스에서 주석과 ConfigMap만 사용하고 잠재적으로 Master/Minion 스타일 처리에 의존하는 것입니다. 이렇게 하면 Ingress 개체의 모든 구성이 유지됩니다.
Note: 이 방법을 사용하여 입력 리소스의 사양 필드를 변경하지 마십시오.
2-1. 고급 구성의 주석
다음 표에는 NGINX Ingress Controller가 지원하는 주석에 직접 해당하는 Community Ingress Controller 주석이 요약되어 있습니다.
| Community Ingress Controller | NGINX Ingress Controller | NGINX Directive |
| nginx.ingress.kubernetes.io/configuration-snippet: | | nginx.org/location-snippets: | | N/A |
| nginx.ingress.kubernetes.io/load-balance1 | nginx.org/lb-method | Default: random two least_conn |
| nginx.ingress.kubernetes.io/proxy-buffering: “on|off” | nginx.org/proxy-buffering: “True|False” | proxy_buffering |
| nginx.ingress.kubernetes.io/proxy-buffers-number: “number” nginx.ingress.kubernetes.io/proxy-buffer-size: “xk” | nginx.org/proxy-buffers: “number 4k|8k” nginx.org/proxy-buffer-size: “4k|8k” | proxy_buffers proxy_buffer_size |
| nginx.ingress.kubernetes.io/proxy-connect-timeout: “seconds” | nginx.org/proxy-connect-timeout: : “secondss” | proxy_connect_timeout |
| nginx.ingress.kubernetes.io/proxy-read-timeout: “seconds“ | nginx.org/proxy-read-timeout: “secondss” | proxy_read_timeout |
| nginx.ingress.kubernetes.io/proxy-send-timeout: “seconds“ | nginx.org/proxy-send-timeout: “secondss” | proxy_send_timeout |
| nginx.ingress.kubernetes.io/rewrite-target: “URI“ | nginx.org/rewrites: “serviceName=svc rewrite=URI“ | rewrite |
| nginx.ingress.kubernetes.io/server-snippet: | | nginx.org/server-snippets: | | N/A |
| nginx.ingress.kubernetes.io/ssl-redirect: “true|false” | ingress.kubernetes.io/ssl-redirect: “True|False” | N/A2 |
설명:1. Community Ingress Controller는 Lua를 사용하여 일부 Load Balancing 알고리즘을 구현합니다. NGINX Ingress Controller에는 모든 항목에 해당하는 항목이 없습니다.
설명:2. HTTP 트래픽을 HTTPS로 리디렉션(Redirection)합니다. Community Ingress Controller는 Lua 코드로 이를 구현하는 반면 NGINX Ingress Controller는 기본 NGINX if 조건을 사용합니다.
다음 표에는 NGINX Plus 기반의 NGINX Ingress Controller에서 지원하는 주에 직접 해당하는 Community Ingress Controller 주석이 요약되어 있습니다.
| Community Ingress Controller | NGINX Ingress Controller Based on NGINX Plus |
| nginx.ingress.kubernetes.io/affinity: “cookie” nginx.ingress.kubernetes.io/session-cookie-name: “cookie_name” nginx.ingress.kubernetes.io/session-cookie-expires: “seconds” nginx.ingress.kubernetes.io/session-cookie-path: “/route“ | nginx.com/sticky-cookie-services: “serviceName=example-svc cookie_name expires=time path=/route“ |
Note: NGINX Plus 기반으로 하는 NGINX Ingress Controller에는 JSON Web Tokens(JWTs)을 사용한 활성 상태 확인 및 인증을 포함하여 Community Ingress Controller가 전혀 지원하지 않는 기능에 대한 추가 주석이 있습니다.
2-2. ConfigMap을 사용한 글로벌 구성
다음 표는 Community Ingress Controller ConfigMap 키를 직접 대응하는 NGINX Ingress Controller ConfigMap 키에 매핑합니다. 일부 ConfigMap 키 이름은 동일합니다. 또한 Community Ingress Controller와 NGINX Ingress Controller에는 다른 Controller에는 없는 ConfigMaps 키가 있습니다(표에 표시되지 않음).
| Community Ingress Controller | NGINX Ingress Controller |
| disable-access-log | access-log-off |
| error-log-level | error-log-level |
| hsts | hsts |
| hsts-include-subdomains | hsts-include-subdomains |
| hsts-max-age | hsts-max-age |
| http-snippet | http-snippets |
| keep-alive | keepalive-timeout |
| keep-alive-requests | keepalive-requests |
| load-balance | lb-method |
| location-snippet | location-snippets |
| log-format-escape-json: “true” | log-format-escaping: “json” |
| log-format-stream | stream-log-format |
| log-format-upstream | log-format |
| main-snippet | main-snippets |
| max-worker-connections | worker-connections |
| max-worker-open-files | worker-rlimit-nofile |
| proxy-body-size | client-max-body-size |
| proxy-buffering | proxy-buffering |
| proxy-buffers-number: “number” proxy-buffer-size: “size“ | proxy-buffers: number size |
| proxy-connect-timeout | proxy-connect-timeout |
| proxy-read-timeout | proxy-read-timeout |
| proxy-send-timeout | proxy-send-timeout |
| server-name-hash-bucket-size | server-names-hash-bucket-size |
| server-name-hash-max-size | server-names-hash-max-size |
| server-snippet | server-snippets |
| server-tokens | server-tokens |
| ssl-ciphers | ssl-ciphers |
| ssl-dh-param | ssl-dhparam-file |
| ssl-protocols | ssl-protocols |
| ssl-redirect | ssl-redirect |
| upstream-keepalive-connections | keepalive |
| use-http2 | http2 |
| use-proxy-protocol | proxy-protocol |
| variables-hash-bucket-size | variables-hash-bucket-size |
| worker-cpu-affinity | worker-cpu-affinity |
| worker-processes | worker-processes |
| worker-shutdown-timeout | worker-shutdown-timeout |
3. 요약
사용자 지정 NGINX Ingress 리소스 또는 주석 및 ConfigMap이 있는 표준 Kubernetes Ingress 리소스를 사용하여 Community Ingress Controller에서 NGINX Ingress Controller로 마이그레이션할 수 있습니다. 전자 옵션은 보다 광범위한 네트워킹 기능을 지원하므로 Production 등급 Kubernetes 환경에 더 적합합니다.
NGINX Plus 기반의 NGINX Ingress Controller를 사용해 보려면 지금 30일 무료 평가판을 신청하거나 사용 사례에 대해 최신 소식을 빠르게 전달받고 싶으시면 아래 뉴스레터를 구독하세요.
