NGINX Ingress Controller: Manifest 로 설치

F5 NGINX Ingress Controller 를 Kubernetes 클러스터에 매니페스트로 설치하고, 공통 리소스와 커스텀 리소스를 생성한 뒤 RBAC을 설정하는 단계별 가이드입니다. 이 방법을 사용하면 Helm이나 Operator 없이 직접 YAML 파일을 적용하여 컨트롤러를 배포할 수 있습니다.

목차

1. 개요
2. 사전 준비
3. NGINX Ingress Controller 이미지 가져오기
4. NGINX Ingress Controller 레포지토리 클론
5. RBAC 설정
6. 공통 리소스 생성
7. 코어 CRD 생성
8. 선택적 CRD 생성
9. NGINX Ingress Controller 배포
9-1. Deployment 배포
 9-2. DaemonSet 배포
10. 설치 확인
11. 접근 방법 구성
11-1. NGINX Ingress Controller Deployment
11-2. NGINX Ingress Controller DaemonSet
12. 마무리 및 다음 단계

1. 개요

F5 NGINX Ingress Controller는 Kubernetes 환경에서 외부 트래픽을 클러스터 내 서비스로 라우팅하는 역할을 수행하는 고성능 Ingress 컨트롤러입니다. 이 가이드는 Helm이나 Operator 기반의 설치 방식과는 달리, 매니페스트(Manifest) 기반으로 컨트롤러를 설치하고 구성하는 방법을 다룹니다. 이 방식은 사용자가 각 구성 요소를 세밀하게 제어하고, YAML 수준에서 리소스를 직접 적용할 수 있기 때문에 운영 환경에 맞는 유연한 커스터마이징이 가능합니다.

2. 사전 준비

  • NGINX Plus를 사용하시는 경우 JWT 토큰으로 라이선스 시크릿을 생성해야 합니다.
  • Kubernetes 클러스터 관리자 권한(admin role)이 필요합니다.
  • kubectl CLI 설치 및 클러스터 접근 설정이 완료되어 있어야 합니다.

3. NGINX Ingress Controller 이미지 가져오기

  1. NGINX OSS 버전: Docker Hub에서 nginx/nginx-ingress 이미지를 가져옵니다.
  2. NGINX Plus 버전:
    • F5 Registry에서 구독 인증서와 키를 사용하여 이미지를 가져옵니다.
    • JWT 토큰 사용 방법은 [NGINX Ingress Controller image with JWT]를 참고하십시오.
  3. 커스텀 이미지 빌드(선택): 소스 레포지토리를 클론한 뒤 직접 빌드할 수 있습니다.

4. NGINX Ingress Controller 레포지토리 클론

git clone https://github.com/nginx/kubernetes-ingress.git --branch v5.1.0
cd kubernetes-ingress

– <version_number>에 원하는 릴리스 태그를 지정하시고, 최신 안정화 버전을 권장드립니다.

5. RBAC 설정

1. 네임스페이스 및 서비스어카운트 생성

kubectl apply -f deployments/common/ns-and-sa.yaml

2. ClusterRole 및 바인딩 생성

kubectl apply -f deployments/rbac/rbac.yaml

6. 공통 리소스 생성

이 섹션에서는 대부분의 NGINX Ingress Controller 설치에 필요한 리소스를 생성합니다.

(선택 사항) 기본 NGINX 서버의 TLS 인증서와 키를 위한 Secret을 생성하세요. 이 단계는 기본 서버 TLS Secret 명령줄 인수를 사용하는 경우에만 완료하세요. 사용하지 않는 경우 이 단계를 건너뛰어도 됩니다.

기본적으로 Ingress 규칙이 설정되어 있지 않으면 서버는 모든 요청에 대해 404 Not Found 페이지를 반환합니다. 테스트용으로 자체 서명된 인증서와 키를 제공하지만, 자체 인증서를 사용하는 것을 권장합니다.

kubectl apply -f examples/shared-examples/default-server-secret/default-server-secret.yaml

NGINX 구을 사용자 지정하려면 ConfigMap을 생성하세요.

kubectl apply -f deployments/common/nginx-config.yaml

IngressClass 리소스를 생성하세요. NGINX Ingress Controller는 IngressClass 리소스가 없으면 시작되지 않습니다.

kubectl apply -f deployments/common/ingress-class.yaml

이 Ingress Controller 인스턴스를 클러스터의 기본값으로 설정하려면 ingressclass.kubernetes.io/is-default-class 주석을 주석 해제하세요.
이 작업을 수행하면 ingressClassName을 지정하지 않은 새로운 Ingress 리소스에 IngressClass가 자동으로 할당됩니다.

7. 코어 CRD 생성

NGINX Ingress Controller 파드가 Ready 상태에 도달하도록 하려면, 여러 구성 요소에 대한 사용자 정의 리소스 정의(CRDs)를 생성해야 합니다.

또는 -enable-custom-resources 명령줄 인수를 false로 설정하여 이 요구 사항을 비활성화할 수 있습니다.

사용자 정의 리소스 정의를 설치하는 방법에는 두 가지가 있습니다:

  1. 단일 CRD YAML 파일의 URL을 사용하여 적용하는 방법 (권장).
  2. 저장소를 클론한 후 로컬에 있는 CRD YAML 파일을 적용하는 방법.

핵심 사용자 정의 CRDs는 다음과 같습니다:

  • VirtualServer 및 VirtualServerRoute
  • TransportServer
  • Policy
  • GlobalConfiguration
  • 권장 방식:
kubectl apply -f https://raw.githubusercontent.com/nginx/kubernetes-ingress/v5.1.0/deploy/crds.yaml
  • 로컬 방식 (레포지토리 클론)
kubectl apply -f config/crd/bases/k8s.nginx.org_virtualservers.yaml
kubectl apply -f config/crd/bases/k8s.nginx.org_virtualserverroutes.yaml
kubectl apply -f config/crd/bases/k8s.nginx.org_transportservers.yaml
kubectl apply -f config/crd/bases/k8s.nginx.org_policies.yaml
kubectl apply -f config/crd/bases/k8s.nginx.org_globalconfigurations.yaml
...

8. 선택적 CRD 생성

NGINX App Protect WAF 또는 NGINX App Protect DoS를 사용하려는 경우에는 선택적 CRD들이 필요합니다.

NGINX App Protect WAF:

  • APPolicy
  • APLogConf
  • APUserSig
kubectl apply -f https://raw.githubusercontent.com/nginx/kubernetes-ingress/v5.1.0/deploy/crds-nap-waf.yaml

NGINX App Protect DoS:

  • APDosPolicy
  • APDosLogConf
  • DosProtectedResource
kubectl apply -f https://raw.githubusercontent.com/nginx/kubernetes-ingress/v5.1.0/deploy/crds-nap-dos.yaml

9. NGINX Ingress Controller 배포

NGINX Ingress Controller를 배포하는 방법에는 두 가지 옵션이 있습니다:

  • Deployment: NGINX Ingress Controller 복제본 수를 동적으로 변경할 수 있는 유연성이 필요할 경우 이 방법을 선택하세요.
  • DaemonSet: 모든 노드 또는 일부 노드에서 NGINX Ingress Controller가 실행되도록 하려면 이 방법을 선택하세요.

시작하기 전에, 관련 매니페스트 파일에서 NGINX Ingress Controller의 컨테이너 명령줄 인수를 업데이트하여 특정 요구 사항에 맞추세요.

9-1. Deployment 배포

Kubernetes Deployment를 사용한 컨테이너 관리에 대한 추가 정보는 공식 Kubernetes Deployment 문서를 참고하세요.

NGINX Ingress Controller를 Deployment로 배포하면, Kubernetes는 자동으로 단일 NGINX Ingress Controller 파드를 설정합니다.

  • NGINX의 경우, 다음을 실행하세요.
kubectl apply -f deployments/deployment/nginx-ingress.yaml
  • NGINX Plus의 경우, 다음을 실행하세요.
kubectl apply -f deployments/deployment/nginx-plus-ingress.yaml

nginx-plus-ingress.yaml 파일을 수정하여 F5 컨테이너 레지스트리에서 선택한 이미지 또는 사용자 정의 컨테이너 이미지를 포함하세요.

9-2. DaemonSet 배포

Kubernetes DaemonSet을 사용한 컨테이너 관리에 대한 추가 정보는 공식 Kubernetes DaemonSet 문서를 참고하세요.

NGINX Ingress Controller를 DaemonSet으로 배포하면, Kubernetes는 클러스터의 모든 노드에 Ingress Controller 파드를 생성합니다.

  • NGINX의 경우, 다음 명령을 사용하세요.
kubectl apply -f deployments/daemon-set/nginx-ingress.yaml
  • NGINX Plus의 경우, 다음 명령을 사용하세요.
kubectl apply -f deployments/daemon-set/nginx-plus-ingress.yaml

nginx-plus-ingress.yaml 파일을 수정하여 F5 컨테이너 레지스트리에서 선택한 이미지 또는 사용자 정의 컨테이너 이미지를 포함하세요.

10. 설치 확인

NGINX Ingress Controller의 설치가 성공적으로 완료되었는지 확인하려면, 다음 명령어를 실행합니다.

kubectl get pods --namespace=nginx-ingress

하위 리소스가 모두 "Running" 또는 "Ready" 상태인지 확인하세요.
이 단계는 컨트롤러가 정상적으로 배포되어 작동 중임을 검증하는 핵심 절차입니다.

11. 접근 방법 구성

배포 방식(Deployment 또는 DaemonSet)에 따라 Ingress Controller에 접근하는 방법은 다음과 같습니다.

11-1. NGINX Ingress Controller Deployment

옵션 1: NodePort 서비스 생성

kubectl create -f deployments/service/nodeport.yaml

이 방법은 클러스터의 모든 노드에서 고정 또는 동적 포트를 할당받아, 해당 노드 IP + 포트 조합으로 접근할 수 있게 합니다.

옵션 2: LoadBalancer 서비스 생성

클라우드 환경에 따라 다음과 같이 실행합니다.

  • GCP 또는 Azure:
kubectl apply -f deployments/service/loadbalancer.yaml
  • AWS:
kubectl apply -f deployments/service/loadbalancer-aws-elb.yaml

AWS에서 ELB를 TCP 모드로 작동시키려면, nginx-config.yaml ConfigMap에 다음 설정을 추가한 후 다시 적용합니다:

proxy-protocol: "True"
real-ip-header: "proxy_protocol"
set-real-ip-from: "0.0.0.0/0"

이 방법을 사용하면 클라우드 제공업체가 자동으로 퍼블릭 IP 또는 DNS를 할당해 줍니다.

11-2. NGINX Ingress Controller DaemonSet

NGINX Ingress Controller를 DaemonSet으로 배포하면, Kubernetes는 클러스터의 모든 노드에 Ingress Controller 파드를 생성합니다.

노드 포트 80과 443에 대해 클러스터 내 모든(또는 특정) 노드 IP로 접근할 수 있습니다.

  • NGINX의 경우:
kubectl apply -f deployments/daemon-set/nginx-ingress.yaml
  • NGINX Plus의 경우:
kubectl apply -f deployments/daemon-set/nginx-plus-ingress.yaml

nginx-plus-ingress.yaml 파일을 업데이트하여 F5 컨테이너 레지스트리에서 선택한 이미지나 사용자 지정 컨테이너 이미지를 포함하세요.

12. 마무리 및 다음 단계

  • 설치 완성 점검
    kubectl get pods 명령으로 모든 Pod가 정상 작동하는지 재차 확인한 후, 서비스 타입(NodePort/LoadBalancer)을 통해 실제로 외부에서 접속이 가능한지 테스트하세요.
  • 다음 단계 제안
    • 인그레스 규칙(Ingress resources)을 생성하여 실제 트래픽 라우팅을 설정합니다.
    • TLS 인증서를 구성해 HTTPS를 활성화합니다.
    • 모니터링(예: Prometheus, Service Insight)과 로깅(예: Status Page)을 추가합니다.
    • 고급 구성: ConfigMap, IngressClass, VirtualServer 등 커스터마이즈하거나 확장 기능(App Protect WAF/DoS 등)을 적용할 수 있습니다.

이로써 NGINX Ingress Controller의 설치 및 초기 접근 설정이 완료되었습니다.

NGINX Ingress Controller에 대해 더 알아보려면 NGINX STORE 블로그의 Kubernetes 카테고리를 참고하세요.

NGINX STORE를 통한 솔루션 도입 및 기술지원 무료 상담 신청

* indicates required