NGINX Ingress Controller Documentation

Helm으로 설치

이 문서에서는 Helm 을 사용하여 Kubernetes 클러스터에 NGINX Ingress Controller를 설치하는 방법을 설명합니다.

목록

1. 필수 구성 요소
2. 차트 Source 가져오기
3. Helm Repository 추가

4. 차트 설치
4-1. CRD 설치
4-2. Helm Repository를 통해 설치
4-3. 차트 Source를 사용하여 설치
5. 차트 업그레이드
6. 차트 제거

7. Multiple Ingress Controllers 실행
8. 구성

1. 필수 구성 요소

  • Ingress Controller에서 지원하는 Kubernetes Version
  • Helm 3.0+
  • Git
  • NGINX Plus를 사용하려면:
    • Container registry에서 가져오려면 여기의 지침에 따라 JWT 토큰을 사용하여 Docker Registry Secret을 구성하십시오. controller.serviceAccount.imagePullSecretName 매개변수를 사용하여 Secret를 지정해야 합니다.
    • 또는 NGINX Plus를 사용하여 Ingress Controller 이미지를 가져오고 여기의 지침에 따라 Private Registry로 Push 합니다.
    • 또는 NGINX Plus를 사용하여 Ingress Controller 이미지를 Build 하고 여기의 지침에 따라 Private Registry에 Push 할 수 있습니다.
    • 그에 따라 values-plus.yamlcontroller.image.repository 필드를 업데이트하십시오.
  • App Protect DoS를 사용하려면 App Protect DoS Arbitrator Helm Chart를 설치하세요. NGINX Ingress Controller와 동일한 Namespace에 설치해야 합니다. 동일한 Namespace에 여러 NGINX Ingress Controller를 설치하는 경우 단일 Namespace에 둘 이상의 Arbitrator를 설치할 수 없기 때문에 동일한 Arbitrator를 공유해야 합니다.

2. 차트 Source 가져오기

이 단계는 해당 Source를 사용하여 차트를 설치하는 경우에 필요합니다. 또한 Ingress Controller에 기본적으로 필요한 사용자 정의 리소스(CRD)를 관리하거나 CRD를 업그레이드/삭제하는 단계도 필요합니다.

1. Ingress Controller Repo를 Clone합니다.

$ git clone https://github.com/nginxinc/kubernetes-ingress.git --branch v2.4.1

2. 작업 디렉터리를 /deployments/helm-chart로 변경하십시오.

$ cd kubernetes-ingress/deployments/helm-chart

3. Helm Repository 추가

Helm Repository를 통해 차트를 설치하는 경우 이 단계가 필요합니다.

$ helm repo add nginx-stable https://helm.nginx.com/stable
$ helm repo update

4. 차트 설치

4-1. CRD 설치

기본적으로 Ingress Controller에는 클러스터에 설치된 여러 사용자 정의 리소스(CRD)가 필요합니다. Helm 클라이언트는 해당 CRD를 설치합니다. CRD가 설치되어 있지 않으면 Ingress Controller Pod가 Ready 상태가 되지 않습니다.

해당 CRD가 필요한 사용자 정의 리소스(controller.enableCustomResourcesfalse로 설정되고 controller.appprotect.enablefalse로 설정됨)를 사용하지 않는 경우, Helm 설치 명령에 --skip-crds를 지정하여 CRD 설치를 건너뛸 수 있습니다.

4-2. Helm Repository를 통해 설치

Release 이름 my-release(my-release는 사용자가 선택한 이름입니다.)를 사용하여 차트를 설치하려면:

NGINX의 경우:

$ helm install my-release nginx-stable/nginx-ingress

NGINX Plus의 경우: (Ingress Controller 이미지 nginx-plus-ingress를 개인 Private Registry인 myregistry.example.com로 Push한 경우)

$ helm install my-release nginx-stable/nginx-ingress --set controller.image.repository=myregistry.example.com/nginx-plus-ingress --set controller.nginxplus=true

4-3. 차트 Source를 사용하여 설치

Release 이름 my-release(my-release는 사용자가 선택한 이름입니다.)를 사용하여 차트를 설치하려면:

NGINX의 경우:

$ helm install my-release .

NGINX Plus의 경우:

$ helm install my-release -f values-plus.yaml .

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

Ingress Controller를 배포할 때 미리 생성된 기본 서버가 아닌 자체 TLS 인증서와 Key를 기본 서버에 사용해야 합니다. 기본 서버에 대한 TLS 인증서 및 Key를 구성하는 방법을 보려면 아래의 구성 섹션을 읽으십시오. 기본 서버는 Ingress 규칙이 정의되지 않은 도메인에 대한 모든 요청에 대해 404 상태 코드와 함께 Not Found 페이지를 반환합니다.

5. 차트 업그레이드

CRD 업그레이드

Helm은 Release 업그레이드 중에 CRD를 업그레이드하지 않습니다. Release를 업그레이드하기 전에 다음 명령을 실행하여 CRD를 업그레이드하십시오.

$ kubectl apply -f crds/

Note: 다음 경고가 예상되며 무시할 수 있습니다.

Warning: kubectl apply should be used on resource created by either kubectl create --save-config or kubectl apply

Note: 특별한 업그레이드 절차는 release 노트에서 새 release를 확인하십시오.

Release 업그레이드

Release (my-release)를 업그레이드 하려면

차트 Source를 사용하여 업그레이드:

$ helm upgrade my-release .

Helm Repository를 통해 업그레이드:

$ helm upgrade my-release nginx-stable/nginx-ingress

6. 차트 제거

Release 제거

Release(my-release)를 제거/삭제하려면:

$ helm uninstall my-release

이 명령은 Release와 관련된 모든 Kubernetes 구성 요소를 제거합니다.

CRD 제거

Release를 제거해도 CRD는 제거되지 않습니다. CRD를 제거하려면 다음을 실행하십시오.

$ kubectl delete -f crds/

Note: 이 명령은 모든 Namespace에서 클러스터의 해당 사용자 정의 Release를 모두 삭제합니다. 유지하려는 사용자 정의 Release가 없고 클러스터에서 실행 중인 다른 Ingress Controller release가 없는지 확인하십시오.

7. Multiple Ingress Controllers 실행

사용자 정의 리소스가 활성화된 클러스터에서 여러 Ingress Controller Release를 실행하는 경우 Release는 단일 버전의 CRD를 공유합니다. 결과적으로 Ingress Controller 버전이 CRD 버전과 일치하는지 확인하십시오. 또한 Release를 제거할 때 클러스터에서 실행 중인 다른 Ingress Controller release가 없을 때까지 CRD를 제거하지 마십시오.

자세한 내용은 Multiple Ingress Controller 실행을 참조하십시오.

8. 구성

다음 표에는 NGINX Ingress Controller 차트의 구성 가능한 매개변수와 해당 default값이 나열되어 있습니다.

Parameter설명기본값
controller.nameIngress Controller, Daemonset 또는 Deployment의 이름Autogenerated
controller.kindIngress Controller 설치 종류 – Deployment 또는 Daemonset.deployment
controller.nginxplusNGINX Plus용 Ingress Controller를 배포false
controller.nginxReloadTimeout변경 후 또는 초기 시작 시 Ingress Controller가 NGINX Reload를 기다리는 시간(ms)입니다.60000
controller.appprotect.enableIngress Controller에서 App Protect WAF 모듈을 활성화합니다.false
controller.appprotectdos.enableIngress Controller에서 App Protect DoS 모듈을 활성화합니다.false
controller.appprotectdos.debugApp Protect DoS 디버그 Log를 활성화 합니다.false
controller.appprotectdos.maxWorkers지원할 최대 NGINX 프로세스 수입니다.시스템의 CPU 코어 수
controller.appprotectdos.maxDaemons최대 ADMD 인스턴스 수입니다.1
controller.appprotectdos.memory사용할 RAM 메모리 크기(MB)입니다.컨테이너에 사용 가능한 RAM의 크기 50% 또는 80MB
controller.hostNetworkIngress Controller Pod이 호스트의 Network Namespace를 사용할 수 있도록 합니다.false
controller.nginxDebugNGINX에 대한 디버깅을 활성화합니다. nginx-debug Binary를 사용합니다. controller.config.entries를 통해 ConfigMap에서 error-log-level: debug가 필요합니다.false
controller.logLevelIngress Controller의 Log Level입니다.1
controller.image.repositoryIngress Controller의 이미지 Repository입니다.nginx/nginx-ingress
controller.image.digestIngress Controller 이미지 Digest입니다. Digest가 태그보다 우선합니다.None
controller.image.tagIngress Controller 이미지의 태그 입니다.2.4.1
controller.image.pullPolicyIngress Controller 이미지에 대한 Pull 정책 입니다.IfNotPresent
controller.lifecycleIngress Controller Pod의 Lifecycle입니다.{}
controller.customConfigMap Ingress Controller에서 사용하는 사용자 정의 ConfigMap의 이름입니다. 설정하는 경우 기본 구성은 무시됩니다.“”
controller.config.nameIngress Controller에서 사용하는 ConfigMap의 이름입니다.Autogenerated
controller.config.entriesNGINX 구성을 사용자 정의하기 위한 ConfigMap의 항목입니다. 지원되는 ConfigMap Key 목록은 ConfigMap 리소스 문서를 참조하세요.{}
controller.customPortsNGINX ingress controller pod에 Expose할 사용자 정의 포트 목록입니다. 컨테이너 Pod에 대한 기존 Kubernetes Yaml 구문을 따릅니다.[]
controller.defaultTLS.cert기본 HTTPS 서버에 대한 base64 인코딩 TLS 인증서 Note: 기본적으로 사전 생성된 자체 서명 인증서가 사용됩니다. 자신의 인증서를 지정하는 것이 좋습니다. 또는 기본 서버 Secret를 완전히 생략하면 기본 서버에 대한 TLS 연결을 거부하도록 NGINX가 구성됩니다.A pre-generated self-signed certificate.
controller.defaultTLS.key기본 HTTPS 서버에 대한 base64 인코딩 TLS Key입니다. Note: 기본적으로 미리 생성된 Key가 사용됩니다. 고유한 Key를 지정하는 것이 좋습니다. 또는 기본 서버 Secret을 완전히 생략하면 NGINX가 기본 서버에 대한 TLS 연결을 거부하도록 구성됩니다.A pre-generated key.
controller.defaultTLS.secret기본 HTTPS 서버에 대한 TLS 인증서 및 Key가 있는 Secret입니다. 값은 <namespace>/<name> 형식을 따라야 합니다. controller.defaultTLS.certcontroller.defaultTLS.key 매개변수를 사용하여 인증서 및 Key를 지정하는 대신 사용됩니다. Note: 또는 기본 서버 Secret을 완전히 생략하면 NGINX가 기본 서버에 대한 TLS 연결을 거부하도록 구성됩니다.None
controller.wildcardTLS.certTLS가 활성화되었지만 Secret이 지정되지 않은 모든 Ingress/VirtualServer 호스트에 대한 base64 인코딩 TLS 인증서. 매개변수가 설정되지 않은 경우 이러한 Ingress/VirtualServer 호스트에 대해 NGINX는 TLS 연결을 설정하려는 모든 시도를 중단합니다.None
controller.wildcardTLS.keyTLS가 활성화되었지만 Secret이 지정되지 않은 모든 Ingress/VirtualServer 호스트에 대한 base64 인코딩 TLS Key. 매개변수가 설정되지 않은 경우 이러한 Ingress/VirtualServer 호스트에 대해 NGINX는 TLS 연결을 설정하려는 모든 시도를 중단합니다.None
controller.wildcardTLS.secretTLS가 활성화되었지만 지정된 Secret이 없는 모든 Ingress/VirtualServer 호스트에 대한 TLS 인증서 및 Key가 있는 Secret입니다. 값은 <namespace>/<name> 형식을 따라야 합니다. controller.wildcardTLS.certcontroller.wildcardTLS.key 매개변수를 사용하여 인증서 및 Key를 지정하는 대신 사용됩니다.None
controller.nodeSelectorIngress Controller Pod에 대한 Pod 할당을 위한 노드 선택기.{}
controller.terminationGracePeriodSeconds Ingress Controller Pod의 종료 유예 기간입니다.30
controller.tolerationsIngress Controller Pod의 허용 오차입니다.[]
controller.affinityIngress Controller Pod의 선호도입니다.{}
controller.volumesIngress Controller Pod의 Volume입니다.[]
controller.volumeMountsIngress Controller Pod의 VolumeMount입니다.[]
controller.initContainersIngress Controller Pod의 InitContainer 입니다.[]
controller.extraContainersIngress Controller Pod용 추가(예: sidecar) 컨테이너 입니다.[]
controller.resourcesIngress Controller Pod의 리소스 입니다.requests: cpu=100m,memory=128Mi
controller.replicaCountIngress Controller Deployment의 Replica 수입니다.1
controller.ingressClassIngress Controller의 Class입니다. Class와 이름이 동일한 IngressClass 리소스를 배포해야 합니다. 그렇지 않으면 Ingress Controller가 시작되지 않습니다. Ingress Controller는 해당 Class에 속하는 리소스만 처리합니다. 즉, “ingressClassName” 필드 리소스가 Class와 동일합니다. Ingress Controller는 모든 버전의 kubernetes에 대해 “ingressClassName” 필드가 없는 모든 VirtualServer/VirtualServerRoute/TransportServer 리소스를 처리합니다.nginx
controller.setAsDefaultIngressingressClassName 필드가 지정되지 않은 새 Ingress에는 controller.ingressClass에 지정된 Class가 할당됩니다.false
controller.watchNamespaceIngress Controller가 리소스를 감시해야 하는 쉼표로 구분된 Namespace 목록입니다. 기본적으로 Ingress Controller는 모든 Namespace를 감시합니다. controller.watchNamespaceLabel과 상호 배타적입니다. Helm cli --set 옵션을 사용하여 여러 Namespace를 구성하는 경우 문자열을 큰따옴표로 묶고 쉼표는 백슬래시를 사용하여 이스케이프 처리해야 합니다. --set controller.watchNamespace="default\,nginx-ingress".“”
controller.watchNamespaceLabel레이블이 foo=bar인 Namespace만 감시하도록 Ingress Controller를 구성합니다. 기본적으로 Ingress Controller는 모든 Namespace를 감시합니다. controller.watchNamespace와 상호 배타적입니다.“”
controller.watchSecretNamespaceIngress Controller가 Secret 유형의 리소스를 감시해야 하는 쉼표로 구분된 Namespace 목록입니다. 이 Arg가 구성되지 않은 경우 Ingress Controller는 모든 리소스에 대해 동일한 Namespace를 감시합니다. controller.watchNamespace 및 controller.watchNamespaceLabel을 참조하십시오. Helm cli --set 옵션을 사용하여 여러 Namespace를 구성하는 경우 문자열을 큰따옴표로 묶고 쉼표는 백슬래시를 사용하여 Escaoe 처리해야 합니다. --set controller.watchSecretNamespace="default\,nginx-ingress".“”
controller.enableCustomResources사용자 정의 리소스를 활성화합니다.true
controller.enablePreviewPolicies미리 보기 정책을 활성화합니다. 이 매개변수는 더 이상 사용되지 않습니다. OIDC 정책을 사용 설정하려면 대신 controller.enableOIDC를 사용하세요.false
controller.enableOIDCOIDC 정책을 활성화합니다.false
controller.includeYearLog 헤더에 연도를 포함합니다. 이 매개변수는 release 2.7에서 제거되며 연도는 기본적으로 포함됩니다.false
controller.enableTLSPassthrough포트 443에서 TLS Passthrough를 사용 설정합니다. controller.enableCustomResources가 필요합니다.false
controller.enableCertManagercert-manager(cert-manager.io)를 사용하여 VirtualServer 리소스에 대한 x509 자동 인증서 관리를 활성화합니다. controller.enableCustomResources가 필요합니다.false
controller.enableExternalDNSExternalDNS를 사용하여 VirtualServer 리소스에 대한 공개 DNS 항목을 구성하기 위해 ExternalDNS와의 통합을 사용 설정합니다. controller.enableCustomResources가 필요합니다.false
controller.globalConfiguration.createGlobalConfiguration 사용자 정의 리소스를 만듭니다. controller.enableCustomResources가 필요합니다.false
controller.globalConfiguration.specIngress Controller의 전역 구성 매개변수를 정의하기 위한 GlobalConfiguration의 사양입니다.{}
controller.enableSnippetsIngress, VirtualServer, VirtualServerRoute 및 TransportServer 리소스에서 사용자 정의 NGINX 구성 Snippet을 활성화합니다.false
controller.healthStatus기본 서버에 “/nginx-health” location를 추가합니다. location는 모든 요청에 대해 200 상태 코드로 응답합니다. Ingress Controller의 External Health Check에 유용합니다.false
controller.healthStatusURI기본 서버에서 상태 위치의 URI를 설정합니다. controller.healthStatus가 필요합니다.“/nginx-health”
controller.nginxStatus.enableNGINX stub_status 또는 NGINX Plus API를 활성화합니다.true
controller.nginxStatus.portNGINX stub_status 또는 NGINX Plus API가 Expose되는 포트를 설정합니다.8080
controller.nginxStatus.allowCidrsNGINX stub_status 또는 NGINX Plus API에 대한 허용 목록에 IP/CIDR 블록을 추가합니다. 여러 IP/CIDR을 쉼표로 구분합니다.127.0.0.1,::1
controller.service.createIngress Controller Pod를 Expose하는 서비스를 생성합니다.true
controller.service.typeIngress Controller에 대해 생성할 서비스 유형입니다.LoadBalancer
controller.service.allocateLoadBalancerNodePorts서비스에 대한 NodePort를 자동으로 할당할지 여부(Bool, LoadBalancers만 해당).“”
controller.service.ipFamilyPolicy이중 스택 기본 설정. 유효한 값: SingleStackPreferDualStackRequireDualStack.“”
controller.service.ipFamilies이 서비스에 할당된 IP 제품군 목록입니다. 유효한 값: IPv4, IPv6“”
controller.service.externalTrafficPolicy서비스의 externalTrafficPolicy입니다. 로컬 값은 클라이언트 Source IP를 유지합니다.Local
controller.service.annotationsIngress Controller 서비스의 Annotation입니다.{}
controller.service.extraLabels서비스의 추가 Label입니다.{}
controller.service.loadBalancerIPLoad Balancer의 Static IP 주소입니다. Controller.service.typeLoadBalancer로 설정해야 합니다. 클라우드 공급자는 이 기능을 지원해야 합니다.“”
controller.service.externalIPsIngress Controller 서비스의 External IP 목록입니다.[]
controller.service.loadBalancerSourceRangesLoad Balancer에 액세스할 수 있는 IP 범위(CIDR)입니다. Controller.service.typeLoadBalancer로 설정해야 합니다. 클라우드 공급자는 이 기능을 지원해야 합니다.[]
controller.service.name서비스의 이름입니다.Autogenerated
controller.service.customPortsIngress Controller 서비스를 통해 표시할 사용자 정의 포트 목록입니다. 서비스 포트에 대한 기존 Kubernetes yaml 구문을 따릅니다.[]
controller.service.httpPort.enableIngress Controller 서비스에 대한 HTTP 포트를 활성화합니다.true
controller.service.httpPort.portIngress Controller 서비스의 HTTP 포트입니다.80
controller.service.httpPort.nodePortHTTP 포트에 대한 사용자 정의 NodePort입니다. controller.service.typeNodePort로 설정해야 합니다.“”
controller.service.httpPort.targetPortIngress Controller 서비스의 HTTP 포트 Target 포트입니다.80
controller.service.httpsPort.enableIngress Controller 서비스에 대한 HTTPS 포트를 활성화합니다.true
controller.service.httpsPort.portIngress Controller 서비스의 HTTPS 포트입니다.443
controller.service.httpsPort.nodePortHTTPS 포트에 대한 사용자 정의 NodePort입니다. controller.service.typeNodePort로 설정해야 합니다.“”
controller.service.httpsPort.targetPortIngress Controller 서비스의 HTTPS 포트 Target 포트입니다.443
controller.serviceAccount.nameIngress Controller Pod의 서비스 계정 이름입니다. RBAC에 사용됩니다.Autogenerated
controller.serviceAccount.imagePullSecretNameDocker Registry 자격 증명을 포함하는 Secret의 이름입니다. Secret은 Helm Release와 동일한 Namespace에 있어야 합니다.“”
controller.reportIngressStatus.enableIngress 리소스 상태의 주소 필드를 Ingress Controller의 외부 주소로 업데이트합니다. 또한 다음을 통해 외부 서비스를 통해 외부 주소의 Source를 지정해야 합니다.
controller.ReportingressStatus.externalService, controller.reportingressStatus.ingressLink 또는 controller.config.entries를 통한 ConfigMap의 external-status-address 항목입니다. Note: controller.config.entries.external-status-address는 다른 항목보다 우선합니다.
true
controller.reportIngressStatus.externalServiceIngress Controller가 외부에 Expose 되는 LoadBalancer 유형의 서비스 이름을 지정합니다. 서비스의 외부 주소는 Ingress, VirtualServer 및 VirtualServerRoute 리소스의 상태를 보고할 때 사용됩니다.
controller.reportIngressStatus.enabletrue로 설정해야 합니다. 기본값은 자동 생성되며 controller.service.createtrue로 설정되고 controller.service.typeLoadBalancer로 설정되면 활성화됩니다.
Autogenerated
controller.reportIngressStatus.ingressLinkBIG-IP 시스템을 통해 Ingress Controller Pod를 Expose 하는 IngressLink 리소스의 이름을 지정합니다. BIG-IP 시스템의 IP는 Ingress, VirtualServer 및 VirtualServerRoute 리소스의 상태를 보고할 때 사용됩니다. controller.reportIngressStatus.enabletrue로 설정해야 합니다.“”
controller.reportIngressStatus.enableLeaderElectionIngress 리소스의 상태를 보고하는 Controller의 여러 Replicas을 방지하려면 리더 선택을 활성화합니다. controller.reportIngressStatus.enabletrue로 설정해야 합니다.true
controller.reportIngressStatus.leaderElectionLockName리더 선택을 위한 잠금으로 사용되는 controller와 동일한 namespace 내에서 ConfigMap의 이름을 지정합니다. controller.reportIngressStatus.enableLeaderElection을 true로 설정해야 합니다.Autogenerated
controller.pod.annotationsIngress Controller pod의 Annotation입니다.{}
controller.readyStatus.enableReadiness Endpoint '/nginx-ready'를 사용 설정합니다. NGINX가 시작 후 모든 구성을 Load 하면 Endpoint는 성공 코드를 반환합니다. 또한 Readiness Endpoint을 사용하는 Ingress Controller Pod에 대한 조사 준비를 구성합니다.true
controller.readyStatus.portReadiness Endpoint HTTP 포트입니다. 8081
controller.readyStatus.initialDelaySecondsIngress Controller Pod이 시작된 후 조사 준비가 시작되기 전의 시간(s)입니다.0
controller.enableLatencyMetricsUpstream에 대한 지연 시간 Metrics 수집을 활성화합니다. prometheus.create가 필요합니다.false
controller.minReadySeconds새로 생성된 Pod가 사용 가능한 것으로 간주되기 위해 컨테이너 충돌 없이 준비되어야 하는 최소 시간(s)을 지정합니다. docs0
controller.strategy이전 Pod를 새 Pod로 교체하는 데 사용할 전략을 지정합니다. docs{}
controller.disableIPV6IPV6 스택을 지원하지 않는 노드에 대해 IPV6  listener를 명시적으로 비활성화합니다.false
rbac.createRBAC 구성.true
prometheus.createNGINX 또는 NGINX Plus Metrics을 Prometheus 형식으로 Expose합니다.false
prometheus.portMetrics을 스크랩하도록 포트를 구성합니다.9113
prometheus.scheme요청이 Prometheus Endpoint에 연결하는 데 사용해야 하는 HTTP 체계를 구성합니다.http
prometheus.secretPrometheus Endpoint의 보안 HTTPS 연결을 설정하는 데 사용할 수 있는 Kubernetes TLS Secret의 namespace/name을 지정합니다.“”