Solucionar problemas de la herramienta de línea de comandos kubectl

En esta página se explica cómo resolver problemas con la herramienta de línea de comandos kubectl cuando trabajas en Google Kubernetes Engine (GKE).

Para obtener más información, consulta los siguientes recursos:

Errores de autenticación y autorización

Si tienes problemas relacionados con la autenticación y la autorización al usar los comandos de la herramienta de línea de comandos kubectl, consulta las siguientes secciones para obtener ayuda.

Error: 401 (Unauthorized)

Al conectarte a clústeres de GKE, puedes recibir un error de autenticación y autorización con el código de estado HTTP 401 (Unauthorized). Este problema puede producirse cuando intentas ejecutar un comando kubectl en tu clúster de GKE desde un entorno local. Para obtener más información, consulta el artículo Problema: errores de autenticación y autorización.

Error: ámbitos de autenticación insuficientes

Cuando ejecutas gcloud container clusters get-credentials, puede que recibas el siguiente error:

ERROR: (gcloud.container.clusters.get-credentials) ResponseError: code=403, message=Request had insufficient authentication scopes.

Este error se produce porque intentas acceder a la API de GKE desde una VM de Compute Engine que no tiene el ámbito cloud-platform.

Para resolver este error, concede el ámbito cloud-platform que falta. Para obtener instrucciones sobre cómo cambiar los ámbitos de tu instancia de VM de Compute Engine, consulta el artículo Crear y habilitar cuentas de servicio para instancias de la documentación de Compute Engine.

Error: No se ha encontrado el ejecutable gke-gcloud-auth-plugin

Al intentar ejecutar comandos de kubectl o clientes personalizados que interactúan con GKE, pueden producirse mensajes de error similares a los siguientes:

Unable to connect to the server: getting credentials: exec: executable gke-gcloud-auth-plugin not found

It looks like you are trying to use a client-go credential plugin that is not installed.

To learn more about this feature, consult the documentation available at:
      https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins

Visit cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#install_plugin to install gke-gcloud-auth-plugin.

Unable to connect to the server: getting credentials: exec: fork/exec /usr/lib/google-cloud-sdk/bin/gke-gcloud-auth-plugin: no such file or directory

Para solucionar el problema, instala gke-gcloud-auth-plugin tal como se describe en Instalar los complementos necesarios.

Error: No se ha encontrado ningún proveedor de autenticación

Se produce el siguiente error si se han creado clientes de Kubernetes kubectl o personalizados con la versión client-go 1.26 o posterior de Kubernetes:

no Auth Provider found for name "gcp"

Para solucionar este problema, siga estos pasos:

  1. Instala gke-gcloud-auth-plugin como se describe en Instalar los complementos necesarios.

  2. Actualiza a la versión más reciente de la CLI de gcloud:

    gcloud components update

  3. Actualiza el archivo de kubeconfig:

    gcloud container clusters get-credentials CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION

    Haz los cambios siguientes:

    • CLUSTER_NAME: el nombre de tu clúster.
    • CONTROL_PLANE_LOCATION: la ubicación de Compute Engine del plano de control de tu clúster. Proporciona una región para los clústeres regionales o una zona para los clústeres zonales.

Error: El complemento de autenticación de GCP está obsoleto. Usa gcloud en su lugar.

Es posible que veas el siguiente mensaje de advertencia después de instalar gke-gcloud-auth-plugin y ejecutar un comando kubectl en un clúster de GKE:

WARNING: the gcp auth plugin is deprecated in v1.22+, unavailable in v1.25+; use gcloud instead.

Este mensaje aparece si la versión de tu cliente es anterior a la 1.26.

Para resolver este problema, pida a su cliente que utilice el complemento de autenticación gke-gcloud-auth-plugin:

  1. Abre el archivo de inicio de sesión de shell en un editor de texto:

    Bash

    vi ~/.bashrc

    Zsh

    vi ~/.zshrc

    Si usas PowerShell, puedes saltarte este paso.

  2. Define la siguiente variable de entorno:

    Bash

    export USE_GKE_GCLOUD_AUTH_PLUGIN=True

    Zsh

    export USE_GKE_GCLOUD_AUTH_PLUGIN=True

    PowerShell

    [Environment]::SetEnvironmentVariable('USE_GKE_GCLOUD_AUTH_PLUGIN', True, 'Machine')

  3. Aplica la variable en tu entorno:

    Bash

    source ~/.bashrc

    Zsh

    source ~/.zshrc

    PowerShell

    Sal del terminal y abre una nueva sesión de terminal.

  4. Actualiza gcloud CLI:

    gcloud components update

  5. Autentícate en tu clúster:

    gcloud container clusters get-credentials CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION

    Haz los cambios siguientes:

    • CLUSTER_NAME: el nombre de tu clúster.
    • CONTROL_PLANE_LOCATION: la ubicación de Compute Engine del plano de control de tu clúster. Proporciona una región para los clústeres regionales o una zona para los clústeres zonales.

Problema: no se encuentra el comando kubectl

Si recibes un mensaje que indica que no se ha encontrado el comando kubectl, vuelve a instalar el archivo binario kubectl y define la variable de entorno $PATH:

  1. Instala el archivo binario kubectl:

    gcloud components update kubectl

  2. Cuando el instalador te pida que modifiques la variable de entorno $PATH, introduce y para continuar. Si modificas esta variable, podrás usar los comandos de kubectl sin tener que escribir su ruta completa.

    También puedes añadir la siguiente línea a la ubicación donde tu shell almacena las variables de entorno, como ~/.bashrc (o ~/.bash_profile en macOS):

    export PATH=$PATH:/usr/local/share/google/google-cloud-sdk/bin/

  3. Ejecuta el siguiente comando para cargar el archivo actualizado. En el siguiente ejemplo se usa .bashrc:

    source ~/.bashrc

    Si usas macOS, utiliza ~/.bash_profile en lugar de .bashrc.

Problema: los comandos de kubectl devuelven el error "connection refused"

Si los comandos de kubectl devuelven un error de conexión rechazada, debes definir el contexto del clúster con el siguiente comando:

gcloud container clusters get-credentials CLUSTER_NAME \
       --location=CONTROL_PLANE_LOCATION

Haz los cambios siguientes:

  • CLUSTER_NAME: el nombre de tu clúster.
  • CONTROL_PLANE_LOCATION: la ubicación de Compute Engine del plano de control de tu clúster. Proporciona una región para los clústeres regionales o una zona para los clústeres zonales.

Si no sabes qué introducir en el nombre o la ubicación del clúster, usa el siguiente comando para ver una lista de tus clústeres:

gcloud container clusters list

Error: se ha superado el tiempo de espera del comando kubectl

Si has creado un clúster y has intentado ejecutar un comando kubectl en él, pero el comando kubectl ha agotado el tiempo de espera, verás un error similar al siguiente:

  • Unable to connect to the server: dial tcp IP_ADDRESS: connect: connection timed out
  • Unable to connect to the server: dial tcp IP_ADDRESS: i/o timeout.

Estos errores indican que kubectl no puede comunicarse con el plano de control del clúster.

Para solucionar este problema, verifica y define el contexto en el que se ha definido el clúster y asegúrate de que hay conectividad con el clúster:

  1. Ve a $HOME/.kube/config o ejecuta el comando kubectl config view para verificar que el archivo de configuración contiene el contexto del clúster y la dirección IP externa del plano de control.

  2. Define las credenciales del clúster:

    gcloud container clusters get-credentials CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --project=PROJECT_ID

    Haz los cambios siguientes:

    • CLUSTER_NAME: el nombre de tu clúster.
    • CONTROL_PLANE_LOCATION: la ubicación de Compute Engine del plano de control de tu clúster. Proporciona una región para los clústeres regionales o una zona para los clústeres zonales.
    • PROJECT_ID: el ID del proyecto en el que se creó el clúster.

  3. Si has habilitado las redes autorizadas en el clúster, asegúrate de que su lista de redes autorizadas incluya la IP saliente de la máquina desde la que intentas conectarte. Puedes encontrar tus redes autorizadas en la consola o ejecutando el siguiente comando:

    gcloud container clusters describe CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --project=PROJECT_ID \
    --format "flattened(controlPlaneEndpointsConfig.ipEndpointsConfig.authorizedNetwork
sConfig.cidrBlocks[])"

    Si la IP saliente del equipo no se incluye en la lista de redes autorizadas de la salida del comando anterior, siga uno de estos pasos:

Error: los comandos de kubectl no han podido negociar una versión de la API

Si los comandos de kubectl devuelven un error failed to negotiate an API version, debes asegurarte de que kubectl tenga credenciales de autenticación:

gcloud auth application-default login

Problema: el comando kubectl logs, attach, exec o port-forward deja de responder

Si los comandos kubectl logs, attach, exec o port-forward dejan de responder, normalmente significa que el servidor de la API no puede comunicarse con los nodos.

Primero, comprueba si tu clúster tiene algún nodo. Si has reducido el número de nodos de tu clúster a cero, los comandos no funcionarán. Para solucionar este problema, cambia el tamaño de tu clúster para que tenga al menos un nodo.

Si tu clúster tiene al menos un nodo, comprueba si estás usando túneles SSH o de proxy de Konnectivity para habilitar la comunicación segura. En las siguientes secciones se describen los pasos para solucionar problemas específicos de cada servicio:

Solucionar problemas de SSH

Si usas SSH, GKE guarda un archivo de clave pública SSH en los metadatos de tu proyecto de Compute Engine. Todas las VMs de Compute Engine que usan imágenes proporcionadas por Google comprueban periódicamente los metadatos comunes de su proyecto y los metadatos de su instancia para buscar claves SSH que añadir a la lista de usuarios autorizados de la VM. GKE también añade una regla de cortafuegos a tu red de Compute Engine para permitir el acceso SSH desde la dirección IP del plano de control a cada nodo del clúster.

Los siguientes ajustes pueden provocar problemas con la comunicación SSH:

  • Las reglas de cortafuegos de tu red no permiten el acceso SSH desde el plano de control.

    Todas las redes de Compute Engine se crean con una regla de cortafuegos llamada default-allow-ssh que permite el acceso SSH desde todas las direcciones IP (se requiere una clave privada válida). GKE también inserta una regla SSH para cada clúster público con el formato gke-CLUSTER_NAME-RANDOM_CHARACTERS-ssh que permite el acceso SSH específicamente desde el plano de control del clúster a los nodos del clúster.

    Si no existe ninguna de estas reglas, el plano de control no podrá abrir túneles SSH.

    Para verificar si esta es la causa del problema, comprueba si tu configuración tiene estas reglas.

    Para solucionar este problema, identifique la etiqueta que se encuentra en todos los nodos del clúster y, a continuación, vuelva a añadir una regla de cortafuegos que permita el acceso a las VMs con esa etiqueta desde la dirección IP del plano de control.

  • La entrada de metadatos comunes de tu proyecto para ssh-keys está llena.

    Si la entrada de metadatos del proyecto llamada ssh-keys se acerca al límite de tamaño máximo, GKE no podrá añadir su propia clave SSH para abrir túneles SSH.

    Para verificar que este es el problema, compruebe la longitud de la lista de ssh-keys. Para ver los metadatos de tu proyecto, ejecuta el siguiente comando. También puedes incluir la marca --project:

    gcloud compute project-info describe [--project=PROJECT_ID]

    Para solucionar este problema, elimina algunas de las claves SSH que ya no necesites.

  • Ha definido un campo de metadatos con la clave ssh-keys en las VMs del clúster.

    El agente de nodo de las VMs prefiere las claves SSH por instancia a las claves SSH de todo el proyecto. Por lo tanto, si has definido alguna clave SSH específicamente en los nodos del clúster, los nodos no respetarán la clave SSH del plano de control en los metadatos del proyecto.

    Para comprobar si este es el problema, ejecuta gcloud compute instances describe VM_NAME y busca el campo ssh-keys en los metadatos.

    Para solucionar este problema, elimina las claves SSH por instancia de los metadatos de la instancia.

Solucionar problemas del proxy de Konnectivity

Para determinar si tu clúster usa el proxy de Konnectivity, comprueba la siguiente implementación del sistema:

kubectl get deployments konnectivity-agent --namespace kube-system

Si tu clúster usa el proxy de Konnectivity, el resultado será similar al siguiente:

NAME                 READY   UP-TO-DATE   AVAILABLE   AGE
konnectivity-agent   3/3     3            3           18d

Una vez que hayas verificado que estás usando el proxy de Konnectivity, asegúrate de que los agentes de Konnectivity tengan el acceso al firewall necesario y de que las políticas de tu red estén configuradas correctamente.

Permitir el acceso al cortafuegos necesario

Comprueba que las reglas del cortafuegos de tu red permitan el acceso a los siguientes puertos:

  • Puerto del plano de control: al crear un clúster, los agentes de Konnectivity establecen conexiones con el plano de control en el puerto 8132. Cuando ejecutas un comando kubectl, el servidor de la API usa esta conexión para comunicarse con el clúster. Asegúrate de permitir el tráfico de salida al plano de control del clúster en el puerto 8132 (a modo de comparación, el servidor de la API usa el puerto 443). Si tiene reglas que deniegan el acceso de salida, es posible que tenga que modificarlas o crear excepciones.

  • Puerto kubelet: como los agentes de Konnectivity son pods del sistema desplegados en los nodos de tu clúster, asegúrate de que tus reglas de cortafuegos permitan los siguientes tipos de tráfico:

    • Tráfico entrante a tus cargas de trabajo en el puerto 10250 desde tus intervalos de pods.
    • Tráfico saliente de tus intervalos de pods.

    Si tus reglas de cortafuegos no permiten este tipo de tráfico, modifica las reglas.

Ajustar la política de red

Es posible que el proxy de Konnectivity tenga problemas si la política de red de tu clúster hace lo siguiente:

  • Bloquea el tráfico de entrada del espacio de nombres kube-system al espacio de nombres workload
  • Bloquea el tráfico de salida al plano de control del clúster en el puerto 8132

Cuando la política de red de los pods de carga de trabajo bloquea el tráfico de entrada, los registros de konnectivity-agent incluyen un mensaje de error similar al siguiente:

"error dialing backend" error="dial tcp POD_IP_ADDRESS:PORT: i/o timeout"

En el mensaje de error, POD_IP_ADDRESS es la dirección IP del pod de la carga de trabajo.

Cuando la política de red bloquea el tráfico de salida, los konnectivity-agentregistros incluyen un mensaje de error similar al siguiente:

"cannot connect once" err="rpc error: code = Unavailable desc = connection error: desc = "transport: Error while dialing: dial tcp CP_IP_ADDRESS:8132: i/o timeout

En el error, CP_IP_ADDRESS es la dirección IP del plano de control del clúster.

Estas funciones no son necesarias para que el clúster funcione correctamente. Si prefieres que la red de tu clúster no tenga acceso externo, ten en cuenta que funciones como estas no funcionarán.

Para verificar que las reglas de entrada o salida de la política de red son la causa del problema, busca las políticas de red en el espacio de nombres afectado ejecutando el siguiente comando:

kubectl get networkpolicy --namespace AFFECTED_NAMESPACE

Para resolver el problema con la política de entrada, añade lo siguiente al campo spec.ingress de las políticas de red:

ingress:
- from:
  - namespaceSelector:
      matchLabels:
        kubernetes.io/metadata.name: kube-system
    podSelector:
      matchLabels:
        k8s-app: konnectivity-agent

Para resolver el problema con la política de salida, añade lo siguiente al campo spec.egress de las políticas de red:

egress:
- to:
  - ipBlock:
      cidr: CP_IP_ADDRESS/32
  ports:
  - protocol: TCP
    port: 8132

Si la política de tu red usa una combinación de reglas de entrada y salida, considera la posibilidad de ajustar ambas.

Ajustar el agente de enmascaramiento de IP

El plano de control del clúster acepta el tráfico de los agentes de Konnectivity si la dirección IP de origen está en los intervalos de direcciones IP de los pods. Si modificas la configuración de ip-masq-agent para enmascarar la dirección IP de origen del tráfico al plano de control del clúster, es posible que los agentes de Konnectivity experimenten errores de conectividad.

Para resolver el problema y asegurarte de que el tráfico de los agentes de Konnectivity al plano de control del clúster no se suplante con la dirección IP del nodo, añade la dirección IP del plano de control a la lista nonMasqueradeCIDRs en el ip-masq-agent ConfigMap:

nonMasqueradeCIDRs:
- CONTROL_PLANE_IP_ADDRESS/32

Para obtener más información sobre esta configuración, consulta Agente de enmascaramiento de IP.

Error: los comandos de kubectl fallan y se muestra el error "No hay ningún agente disponible"

Cuando ejecutas comandos kubectl que necesitan conectarse desde el plano de control de GKE a un pod (por ejemplo, kubectl exec, kubectl logs o kubectl port-forward), es posible que el comando falle y se muestren mensajes de error similares a los siguientes:

Error from server: error dialing backend: No agent available

failed to call webhook: Post "https://WEBHOOK_SERVICE.WEBHOOK_NAMESPACE.svc:PORT/PATH?timeout=10s": No agent available

v1beta1.metrics.k8s.io failed with: failing or missing response from https://NODE_IP:10250/apis/metrics.k8s.io/v1beta1: Get "https://NODE_IP:10250/apis/metrics.k8s.io/v1beta1": No agent available

Estos errores indican que hay un problema con Konnectivity, el túnel de comunicación segura entre el plano de control de GKE y los nodos de tu clúster. En concreto, significa que el konnectivity-server del plano de control no puede conectarse a ningún pod konnectivity-agent en buen estado del espacio de nombres kube-system.

Para solucionar este problema, prueba las siguientes soluciones:

  1. Verifica el estado de los pods konnectivity-agent:

    1. Comprueba si los pods de konnectivity-agent se están ejecutando:

      kubectl get pods -n kube-system -l k8s-app=konnectivity-agent

      El resultado debería ser similar al siguiente:

      NAME                                   READY   STATUS    RESTARTS  AGE
konnectivity-agent-abc123def4-xsy1a    2/2     Running   0         31d
konnectivity-agent-abc123def4-yza2b    2/2     Running   0         31d
konnectivity-agent-abc123def4-zxb3c    2/2     Running   0         31d

      Revisa el valor de la columna Status. Si los pods tienen el estado Running, revisa los registros para detectar problemas de conexión. De lo contrario, investiga por qué no se están ejecutando los pods.

    2. Revisa los registros para ver si hay problemas de conexión. Si los pods tienen el estado Running, comprueba los registros para ver si hay problemas de conexión. Como el comando kubectl logs depende de Konnectivity, usa Explorador de registros en la consolaGoogle Cloud :

      1. En la Google Cloud consola, ve a Explorador de registros.

        Ir a Explorador de registros

      2. En el panel de consultas, introduce la siguiente consulta.

        resource.type="k8s_container"
resource.labels.cluster_name="CLUSTER_NAME"
resource.labels.namespace_name="kube-system"
labels."k8s-pod/k8s-app"="konnectivity-agent"
resource.labels.container_name="konnectivity-agent"

        Sustituye CLUSTER_NAME por el nombre de tu clúster.

      3. Haz clic en Realizar una consulta.

      4. Revisa el resultado. Cuando revises los registros de konnectivity-agent, busca errores que indiquen por qué no se puede conectar el agente. Los errores de autenticación o de permisos suelen indicar que un webhook mal configurado está bloqueando las revisiones de tokens. Los errores "Conexión rechazada" o "Tiempo de espera agotado" suelen significar que una regla de cortafuegos o una política de red están bloqueando el tráfico al plano de control en el puerto TCP 8132 o que están bloqueando el tráfico entre el agente de Konnectivity y otros nodos. Los errores de certificado indican que un cortafuegos o un proxy están inspeccionando e interfiriendo con el tráfico TLS cifrado.

    3. Investiga por qué no se están ejecutando los pods. Si los pods tienen el estado Pending u otro estado que no sea de ejecución, investiga la causa. El konnectivity-agent se ejecuta como una implementación, no como un DaemonSet. Como se ejecuta como un Deployment, los pods del agente solo tienen que ejecutarse en un subconjunto de nodos. Sin embargo, si ese subconjunto específico de nodos no está disponible, todo el servicio puede fallar.

      Estas son algunas de las causas más habituales por las que un pod no se ejecuta:

      • Intolerancias de nodos personalizadas que impiden que se programe un pod.
      • Recursos de nodo insuficientes (CPU o memoria).
      • Políticas de autorización binaria restrictivas que bloquean las imágenes del sistema de GKE.

      Para obtener más información sobre por qué no se está ejecutando un Pod específico, usa el comando kubectl describe:

      kubectl describe pod POD_NAME -n kube-system

      Sustituye POD_NAME por el nombre del pod que no se está ejecutando.

  2. Investiga tus webhooks de admisión para asegurarte de que ninguno bloquea las solicitudes de la API TokenReview. konnectivity-agent se basa en tokens de cuentas de servicio, por lo que, si se interfiere en las revisiones de tokens, los agentes no podrán conectarse. Si la causa es un webhook, Konnectivity no podrá recuperarse hasta que se elimine o se repare el webhook defectuoso.

  3. Asegúrate de que tus reglas de cortafuegos permitan el tráfico de salida TCP desde tus nodos de GKE a la dirección IP del plano de control en el puerto 8132. Esta conexión es necesaria para que konnectivity-agent pueda acceder al servicio Konnectivity. Para obtener más información, consulta Permitir el acceso al cortafuegos necesario.

  4. Asegúrate de que no haya reglas de política de red que restrinjan el tráfico esencial de Konnectivity. Las reglas de la política de red deben permitir tanto el tráfico dentro del clúster (de pod a pod) en el espacio de nombres kube-system como el tráfico de salida de los pods konnectivity-agent al plano de control de GKE.

Siguientes pasos