웹훅 오류로 인해 클러스터 마스터 작업이 실패하는 이유는 무엇인가요?

가상 프라이빗 클라우드 클래식 인프라

이 문제점 해결 주제는 일반 웹훅 문제점 해결을 위한 것이 아닙니다. 클러스터 마스터 업데이트와 관련되지 않은 웹훅 문제점은 웹훅 디버깅 을 참조하십시오.

클러스터 마스터 운영에 지장을 주는 웹훅 오류 문제를 해결합니다.

클러스터 버전을 업데이트하는 것과 같은 마스터 오퍼레이션 중에 클러스터에서 웹훅 애플리케이션이 중단되었습니다.

지금 마스터 오퍼레이션을 완료할 수 없습니다. 다음과 유사한 오류가 표시됩니다.

Cannot complete cluster master operations because the cluster has a broken webhook application. For more information, see the troubleshooting docs: 'https://ibm.biz/master_webhook'

클러스터에 구성 가능한 Kubernetes 웹훅 리소스가 있으며, 승인 웹훅을 유효성 검증하거나 변형하여 클러스터의 다양한 서비스에서 클러스터 마스터의 API 서버로의 요청을 인터셉트하고 수정할 수 있습니다.

웹훅이 요청을 변경하거나 거부할 수 있으므로, 실행이 중단된 웹훅은 마스터 버전 업데이트 또는 기타 유지보수 오퍼레이션을 방해하는 등과 같은 다양한 방식으로 클러스터의 기능에 영향을 줄 수 있습니다. 자세한 내용은 ‘ Kubernetes ’ 문서의 ‘동적 접속 제어(Dynamic Admission Control )’ 항목을 참조하십시오.

실행이 중단된 웹훅이 발생하는 잠재적 원인에는 다음 항목이 포함됩니다.

• 요청이 누락되었거나 비정상임을 알리는 기반 리소스(Kubernetes 서비스, 엔드포인트 또는 팟(Pod))가 있습니다.
• 해당 웹훅이 올바르게 설치되지 않았거나 비정상 상태인 추가 기능 또는 기타 플러그인의 일부입니다.
• 클러스터에 웹훅이 클러스터 마스터의 Kubernetes API 서버와 통신하지 못하도록 하는 네트워킹 연결 문제가 있을 수 있습니다.

다음 명령을 실행하여 테스트 포드를 생성하여 손상된 웹훅을 식별하는 오류를 얻습니다. 테스트가 통과된다면, 이전의 실패는 일시적인 것이었을 수 있으므로 다시 시도해 볼 수 있습니다.

1. 다음 명령을 실행하여 테스트 파드를 생성하고 ibm-system 네임스페이스에 레이블을 지정합니다.

   oc run webhook-test --image us.icr.io/armada-master/pause:3.10 -n ibm-system
   oc delete pod -n ibm-system webhook-test --ignore-not-found
   oc label ns ibm-system ibm-cloud.kubernetes.io/webhook-test-at="$(date -u +%FT%H_%M_%SZ)" --overwrite
   

   해당 오류 메시지에 실행이 중단된 웹훅의 이름이 있을 수 있습니다. 다음 예시 출력에서 웹훅은 trust.hooks.securityenforcement.admission.cloud.ibm.com 입니다.

   Error from server (InternalError): Internal error occurred: failed calling webhook "trust.hooks.securityenforcementadmission.cloud.ibm.com": Post https://ibmcloud-image-enforcement.ibm-system.svc:443/mutating-pods?timeout=30s: dialtcp 172.21.xxx.xxx:443: connect: connection timed out
   

2. 실행이 중단된 웹훅의 이름을 가져오십시오.

   • 오류 메시지에 실행이 중단된 웹훅의 이름이 있는 경우에는 trust.hooks.securityenforcement.admission.cloud.ibm.com을 이전에 식별한, 실행이 중단된 웹훅으로 대체하십시오.

       oc get mutatingwebhookconfigurations,validatingwebhookconfigurations -o jsonpath='{.items[?(@.webhooks[*].name=="trust.hooks.securityenforcement.admission.cloud.ibm.com")].metadata.name}{"\n"}'
       ```
       출력 예
       ```sh {: pre}
       image-admission-config
       ```
   *   오류 메시지에 실행이 중단된 웹훅이 없는 경우에는 클러스터에 있는 모든 웹훅을 나열하고 다음 단계에 따라 이들의 구성을 확인하십시오.
   ```sh {: pre}
       oc get mutatingwebhookconfigurations,validatingwebhookconfigurations
       ```
   

3. 다음 명령의 출력에서 clientConfig 섹션에 있는 변경 또는 유효성 검증 웹훅 구성의 서비스 및 위치 세부사항을 검토하십시오. image-admission-config를 이전에 식별한 이름으로 대체하십시오. 해당 웹훅이 클러스터 외부에 있는 경우에는 클러스터 소유자에게 웹훅 상태를 확인하도록 요청하십시오.

   oc get mutatingwebhookconfiguration image-admission-config -o yaml
   

   oc get validatingwebhookconfigurations image-admission-config -o yaml
   

   출력 예

     clientConfig:
       caBundle: <redacted>
       service:
           name: <name>
           namespace: <namespace>
           path: /inject
           port: 443
   

4. 선택: 특히 웹훅을 다시 설치하는 방법을 모르거나 웹훅을 만드는 데 필요한 권한이 없는 경우 웹훅을 백업합니다.

   oc get mutatingwebhookconfiguration <name> -o yaml > mutatingwebhook-backup.yaml
   

   oc get validatingwebhookconfiguration <name> -o yaml > validatingwebhook-backup.yaml
   

5. 웹훅 관련 서비스 및 팟(Pod)의 상태를 확인하십시오.

   1. 서비스 유형, 선택기 및 엔드포인트 필드를 확인하십시오.

       oc describe service -n <namespace> <service_name>
       ```
   2. 서비스 유형이 **ClusterIP인** 경우, 웹훅이 클러스터 마스터의 Kubernetes API에 안전하게 연결될 수 있도록 Konnectivity 포드가 ‘실행 중( **Running** )’ 상태인지 확인하십시오. 이 팟(Pod)이 비정상 상태인 경우에는 팟(Pod) 이벤트, 작업자 노드 상태 및 기타 컴포넌트에 문제점이 없는지 확인하십시오.
   
       * Konnectivity 에이전트 팟 (Pod) 을 확인하십시오.
           ```sh {: pre}
           oc describe pods -n kube-system -l app=konnectivity-agent
           ```
   
   1. 서비스에 엔드포인트가 없는 경우에는 기반 리소스(예: 배치 또는 팟(Pod))의 상태를 확인하십시오. 이러한 리소스가 비정상 상태인 경우에는 팟(Pod) 이벤트, 작업자 노드 상태 및 기타 컴포넌트에 문제점이 없는지 확인하십시오. 자세한 정보는 [앱 배치 디버깅](/docs/openshift?topic=openshift-debug_apps)을 참조하십시오.
   ```sh {: pre}
       oc get all -n my-service-namespace -l <key=value>
       ```
   1. 서비스에 백엔드 리소스가 없거나, 파드 문제 해결을 통해 문제가 해결되지 않는 경우, 앞서 확인한 변형(mutating) 또는 유효성 검사(validating) 웹훅 구성을 제거하십시오.
   ```sh {: pre}
       oc delete validatingwebhookconfiguration NAME
       ```
       ```sh {: pre}
       oc delete mutatingwebhookconfiguration NAME
       ```
   

6. 클러스터 업데이트와 같은 클러스터 마스터 오퍼레이션을 재시도하십시오.

7. 여전히 해당 오류가 발생하는 경우에는 작업자 노드 또는 네트워크 연결 문제가 있을 수 있습니다.

   • 작업자 노드의 문제점을 해결하십시오.
   • 웹훅이 클러스터 마스터에 있는 Kubernetes API 서버에 연결할 수 있도록 하십시오. 예를 들어 Calico 네트워크 정책, 보안 그룹 또는 특정 유형의 방화벽을 사용하고 있는 경우에는 클래식 또는 VPC 클러스터에 적절한 액세스를 설정하십시오.
   • 자신이 설치한 추가 기능에서 웹훅을 관리하는 경우에는 해당 추가 기능을 설치 제거하십시오. 일반적으로 웹훅 문제를 일으키는 추가 기능에는 다음 항목이 포함됩니다.
     • Portieris

8. 웹훅을 다시 작성하거나 추가 기능을 다시 설치하십시오.

9. 문제가 계속되면 지원에 문의하십시오. 지원 케이스 열기 케이스 세부 정보에 관련 로그 파일, 오류 메시지 또는 명령 출력을 모두 포함해야 합니다.