NGINX Ingress Controller Troubleshooting 가이드

NGINX Ingress Controller Troublesshooting 가이드입니다.

목차

1. 일반적인 문제 해결
 1-1. 일반적 문제
 1-2. 문제 해결
2. 정책 리소스 문제 해결
 2-1. 정책 리소스
 2-2. Configmap 리소스
3. Ingress 리소스 문제 해결
 3-1. Ingress 리소스
4. VirtualServer 리소스 문제 해결
 4-1. VirtualServer 및 VirtualServerRoute리소스 이벤트 검사

1. 일반적인 문제 해결


NGINX Ingress Controller와 관련된 일반적인 문제를 해결하는 방법을 설명합니다.

1-1. 일반적 문제

문제 영역징후문제 해결 방법공통 원인
StartupNGINX Ingress Controller가 시작되지 않습니다.로그를 확인하세요.잘못 구성된 RBAC, 기본 서버 TLS Secret이 누락되었습니다.
Ingress resource and annotations구성이 적용되지 않습니다Ingress 리소스의 이벤트를 확인하고, 로그를 확인하고, 생성된 구성을 확인하세요.annotation의 값이 잘못되었습니다.
VirtualServer and VirtualServerRoute resources구성이 적용되지 않습니다.VirtualServer와 VirtualServerRoutes의 이벤트를 확인하고, 로그를 확인하고, 생성된 구성을 확인하세요.VirtualServer 또는 VirtualServerRoute가 잘못되었습니다.
Policy resource구성이 적용되지 않습니다.정책 리소스의 이벤트와 해당 정책을 참조하는 VirtualServers의 이벤트를 확인하고, 로그를 확인하고, 생성된 구성을 확인하세요.정책이 잘못되었습니다.
ConfigMap keys구성이 적용되지 않습니다.ConfigMap의 이벤트를 확인하고, 로그를 확인하고, 생성된 구성을 확인하세요.ConfigMap 키 값이 잘못되었습니다.
NGINXNGINX가 예상치 못한 응답을 합니다.로그를 확인하고, 생성된 구성을 확인하고, 라이브 활동 대시보드를 확인하고(NGINX Plus만 해당), 디버그 모드에서 NGINX를 실행합니다.잘못된 백엔드 pods, 잘못 구성된 백엔드 서비스입니다.

1-2. 문제해결 방법

다음 예제에서는 다음과 같은 구성이 진행 후에 해결을 진행합니다.

  • 해당 NGINX Ingress Controller는 nginx-ingress 네임스페이스에 배포됩니다.
  • <nginx-ingress-pod>는 NGINX Ingress Controller deployment로 배포한 파드중 하나의 이름입니다.

NGINX Ingress Controller 로그 확인

NGINX Ingress Controller의 로그를 확인하려면 아래와 같이 로그를 확인합니다.
NGINX Ingress Controller 로그에서는 NGINX 엑세스 및 오류 로그가 포함되어 있습니다.

$ kubectl logs <nginx-ingress-pod> -n nginx-ingress

NGINX Ingress Controller의 NGINX 구성 파일 확인

각 Ingress/VirtualServer 리소스에 대해 NGINX INgress Controller는 NGINX 구성 파일을 생성합니다.
/etc/nginx/conf.d 폴더안에 만들어집니다.

/etc/nginx/nginx/conf또한 NGINX Ingress Controller는 모든 구성 파일을 포함하는 구성파일을 생성합니다.
/etc/nginx/conf.d. VirtualServerRoute 리소스의 구성은 리소스를 참조하는 VirtualServer의 구성 파일에 있습니다.

다음을 실생하면 주요 구성 파일의 내용을 볼 수 있습니다

$ kubectl exec <nginx-ingress-pod> -n nginx-ingress -- cat /etc/nginx/nginx.conf

모든 NGINX 구성 파일을 출력할 수도 있습니다.

$ kubectl exec <nginx-ingress-pod> -n nginx-ingress -- nginx -T

구성 파일이 유효하지 않다면 위의 명령문은 실패합니다.

라이브 모니터링 대쉬보드 확인

라이브 모니터링 대쉬보드는 NGINX Plus와 로드밸런싱하는 애플리케이션에 대한 실시간 정보를 표시하여 문제 해결에 도움이 됩니다. 대쉬보드에 액세스하려면 상태 페이지를 읽어보세요.

NGINX Ingress Controller에 대한 디버깅 활성화

NGINX Ingress Controller 디버깅 설정을 활성화하여 더 자세한 로그를 얻을 수 있습니다.
NGINX Ingress Controller 디버그 로그 레벨을 높이면 NGINX 자체에도 적용됩니다.
NGINX Ingress Controller에 대해 더 자세한 로깅을 구성할 수 있는 2가지 위치가 있습니다.
1. Command line 인수
2. Configmap 설정

Command line 인수

deployment에 사용할 경우 deployment 또는 daemonset에서 manifest command line 인수를 사용하세요. -nginx-debug

-v 는 NGINX Ingress Controller 프로세스의 자세한 정보를 제공합니다.
args 은 deployment 섹션에서 command line 인수를 설정하는 코드입니다.

args:
  - -nginx-configmaps=$(POD_NAMESPACE)/nginx-config
  - -enable-cert-manager
  - -nginx-debug
  - -v=3

NGINX Ingress Controller에서 설정할 수 있는 Configmap입니다 다음을 추가합니다.
error-log-level configMap

kind: ConfigMap
apiVersion: v1
metadata:
  name: nginx-config
  namespace: nginx-ingress
data:
  error-log-level: "debug"

Helm에서 사용하기

Helm을 사용하는 경우 다음 두가지 설정을 사용할 수 있습니다.

controller.nginxDebug = true or false
controller.loglevel = 1 to 3 value

values.yaml을 사용하는 경우

  ## Enables debugging for NGINX. Uses the nginx-debug binary. Requires error-log-level: debug in ConfigMap via `controller.config.entries`.
  nginxDebug: true

  ## The log level of the Ingress Controller.
  logLevel: 3

다음은 완전한 예시입니다.

controller:
  kind: Deployment
  nginxDebug: true
  logLevel: 3
  annotations:
    nginx: ingress-prod
  pod:
    annotations:
      prometheus.io/scrape: "true"
      prometheus.io/port: "9113"
      prometheus.io/scheme: http
    extraLabels:
      env: prod-weset
  nginxplus: plus
  image:
    repository: nginx/nginx-ingress
    tag: 3.6.1
  # NGINX Configmap
  config:
    entries:
      error-log-level: "debug"
      proxy_connet_timeout: "5s"
      http-snippets: |
        underscores_in_headers on;        
  ingressClass: nginx

CLI 인수를 활성화하고 디버깅을 위해 nginx-debug를 변경합니다. error-log-level.debug

NGINX Ingress Controller 디버그 출력 예제

아래 로그는 NGINX Ingress Controller 디버그를 구성한 후의 출력입니다.

I1026 15:39:03.269092       1 manager.go:301] Reloading nginx with configVersion: 1
I1026 15:39:03.269115       1 utils.go:17] executing /usr/sbin/nginx-debug -s reload -e stderr
2022/10/26 15:39:03 [notice] 19#19: signal 1 (SIGHUP) received from 42, reconfiguring
2022/10/26 15:39:03 [debug] 19#19: wake up, sigio 0
2022/10/26 15:39:03 [notice] 19#19: reconfiguring
2022/10/26 15:39:03 [debug] 19#19: posix_memalign: 000056362AF0A420:16384 @16
2022/10/26 15:39:03 [debug] 19#19: add cleanup: 000056362AF0C318
2022/10/26 15:39:03 [debug] 19#19: posix_memalign: 000056362AF48230:16384 @16
2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362AF00DE0:4096
2022/10/26 15:39:03 [debug] 19#19: read: 46, 000056362AF00DE0, 3090, 0
2022/10/26 15:39:03 [debug] 19#19: posix_memalign: 000056362AF58670:16384 @16
2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362AF12440:4280
2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362AF13500:4280
2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362AF145C0:4280
2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362AF5C680:4280
2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362AF5D740:4280
2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362AF5E800:4280
2022/10/26 15:39:03 [debug] 19#19: posix_memalign: 000056362AF5F8C0:16384 @16
2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362AF41500:4096
2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362AF638D0:8192
2022/10/26 15:39:03 [debug] 19#19: include /etc/nginx/mime.types
2022/10/26 15:39:03 [debug] 19#19: include /etc/nginx/mime.types
2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362AF658E0:4096
2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362AF668F0:5349
2022/10/26 15:39:03 [debug] 19#19: read: 47, 000056362AF658E0, 4096, 0
2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362AF67DE0:4096
2022/10/26 15:39:03 [debug] 19#19: read: 47, 000056362AF658E1, 1253, 4096
2022/10/26 15:39:03 [debug] 19#19: posix_memalign: 000056362AF68DF0:16384 @16
2022/10/26 15:39:03 [debug] 19#19: posix_memalign: 000056362AF6CE00:16384 @16
2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362AF70E10:524288
2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362AFF0E20:524288
2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362B070E30:524288
2022/10/26 15:39:03 [debug] 19#19: malloc: 000056362B0F0E40:400280

2. 정책 리소스 문제 해결

 NGINX Ingress Controller 정책 리소스의 문제를 해결하는 방법을 설명합니다.

2-1. 정책 리소스

정책 리소스를 생성하거나 업데이트한 후에는 NGINX Ingress Controller가 정책 업데이트를 완료했는지 여부를 확인하는데 사용할 수 있습니다. kubectl describe policy webapp-policy 명령어를 통하여

$ kubectl describe policy webapp-policy
Events:
  Type    Reason          Age   From                      Message
  ----    ------          ----  ----                      -------
  Normal  AddedOrUpdated  11s   nginx-ingress-controller  Policy default/webapp-policy was added or updated

이벤트 섹션에는 정책이 성공적으로 적용되었다는 것을 나타내는 AddedOrUpdated를 나타내게 됩니다.
하지만 정책이 적용되었다는 것은 NGINX 구성이 성공적으로 적용되었다는 것을 보장하지 않습니다.
적용된 구성을 확인하려면 정책을 참조하는 VirtualServer 리소스 문제 해결의 이벤트를 확인합니다.

2-2. ConfigMap 리소스

ConfigMap 리소스를 생성하거나 업데이트 한 후에 NGINX에서 구성이 성공적으로 적용되었는지 즉시 확인할 수 있습니다. kubectl describe configmap <configmap-name> -n <namespace-name>

$ kubectl describe configmap nginx-config -n nginx-ingress

Name:         nginx-config
Namespace:    nginx-ingress
Labels:       <none>

Events:
  Type    Reason   Age                From                      Message
  ----    ------   ----               ----                      -------
  Normal  Updated  11s (x2 over 26m)  nginx-ingress-controller  Configuration from nginx-ingress/nginx-config was updated

정책과 마찬가지로 이벤트 섹션에는 정책이 성공적으로 적용되었음을 나타내는 AddedorUpdate가 포함된 이벤트가 있습니다.

3. Ingress 리소스 문제 해결

NGINX Ingress Controller의 Ingress 리소스의 문제 해결하는 방법을 설명합니다.

3-1. Ingress 리소스

Ingress 리소스를 생성하거나 업데이트한 후에는 해당 Ingress 리소스에 대한 NGINX 구성이 NGINX에 의해 성공적으로 적용되었는지 즉시 확인할 수 있습니다. kubectl describe ingress <ingress-name>

$ kubectl describe ingress cafe-ingress

Name:             cafe-ingress
Namespace:        default

Events:
  Type    Reason          Age   From                      Message
  ----    ------          ----  ----                      -------
  Normal  AddedOrUpdated  12s   nginx-ingress-controller  Configuration for default/cafe-ingress was added or updated

이벤트 섹션에는 정책이 성공적으로 적용되었음을 나타내는 AddedOrUpdate 이벤트가 있습니다.

4. VirtualServer 리소스 문제 해결

VirtualServer 및 VirtualServer 리소스의 문제를 해결하는 방법을 설명합니다.

4-1. VirtualServer 및 VirtualServerRoute 리소스 이벤트 검사

VirtualServer 리소스를 만들거나 업데이트한 후 다음을 사용하여 해당 리소스에 대한 NGINX 구성이 성공적으로 수행되었는지 즉시 확인할 수 있습니다. kubectl describe vs <VirtualServer-name>

$ kubectl describe vs cafe 

Events:
  Type    Reason          Age   From                      Message
  ----    ------          ----  ----                      -------
  Normal  AddedOrUpdated  16s   nginx-ingress-controller  Configuration for default/cafe was added or updated

위의 예시에서 구성이 성공적으로 적용되었음을 알려주는 AddedorUPdate를 볼 수 있습니다.
VirtualServerRoute의 이벤트를 확인하는 것은 비슷합니다.

$ kubectl describe vsr coffe

Events:
  Type     Reason                 Age   From                      Message
  ----     ------                 ----  ----                      -------
  Normal   AddedOrUpdated         1m    nginx-ingress-controller  Configuration for default/coffee was added or updated

NGINX Ingress Controller에 더 많은 정보를 원하신다면 NGNIX STORE kubernetes를 방문해주세요.

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

* indicates required