Risolvere i problemi del server dell'API Kubernetes
Mantieni tutto organizzato con le raccolte
Salva e classifica i contenuti in base alle tue preferenze.
Questa pagina mostra come risolvere i problemi relativi al server API Kubernetes
(kube-apiserver) per Google Distributed Cloud.
Questa pagina è dedicata agli amministratori IT e agli operatori che gestiscono il ciclo di vita dell'infrastruttura tecnologica sottostante e rispondono agli avvisi e alle pagine quando gli obiettivi del livello di servizio (SLO) non vengono raggiunti o le applicazioni non funzionano. Per scoprire
di più sui ruoli comuni e sulle attività di esempio a cui facciamo riferimento nei contenuti, consulta la pagina
Ruoli e attività comuni degli utenti GKE. Google Cloud
Timeout webhook e chiamate webhook non riuscite
Questi errori possono essere visualizzati in diversi modi. Se riscontri uno dei
seguenti sintomi, è possibile che le chiamate webhook non vadano a buon fine:
Connessione rifiutata:se kube-apiserver segnala errori di timeout per la chiamata del webhook, nei log viene segnalato il seguente errore:
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
Context deadline exceeded: nei log potrebbe essere segnalato anche il seguente errore:
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"
Se ritieni di riscontrare timeout webhook o chiamate webhook non riuscite,
utilizza uno dei seguenti metodi per confermare il problema:
Controlla il log del server API per verificare se si è verificato un problema di rete.
Controlla il log per errori correlati alla rete, ad esempio TLS handshake error.
Verifica che l'IP/la porta corrisponda a ciò a cui è configurato per rispondere il server API.
Monitora la latenza del webhook seguendo questi passaggi:
Se il webhook richiede più tempo per essere completato, puoi
configurare un valore di timeout personalizzato.
La latenza dei webhook si aggiunge alla latenza delle richieste API, pertanto deve essere valutata il più rapidamente possibile.
Se l'errore del webhook blocca la disponibilità del cluster o il webhook è innocuo
da rimuovere e mitiga la situazione, controlla se è possibile impostare temporaneamente
failurePolicy su Ignore o rimuovere il webhook problematico.
Errore di connessione o latenza del server API
Questo errore può essere visualizzato in diversi modi:
Errori di risoluzione dei nomi esterni: un client esterno potrebbe restituire errori
che contengono lookup nel messaggio, ad esempio:
dial tcp: lookup kubernetes.example.com on 127.0.0.1:53: no such host
Questo errore non si applica a un client in esecuzione all'interno del cluster. L'IP del servizio Kubernetes viene inserito, quindi non è necessaria alcuna risoluzione.
Errori di rete: il client potrebbe stampare un errore di rete generico durante il tentativo
di chiamare il server API, come nei seguenti esempi:
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
Latenza elevata durante la connessione al server API:la connessione al server API potrebbe
andare a buon fine, ma le richieste scadono lato client. In questo scenario,
il client di solito stampa messaggi di errore contenenti context deadline
exceeded.
Se la connessione al server API non va a buon fine, prova la connessione nello stesso ambiente in cui il client segnala l'errore.
I container effimeri Kubernetes possono essere utilizzati per inserire un container di debug negli spazi dei nomi esistenti come segue:
Da dove viene eseguito il client problematico, utilizza kubectl per eseguire una richiesta
con un livello di dettaglio elevato. Ad esempio, una richiesta GET a /healthz di solito
non richiede autenticazione:
kubectlget-v999--raw/healthz
Se la richiesta non va a buon fine o kubectl non è disponibile, puoi ottenere l'URL dall'output ed eseguire manualmente la richiesta con curl. Ad esempio, se l'host del servizio ottenuto dall'output precedente era https://192.0.2.1:36917/,
puoi inviare una richiesta simile nel seguente modo:
# 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
L'output di questo comando indica in genere la causa principale di un errore di connessione.
Se la connessione viene stabilita, ma è lenta o si verifica un timeout, significa che il server API è sovraccarico. Per confermare, nella console esamina le metriche di latenza di API
Server Request Rate e delle richieste in Cloud Kubernetes > Anthos >
Cluster > K8s Control Plane.
Per risolvere questi errori di connessione o problemi di latenza, esamina le seguenti
opzioni di correzione:
Se si verifica un errore di rete all'interno del cluster, potrebbe esserci un problema con il plug-in Container Network Interface (CNI). Questo problema è in genere temporaneo
e si risolve automaticamente dopo la ricreazione o la riprogrammazione di un pod.
Se l'errore di rete proviene dall'esterno del cluster, verifica che il client sia
configurato correttamente per accedere al cluster o genera di nuovo la
configurazione del client. Se la connessione passa attraverso un proxy o un gateway, controlla
se un'altra connessione che utilizza lo stesso meccanismo funziona.
Se il server API è sovraccarico, di solito significa che molti client accedono al server API contemporaneamente. Un singolo client non può sovraccaricare un server API a causa della limitazione e della funzionalità Priorità e correttezza. Esamina il carico di lavoro per le seguenti aree:
Funziona a livello di pod. È più comune creare e dimenticare per errore i pod
rispetto alle risorse di livello superiore.
Modifica il numero di repliche tramite un calcolo errato.
Un webhook che esegue il loop della richiesta o amplifica il carico
creando più richieste di quelle che gestisce.
[[["Facile da capire","easyToUnderstand","thumb-up"],["Il problema è stato risolto","solvedMyProblem","thumb-up"],["Altra","otherUp","thumb-up"]],[["Difficile da capire","hardToUnderstand","thumb-down"],["Informazioni o codice di esempio errati","incorrectInformationOrSampleCode","thumb-down"],["Mancano le informazioni o gli esempi di cui ho bisogno","missingTheInformationSamplesINeed","thumb-down"],["Problema di traduzione","translationIssue","thumb-down"],["Altra","otherDown","thumb-down"]],["Ultimo aggiornamento 2025-09-01 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).\nYou can also see\n[Getting support](/kubernetes-engine/distributed-cloud/bare-metal/docs/getting-support) for more information about support resources, including the following:\n\n- [Requirements](/kubernetes-engine/distributed-cloud/bare-metal/docs/getting-support#intro-support) for opening a support case.\n- [Tools](/kubernetes-engine/distributed-cloud/bare-metal/docs/getting-support#support-tools) to help you troubleshoot, such as your environment configuration, logs, and metrics.\n- Supported [components](/kubernetes-engine/distributed-cloud/bare-metal/docs/getting-support#what-we-support)."]]
