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

Cuando trabajas con Google Kubernetes Engine (GKE), los problemas con la herramienta de línea de comandos kubectl pueden impedir que implementes aplicaciones o administres recursos del clúster. Por lo general, estos problemas se clasifican en dos categorías: errores de autenticación, en los que el clúster no reconoce tu identidad, y errores de conectividad, en los que tu herramienta no puede acceder al plano de control del clúster.

Usa esta página para diagnosticar y resolver estos problemas. Encuentra los pasos para solucionar diversos problemas de autenticación y depurar los problemas de conectividad entre la herramienta kubectl y el plano de control de tu clúster. Aprende a verificar que los complementos necesarios estén instalados y configurados, y revisa las consideraciones sobre la política de red y el firewall para servicios como SSH y Konnectivity.

Esta información es importante para cualquier persona que use comandos de kubectl para administrar aplicaciones o recursos de clúster en GKE. Es especialmente importante para los desarrolladores de aplicaciones y los administradores y operadores de plataformas que dependen de los comandos de kubectl para sus tareas diarias principales. Para obtener más información sobre los roles comunes y las tareas de ejemplo a los que hacemos referencia en el contenido de Google Cloud, consulta Roles y tareas comunes de los usuarios de GKE.

Para obtener información relacionada, consulta los siguientes recursos:

Errores de autenticación y autorización

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

Error: 401 (no autorizado)

Cuando te conectas 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 ocurrir cuando intentas ejecutar un comando kubectl en tu clúster de GKE desde un entorno local. Para obtener más información, consulta Problema: Errores de autenticación y autorización.

Error: Permisos de autenticación insuficientes

Cuando ejecutas gcloud container clusters get-credentials, es posible 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 permiso cloud-platform.

Para resolver este error, otorga el alcance cloud-platform faltante. Si deseas obtener instrucciones para cambiar los permisos en tu instancia de VM de Compute Engine, consulta Crea y habilita cuentas de servicio para instancias en la documentación de Compute Engine.

Error: No se encontró el gke-gcloud-auth-plugin ejecutable

Pueden producirse mensajes de error similares a los siguientes cuando se intenta ejecutar comandos kubectl o clientes personalizados que interactúan con GKE:

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 resolver el problema, instala gke-gcloud-auth-plugin como se describe en Instala los complementos obligatorios.

Error: No se encontró ningún proveedor de autenticación

El siguiente error se produce si kubectl o los clientes personalizados de Kubernetes se compilaron con la versión 1.26 o posterior de Kubernetes client-go:

no Auth Provider found for name "gcp"

Para resolver este problema, realiza los siguientes pasos:

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

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

    gcloud components update

  3. Actualiza el archivo kubeconfig:

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

    Reemplaza lo siguiente:

    • CLUSTER_NAME: El nombre de tu clúster.
    • CONTROL_PLANE_LOCATION: Es 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 gcp está obsoleto; usa gcloud en su lugar

Es posible que veas el siguiente mensaje de advertencia después de instalar el 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 tu versión del cliente es anterior a 1.26.

Para resolver este problema, indícale a tu cliente que use el complemento de autenticación gke-gcloud-auth-plugin:

  1. Abre tu secuencia de comandos de acceso de shell en un editor de texto:

    Bash

    vi ~/.bashrc

    Zsh

    vi ~/.zshrc

    Si usas PowerShell, omite este paso.

  2. Configura la siguiente variable del 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 de la terminal y abre una nueva sesión de la terminal.

  4. Actualiza la CLI de gcloud:

    gcloud components update

  5. Autentícate en el clúster:

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

    Reemplaza lo siguiente:

    • CLUSTER_NAME: El nombre de tu clúster.
    • CONTROL_PLANE_LOCATION: Es 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 encontró el comando kubectl, reinstala el objeto binario kubectl y configura la variable de entorno $PATH:

  1. Instala el objeto binario kubectl:

    gcloud components update kubectl

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

    Como alternativa, agrega la siguiente línea a donde tu shell almacene 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, usa ~/.bash_profile en lugar de .bashrc.

Problema: Los comandos kubectl muestran el error “conexión rechazada”

Si los comandos kubectl muestran el error “conexión rechazada”, debes establecer el contexto del clúster con el siguiente comando:

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

Reemplaza lo siguiente:

  • CLUSTER_NAME: El nombre de tu clúster.
  • CONTROL_PLANE_LOCATION: Es 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é ingresar para el nombre o la ubicación del clúster, usa el siguiente comando para hacer una lista de tus clústeres:

gcloud container clusters list

Error: Se agotó el tiempo de espera del comando kubectl

Si creaste un clúster y trataste de ejecutar un comando kubectl en él, pero se agota el tiempo de espera del comando kubectl, 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 resolver este problema, verifica y establece el contexto en el que se establece el clúster y asegúrate de que haya 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 contenga el contexto del clúster y la dirección IP externa del plano de control.

  2. Configura las credenciales del clúster:

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

    Reemplaza lo siguiente:

    • CLUSTER_NAME: El nombre de tu clúster.
    • CONTROL_PLANE_LOCATION: Es 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 habilitaste las redes autorizadas en el clúster, asegúrate de que su lista de redes autorizadas existentes incluya la IP saliente de la máquina desde la que intentas conectarte. Puedes encontrar las redes autorizadas existentes en la consola o con la ejecución del 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 de la máquina no se incluye en la lista de redes autorizadas del resultado del comando anterior, completa uno de los siguientes pasos:

Error: Los comandos kubectl muestran el error “no se pudo negociar una versión de API”

Si los comandos 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, es probable que el servidor de la API no pueda comunicarse con los nodos.

Primero, verifica si tu clúster tiene nodos. Si reduces la cantidad de nodos en tu clúster a cero, los comandos no funcionarán. Para resolver este problema, cambia el tamaño del clúster para tener al menos un nodo.

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

Soluciona problemas de SSH

Si usas SSH, GKE guarda un archivo de clave pública SSH en los metadatos del proyecto de Compute Engine. Todas las VM de Compute Engine que usan imágenes proporcionadas por Google verifican con regularidad los metadatos comunes del proyecto y los metadatos de la instancia para las claves SSH a fin de agregarlos a la lista de usuarios autorizados de la VM. GKE también agrega una regla de firewall a la red de Compute Engine, lo que permite el acceso SSH desde la dirección IP del plano de control a cada nodo en el clúster.

Los siguientes parámetros de configuración pueden causar problemas con la comunicación SSH:

  • Las reglas de firewall de la red no permiten el acceso de SSH desde el plano de control.

    Todas las redes de Compute Engine se crean con una regla de firewall llamada default-allow-ssh que permite el acceso SSH desde todas las direcciones IP (mediante la solicitud de 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 de forma específica desde el plano de control del clúster hacia los nodos del clúster.

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

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

    Para resolver este problema, identifica la etiqueta que se encuentra en todos los nodos del clúster y, luego, vuelve a agregar una regla de firewall que permita el acceso a las VMs con esa etiqueta desde la dirección IP del plano de control.

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

    Si la entrada de metadatos del proyecto llamada ssh-keys está cerca de su límite de tamaño máximo, GKE no puede agregar su propia clave SSH para abrir túneles SSH.

    Para verificar que este es el problema, comprueba la longitud de la lista de ssh-keys. Para ver los metadatos del proyecto, ejecuta el siguiente comando. De manera opcional, puedes incluir la marca --project:

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

    Para resolver este problema, borra algunas de las claves SSH que ya no sean necesarias.

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

    El agente de nodo en las VM prefiere claves SSH por instancia en vez de claves SSH por proyecto completo, por lo que, si estableciste claves SSH de forma específica en los nodos del clúster, los nodos no respetaran la clave SSH del plano de control en los metadatos del proyecto.

    Para verificar que este sea el problema, ejecuta gcloud compute instances describe VM_NAME y busca un campo ssh-keys en los metadatos.

    Para resolver este problema, borra las claves SSH por instancia de los metadatos de la instancia.

Soluciona problemas del proxy de Konnectivity

Puedes determinar si tu clúster usa el proxy de Konnectivity verificando la siguiente Deployment del sistema:

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

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

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

Después de verificar que estás usando el proxy de Konnectivity, asegúrate de que los agentes de Konnectivity tengan el acceso de firewall requerido y de que tus políticas de red estén configuradas correctamente.

Permite el acceso requerido al firewall

Verifica que las reglas de firewall de tu red permitan el acceso a los siguientes puertos:

  • Puerto del plano de control: Durante la creación del 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 (en comparación, el servidor de la API usa el puerto 443). Si tienes reglas que deniegan el acceso de salida, es posible que debas modificarlas o crear excepciones.

  • Puerto kubelet: Debido a que los agentes de Konnectivity son Pods del sistema implementados en los nodos de tu clúster, asegúrate de que tus reglas de firewall permitan los siguientes tipos de tráfico:

    • Tráfico entrante a tus cargas de trabajo en el puerto 10250 desde tus rangos de Pods
    • Tráfico saliente de los rangos de tu Pod

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

Ajusta la política de red

El proxy de Konnectivity puede tener problemas si la política de red de tu clúster realiza alguna de las siguientes acciones:

  • Bloquea la entrada del espacio de nombres kube-system al espacio de nombres workload
  • Bloquea la 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 la 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 carga de trabajo.

Cuando la política de red bloquea la salida, los registros de konnectivity-agent 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 características no se requieren para el funcionamiento correcto del clúster. Si prefieres mantener el acceso exterior bloqueado para la red del clúster, ten en cuenta que las características como estas no funcionarán.

Para verificar que las reglas de entrada o salida de la política de red sean la causa del problema, ejecuta el siguiente comando para encontrar las políticas de red en el espacio de nombres afectado:

kubectl get networkpolicy --namespace AFFECTED_NAMESPACE

Para resolver el problema con la política de entrada, agrega 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, agrega 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 tu política de red usa una combinación de reglas de entrada y salida, considera ajustar ambas.

Ajusta 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 se encuentra en los rangos de direcciones IP del Pod. Si modificas la configuración de ip-masq-agent para enmascarar la dirección IP de origen del tráfico hacia el plano de control del clúster, es posible que los agentes de Konnectivity experimenten errores de conectividad.

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

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 kubectl fallan con el error de que no hay ningún agente disponible

Cuando ejecutas comandos de 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 muestre 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 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 particular, significa que konnectivity-server en el plano de control no se puede conectar a ningún Pod konnectivity-agent en buen estado en el espacio de nombres kube-system.

Para resolver este problema, prueba con las siguientes soluciones:

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

    1. Verifica si los Pods konnectivity-agent se están ejecutando:

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

      El resultado es similar a este:

      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 en 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 detectar problemas de conexión. Si los Pods tienen el estado Running, verifica los registros para detectar problemas de conexión. Dado que el comando kubectl logs depende de Konnectivity, usa el Explorador de registros en la consola deGoogle Cloud :

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

        Ir al Explorador de registros

      2. En el panel de consultas, ingresa 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"

        Reemplaza CLUSTER_NAME por el nombre de tu clúster.

      3. Haz clic en Ejecutar consulta.

      4. Revise el resultado. Cuando revises los registros de konnectivity-agent, busca errores que indiquen por qué el agente no se puede conectar. Los errores de autenticación o de permisos suelen indicar que hay un webhook mal configurado que bloquea las revisiones de tokens. Los errores de "conexión rechazada" o "tiempo de espera agotado" suelen significar que una regla de firewall o una política de red bloquean el tráfico al plano de control en el puerto TCP 8132, o bien bloquean el tráfico entre el agente de Konnectivity y otros nodos. Los errores de certificado sugieren que un firewall o proxy está inspeccionando el tráfico de TLS encriptado y, por lo tanto, interfiriendo en él.

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

      Entre las causas comunes por las que un Pod no se ejecuta, se incluyen las siguientes:

      • Son taints de nodos personalizados que impiden que se programe un Pod.
      • Recursos de nodo insuficientes (CPU o memoria).
      • Políticas restrictivas de Autorización binaria que bloquean las imágenes del sistema de GKE

      Para obtener más detalles sobre por qué no se ejecuta un Pod específico, usa el comando kubectl describe:

      kubectl describe pod POD_NAME -n kube-system

      Reemplaza POD_NAME por el nombre del Pod que no se está ejecutando.

  2. Investiga tus webhooks de admisión para asegurarte de que ninguno bloquee las solicitudes a la API de TokenReview. konnectivity-agent depende de los tokens de cuentas de servicio, por lo que la interferencia con las revisiones de tokens puede impedir que los agentes se conecten. Si la causa es un webhook, Konnectivity no puede recuperarse hasta que se quite o repare el webhook defectuoso.

  3. Asegúrate de que tus reglas de firewall permitan el tráfico de salida de 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 llegue al servicio de Konnectivity. Para obtener más información, consulta Permite el acceso requerido al firewall.

  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 el tráfico dentro del clúster (de Pod a Pod) dentro del espacio de nombres kube-system y el tráfico de salida de los Pods konnectivity-agent al plano de control de GKE.

¿Qué sigue?