이 페이지에서는 Google Distributed Cloud용 Kubernetes API 서버(kube-apiserver) 관련 문제를 해결하는 방법을 설명합니다.
이 페이지는 기본 기술 인프라의 수명 주기를 관리하고 서비스 수준 목표(SLO)가 충족되지 않거나 애플리케이션이 실패할 때 알림 및 페이지에 응답하는 IT 관리자 및 운영자를 위해 작성되었습니다. Google Cloud콘텐츠에서 참조하는 일반적인 역할 및 예시 태스크에 대해 자세히 알아보려면 일반 GKE Enterprise 사용자 역할 및 태스크를 참조하세요.
웹훅 시간 제한 및 웹훅 호출 실패
이러한 오류는 몇 가지 다른 방법으로 확인할 수 있습니다. 다음과 같은 증상이 발생하면 웹훅 호출이 잘못되었을 수 있습니다.
연결이 거부됨:kube-apiserver가 웹훅 호출의 제한 시간 오류를 보고하는 경우 로그에 다음 오류가 보고됩니다.
failed calling webhook "server.system.private.gdc.goog":
failed to call webhook: Post "https://root-admin-webhook.gpc-system.svc:443/mutate-system-private-gdc-goog-v1alpha1-server?timeout=10s":
dial tcp 10.202.1.18:443: connect: connection refused
컨텍스트 기한 초과: 로그에 다음과 같은 오류가 보고될 수도 있습니다.
failed calling webhook "namespaces.hnc.x-k8s.io": failed to call webhook: Post
"https://hnc-webhook-service.hnc-system.svc:443/validate-v1-namespace?timeout=10s\":
context deadline exceeded"
웹훅 시간 초과 또는 웹훅 호출 실패가 발생한다고 생각되면 다음 방법 중 하나를 사용하여 문제를 확인합니다.
웹훅에 추가 완료 시간이 필요하면 커스텀 제한 시간 값을 구성할 수 있습니다.
웹훅 지연 시간은 API 요청 지연 시간에 추가되므로 가능한 한 빨리 평가해야 합니다.
웹훅 오류가 클러스터 가용성을 차단하거나 웹훅이 상황을 해소 및 완화할 수 있는 경우 일시적으로 failurePolicy를 Ignore로 설정하거나 문제가 있는 웹훅을 삭제할 수 있는지 확인합니다.
API 서버 dial 실패 또는 지연 시간
이 오류는 몇 가지 다른 방법으로 확인할 수 있습니다.
외부 이름 변환 오류: 다음과 같이 메시지에 lookup이 포함된 오류가 외부 클라이언트에서 반환될 수 있습니다.
dial tcp: lookup kubernetes.example.com on 127.0.0.1:53: no such host
이 오류는 클러스터 내에서 실행 중인 클라이언트에 적용되지 않습니다. Kubernetes 서비스 IP가 삽입되었으면 변환이 필요하지 않습니다.
네트워크 오류: 다음 예시와 같이 API 서버에 dial을 시도할 때 클라이언트에서 일반적인 네트워크 오류가 출력될 수 있습니다.
dial tcp 10.96.0.1:443: connect: no route to host
dial tcp 10.96.0.1:443: connect: connection refused
dial tcp 10.96.0.1:443: connect: i/o timeout
API 서버 연결 지연 시간이 김: API 서버에 대한 연결은 성공할 수 있지만 클라이언트 측에서는 요청 시간이 초과됩니다. 이 시나리오에서 클라이언트는 일반적으로 context deadline
exceeded가 포함된 오류 메시지를 출력합니다.
API 서버 연결이 완전히 실패하면 클라이언트가 오류를 보고하는 것과 동일한 환경 내에서 연결을 시도합니다.
다음과 같이 Kubernetes 임시 컨테이너를 사용해서 기존 네임스페이스에 디버깅 컨테이너를 삽입할 수 있습니다.
문제가 있는 클라이언트가 실행되는 위치에서 kubectl을 사용하여 세부정보 수준이 높은 요청을 수행합니다. 예를 들어 /healthz에 대한 GET 요청에는 일반적으로 인증이 필요하지 않습니다.
kubectlget-v999--raw/healthz
요청이 실패하거나 kubectl을 사용할 수 없으면 출력에서 URL을 가져오고 curl을 사용해서 요청을 수동으로 수행할 수 있습니다. 예를 들어 이전 출력에서 가져온 서비스 호스트가 https://192.0.2.1:36917/인 경우 다음과 같이 비슷한 요청을 전송할 수 있습니다.
# Replace "--ca-cert /path/to/ca.pem" to "--insecure" if you are accessing# a local cluster and you trust the connection cannot be tampered.# The output is always "ok" and thus contains no sensentive information.
curl-v--cacert/path/to/ca.pemhttps://192.0.2.1:36917/healthz
이 명령어의 출력은 일반적으로 실패한 연결의 근본 원인을 나타냅니다.
연결에 성공했지만 느리거나 시간이 초과되면 API 서버가 과부하되었음을 나타냅니다. 확인하려면 콘솔에서 API
Server Request Rate를 확인하고 Cloud Kubernetes > Anthos >
Cluster > K8s Control Plane에서 지연 시간 측정항목을 요청합니다.
이러한 연결 실패 또는 지연 시간 문제를 확인하려면 다음 해결 옵션을 검토합니다.
클러스터 내에서 네트워크 오류가 발생하면 컨테이너 네트워크 인터페이스(CNI) 플러그인에 문제가 있을 수 있습니다. 이 문제는 일반적으로 일시적이며 포드 재생성 또는 일정 변경 후 자동으로 해결됩니다.
네트워크 오류가 클러스터 외부에서 비롯된 경우 클라이언트가 클러스터에 액세스하도록 올바르게 구성되었는지 확인하거나 클라이언트 구성을 다시 생성합니다. 연결이 프록시 또는 게이트웨이를 통과하는 경우 동일한 메커니즘을 통과하는 다른 연결이 작동하는지 확인합니다.
API 서버가 과부하되었으면 일반적으로 많은 클라이언트가 동시에 API 서버에 액세스하고 있음을 나타냅니다. 단일 클라이언트는 제한과 우선순위 및 공정성 기능으로 인해 API 서버에 과부하를 일으키지 않습니다. 다음 영역의 워크로드를 검토합니다.
포드 수준에서 작동합니다. 상위 수준의 리소스보다 실수로 포드를 만들고 잊는 경우가 더 많습니다.
잘못된 계산을 통한 복제본 수를 조정합니다.
요청을 자체적으로 루프백하거나 처리하는 것보다 더 많은 요청을 생성하여 부하를 증폭시키는 웹훅입니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-06-27(UTC)"],[],[],null,["This page shows you how to resolve issues with the Kubernetes API server\n(`kube-apiserver`) for Google Distributed Cloud.\n\nThis page is for IT administrators and Operators who manage the\nlifecycle of the underlying tech infrastructure, and respond to alerts and pages\nwhen service level objectives (SLOs) aren't met or applications fail. To learn\nmore about common roles and example tasks that we reference in Google Cloud\ncontent, see\n[Common GKE user roles and tasks](/kubernetes-engine/enterprise/docs/concepts/roles-tasks).\n\nWebhook timeouts and failed webhook calls\n\nThese errors might be seen in a few different ways. If you experience any of the\nfollowing symptoms, it's possible that webhook calls are failing:\n\n- **Connection refused:** If `kube-apiserver` reports timeout errors for\n calling the webhook, the following error is reported in the logs:\n\n failed calling webhook \"server.system.private.gdc.goog\":\n failed to call webhook: Post \"https://root-admin-webhook.gpc-system.svc:443/mutate-system-private-gdc-goog-v1alpha1-server?timeout=10s\":\n dial tcp 10.202.1.18:443: connect: connection refused\n\n- **Context deadline exceeded:** You might also see the following error reported\n in the logs:\n\n failed calling webhook \"namespaces.hnc.x-k8s.io\": failed to call webhook: Post\n \"https://hnc-webhook-service.hnc-system.svc:443/validate-v1-namespace?timeout=10s\\\":\n context deadline exceeded\"\n\nIf you think that you are experiencing webhook timeouts or failed webhook calls,\nuse one of the following methods to confirm the issue:\n\n- Check the API server log to see if there is network issue.\n\n - Check the log for network-related errors like `TLS handshake error`.\n - Check if the IP/Port matches what the API server is configured to respond on.\n- Monitor webhook latency with the following steps:\n\n 1. In the console, go to the Cloud Monitoring page.\n\n [Go to the Cloud Monitoring page](https://console.cloud.google.com/monitoring/)\n 2. Select **Metrics explorer**.\n\n 3. Select the `apiserver_admission_webhook_admission_duration_seconds` metric.\n\nTo resolve this issue, review the following suggestions:\n\n- Additional firewall rules might be required for the webhook. For more\n information, see how to\n [add firewall rules for specific use cases](/kubernetes-engine/docs/how-to/private-clusters#add_firewall_rules).\n\n- If the webhook requires more time to complete, you can\n [configure a custom timeout value](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#timeouts).\n The webhooks latency adds to API request latency, so should be evaluated as\n quickly as possible.\n\n- If the webhook error blocks cluster availability or the webhook is harmless\n to remove and mitigates the situation, check if it's possible to temporarily\n set the `failurePolicy` to `Ignore` or remove the offending webhook.\n\nAPI server dial failure or latency\n\nThis error might be seen in a few different ways:\n\n- **External name resolution errors:** An external client might return errors\n that contain `lookup` in the message, such as:\n\n dial tcp: lookup kubernetes.example.com on 127.0.0.1:53: no such host\n\n This error doesn't apply to a client running within the cluster. The\n Kubernetes Service IP is injected, so no resolution is required.\n- **Network errors:** The client might print a generic network error when trying\n to dial the API server, like the following examples:\n\n dial tcp 10.96.0.1:443: connect: no route to host\n dial tcp 10.96.0.1:443: connect: connection refused\n dial tcp 10.96.0.1:443: connect: i/o timeout\n\n- **High latency connecting to API server:** The connection to API server might\n be successful, but the requests timeout on the client side. In this scenario,\n the client usually prints error messages containing `context deadline\n exceeded`.\n\nIf the connection to the API server fails completely, try the connection within\nthe same environment where the client reports the error.\n[Kubernetes ephemeral containers](https://kubernetes.io/docs/concepts/workloads/pods/ephemeral-containers/)\ncan be used to inject a debugging container to the existing namespaces as\nfollows:\n\n1. From where the problematic client runs, use `kubectl` to perform a request\n with high verbosity. For example, a `GET` request to `/healthz` usually\n requires no authentication:\n\n kubectl get -v999 --raw /healthz\n\n2. If the request fails or `kubectl` is unavailable, you can obtain the URL from\n the output and manually perform the request with `curl`. For example, if the\n service host obtained from the previous output was `https://192.0.2.1:36917/`,\n you can send a similar request as follows:\n\n # Replace \"--ca-cert /path/to/ca.pem\" to \"--insecure\" if you are accessing\n # a local cluster and you trust the connection cannot be tampered.\n # The output is always \"ok\" and thus contains no sensentive information.\n\n curl -v --cacert /path/to/ca.pem https://192.0.2.1:36917/healthz\n\n The output from this command usually indicates the root cause of a failed\n connection.\n | **Note:** You can't use the `ping` or `traceroute` commands to the IP address. A Kubernetes Service IP doesn't accept ICMP or protocols outside the list defined in the Service resource.\n\n If the connection is successful but is slow or times out, it indicates an\n overloaded API server. To confirm, in the console look at `API\n Server Request Rate` and request latency metrics in `Cloud Kubernetes \u003e Anthos \u003e\n Cluster \u003e K8s Control Plane`.\n\nTo resolve these connection failures or latency problems, review the following\nremediation options:\n\n- If a network error occurs within the cluster, there might be problem with the\n Container Network Interface (CNI) plugin. This problem is usually transient\n and resolves itself after a Pod recreation or reschedule.\n\n- If the network error is from outside the cluster, check if the client is\n properly configured to access the cluster, or generate the client\n configuration again. If the connection goes through a proxy or gateway, check\n if another connection that goes through the same mechanism works.\n\n- If the API server is overloaded, it usually means that many clients access the\n API server at the same time. A single client can't overload an API server due\n to throttling and the\n [Priority and Fairness](https://kubernetes.io/docs/concepts/cluster-administration/flow-control/)\n feature. Review the workload for the following areas:\n\n - Works at Pod level. It's more common to mistakenly create and forget Pods than higher level resources.\n - Adjust the number of replicas through erroneous calculation.\n - A webhook that loops back the request to itself or amplifies the load by creating more requests than it handles.\n\nWhat's next\n\nIf you need additional assistance, reach out to\n\n[Cloud Customer Care](/support-hub).\n\nYou can also see\n[Getting support](/kubernetes-engine/distributed-cloud/vmware/docs/getting-support) for more information about support resources, including the following:\n\n- [Requirements](/kubernetes-engine/distributed-cloud/vmware/docs/getting-support#support_requirements) for opening a support case.\n- [Tools](/kubernetes-engine/distributed-cloud/vmware/docs/getting-support#support_tools) to help you troubleshoot, such as logs and metrics.\n- Supported [components](/kubernetes-engine/distributed-cloud/vmware/docs/getting-support#whats_supported), [versions](/kubernetes-engine/distributed-cloud/vmware/docs/getting-support#version_support_policy), and [features](/kubernetes-engine/distributed-cloud/vmware/docs/getting-support#supported_features) of Google Distributed Cloud for VMware (software only)."]]
