NGINX Ingress Controller Documentation

일반적인 문제 해결

이 문서에서는 Ingress Controller의 문제를 해결하는 방법을 설명합니다.

목차

1. 잠재적인 문제
2. 문제 해결 방법
 2-1. Ingress Controller Log 확인
2-2. Ingress 리소스의 이벤트 확인
2-3. VirtualServer 및 VirtualServerRoute 리소스의 이벤트 확인
2-4. 정책 리소스의 이벤트 확인
2-5. ConfigMap 리소스의 이벤트 확인
2-6. 생성된 구성 확인
2-7. 실시간 활동 모니터링 대시보드 확인
2-8. 디버그 모드에서 NGINX 실행

1. 잠재적인 문제

아래 표는 발생할 수 있는 Ingress Controller의 몇 가지 잠재적인 문제를 분류하고 다음 섹션에서 하나 이상의 방법을 사용하여 이러한 문제를 해결하는 방법을 제안합니다.

문제 영역증상문제 해결 방법원인
StartIngress Controller 시작되지 않습니다.Log 확인합니다.잘못 구성된 RBAC, 누락된 기본 서버 TLS Secret.
Ingress Resource 및 Annotations구성이 적용되지 않았습니다.Ingress 리소스의 이벤트를 확인하고 Log를 확인하고 생성된 구성을 확인합니다.잘못된 annotation 값 입니다.
VirtualServer 및 VirtualServerRoute Resources구성이 적용되지 않았습니다.VirtualServer 및 VirtualServerRoutes의 이벤트를 확인하고 Log를 확인하고 생성된 구성을 확인합니다.VirtualServer 또는 VirtualServerRoute가 잘못되었습니다.
Policy Resource구성이 적용되지 않았습니다.정책 리소스의 이벤트와 해당 정책을 참조하는 VirtualServer의 이벤트를 확인하고, Log를 확인하고, 생성된 구성을 확인합니다.정책이 잘못되었습니다.
ConfigMap Keys구성이 적용되지 않았습니다.ConfigMap의 이벤트를 확인하고 Log를 확인하고 생성된 구성을 확인합니다.ConfigMap Key 값이 잘못되었습니다.
NGINXNGINX가 예상치 못한 응답으로 응답합니다.Log를 확인하고, 생성된 구성을 확인하고, 라이브 활동 대시보드를 확인하고(NGINX Plus만 해당) 디버그 모드에서 NGINX를 실행합니다.비정상적인 Backend Pod, 잘못 구성된 Backend 서비스

2. 문제 해결 방법

다음 섹션의 명령은 다음을 가정합니다:

  • Ingress Controller는 Namespace nginx-ingress에 배포됩니다.
  • <nginx-ingress-pod>는 Ingress Controller Pod 중 하나의 이름입니다.

2-1. Ingress Controller Log 확인

Ingress Controller Log(Ingress Controller 소프트웨어와 NGINX Access 및 Error Log 모두)를 확인하려면 다음을 실행합니다.

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

세부 정보 표시 및 형식 제어:

  • Ingress Controller 소프트웨어 Log의 자세한 정도(1에서 4까지)를 제어하려면 -v Command-Line Argument를 사용합니다. 예를 들어 -v=3을 사용하면 더 많은 정보를 얻을 수 있으며 새롭거나 업데이트된 구성 파일의 내용이 Log에 인쇄됩니다.
  • NGINX Log의 상세도와 형식을 제어하려면 해당 ConfigMap Key를 구성합니다.

2-2. Ingress 리소스의 이벤트 확인

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

$ kubectl describe ing 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

이벤트 섹션에는 구성이 성공적으로 적용되었음을 알려주는 AddedOrUpdated Reason이 있는 Normal 이벤트가 있습니다.

2-3. VirtualServer 및 VirtualServerRoute 리소스의 이벤트 확인

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

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

이벤트 섹션에는 구성이 성공적으로 적용되었음을 알려주는 AddedOrUpdated Reason가 있는 Normal 이벤트가 있습니다.

VirtualServerRoute의 이벤트를 확인하는 것은 비슷합니다.

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

2-4. 정책 리소스의 이벤트 확인

정책 리소스를 생성하거나 업데이트한 후 kubectl describe를 사용하여 Ingress Controller가 정책을 수락했는지 여부를 확인할 수 있습니다.

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

이벤트 섹션에는 정책이 성공적으로 수락되었음을 알려주는 AddedOrUpdated Reason가 있는 Normal 이벤트가 있습니다.

그러나 정책이 수락되었다고 해서 NGINX 구성이 성공적으로 적용되었다는 보장은 없습니다. 이를 확인하려면 해당 정책을 참조하는 VirtualServer 및 VirtualServerRoute 리소스의 이벤트를 확인하십시오.

2-5. ConfigMap 리소스의 이벤트 확인

ConfigMap 리소스를 업데이트한 후 NGINX에서 구성이 성공적으로 적용되었는지 즉시 확인할 수 있습니다.

$ 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

이벤트 섹션에는 구성이 성공적으로 적용되었음을 알려주는 Updated Reason가 있는 일반 Normal가 있습니다.

2-6. 생성된 구성 확인

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

다음을 실행하여 기본 구성 파일의 내용을 볼 수 있습니다.

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

마찬가지로 /etc/nginx/conf.d 폴더에서 생성된 구성 파일의 내용을 볼 수 있습니다.

모든 NGINX 구성 파일을 함께 Print할 수도 있습니다.

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

그러나 구성 파일 중 하나라도 유효하지 않으면 이 명령은 실패합니다.

2-7. 실시간 활동 모니터링 대시보드 확인

라이브 활동 모니터링 대시보드는 NGINX Plus와 Load Balancing 중인 애플리케이션에 대한 실시간 정보를 보여주므로 문제 해결에 도움이 됩니다. 대시보드에 액세스하려면 여기에서 단계를 따르십시오.

2-8. 디버그 모드에서 NGINX 실행

디버그 모드에서 NGINX를 실행하면 NGINX의 문제를 해결하는 데 도움이 될 수 있는 디버그 Log를 활성화할 수 있습니다. Ingress Controller에서 발생하는 문제가 NGINX 코드의 버그로 인한 것일 가능성은 거의 없으며 오히려 NGINX 구성 오류로 인해 발생합니다. 따라서 이 방법은 거의 필요하지 않습니다.

디버그 모드를 활성화하려면 ConfigMap에서 error-log-level을 debug로 설정하고 Ingress Controller를 실행할 때 -nginx-debug Command-Line Argument를 사용합니다.