Helm Chart 를 통한 NGINX Ingress Controller 설치 가이드

이 가이드에서는 Helm Chart 를 사용하여 NGINX Ingress Controller 를 Kubernetes 클러스터에 설치하는 방법을 단계별로 설명합니다. Helm은 Kubernetes 애플리케이션의 설치 및 관리를 간편하게 해주는 패키지 관리 도구로, 복잡한 애플리케이션 설정을 손쉽게 배포할 수 있습 니다.

Kubernetes 클러스터에서 애플리케이션을 배포하고 관리할 때, 인그레스(ingress) 리소스를 통해 외부 트래픽을 클러스터 내부의 서비스로 라우팅하는 것이 중요합니다. NGINX Ingress Controller 는 이러한 인그레스 리소스를 관리하는 데 있어 널리 사용되는 솔루션으로, 다양한 기능과 유연성을 제공합니다.

목차

1. 사전 요구 사항
2. NGINX Ingress Controller CRD
 2-1. NGINX Ingress Controller CRD 업그레이드
 2-2. NGINX Ingress Controller CRD 제거
3. OCI Registry를 통한 Helm Chart 관리
 3-1. Helm Chart 설치
 3-2. Helm Chart 업그레이드
 3-3. Helm Chart 제거
 3-4. Edge 버전
4. Source를 통한 Helm Chart 관리
 4-1. Helm Chart Pulling
 4-2. Helm Chart 설치
 4-3. Helm Chart 업그레이드
 4-4. Helm Chart 제거
5. 무중단 업그레이드 가이드
 5-1. Background 업그레이드
 5-2. 업그레이드 단계

1. 사전 요구 사항

참고:

모든 문서는 최신 안정 릴리스에서만 사용해야 합니다.

NGINX Ingress Controller가 지원하는 Kubernetes 버전:

NIC VersionSupported Kubernetes VersionNIC Helm Chart VersionNIC Operator VersionNGINX / NGINX Plus version
3.6.11.25 – 1.301.3.12.3.11.27.0 / R32
3.5.21.23 – 1.301.2.22.2.21.27.0 / R32
3.4.31.23 – 1.291.1.32.1.21.25.4 / R31 P1
3.3.21.22 – 1.281.0.22.0.21.25.3 / R30
3.2.11.22 – 1.270.18.11.5.11.25.2 / R30
3.1.11.22 – 1.260.17.11.4.21.23.4 / R29
3.0.21.21 – 1.260.16.21.3.11.23.3 / R28
2.4.21.19 – 1.250.15.21.2.11.23.2 / R28
2.3.11.19 – 1.240.14.11.1.01.23.1 / R27
2.2.21.19 – 1.230.13.21.0.01.21.6 / R26
2.1.21.19 – 1.230.12.10.5.11.21.6 / R26
2.0.31.19 – 1.220.11.30.4.01.21.3 / R25
1.12.41.16 – 1.210.10.40.3.01.21.6 / R26
1.11.31.16 – 1.200.9.00.2.01.21.0 / R23 P1
1.10.11.16 – 1.190.8.00.1.01.19.8 / R23
1.9.11.16 – 1.180.7.10.0.71.19.3 / R22
  • Helm 3.0+.
  • NGINX Plus를 사용하려면:
    • JWT 토큰을 사용하여 Docker Regisrty Secret을 구성하고 해당 지침을 따르세요. controller.serviceAccount.imagePullSecretName 또는 controller.serviceAccount.imagePullSecretsNames 매개변수를 사용하여 Secret을 지정하십시오.
    • 또는 이 지침을 따라 NGINX Plus가 포함된 NGINX Ingress Controller 이미지를 가져와서 개인 레지스트리에 Push 하십시오.
    • 또는 NGINX를 빌드하여 NGINX Plus가 포함된 Ingress Controller 이미지를 생성하고 이를 개인 레지스트리에 Push할 수 있습니다.
    • values-plus.yaml의 controller.image.repository 필드를 적절하게 업데이트하십시오.
  • App Protect DoS를 사용하려면 NGINX Ingress Controller와 동일한 네임스페이스에 App Protect DoS Arbitrator Helm Chart를 설치하십시오. 동일한 네임스페이스에 여러 NGINX Ingress Controller를 설치하는 경우 하나의 네임스페이스에 하나의 Arbitrator만 있을 수 있으므로 동일한 Arbitrator를 공유해야 합니다.

2. NGINX Ingress Controller CRD

2-1. NGINX Ingress Controller CRD 업그레이드

CRDs를 업그레이드하려면, ‘4-1. Helm Chart Pulling‘에서 설명한 대로 차트 소스를 가져온 다음 다음 명령을 실행하세요.

# kubectl apply -f crds/

또는 차트를 가져오지 않고 CRDs를 업그레이드하려면 다음 명령을 실행하세요.

# kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.6.1/deploy/crds.yaml

위 명령에서 v3.6.1은 Helm 버전이 아닌 NGINX Ingress Controller 릴리스의 버전을 나타냅니다.

참고:

다음 경고는 예상되는 것으로 무시해도 됩니다.
Warning: kubectl apply should be used on resource created by either kubectl create --save-config or kubectl apply.

2-2. NGINX Ingress Controller CRD 제거

CRDs를 제거하려면, 4-1. Helm Chart Pulling‘에서 설명한 대로 차트 소스를 가져온 다음 다음 명령을 실행하세요.

kubectl delete -f crds/

참고:

이 명령은 모든 네임스페이스에서 클러스터의 해당 Custom Resource를 모두 삭제합니다. 유지하고 싶은 Custom Resource가 없고 클러스터에서 다른 Ingress Controller 릴리스가 실행 중이지 않은지 확인하세요.

3. OCI Registry를 통한 Helm Chart 관리

3-1. Helm Chart 설치

Helm을 릴리스 이름 my-release로 설치하려면 다음과 같이 진행하세요. (my-release는 사용자 지정 커스텀 이름입니다.)

  • NGINX OSS용:
# helm install my-release oci://ghcr.io/nginxinc/charts/nginx-ingress --version 1.3.1
  • NGINX Plus용: (Ingress Controller 이미지 nginx-plus-ingress를 개인 레지스트리 myregistry.example.com에 푸시했다고 가정)
# helm install my-release oci://ghcr.io/nginxinc/charts/nginx-ingress --version 1.3.1 --set controller.image.repository=myregistry.example.com/nginx-plus-ingress --set controller.nginxplus=true

이 명령은 GitHub Container Registry에서 Ingress Controller의 최신 Edge 버전을 설치합니다.

Docker Hub를 사용하려면, ghcr.io/nginxinc/charts/nginx-ingress를 registry-1.docker.io/nginxcharts/nginx-ingress로 대체할 수 있습니다.

3-2. Helm Chart 업그레이드


Helm Chart 은 릴리스 업그레이드 중에 CRDs를 업그레이드하지 않습니다. 릴리스를 업그레이드하기 전에 CRDs 업그레이드를 참조하세요.

릴리스 my-release 업그레이드:

# helm upgrade my-release oci://ghcr.io/nginxinc/charts/nginx-ingress --version 1.3.1

3-3. Helm Chart 제거

릴리스 my-release 삭제 혹은 제거:

helm uninstall my-release

이 명령은 릴리스와 관련된 모든 Kubernetes 구성 요소를 제거하고 릴리스를 삭제합니다.

릴리스를 삭제해도 CRDs는 제거되지 않습니다. CRDs를 제거하려면 ‘2-2. NGINX Ingress Controller CRD 제거‘를 참조하세요.

3-4. Edge 버전

NGINX Ingress Controller의 최신 변경 사항을 새 릴리스 전에 테스트하려면 edge 버전을 설치할 수 있습니다. 이 버전은 NGINX Ingress Controller 리포지토리의 main 브랜치에서 빌드됩니다. edge 버전을 설치하려면 –version 플래그에 값 0.0.0-edge를 지정하십시오.

# helm install my-release oci://ghcr.io/nginxinc/charts/nginx-ingress --version 0.0.0-edge

경고:

edge 버전은 프로덕션 환경에서 사용하기 위한 것이 아닙니다. 테스트 및 개발 목적에만 사용하도록 설계되었습니다.

4. Source를 통한 Helm Chart 관리

이 단계는 Helm Chart 의 Source를 사용하여 설치할 때 필요합니다. 또한, Ingress Controller가 기본적으로 필요로 하는 커스텀 리소스 정의(CRD)를 관리하거나 CRD를 업그레이드/삭제하기 위해서도 이 단계가 필요합니다.

4-1. Helm Chart Pulling

1. 차트 소스를 가져오세요.

# helm pull oci://ghcr.io/nginxinc/charts/nginx-ingress --untar --version 1.3.1

2. 작업 디렉터리를 nginx-ingress로 변경하세요.

# cd nginx-ingress

4-2. Helm Chart 설치

Helm Chart 를 릴리스 이름 my-release로 설치하려면(my-release는 사용자 정의 이름입니다.)

  • NGINX용:
# helm install my-release .
  • NGINX Plus용:
# helm install my-release -f values-plus.yaml .

이 명령은 기본 설정으로 Kubernetes 클러스터에 Ingress Controller를 배포합니다. 설치 중 구성할 수 있는 매개변수는 구성 섹션에 나열되어 있습니다.

4-3. Helm Chart 업그레이드

Helm Chart 은 릴리스 업그레이드 중에 CRDs를 업그레이드하지 않습니다. 릴리스를 업그레이드하기 전에 2-1. NGINX Ingress Controller CRD 업그레이드를 참조하세요.

릴리스 my-release를 업그레이드하려면:

# helm upgrade my-release .

4-4. Helm Chart 제거

Helm Chart 릴리스 my-release를 삭제/제거하려면:

# helm uninstall my-release

이 명령은 릴리스와 관련된 모든 Kubernetes 구성 요소를 제거하고 릴리스를 삭제합니다.

릴리스를 삭제해도 CRDs는 제거되지 않습니다. CRDs를 제거하려면 2-2. NGINX Ingress Controller CRD 제거 를 참조하세요.

5. 무중단 업그레이드 가이드

5-1. Background 업그레이드

NGINX Ingress Controller 버전 3.1.0에서는 Helm Chart 모범 사례에 맞추어 Helm Resource 이름, Label 및 Annotation에 변경 사항이 도입되었습니다. 3.1.0 이전 버전에서 업그레이드할 때, Deployment, DaemonSet, Service와 같은 특정 리소스가 재생성되어 Downtime이 발생할 수 있습니다.

5-2. 업그레이드 단계

참고:

다음 단계는 2.x 및 3.0.x 릴리스에 모두 적용됩니다.

Helm 릴리스 이름에 따라 따라야 할 단계가 달라집니다.

HELM 릴리스 이름이 NGINX-INGRESS인 경우:

1. 배포/데몬셋에 대해 kubectl describe 명령을 사용하여 Selector 값을 가져옵니다:

# kubectl describe deployments -n <namespace>

Selector 아래의 key=value를 복사합니다. 예를 들어:

# Selector: app=nginx-ingress-nginx-ingress

2. git checkout v3.6.1 명령을 사용하여 최신 태그를 체크아웃합니다.

3. /kubernates-ingress/charts/nginx-ingress 디렉토리로 이동합니다.

4. /kubernates-ingress/charts/nginx-ingress에 위치한 values.yaml 파일의 selectorLabels: {} 필드를 복사한 Selector 값으로 업데이트합니다.

# selectorLabels: {app: nginx-ingress-nginx-ingress}

5. 다음 매개변수가 설정된 helm upgrade 명령을 실행합니다:

# --set serviceNameOverride="nginx-ingress-nginx-ingress"
--set controller.name=""
--set fullnameOverride="nginx-ingress-nginx-ingress"

전체 명령은 다음과 같이 보일 수 있습니다:

# helm upgrade nginx-ingress oci://ghcr.io/nginxinc/charts/nginx-ingress --version 0.19.0 --set controller.kind=deployment/daemonset --set controller.nginxplus=false/true --set controller.image.pullPolicy=Always --set serviceNameOverride="nginx-ingress-nginx-ingress" --set controller.name="" --set fullnameOverride="nginx-ingress-nginx-ingress" -f values.yaml

6. 업그레이드 프로세스가 완료되면 배포의 이벤트를 검토하여 변경 사항을 확인하기 위해 kubectl describe 명령을 사용합니다:

Type    Reason             Age    From                   Message
----    ------             ----   ----                   -------
Normal  ScalingReplicaSet  9m11s  deployment-controller  Scaled up replica set nginx-ingress-nginx-ingress-<old_version> to 1
Normal  ScalingReplicaSet  101s   deployment-controller  Scaled up replica set nginx-ingress-nginx-ingress-<new_version> to 1
Normal  ScalingReplicaSet  98s    deployment-controller  Scaled down replica set nginx-in
HELM 릴리스 이름이 NGINX-INGRESS인 경우:

kubectl describe 명령을 사용하여 배포/데몬셋의 Selector 값을 가져오세요:

# kubectl describe deployment/daemonset -n <namespace>

Selector 아래의 key=value를 복사합니다. 예를 들어,

# Selector: app=<helm_release_name>-nginx-ingress

2. git checkout v3.6.1 명령을 사용하여 최신 태그를 체크아웃합니다.

3. /kubernates-ingress/charts/nginx-ingress 디렉토리로 이동합니다.

4. /kubernates-ingress/charts/nginx-ingress에 위치한 values.yaml 파일의 selectorLabels: {} 필드를 복사한 Selector 값으로 업데이트합니다.

# selectorLabels: {app: <helm_release_name>-nginx-ingress}

5. 다음 매개변수가 설정된 helm upgrade 명령을 실행합니다:

# --set serviceNameOverride="<helm_release_name>-nginx-ingress"
--set controller.name=""

6. 전체 명령은 다음과 같이 보일 수 있습니다:

# helm upgrade test-release oci://ghcr.io/nginxinc/charts/nginx-ingress --version 0.19.0 --set controller.kind=deployment/daemonset --set controller.nginxplus=false/true --set controller.image.pullPolicy=Always --set serviceNameOverride="test-release-nginx-ingress" --set controller.name="" -f values.yaml

업그레이드 프로세스가 완료되면 배포의 이벤트를 검토하여 변경 사항을 확인하기 위해 kubectl describe 명령을 사용합니다:

Type    Reason             Age    From                   Message
----    ------             ----   ----                   -------
Normal  ScalingReplicaSet  9m11s  deployment-controller  Scaled up replica set test-release-nginx-ingress-<old_version> to 1
Normal  ScalingReplicaSet  101s   deployment-controller  Scaled up replica set test-release-nginx-ingress-<new_version> to 1
Normal  ScalingReplicaSet  98s    deployment-controller  Scaled down replica set test-releas

Helm Chart를 통해 설치하는 방법 이외에도 NGINX Ingress Controller를 다양한 방법으로 설치하고 싶으신가요?
NGINX STORE의 Kubernetes 카테고리를 참고하거나 NGINX STORE에 문의하여 사용 사례에 대해 상담 받아보세요.

NGINX 및 NGINX Plus에 대한 상담이 필요하다면 아래 폼으로 NGINX STORE에게 연락해주세요.

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

* indicates required