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

En esta página, se muestra cómo resolver problemas con la herramienta de línea de comandos kubectl cuando trabajas en Google Kubernetes Engine (GKE). Para obtener más consejos generales, consulta Cómo solucionar problemas de kubectl en la documentación de Kubernetes.

Errores de autenticación y autorización

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

Error: 401 (no autorizado)

Cuando te conectas a clústeres de GKE, puedes obtener 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 se intenta acceder a la API de Kubernetes Engine desde una VM de Compute Engine que no tiene el permiso cloud-platform.

Para resolver este error, otorga el permiso 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 ocurrir mensajes de error similares a los siguientes cuando se intentan 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

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

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 \
    --region=COMPUTE_REGION

    Reemplaza lo siguiente:

    • CLUSTER_NAME: El nombre de tu clúster.
    • COMPUTE_REGION: La región de Compute Engine del clúster. Para los clústeres zonales, usa --zone=COMPUTE_ZONE.

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, pídele al 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 \
    --region=COMPUTE_REGION

    Reemplaza lo siguiente:

    • CLUSTER_NAME: El nombre de tu clúster.
    • COMPUTE_REGION: La región de Compute Engine del clúster. Para los clústeres zonales, usa --zone=COMPUTE_ZONE.

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 cualquier lugar 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 un error de “conexión rechazada”, debes configurar el contexto del clúster con el siguiente comando:

gcloud container clusters get-credentials CLUSTER_NAME

Reemplaza CLUSTER_NAME por el nombre del clúster. Si no estás seguro de qué ingresar para el nombre del clúster, usa el siguiente comando para hacer una lista de 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 donde se estableció el clúster y asegúrate de que tenga conectividad:

  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=COMPUTE_LOCATION \
    --project=PROJECT_ID

    Reemplaza lo siguiente:

    • CLUSTER_NAME: es el nombre de tu clúster.
    • COMPUTE_LOCATION: la ubicación de Compute Engine.
    • PROJECT_ID: El ID del proyecto en el que se creó el clúster.

  3. Si el clúster es un clúster de GKE privado, 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=COMPUTE_LOCATION \
    --project=PROJECT_ID \
    --format "flattened(masterAuthorizedNetworksConfig.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:

    • Si usas la consola, aumenta la probabilidad de que se pueda acceder al plano de control del clúster mediante la implementación de cualquiera de las opciones de configuración de acceso del extremo del clúster. Si deseas obtener más información, consulta el acceso a los extremos del clúster.
    • Si te conectas desde Cloud Shell, sigue las instrucciones que se indican en Usa Cloud Shell para acceder a un clúster privado.

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

Si los comandos kubectl muestran 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, por lo general, el servidor de la API no puede comunicarse con los nodos.

Primero, verifica si tu clúster tiene algún nodo. 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.

La siguiente configuración puede causar problemas con la comunicación de 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 que esta sea 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, verifica la longitud de la lista de ssh-keys. Para ver los metadatos del proyecto, ejecuta el siguiente comando y, de manera opcional, incluye 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 es 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 de proxy de Konnectivity

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

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

La siguiente configuración puede causar problemas con el proxy de Konnectivity:

  • Las reglas de firewall de la red no permiten el acceso del agente de Konnectivity al plano de control.

    Durante la creación del clúster, los pods del agente de Konnectivity establecen y mantienen una conexión con el plano de control en el puerto 8132. Cuando se ejecuta uno de los comandos kubectl, el servidor de la API usa esta conexión para comunicarse con el clúster.

    Si las reglas de firewall de la red contienen reglas de denegación de salida, puede impedir que el agente se conecte.

    Para verificar que esta sea la causa del problema, verifica las reglas de firewall de tu red para ver si contienen reglas de denegación de salida.

    Para resolver este problema, permite 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 443).

  • La política de red del clúster bloquea la entrada del espacio de nombres kube-system al espacio de nombres workload.

    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 esta sea 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 este problema, agrega lo siguiente al campo spec.ingress de las políticas de red:

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

¿Qué sigue?

Si necesitas asistencia adicional, comunícate con Atención al cliente de Cloud.