Kubernetes: Internal error occurred: failed calling webhook

안녕하세요, BlueByte입니다. 어제까지 잘 되던 kubectl apply가 1초도 안 되어 Internal error occurred: failed calling webhook으로 실패하는데, 매니페스트는 그대로입니다. 사실 객체는 검사조차 받지 못했습니다. 그 쓰기 앞에 admission webhook이 서 있고, API server가 거기서 응답을 받아내지 못했으며, 기본 실패 정책이 그 침묵을 거부로 바꾼 것입니다. 오늘은 이 메시지의 구조, 내가 설치하지도 않은 webhook이 쓰기를 막는 이유, 네트워크 차단과 인증서 불일치를 구분하는 법, 원인별 해결, 그리고 다시는 잠기지 않도록 webhook 범위를 좁히는 법까지 하나씩 짚어보겠습니다.

API server가 실제로 보고하는 내용

webhook이 매칭하는 모든 verb에서 서버 측 오류로 돌아옵니다:

Error from server (InternalError): error when creating "ingress.yaml": Internal error occurred: failed calling webhook "validate.example.com": failed to call webhook: Post "https://webhook-service.webhook-system.svc:443/validate?timeout=10s": context deadline exceeded

정보를 담고 있는 조각은 셋입니다. 따옴표 안의 webhook 이름은 ValidatingWebhookConfiguration 또는 MutatingWebhookConfiguration 안의 항목 하나를 가리킵니다. URL은 clientConfig.service에서 조립되며 — namespace·name·port — 문서상 기본값은 port 443, path /입니다. 마지막 콜론 뒤 꼬리가 진단이고, 몇 가지 정해진 모양으로 옵니다:

• context deadline exceeded — 호출은 나갔는데 제한 시간 안에 응답이 오지 않음.
• connect: connection refused — 그 주소까지는 닿았고 해당 포트에서 아무도 듣고 있지 않음.
• no endpoints available for service "webhook-service" — Service는 있는데 ready 상태의 백엔드가 없음.
• x509: certificate signed by unknown authority — webhook이 내민 인증서를 API server가 신뢰하지 않음.
• x509: certificate is valid for ..., not webhook-service.webhook-system.svc — 신뢰는 하는데 이름이 틀림.

이 꼬리부터 읽으십시오. 아래 내용은 전부 여기서 갈라집니다.

응답하지 못한 webhook이 쓰기를 거부로 돌리는 이유

webhook 항목마다 failurePolicy가 붙어 있고, Kubernetes 레퍼런스는 기본값이 Fail이라고 명시합니다. webhook 호출 오류는 admission 실패가 되고 요청은 거부됩니다. 다른 값인 Ignore는 요청을 통과시킵니다. 이 정책은 네트워크 오류, 타임아웃, non-2xx 응답, 형식이 깨진 응답, 직렬화 실패를 모두 포함합니다 — 쓸 만한 답을 받지 못하는 모든 경우입니다.

시계는 timeoutSeconds이고, 문서상 허용 범위는 1~30초, 기본값은 10초입니다. 이 시간이 지나면 같은 실패 정책에 따라 호출이 무시되거나 요청이 거부됩니다.

한 가지 구분을 먼저 잡아두면 헛수고를 크게 줄입니다. webhook이 정상 동작하면서 "안 된다"고 답한 경우는 완전히 다른 사건입니다. 레퍼런스는 올바르게 전달된 명시적 거부는 failurePolicy 설정과 무관하게 항상 API 요청을 거부한다고 적고 있습니다. 그 메시지는 failed calling webhook이 아니라 admission webhook "..." denied the request로 나옵니다.

API server가 webhook에 닿지 못하게 만드는 네 가지

• ready 백엔드 없음. webhook Deployment가 0으로 스케일됐거나, evict됐거나, 크래시 루프 중입니다. Service 이름은 풀리는데 엔드포인트 목록이 비어 있습니다.
• 막힌 네트워크 경로. 관리형 클러스터에서는 control plane이 내 VPC 바깥에 있고 좁은 구멍으로만 노드에 닿습니다. Google의 GKE 문서는 기본적으로 방화벽이 포트 443(HTTPS)과 10250(kubelet)을 제외하면 노드로의 TCP 연결을 허용하지 않으며, 다른 포트의 Pod로 통신하려는 admission webhook은 커스텀 방화벽 규칙이 없으면 실패한다고 기술합니다.
• 깨진 TLS 신뢰. caBundle은 API server가 검증에 쓰는 PEM 인코딩(필드 값은 base64) CA이고, 서빙 인증서는 <svc_name>.<svc_namespace>.svc에 대해 유효해야 합니다. 인증서를 재발급했거나, 만료됐거나, Secret을 다시 만들었다면 이 짝이 깨집니다.
• 살아 있지만 느린 webhook. 외부 API나 DB를 호출하는 핸들러는 부하가 걸리면 timeoutSeconds를 넘길 수 있습니다. 정작 자기 로그에는 아무 문제도 남지 않습니다.

스스로 자초하는 다섯 번째 경우도 이름을 붙여둘 값어치가 있습니다. 자기가 떠 있는 namespace를 검사하는 webhook은 한번 죽으면 되살릴 수 없습니다. 자기 Pod 생성을 자기가 막기 때문입니다.

꼬리가 가리키는 세 곳을 확인하기

먼저 admission 경로에 무엇이 들어 있는지, 정책과 타임아웃까지 함께 봅니다:

kubectl get validatingwebhookconfigurations -o custom-columns=NAME:.metadata.name,HOOKS:.webhooks[*].name,POLICY:.webhooks[*].failurePolicy,TIMEOUT:.webhooks[*].timeoutSeconds

NAME                HOOKS                  POLICY   TIMEOUT
example-admission   validate.example.com   Fail     10

그다음 URL에 적힌 Service 뒤에 무언가 붙어 있는지 확인합니다:

kubectl -n webhook-system get endpoints webhook-service
kubectl -n webhook-system get pods -l app=webhook-server

NAME              ENDPOINTS         AGE
webhook-service   10.20.1.23:8443   41d

ENDPOINTS 열이 <none>이면 조사는 여기서 끝입니다 — 워크로드를 살리면 됩니다. 엔드포인트가 있다면 클러스터 안에서 같은 URL을 두드려 봅니다:

kubectl -n webhook-system run probe --rm -i --restart=Never --image=curlimages/curl:8.11.1 -- curl -sk -o /dev/null -w '%{http_code}\n' https://webhook-service.webhook-system.svc:443/

이 결과는 읽는 법이 중요합니다. Pod는 클러스터 네트워크 안에 있고, 관리형 control plane의 API server는 그렇지 않습니다. Pod에서는 상태 코드가 돌아오는데 API server는 여전히 타임아웃이라면, 그것은 아픈 webhook이 아니라 방화벽 규칙의 흔적입니다. TLS 쪽이 의심되면 신뢰 짝의 양쪽을 맞대어 봅니다:

kubectl get validatingwebhookconfiguration example-admission -o jsonpath='{.webhooks[0].clientConfig.caBundle}' | base64 -d | openssl x509 -noout -subject -dates
kubectl -n webhook-system get secret webhook-server-cert -o go-template='{{index .data "tls.crt"}}' | base64 -d | openssl x509 -noout -ext subjectAltName -dates

서빙 인증서의 발급자가 caBundle에 든 CA여야 하고, subjectAltName에 webhook-service.webhook-system.svc가 들어 있어야 합니다. 이 명령을 한 번도 써본 적 없어도 겁먹지 않아도 됩니다. 읽기만 하는 명령이라, 멀쩡한 클러스터에서 먼저 돌려보면서 정상적인 짝이 어떤 모습인지 눈에 익혀도 됩니다.

원인별로, 값싼 수부터

엔드포인트가 비었을 때: 워크로드를 되살리고 다음 재시도를 통과시킵니다.

kubectl -n webhook-system rollout restart deploy/webhook-server
kubectl -n webhook-system rollout status deploy/webhook-server --timeout=120s

프라이빗 클러스터에서 포트가 막혔을 때: webhook Pod이 실제로 듣고 있는 포트를 control plane 대역에 열어 줍니다. Google 문서는 gcloud container clusters describe에서 masterIpv4CidrBlock을, 기존 gke- 규칙에서 노드 target tag를 먼저 모으라고 안내한 뒤 다음을 제시합니다:

gcloud compute firewall-rules create allow-webhook-8443 \
  --action ALLOW \
  --direction INGRESS \
  --source-ranges CONTROL_PLANE_RANGE \
  --rules tcp:8443 \
  --target-tags TARGET

인증서 불일치일 때: caBundle에 든 CA로 서빙 인증서를 재발급하거나, webhook 설치 도구가 관리하는 CA를 다시 주입합니다. cert-manager가 맡고 있다면 설정 객체의 cert-manager.io/inject-ca-from 애너테이션이 그 필드를 다시 채웁니다 — 손으로 패치하기 전에 그 애너테이션이 아직 붙어 있는지부터 보십시오.

핸들러가 느릴 때: 문서상 상한까지 타임아웃을 올리되, 이것은 지연을 고친 게 아니라 시간을 산 것으로 취급하십시오.

kubectl patch validatingwebhookconfiguration example-admission --type=json -p='[{"op":"replace","path":"/webhooks/0/timeoutSeconds","value":20}]'

배포를 앞두고 잠겨버렸을 때: 문제가 된 항목 하나만 failurePolicy: Ignore로 바꾸면 쓰기는 즉시 풀리고, 되돌릴 때까지 검사받지 않은 객체가 통과합니다. 설정 객체 자체를 지워도 결과는 같지만 훨씬 거칩니다. 게다가 Helm 릴리스나 operator가 다음 reconcile에서 대개 다시 만들어 놓습니다.

실제 사례: 프라이빗 클러스터와 8443 포트의 webhook

한 팀이 프라이빗 GKE 클러스터에 정책 컨트롤러를 추가합니다. 설치는 깔끔하고 Pod은 Running이며 로그도 조용합니다. 그런데 매칭되는 리소스에 kubectl apply를 할 때마다 딱 10초쯤 뒤 context deadline exceeded로 끝나는 failed calling webhook이 납니다. 엔드포인트는 10.20.1.23:8443이고, Pod에서 쏜 curl 프로브는 200을 돌려줘 워크로드 문제는 제외됩니다. 10초라는 벽은 문서상 기본 타임아웃과 맞아떨어지고, 포트는 8443 — control plane이 열 수 있는 두 포트 중 어느 것도 아닙니다. 팀은 control plane CIDR에서 노드 태그로 tcp:8443을 허용하는 위 방화벽 규칙을 추가합니다. 다음 apply는 매니페스트를 한 글자도 고치지 않은 채 ingress.networking.k8s.io/site created를 돌려줍니다.

자리를 뜨기 전에 admission이 다시 도는지 확인하기

실패했던 쓰기를 다시 실행하고, 이어서 거부당할 것으로 예상되는 객체로 webhook을 일부러 건드려 봅니다:

kubectl apply -f ingress.yaml
kubectl apply -f deliberately-invalid.yaml

첫 번째는 성공, 두 번째는 admission webhook "validate.example.com" denied the request — 이게 원하는 결과입니다. 두 번째까지 성공한다면 webhook이 건너뛰어지고 있다는 뜻이고, 그것은 고쳐진 것과 다릅니다.

다시는 잠기지 않도록 범위 좁히기

Kubernetes good practices 문서는 시스템 namespace와 webhook 자신의 namespace를 제외해 스스로의 복구를 막지 않도록 하라고 권합니다:

namespaceSelector:
  matchExpressions:
  - key: kubernetes.io/metadata.name
    operator: NotIn
    values:
    - kube-system
    - webhook-system

같은 문서는 짧은 타임아웃, 좁은 rules, objectSelector·namespaceSelector 필터링으로 호출 횟수를 줄일 것, 그리고 Service 뒤에 레플리카를 둘 이상 둘 것을 함께 권합니다. 인증서 만료도 함께 지켜보십시오 — 1년 동안 아무 말 없던 webhook이 인증서가 갱신되는 날 무너집니다.

kubectl의 x509 오류·거부 응답과 다른 점

kubectl: x509: certificate signed by unknown authority는 같은 연결의 반대 방향을 가리킵니다. 그쪽은 내 클라이언트가 API server 인증서를 신뢰하지 않는 것이고, 고칠 곳은 kubeconfig입니다. 여기서는 API server가 클라이언트이고 webhook이 서버이므로, 고칠 곳은 클러스터 안의 caBundle과 서빙 인증서입니다. 내 kubeconfig는 멀쩡하며, 그래서 쓰기만 실패하는 동안에도 kubectl get은 계속 잘 됩니다.

두 번째 닮은꼴은 admission webhook "..." denied the request입니다. 이건 webhook이 제 일을 한 것입니다. 객체를 받아 규칙을 적용하고 거절했습니다. failurePolicy는 여기 관여하지 않고, 고칠 곳은 클러스터가 아니라 매니페스트입니다.

다음에 webhook에서 쓰기가 죽으면 이 순서를 거꾸로 따라가 보세요. 메시지 꼬리를 읽고, 엔드포인트를 확인하고, Pod에서 Service를 두드려 보고, 그다음 CA와 서빙 인증서를 맞대어 보면 됩니다.